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).

Tras un periodo de exámenes, continúo escribiendo este tutorial.

Descripción de modsms

Como ya se ha comentado en entradas anteriores, vamos a realizar un módulo de actividad muy sencillo llamado modsms que nos permitirá tratar todos los aspectos básicos a tener en cuenta a la hora de desarrollar nuestro módulo. Este módulo hará uso de una base de datos para almacenar una serie de mensajes breves escritos por los alumnos (como un chat aunque sin una actualización en tiempo real) que responden a una pregunta del profesor. El diseño relacional de la base de datos queda de la siguiente forma:

Esquema Entidad-Relación modSMS

De color azul tenemos las tablas creadas por este módulo, y de color rosa las ya existentes en moodle pero que son referenciadas desde las nuestras.

Definición de las tablas: db/install.xml

El primer archivo que vamos a crear en nuestro módulo es el archivo de definición de las tablas que se usarán en nuestro módulo y que se crearán cuando lo activemos/instalemos. Este archivo es necesario crearlo aunque no usemos en nuestro módulo nada de las bases de datos, pero, como veremos más adelante, siempre resulta necesario crear una tabla con el nombre de nuestro módulo donde se almacenarán las distintas instancias de nuestro módulo en los cursos.

Este archivo contiene una definición de las tablas en un formato XMLDB modificado por moodle a su manera, por lo que si usamos algún editor existente que soporte ese xml deberemos prestar atención a los cambios. Para facilitarnos esa tarea, el propio moodle lleva incorporado un editor web que es el que usaremos para crear el esquema. Para ello, crearemos la estructura inicial del módulo creando la carpeta modsms bajo raiz-de-moodle/mood, dentro de ella la carpeta db y dentro de esta un archivo de texto llamado install.xml.

El primer paso es dotar de contenido a este archivo con una estructura básica para que el editor de moodle pueda reconocerlo y editarlo:

Como puede observarse, el xml consta de dos partes: la definición de tablas (tables) y la definición de consultas (statements). Por ahora nos olvidaremos de esta última parte y nos centraremos en la primera, la cual define la tabla principal del módulo (modsms) con un único campo (id) que identifica cada instancia de nuestro módulo de forma única.

Ahora entramos como administrador en moodle y en el menú de administración seleccionamos Miscelánea > XMLDB Editor. Una vez estemos en la página, buscamos la línea mod/modsms/db y pulsamos sobre Load, lo cual cargará nuestro archivo xml para su edición. Una vez cargado, en la misma línea tendremos activada la opción de editar (Edit), y pulsando sobre ella accederemos a la interfaz de edición del xmldb.

Vista de la interfaz de edición de XMLDB

Creando la estructura de las tablas

Como puede apreciarse en la página de edición, disponemos ya de una tabla creada, llamada modsms, que se corresponde con la única tabla obligatoria para un módulo de actividad en moodle. En esta tabla se creará un registro/fila/tupla por cada una de las instancias de nuestra actividad en cualquier curso de todo moodle. Y… ¿qué es una instancia? Pues es simplemente una actividad que insertamos en algún curso, que se diferencia de otras instancias de la misma actividad por un número de identificación único que se guarda en la tabla como el campo id. Esta tabla debe contener obligatoriamente tres campos: id, course y name, que identifican de forma unica cada instancia, hace referencia al curso donde está y el nombre que tiene, respectivamente. Para editar la tabla solamente pulsaremos sobre el enlace [Edit] que se encuentra junto al nombre de la tabla bajo la sección Tables.

Como se observa, la tabla ya contiene el campo id mencionado anteriormente. Ahora es el turno de añadir los demás campos que necesitamos en base al diseño realizado arriba. Para añadir un nuevo campo, sólo hay que pulsar sobre [New Field] y rellenar los datos del campo en la siguiente página. En el caso del campo course, el formulario lucirá el siguiente aspecto:

Editando el campo course

Repetiremos este proceso hasta completar todos los campos de la tabla. Es importante que todos los campos tengan la restricción de no nulo (NOT NULL), ya que ninguno debe ser nulo para el correcto funcionamiento del módulo. Una vez creados todos los campos, el siguiente paso es aplicar las restricciones y las relaciones a los campos que lo requieran. En esta tabla, deberemos reflejar que el campo course es una clave foránea (hace referencia a) del campo id en la tabla course. Para informar de esto a la base de datos, pulsamos sobre [New Key] y rellenamos los datos:

Editando las restricciones de clave foranea

Usando el enlace [Back] volvemos hacia atrás hasta llegar a la página que muestra la lista de tablas creadas (solo hay una por el momento). Si pulsamos sobre el enlace [New Table] nos mostrará la interfaz de creación de tablas dónde sólo hay que darle un nombre y el comentario es opcional, y la aplicación se encargará de crear el campo identificativo por defecto (id). En este paso creamos la tabla de nombre modsms_messages donde guardar los mensajes escritos por los alumnos. Y repetimos los pasos anteriores para dotar de contenido a esta nueva tabla.

Guardando el nuevo archivo

Por razones que desconozco, pese a contar el archivo con permisos 777 en linux, resulta imposible guardarlo desde moodle con la opción [Save] que aparece junto a la ruta en la lista de archivos editables de la interfaz de edición de xmldb. Por ello, la única manera de guardar los cambios es, estando en la interfaz de edición, pulsar sobre [View Edited] con el botón derecho del ratón y darle a Guardar como…, sustituyendo el antiguo archivo por este nuevo.

Cuando todo esté terminado, el contenido del archivo install.xml debe ser muy parecido a este:

Nota sobre los nombres de tablas y campos

En moodle, el nombre de la tabla principal de un módulo debe llamarse igual que este, y las demás tablas que necesitemos deben empezar por el nombre del módulo. En nuestro caso, el módulo se llama modsms, su tabla principal modsms y la otra que necesitamos modsms_messages.

Si en una tabla hacemos referencia al campo de otra tabla, este campo deberá llamarse de la forma nombredelatablanombredelcampo. Así, para hacer referencia al campo id de la tabla user, en nuestra tabla modsms_messages hemos creado un campo llamado userid.

Todos estos requerimientos pueden consultarse en la documentación en inglés sobre las bases de datos en moodle.

Estructura de archivos de un módulo

Para que moodle reconozca nuestro módulo de actividad este debe seguir una estructura de archivos (algunos necesarios y otros opcionales). Para ello, a partir de este momento vamos a considerar que nuestro módulo de prueba va a llamarse “modsms“. Por tanto la estructura sería:

• / – raíz de moodle.
• /mod – carpeta de módulos.
  • /modsms – carpeta raíz de nuestro módulo. Aquí dentro irán todos nuestros archivos y carpetas.
    • /db – carpeta con datos a introducir en la base de datos durante la instalación/actualización del módulo.
      • /access.php – contiene las capacidades/permisos del módulo.
      • /install.xml – esquema de la base de datos en xmldb para la instalación del módulo.
      • /upgrade.php – procedimientos de actualización del módulo.
    • /icon.gif – icono de la actividad que se muestra en el curso (entre otros sitios).
    • /index.php – muestra la lista de instancias de actividades de nuestro módulo que hay en el curso.
    • /lib.php – funciones requeridas por moodle para comunicarse con nuestro módulo.
    • /locallib.php – funciones propias que necesitemos para nuestro módulo.
    • /mod_form.php – formulario de configuración de la actividad al ser creada o editada.
    • /version.php – información sobre versiones relacionadas con el módulo.
    • /view.php – página de inicio de la actividad (cuando entra en la actividad un alumno por ejemplo).
    • /styles.php – definición de estilos css para nuestro módulo.
    • /backuplib.php – funciones para realizar la copia de seguridad del módulo.
    • /restorelib.php – funciones para realizar el restablecimiento de una copia de seguridad del módulo.
    • /lang – directorio de idiomas
      • /es_es_utf8 – directorio de idioma correspondiente al español de España versión UTF8.
        • /modsms.php – archivo con las cadenas usadas en el módulo en el idioma de arriba.
          • /help – carpeta con los archivos de ayuda.
            • /modsms – ayuda de este módulo.
              • index.html – índice con enlaces a los demás archivos de ayuda de este módulo.
              • mods.html – información general de nuestro módulo.
              • miayuda5.html – archivo de ayuda propio con ayuda sobre algo de nuestro módulo.
    • /miarchivo.php – también podemos crear tantos archivos (páginas) como necesitemos.

Los archivos en negrita son los archivos “obligatorios” que deberemos tener en nuestro módulo, siendo el resto opcionales.

Referencias básicas a la hora de desarrollar un módulo

Dado que como comentábamos en la anterior entrega de este tutorial la documentación de moodle es bastante escasa, cuando estemos desarrollando nuestro módulo o mirando cómo están hechos los otros (algo muy recomendable por otra parte) nos encontraremos con funciones que no sabemos qué hacen o que parámetros se le pueden pasar. Para ello moodle posee dos webs donde tiene subido la documentación generada por phpDocumentor y PHPXref que nos van a ser muy útiles para lo anterior:

• Moodle phpDocs
• Moodle PHPXref

Una vez conocida la estructura de archivos de los módulos, en la siguiente entrega comenzaremos de lleno a programar nuestro módulo modsms.

Lejos de pasar unas vacaciones relajadas en la playa como merecido descanso tras el periodo de exámenes de junio, en las últimas semanas (en realidad en los últimos tres meses) me he metido sin yo saberlo en un proyecto bastante complejo: la creación de un módulo para Moodle, la plataforma e-learning que usa la Universidad de Córdoba, patrocinado por el Departamento de Estadística que es quién paga la beca. Y además, me servirá como proyecto de fin de carrera del que ya iré hablando también en este blog.

Cuando uno tiene que enfrentarse a una situación como esta, lo primero que debe hacer es documentarse sobre el sistema donde va a ser implementado. Moodle es un proyecto de software libre bastante usado en esto de las enseñanzas a distancia o virtuales. Dispone de una wiki que contiene documentación. Pero… ¡siempre hay un pero! por poco que empecemos a navegar por la misma nos daremos cuenta que sufre un caos bastante severo, con documentación mal organizada, escasa y mezclando las versiones de la rama 1.9 y la 2.0 en desarrollo. Con semejante panorama, donde la documentación oficial es deficiente o inexistente, no queda más remedio que buscar terceras fuentes o ponerse a mirar cómo funcionan los módulos oficiales que vienen con la distribución estándar de moodle.

Documentación de terceros

No es que exista una gran documentación y más en español, pero he encontrado alguna. En primer lugar tenemos un tutorial realizado por un alumno de informática para su proyecto de fin de carrera en español, disponible aquí, aunque es para la versión 1.7, cuya estructura de archivos es distinta a la 1.9 y por tanto sólo nos serviría para hacernos una idea de lo necesario en un módulo. En segundo lugar disponemos de una presentación power point en inglés sobre la estructura de los módulos en la versión 1.8 disponible aquí.

Documentación oficial

La documentación oficial nos ofrece cinco páginas:

• Estructura de los módulos (Development:Modules)
• Escueto tutorial (Development:NEWMODULE Tutorial)
• Referencia (Development:NEWMODULE Reference)
• Preguntas frecuentes (Development:NEWMODULE FAQ)
• Permisos (Development:NEWMODULE Adding capabilities)

En la siguiente entrega empezaré por el primero de ellos: la estructura de un módulo.