El blog de Javier Aranda

Para completar los archivos necesarios dentro del directorio db, en esta entrada aprenderemos a especificar las capacidades del módulo y el archivo de actualización por si el módulo que instalamos fuese una versión superior a una que ya existiese.

Definiendo las capacidades

Moodle posee un sistema de capacidades, una especie de sistema de permisos que nos permitirán definir acciones y decidir qué usuarios pueden ejecutarlas. Esto nos resultará especialmente útil para definir acciones de administración o que sólo deban ser ejecutadas por un role de usuario (alumno, profesor, administrador, etc). Estas accionen deben definirse en un archivo llamado access.php que se encuentra bajo el directorio db. Cuando instalamos el módulo, moodle lee este archivo y copia su información en la base de datos, por lo que si lo modificamos, tendremos que aumentar el valor de la versión del módulo (esto lo veremos más adelante) para que moodle vuelva a leerlo y almacenar sus nuevos valores. Veamos su estructura:

access.php

$mod_modsms_capabilities = array(

    //capacidad de enviar mensajes en el tablon
    'mod/modsms:participate' => array(

        'riskbitmask' => RISK_SPAM,

        'captype' => 'write',
        'contextlevel' => CONTEXT_MODULE,
        'legacy' => array(
            'student' => CAP_ALLOW
        )
    ),

    //capacidad de administrar el tablón
    'mod/modsms:manage' => array(

        'riskbitmask' => RISK_SPAM,

        'captype' => 'write',
        'contextlevel' => CONTEXT_MODULE,
        'legacy' => array(
            'teacher' => CAP_ALLOW,
            'editingteacher' => CAP_ALLOW,
            'admin' => CAP_ALLOW
        )
    )
);

Como podemos observar en el código anterior, la variable ($mod_modsms_capabilities) incluye el nombre del módulo para diferenciarla de la que pueda existir en otros módulos. Internamente, está formada por un array de tantos elementos como capacidades queramos definir, en la forma nombre_de_la_capacidad => array_de_configuración_de_esa_capacidad. Entre esas configuraciones, caben destacar:

captype: tipo de la capacidad. El valor write indica que la capacidad será usada para la entrada de datos o el cambio de cosas. El valor read por contra se usa para la salida de datos, para mostrar cosas.

legacy: este elemento es a su vez un array que permite indicar que tipo de role posee autorización para realizar la acción indicada en la capacidad.

Para más información sobre las capacidades se puede consultar la documentación oficial en inglés:

• http://docs.moodle.org/en/Development:NEWMODULE_Adding_capabilities
• http://docs.moodle.org/en/Development:Roles
• http://docs.moodle.org/en/Development:Hardening_new_Roles_system

Viendo el código podemos observar que se han definido dos capacidades: la de enviar mensajes al tablón y la de administrarlo. Para la primera, que es de tipo escritura (ya que el usuario envía datos), sólo autorizamos a que sea el usuario cuyo rol es estudiante a que pueda escribir mensajes. En la segunda, de tipo escritura, los roles que pueden hacer uso de esta capacidad son los de profesor (ambos tipos) y administrador. Se podría haber definido un tercer rol de tipo lectura con la capacidad de leer los mensajes, pero como los mensajes pueden ser vistos por cualquier tipo de usuario, no se ha considerado.

Actualizando versiones anteriores del módulo

Si nuestro módulo no es de nueva creación sino que se trata de una versión posterior, es posible que necesitemos realizar actualizaciones en la base de datos existente (ya que al existir una en el sistema no se sobreescriben los datos con el contenido del archivo install.xml visto en entradas anteriores) al necesitar esta nueva versión de campos adicionales por ejemplo. La forma de realizar esto es mediante el archivo upgrade.php que se encuentra también bajo el directorio db. Este archivo contiene en su interior una función llamada xmldb_nombremodulo_upgrade, la cual será invocada por moodle en la instalación del módulo y pasándole como parámetro la versión del módulo instalado actualmente.

upgrade.php

function xmldb_modsms_upgrade($oldversion=0)
{
    global $CFG, $THEME, $db;

    $result = true;

    /*
    And upgrade begins here. For each one, you'll need one
    block of code similar to the next one. Please, delete
    this comment lines once this file start handling proper
    upgrade code.

    if ($result && $oldversion < YYYYMMDD00) { //New version in version.php
        $result = result of "/lib/ddllib.php" function calls
    }
    */

    return $result;
}

Es en esta función donde deberemos implementar las diferentes consultas a la base de datos para transformar los datos antiguos al nuevo formato. En nuestro caso, al ser la primera versión del módulo, no la necesitamos, por lo que devolvemos true indicando que todo ha salido correctamente.

La versión del módulo y otros datos de interés

En los apartados anteriores vimos que resulta necesario para ciertas operaciones conocer el número de versión del módulo instalado actualmente. La forma que tiene moodle de saberlo es mediante el contenido del archivo version.php situado en la raíz del módulo. El contenido del archivo es el siguiente:

version.php

//versión del módulo
$module->version  = 2009101200;

//versión de moodle mínima para instalarse
$module->requires = 2007101509;

//tiempo cada cual debe ser llamada la función de cron del módulo
$module->cron     = 0;

La primera de ellas le indica a moodle la versión de este módulo. La segunda indica la versión mínima de moodle sobre la que corre este módulo. Las versiones siguen la forma AAAAMMDDXY.YY siendo YYYYMMDD la fecha de lanzamiento de la rama (1.9 en el caso de la versión de moodle), X número de release 1.9.[0,1,2,3...] e Y.YY pequeños incrementos de las versiones entre releases. El último parámetro nos permite establecer cada cuanto tiempo moodle debe llamar a la función de cron que se encuentra dentro de lib.php como veremos en futuras entregas de este tutorial. Si se pone a cero nunca se llamará a la función (por que no nos haga falta en nuestro módulo).

Entradas relacionadas:

1. Tutorial de creación de un módulo para Moodle 1.9 (II)
2. Tutorial de creación de un módulo para Moodle 1.9 (I)
3. Tutorial de creación de un módulo para Moodle 1.9 (III)