Desarrollo de bloques

De MoodleDocs
Autor: Jon Papaioannou (pj@uom.gr)</div> Traduccin: Astrid Snchez (astrid@solearning.com) Versin: $Id: HOWTO.html,v 1.10 2005/02/11 06:30:49 defacer Exp

Una gua paso-a-paso para crear bloques

Resmen
El presente documento sirve como gua a los desarrolladores que quieren crear sus propios bloques para usar en Moodle. Aplica solamente a la versin en desarrollo 1.5 de Moodle (y cualquiera ms reciente), ya que el subsistema de bloques fue re-escrito y expandido. Sin embargo, tambin la puedes encontrar til si quieres modificar los bloques escritos para Moodle 1.3 o 1.4 de modo que funcionen con las ltimas versiones. (Ver Apndice B). La gua est escrita como un curso interactivo el cul apunta al desarrollo de un bloque configurable, multipropsito que despliega HTML arbitrario. Est dirigida principalmente a personas con poca experiencia con Moodle o en programacin en general y pretende mostrar que tan fcil es crear nuevos bloques para Moodle. A pesar de esto se requieren unos conocimientos bsicos en programacin PHP. Desarrolladores experimentados y aquellos que solo quieren un texto de referencia deberan referirse al Apndice A, porque el contenido central es ms bien sencillo.

Conceptos bsicos
A travs de esta gua, seguiremos la creacin de un bloque "HTML" desde cero con el objeto de demostrar la mayora de las caractersticas del bloque que tenemos a nuestra disposicin. Nuestro bloque se llamar "SimpleHTML". No es necesario que recordemos el nombre del directorio real en el servidor donde se guardarn los archivos de nuestro bloque, pero por consistencia seguiremos la prctica de usar la forma en minscula "simplehtml" en cualquier caso donde tal nombre se necesite. Cuando nos referimos a un archivo o al nombre de un directorio que contiene "simplehtml", es importante recordar que solo cambiaremos la parte "simplehtml"; el resto es estandarizado y esencial para que Moodle funcione correctamente. Cuando en esta gua se mencione la ruta de un archivo, siempre comenzar con un slash (/). Esto se refiere al directorio home de Moodle; todos los archivos y directorios sern referidos con respecto a este directorio.

En sus marcas, listos, Fuera!

Para definir un "bloque" en Moodle, en el caso ms bsico solo necesitamos un archivo de cdigo fuente. Comenzamos por crear el directorio /blocks/simplehtml/ y un archivo llamado /blocks/simplehtml/block_simplehtml.php el cual contendr nuestro cdigo. Entonces comenzamos a codificar el bloque:
class block_simplehtml extends block_base { function init() { $this->title = get_string('simplehtml', 'block_simplehtml'); $this->version = 2004111200; } }

La primera lnea es la definicin de nuestra clase bloque; debe nombrarse exactamente de la manera mostrada. De nuevo, solo la parte "simplehtml" puede (en realidad debe) ser cambiada; todo lo dems est estandarizado. A nuestra clase se le da entonces un pequeo mtodo: init. Este es esencial para todos los bloques, y su propsito es definir las dos variables miembros de la clase listados en ella. Pero, qu significan realmente estos valores? Aqu hay una descripcin ms detallada. $this->title es el ttulo que aparece en la cabecera de nuestro bloque. Podemos poner lo que queramos; en este caso est definido para que lea el ttulo real de un archivo de lenguaje que presumiblemente estamos distribuyendo con el bloque. Saltar un poco adelante aqu y dir que si quieres que tu bloque no muestre absolutamente ningn ttulo, entonces debes poner cualquier valor descriptivo que quieras (pero no lo dejes vaco). Ms adelante veremos como deshabilitar el despliegue del ttulo. $this->version es la versin de nuestro bloque. Realmente hara alguna diferencia solo si queremos que nuestro bloque guarde sus propios datos en tablas especiales en la base de datos (esto es, para bloque muy complejos). En este caso el nmero de la versin es usada exactamente como se usa en las actividades; un script de actualizacin lo usa para incrementalmente actualizar una versin "vieja" de los datos del bloque a los ms recientes. Bosquejaremos este proceso ms adelante, ya que los bloques tienden a ser relativamente simples y no mantienen sus propios datos privados. Ciertamente este es el caso de nuestro ejemplo, as que solo definiremos $this->version como YYYYMMDD00 y nos olvidamos de esto. ACTUALIZANDO: Antes de la versin 1.5, la estructura bsica de cada clase bloque era ligeramente diferente. Vaya al Apndice B para ms informacin acerca de los cambios que los bloques viejos tienen que hacer para estar conforme al nuevo estndar.

Acabo de escuchar esttico

Con el fin de que nuestro bloque realmente muestre algo en pantalla, necesitamos agregar un mtodo ms a nuestra clase (antes del corchete de cierre final en nuestro archivo). El nuevo cdigo es:
function get_content() { if ($this->content !== NULL) { return $this->content; } $this->content = new stdClass; $this->content->text = 'El contenido de nuestro bloque SimpleHTML!'; $this->content->footer = 'Pie de pgina aqu...'; return $this->content; }

No podra ser ms simple, verdad?, Vamos a examinar este mtodo para ver que est pasando Primero que todo, hay un chequeo que retorna el valor actual de $this->content si no es NULL; de otra manera procedemos a "calcularlo". Dado que este clculo es una operacin potencialmente consumidora de tiempo y ser llamada varias veces por cada bloque (Moodle trabaja de esa manera internamente) tomamos una precaucin e incluimos este ahorrador de tiempo. Suponiendo que el contenido no ha sido calculado antes (este era NULL), entonces lo definimos desde cero. El cdigo habla por si mismo aqu, as que no hay mucho por decir. Solo ten presente que podemos usar HTML en ambos el texto y el pie de pgina, si queremos. En este punto nuestro bloque debera poder de ser instalado automticamente en Moodle y agregarse a cursos; visita tu pgina de administracin para instalarlo y despus de verlo en accin regresa a nuestro tutorial (N. del T. La pgina de administracin depende de donde tengas instalado tu Moodle, generalmente ''http://host/moodle/admin'')

Configralo
La versin actual de nuestro bloque no hace mucho en realidad; solo muestra un mensaje fijo, lo cual no es muy til. Lo que realmente queremos hacer es permitirle a los profesores configurar lo que hay en el bloque. Esto, en lenguaje de bloque, se llama "configuracin de instancias". As que vamos a darle a nuestro bloque una configuracin de instancia... Primero que todo, necesitamos decirle a Moodle que queremos que le de a nuestro bloque opciones de configuracin de instancia especfica. Es tan simple como agregar un mtodo ms a nuestra clase bloque:

function instance_allow_config() { return true; }

Este pequeo cambio es suficiente para hacer que Moodle muestre un icono de "Edit " en la cabecera de nuestro bloque cuando entramos en modo edicin de cualquier curso. Sin embargo, si tratas de dar click en este icono se te presentar una nota que se queja diciendo que la configuracin no ha sido implementada correctamente. Intntalo, es inofensivo. La queja de Moodle tiene sentido. Le dijimos que queremos configurar, pero no le dijimos qu tipo de configuracin queremos, o como debe ser mostrada. Para hacerlo, necesitamos crear un archivo ms: /blocks/simplehtml/config_instance.html (el cual tiene que estar nombrado exactamente as). Por el momento, copia y pega lo siguiente en l y gurdalo:
<table cellpadding="9" cellspacing="0"> <tr valign="top"> <td align="right"> <?php print_string('configcontent', 'block_simplehtml'); ?>: </td> <td> <?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?> </td> </tr> <tr> <td colspan="2" align="center"> <input type="submit" value="<?php print_string('savechanges') ?>" /> </td> </tr> </table> <?php use_html_editor(); ?>

No es difcil ver que el cdigo de arriba solo nos dar un rea de texto con un editor wysiwyg habilitado para escribir el contenido deseado de nuestro bloque en l y un botn de envio para grabar (N. del T. "submit", envo de un formulario; Un editor "wysiwyg" What You See Is What You Get - es en el que "Lo que ves es lo que obtienes", como muchos de los procesadores de texto conocidos, que permiten modificaciones de fuente, colores, etc.). Pero... qu es $this->config->text? Bien... Moodle vas ms all hacindole las cosas ms fciles a los desarrolladores de bloques. Notaste que el rea de texto se llama realmente "text"? Cuando se presiona el botn submit, Moodle guarda todos y cada uno de los campos que pueda encontrar en nuestro archivo config_instance.html como datos de configuracin de instancia. Podemos ahora acceder a estos datos como $this>config->nombredevariable, donde nombredevariable es el nombre real que usamos para nuestro campo; en este caso "text". As en esencia, el formulario anterior solo muestra en el rea de texto el contenido actual del bloque (como en realidad debera ser) y entonces nos permite cambiarlo. Tambin podrs sorprenderte por la presencia de un botn de enviar y al mismo tiempo la ausencia de cualquier elemento <form>. Pero la verdad es que, no necesitamos

preocuparnos acerca de esto para nada; Moodle realmente va mas all hacindole las cosas ms fciles a los desarrolladores! Solo imprimimos las opciones de configuracin que nosotros queremos, en cualquier formato que nosotros queramos; incluyendo un botn enviar, y Moodle manejar el resto por s mismo. Las variables de configuracin de instancias estn a nuestra disposicin para accederlas desde cualquier mtodo de la clase exceptoinit. En el caso de que el comportamiento por defecto no sea satisfactorio, todava podemos reconfigurarlo. Sin embargo, esto requiere modificaciones avanzadas a nuestra clase bloque y no se cubrir aqu; vaya al [#appendix_a Apndice A] para ms detalles. Ahora que tenemos la habilidad de referirnos a estos datos de configuracin de instancias a travs de $this->config, el truco final es decirle a nuestro bloque que muestre realmente lo que se ha guardado en su configuracin. Para hacer esto, encuentra esta parte en /blocks/simplehtml/block_simplehtml.php:
$this->content = new stdClass; $this->content->text = 'El contenido de nuestro bloque SimpleHTML!'; $this->content->footer = 'Pie de pgina aqu...';

y cambiala por:
$this->content = new stdClass; $this->content->text = $this->config->text; $this->content->footer = 'Pie de pgina aqu...';

Ah, y dado que el pie de pgina no es realmente excitante en este punto, lo removemos de nuestro bloque porque no est contribuyendo en nada. Fcilmente podramos haber decidido hacer configurable tambin al pie de pgina de la manera anterior. Ahora en nuestro cdigo ms actualizado, esta parte sera:
$this->content = new stdClass; $this->content->text = $this->config->text; $this->content->footer = ;

Despus de esta discusin, nuestro bloque est listo para exhibirse!. En realidad, si visitas ahora cualquier curso con un bloque SimpleHTML, vers que modificar su contenido es ahora tan fcil como un chasquido.

El especialista
Implementar la configuracin de instancia para el contenido del bloque fue bueno para estimular nuestro apetito, pero quin quiere detenerse aqu? Por qu no configurar tambin el ttulo del bloque? Por qu no, ciertamente. Bien, nuestro primer intento para lograrlo es bastante natural: Vamos a agregar otro campo a /blocks/simplehtml/config_instance.html. Aqu va:
<tr valign="top">

<td align="right"><p><?php print_string('configtitle', 'block_simplehtml'); ?>:</td> <td><input type="text" name="title" size="30" value="<?php echo $this>config->title; ?>" /></td> </tr>

Guardamos el archivo editado, vamos a un curso, editamos el ttulo del bloque y nada pasa! La configuracin de la instancia est guardada correctamente, todo est bien (editarlo una vez ms lo comprueba) pero no se est desplegando. Todo lo que tenemos es el simple ttulo "SimpleHTML". Esto no es tan raro, si pensamos un poco atrs. Recuerdas ese mtodo init, donde definimos $this->title? Realmente no hemos cambiado su valor desde entonces, y $this->title definitivamente no es el mismo $this->config->title (al menos para Moodle). Los que necesitamos es un modo de actualizar $this->title con el valor en la configuracin de la instancia. Pero como dijimos hace poco, podemos usar $this->config en todos los mtodos excepto en init! Entonces qu podemos hacer? Vamos a sacar otro as bajo la manga, y agregar este pequeo mtodo a nuestra clase bloque:
function specialization() { $this->title = $this->config->title; }

Aj, aqu est lo que hemos querido hacer desde el principio! Pero que pasa con el mtodo specialization? Este mtodo "mgico" tiene en realidad un propiedad muy interesante: se garantiza que es llamado automticamente por Moodle tan pronto como la configuracin de nuestra instancia est cargada y disponible (esto es, inmediatamente despus de que se llama init). Es decir antes de que el contenido del bloque sea calculado por primera vez, y por cierto antes de que cualquier otra cosa sea hecha con nuestro bloque. De este modo, poner un mtodo specialization es la eleccin natural para cualquier configuracin que necesita ser realizada "tan rpido como sea posible", como en este caso.

Ahora me ves, ahora no me ves

Este sera un buen momento para mencionar otra elegante tcnica que puede ser usada en los bloques, y la cual se aplica muy a menudo. Especficamente puede ser el caso en que nuestro bloque tenga algo interesante que mostrar en algn momento; pero en otros casos, no tenga nada til que decir. (Un ejemplo aqu sera el bloque "Actividades recientes", cuando no hayan actividades recientes. Sin embargo en ese caso el bloque escoge informarte explcitamente de la falta de actividades, lo cul es razonablemente til). Sera bueno, entonces que nuestro bloque "desapareciera" si no hay necesidad de mostrarlo. Ciertamente esto es posible, y la manera de hacerlo es asegurarse de que despus de que el mtodo get_content es llamado, el bloque est completamente desprovisto de contenido. Especficamente, "desprovisto de contenido" significa que tanto $this->content->text

como $this->content->footer son iguales al string vaco ("). Moodle hace este chequeo llamando al mtodo is_empty, y si el bloque est realmente vaco entonces no se mostrar en lo absoluto. Nota que el valor exacto del ttulo del bloque y la presencia o ausencia de un mtodo hide_headerno afecta este comportamiento. Un bloque es considerado vaco si no tiene contenido, sin importar nada ms.

Somos legin
Ahora mismo nuestro bloque es completamente configurable, tanto en el ttulo como en el contenido. Es tan verstil, de hecho, que podramos hacer casi cualquier cosa de l. Sera muy agradable poder agregar mltiples bloques de este tipo en un curso. Y, como puedes haber adivinado, hacerlo es tan simple como agregar otro pequeo mtodo a nuestra clase bloque:
function instance_allow_multiple() { return true; }

Esto le dice a Moodle que debera permitir cualquier cantidad de instancias del bloque SimpleHTML en cualquier curso. Despus de grabar los cambios en nuestro archivo, Moodle nos permite agregar mltiples copias del bloque a un curso inmediatamente sin ms! Hay un par de puntos interesantes ms para notar aqu. Primero que todo, incluso si un bloque permite mltiples instancias en la misma pgina, el administrador todava tiene la opcin de deshabilitar tal comportamiento. Esto puede ser definido para cada bloque desde la pgina Administration/Configuration/Blocks. Y finalmente, un bonito detalle es que tan pronto como definimos un mtodo instance_allow_multiple, el mtodo instance_allow_config que ya estaba definido se vuelve obsoleto. Moodle asume que si un bloque permite mltiples instancias de s mismo, estas instancias querrn ser configuradas (Qu sentido tienen mltiples instancias iguales en la misma pgina si son idnticas?) y automticamente les da un icono de "Edit". As, podemos remover todo el mtodo instance_allow_config sin ningn dao. Solo lo necesitaremos cuando no se permiten mltiples instancias del bloque.

Los efectos de la globalizacin

Configurar cada instancia del bloque con sus propios datos personales, es bastante bueno, pero algunas veces los administradores necesitan alguna manera de "tocar" todas las instancias de un bloque especfico a la vez. En el caso de nuestro bloque SimpleHTML, algunas configuraciones que tendran sentido aplicar a todas las instancias no son tan difciles de encontrar. Por ejemplo, podramos querer limitar el contenido de cada bloque para solo tantos caracteres, o podramos tener una configuracin que filtre el HTML del contenido del bloque, permitiendo solo texto puro en l. Grandioso, tal caracterstica no

har que nos ganemos un premio por nombrar nuestro bloque "SimpleHTML" pero algn administrador atormentado en alguna parte podra encontrarlo realmente til. Este tipo de configuracin se llama "configuracin global" y aplica solo a un tipo de bloque especfico (sin embargo, todas las instancias de ese tipo de bloque son afectadas). Implementar tal configuracin para nuestro bloque es bastante similar a implementar la configuracin de instancia. Veremos ahora la implementacin del segundo ejemplo, teniendo una configuracin que solo permite texto y no HTML en el contenido del bloque. Primero que todo, necesitamos decirle a Moodle que queremos que nuestro bloque tenga una configuracin global, qu sorpresa, agregando un pequeo mtodo a nuestra clase bloque:
function has_config() { return true; }

Entonces, necesitamos crear un archivo HTML que realmente muestre la pantalla de configuracin. En nuestro caso, solo mostraremos una caja de seleccin (N. del T. "checkbox") que diga "No permitir HTML en el contenido" (N. del T. "Do not allow HTML in the content") y un botn de "Enviar" (N. del T. "submit") . Vamos a crear el archivo /blocks/simplehtml/config_global.html el cul otra vez debe ser nombrado tal cual, y copia y pega lo siguiente dentro l:
<div style="text-align: center;"> <input type="hidden" name="block_simplehtml_strict" value="0" /> <input type="checkbox" name="block_simplehtml_strict" value="1" <?php if(!empty($CFG->block_simplehtml_strict)) echo 'checked="checked"'; ?> /> <?php print_string('donotallowhtml', 'block_simplehtml'); ?> <p><input type="submit" value="<?php print_string('savechanges'); ?>" /></p> </div>

La verdad en el nombre de nuestro bloque, luce bastante simple. Lo que hace es mostrar una caja de seleccin llamada block_simplehtml_strict y si la variable de configuracin de Moodle con el mismo nombre (esto es, $CFG->block_simplehtml_strict) existe y no esta vaca (lo que significa si no es igual a un string vaco, a cero, o a un falso booleano) muestra la opcin pre-seleccionada (reflejando el estado actual). Por qu seleccionamos la configuracin con el mismo nombre? Porque la implementacin por defecto de la configuracin global toma todas las variables que tenemos en nuestro formulario y las guarda como opciones de configuracin en Moodle con el mismo nombre. As, es buena prctica usar un nombre descriptivo y tambin uno que no tenga la posibilidad de tener conflictos con otra configuracin. block_simplehtml_strict claramente satisface los dos requerimientos. El lector astuto puede haber notado que en realidad tenemos dos campos de entrada llamados block_simplehtml_strict en nuestro archivo de configuracin. Uno est

escondido y su valor es siempre 0; el otro es la caja de seleccin y su valor es 1. Que pasa? Porqe tenerlos a los dos ah? Realmente, esto es un pequeo truco para hacer nuestro trabajo tan simple como sea posible. Los formularios HTML trabajan de esta manera: Si una caja de seleccin en un formulario no esta seleccionada, su nombre no aparece para nada en las variables que se le pasan a PHP cuando el formulario es enviado. Esto efectivamente significa que, cuando deseleccionemos una caja y hagamos clic en enviar, la variable no se le pasa a PHP en lo absoluto. As PHP no sabr que debe actualizar su valor a "0", y nuestra configuracin "strict" no podr ser desactivada de ninguna forma despus de que la activamos por primera vez. Definitivamente no es el comportamiento que deseamos. Sin embargo, cuando PHP maneja las variables recibidas de un formulario, son procesadas en el orden en que aparecen en el formulario. Si una variable aparece teniendo el mismo nombre que una variable ya procesada, el nuevo valor sobrescribe el antiguo. Aprovechando esto, nuestra lgica es la siguiente: La variable block_simplehtml_strict es puesta primero incondicionalmente en "0". Entonces, si la caja es seleccionada, es puesta en "1", sobrescribiendo el valor previo como se dijo. El resultado neto es que nuestra configuracin funciona como debera. Para redondear nuestra bolsa de trucos, note que el uso de if(!empty($CFG>block_simplehtml_strict)) en la prueba para "debera estar la caja seleccionada por defecto?" es bastante deliberado. La primera vez que se corre el script, la variable $CFG>block_simplehtml_strict no existir para nada. Despus de que este puesta por primera vez, su valor puede ser "0" "1". Dado que ambos "no seleccionado" (N. del T. nulo) y el string "0" son evaluados como vaco mientras que el string "1" no, nos las hemos arreglado para evitar cualquier advertencia de PHP considerando la variable vaca, y tendremos una agradable y humana representacin para sus dos posibles valores ("0" y "1"). Ahora que nos las hemos arreglado para introducir una cantidad respetable de trucos en unas pocas lneas de HTML, podemos discutir tambin una alternativa en caso de que los trucos no sean suficientes para la configuracin especfica que tenemos en mente. El mtodo config_save guarda los datos, y su implementacin por defecto es como sigue:
function config_save($data) { // Comportamiento por defecto: graba todas las variables como propiedades $CFG foreach ($data as $name => $value) { set_config($name, $value); } return true; }

Como se ve claramente, Moodle le pasa a este mtodo un arreglo asociativo $data el cual contiene todas las variables que vienen de nuestra pantalla de configuracin. Si queremos hacer el trabajo sin el truco de "esconder la variable con el mismo nombre" que usamos arriba, un modo de hacerlo sera sobrescribiendo este mtodo como sigue:

function config_save($data) { if(isset($data['block_simplehtml_strict'])) { set_config('block_simplehtml_strict', '1'); } else { set_config('block_simplehtml_strict', '0'); } return true; }

Bastante directo: si se nos pasa la variable "block_simplehtml_strict", entonces solo puede significar que el usuario la ha seleccionado, as que ponemos la variable de configuracin con el mismo nombre en "1". De otra manera, la ponemos en "0". Por supuesto esta versin necesitara ser actualizada si agregamos ms opciones de configuracin porque no responde a ellas como lo hace la implementacin por defecto. An as, es til saber como podemos sobrescribir la configuracin por defecto si esta no llena nuestras necesidades (por ejemplo, podemos no querer guardar las variables como parte de la configuracin de Moodle sino hacer otra cosa con ellas). As, ahora estamos en el punto donde sabemos si el bloque debe permitir etiquetas HTML en su contenido o no. Como hacemos que el bloque realmente respete esta configuarcin? Podramos decidir hacer una de estas cosas: ya sea tener nuestro bloque "limpio" de HTML desde la entrada antes de guardarlo en la configuracin de la instancia y entonces mostrarlo tal cual (el acercamiento "impaciente"); o guardar los datos "tal cual" y entonces limpiarlos cada vez justo antes de mostrarlos (el acercamiento "perezoso"). El acercamiento impaciente involucra hacer el trabajo una vez cuando se guarda la configuracin; el acercamiento perezoso implica hacer el trabajo cada vez que el bloque se muestra y as apunta a tener un peor desempeo. Desde aqu iremos con el acercamiento impaciente. Tal como hicimos antes al sobrescribir config_save, lo que necesitamos aqu es sobrescribir el mtodo instance_config_save el cual maneja la configuracin de instancia. La implementacin por defecto es como sigue:
function instance_config_save($data) { $data = stripslashes_recursive($data); $this->config = $data; return set_field('block_instance', 'configdata', base64_encode(serialize($data)), 'id', $this->instance->id); }

Esto puede parecer intimidante al principio (Qu es todo eso de stripslashes_recursive() y base64_encode() y serialize()?) pero no desfallezcas; no tenemos que tocar ninguna de estas. Solo agregaremos algn cdigo extra de validacin al principio y entonces le ordenaremos a Moodle que adicionalmente llame esta implementacin por defecto para hacer el almacenamiento real de los datos. Especficamente, agregaremos un mtodo a nuestra clase el cual ir como este:

function instance_config_save($data) { // Limpia los datos si tenemos que hacerlo global $CFG; if(!empty($CFG->block_simplehtml_strict)) { $data['text'] = strip_tags($data['text']); } // Y ahora remite a la implementacin por defecto definida en la clase padre return parent::instance_config_save($data); }

Finalmente! Ahora el administrador tiene el poder absoluto de la vida y la muerte sobre que tipo de contenido est permitido en nuestro bloque "SimpleHTML"! Absoluto? Bien... no exactamente. De hecho, si lo pensamos un momento, se har evidente que si en algn punto en el tiempo se permite HTML y algunos bloques han guardado su contenido con HTML, y el administrador cambia la configuracin a "off", esta solo evitara que los subsecuentes cambios incluyan HTML. Los bloques que ya tengan HTML en su contenido continuarn mostradolo! Siguiendo esa lnea de pensamiento, nuestra prxima parada es darse cuenta de que no tendramos este problema si hubiramos escogido el acercamiento perezoso hace un momento, porque en ese caso hubiramos "higienizado" (N. del T. filtrado, limpiado) cada contenido del bloque justo antes de que este fuera mostrado. La nica cosa que podemos hacer con la aproximacin impaciente es quitar todas las etiquetas del contenido de todas las instancias SimpleHTML tan pronto como el administrador ponga "HTML off"; pero incluso entonces, poniendo de nuevo "HTML on" no traer de regreso las etiquetas que quitamos. Del otro lado, la aproximacin perezosa puede ser ms lenta, pero es ms verstil; podemos escoger si quitar o conservar el HTML antes de mostrar el contenido, y no lo perdemos para nada si el administrador cambia de off y on de nuevo. No es la vida de un desarrollador simple y maravillosa? Vamos a dejar esta parte del tutorial con el obligatorio ejercicio para el lector: con el fin de tener el bloque SimpleHTML funcionando "correctamente", encuentra como fortalecer el acercamiento impaciente para quitar todas las etiquetas de la configuracin existente de todas las instancias de nuestro bloque, o regresa e implementa el acercamiento perezoso. (Pista: hazlo en el mtodo esarrollo de bloques#get_content|get_content]]) ACTUALIZANDO: Antes de la versin 1.5, el archivo config_global.html se llamaba simplemente config.html. Tambin, los mtodos config_save y config_print se llamaban handle_config y print_config respectivamente. Mejorar un bloque para que funcione con Moodle 1.5 implica actualizar estos aspectos; vea el Apndice B para ms informacin.

Apariencia bonita
Nuestro bloque es ahora completamente funcional, as que vamos a ver ahora algunos de los trucos que podemos usar para hacer su comportamiento personalizado en maneras un poco ms tiles.

Primero que todo, hay un par de maneras en que podemos ajustar el aspecto visual de nuestro bloque. Para comenzar, puede ser til crear un bloque que no muestre cabecera (ttulo) en lo absoluto. Puedes ver este efecto en accin en el bloque Descripcin del curso que viene con Moodle. Este comportamiento es logrado, lo adivinaste, agregando un mtodo ms a nuestra clase bloque:
function hide_header() { return true; }

Una nota ms aqu: no podemos simplemente poner un ttulo vaco en el mtodo del bloque init; es necesario que cada bloque tenga un ttulo nico, no vaco despus de que se llama init tal que Moodle pueda usarlos para diferenciar entre todos los bloques instalados. Otro ajuste que podemos querer hacer es ordenarle a nuestro bloque que tome un cierto ancho en la pantalla. Moodle maneja esto como un proceso de dos partes: primero, le pregunta a cada bloque por su ancho preferido y toma el nmero mximo como el valor deseado. Entonces, la pgina que esta siendo mostrada puede escoger usar este valor o, ms probablemente, acomodarlo en algn rango especfico de valores si no lo est ya. Esto significa que la configuracin del ancho es un convenio del mejor-resultado; tu bloque puede pedir un cierto ancho y Moodle tratar de drselo, pero no hay garanta de lo que sea el resultado final. Como ejemplo concreto, todos los formatos estndar de un curso de Moodle entregan cualquier pedido de ancho entre 180 y 210 pxeles, inclusive. Para decirle a Moodle nuestro ancho de bloque preferido, agregamos un mtodo ms a nuestra clase bloque:
function preferred_width() { // El valor preferido est en pixeles return 200; }

Esto har a nuestro bloque (y todos los otros bloques mostrados en el mismo lado de la pgina) un poco ms anchos que lo estndar. Finalmente, podemos afectar tambin algunas propiedades del HTML que ser usado para imprimir nuestro bloque. Cada bloque est contenido en un elemento <table>, dentro del cual est todo el HTML para ese bloque. Podemos ordenarle a Moodle que agregue atributos HTML con valores especficos a ese contenedor. Esto ser hecho para a) afectar directamente el resultado final (si decimos, assign bgcolor="black"), o b) darnos la libertad de personalizar el resultado final usando CSS (de hecho este es el comportamiento por defecto como veremos mas adelante). En nuestro caso el comportamiento por defecto de esta caracterstica le asignar a nuestro contenedor de bloque el atributo HTML de clase con el valor "sideblock block_simplehtml" (el prefijo "block_" seguido por el nombre de nuestro bloque, en minscula). Podemos usar

entonces esta clase para hacer selectores CSS en nuestro tema para alterar el estilo visual de nuestro bloque (por ejemplo, ".sideblock.block_simplehtml { border:1px black solid}"). Para cambiar el comportamiento por defecto, necesitaremos definir un mtodo el cual retorne un arreglo asociativo de nombres de atributo y valores. Por ejemplo la versin
function html_attributes() { return array( 'class' => 'sideblock block_'. $this->name(), 'onmouseover' =>'alert("Mouseover on our block!");' ); }

resultar en un evento mouseover agregado a nuestro bloque usando JavaScript, tal como si hubiramos escrito la parte onfiltered="alert(...)" nosotros mismos en HTML. Nota que realmente duplicamos la parte donde se define el atributo clase (queremos conservar eso, y puesto que sobrescribimos el comportamiento por defecto es nuestra responsabilidad emularlo si es requerido). Y el elegante toque final es que no definamos la clase al valor "block_simplehtml" en el cdigo sino que en vez de eso usemos el mtodo name para hacer que concuerde dinmicamente con el nombre de nuestro bloque.

Solo personal autorizado

No es difcil imaginar un bloque que es muy til en ciertas circunstancias pero que simplemente puede no tener sentido en otras. Un ejemplo podra ser el bloque "Actividades sociales" el cual es ciertamente til en un curso con el formato social, pero no es nada til en un curso con el formato de semanas. Debera haber alguna manera de permitir el uso de tales bloques solo cuando sean en realidad significativos, y no confundir a los usuarios si no lo son. Moodle nos permite declarar en cuales formatos de curso se le permite a cada bloque ser mostrado, y siempre impone estas restricciones como fueron definidas por los desarrolladores del bloque. La informacin es dada a Moodle como un arreglo asociativo estndar, con cada clave correspondiendo a un formato de pgina y definiendo un valor booleano (verdadero/falso) que declara si al bloque debera serle permitido aparecer en este formato de pgina. Note el uso deliberado del trmino pgina en vez de curso en el prrafo anterior. Esto es porque en Moodle 1.5 y en adelante, los bloques pueden ser mostrados en cualquier pgina que los soporte. El mejor ejemplo de tales pginas son las pginas de curso, pero no estamos restringidos a ellas. Por ejemplo, la pgina de vista de quiz (la primera que vemos cuando hacemos click en el nombre del quiz) tambin soporta bloques. Los nombres de formato que podemos usar se derivan del nombre del script que es usado realmente para mostrar esa pgina. Por ejemplo, cuando estamos viendo un curso, el script es /course/view.php (esto es evidente por la lnea de direccin del browser). As, el nombre del formato de esa pgina es course-view. Se sigue fcilmente que el nombre del formato

para una pgina de vista de quiz es mod-quiz-view. Sin embargo, esta rgla tiene unas pocas excepciones:
y y y

El nombre de formato para la pgina frontal de Moodle es site-index. El nombre de formato para los cursos en realidad no es simplemente course-view; es course-view-weeks', course-view-topics, etc. Incluso aunque no exite tal pgina, el nombre de formato all puede ser usado como una opcin para cubrir todas las posibiliades. Podemos incluir tantos nombres de formatos como queramos en nuestra definicin de formatos aplicables. Cada formato puede ser permitido o no, y hay tres reglas ms que ayudan a resolver la pregunta "Esta este bloque permitido en esta pgina, o no?": Los prefijos de un nombre de formato corresponder al nombre del formato; por ejemplo, mod corresponder a todos los mdulos de actividades. course-view corresponder a cualquier curso, sin importar el formato del curso. Y finalmente, site tambin corresponder a la pgina frontal (recuerda que el nombre de formato completo es site-index). Entre ms especializado sea un nombre que se corresponde con nuestro pgina, ms alta precedencia tiene cuando se decide si el bloque ser permitido. Por ejemplo, mod, mod-quiz y mod-quiz-view corresponden todas a la pgina de vista de quiz. Pero si todas estn presentes, mod-quiz-view tendr precedencia sobre las otras dos porque tiene una mejor correspondencia. El carcter * puede ser usado en lugar de cualquier palabra. Por ejemplo, mod y mod-* son equivalentes. En el momento que esto documento fue escrito, no hay ninguna razn para utilizar este "comodn de correspondencia" pero existe para un uso futuro. El orden en que aparezcan los nombres de formato no hace ninguna diferencia.

Todo lo anterior son suficientes para hacer parecer que la situacin suene compleja, as que vamos a ver algunos ejemplos especficos. Primero que todo, para que nuestro bloque aprezca solo en la pgina frontal de nuestro bloque, usaramos:
function applicable_formats() { return array('site' => true); }

Dado que all no est, el bloque no se le permite aparecer en ningn formato de curso, pero entonces site se define como true (N. del T verdadero), as que se le permite aparecer en la pgina frontal (recuerda que site corresponde a site-index porque es un prefijo). Por ejemplo, si queremos permitir que el bloque aparezca en todos los formatos de curso excepto social, y adems que no se permita sino en los cursos, usaramos:
function applicable_formats() { return array('course-view' => true, 'course-view-social' => false); }

Esta vez, primero permitimos que nuestro bloque aparezca en todos los cursos y luego no lo permitimos explicitamente en el formato social. Para nuestro ejemplo final, ms complicado, supongamos que un bloque puede ser mostrado en la pgina frontal, en los cursos (pero no en los cursos sociales) y tambin cuando estamos viendo cualquier mdulo de actividad, excepto quiz. Esto sera:
function applicable_formats() { return array('site-index' => true, 'course-view' => true, 'course-view-social' => false, 'mod' => true, 'mod-quiz' => false); }

No es difcil darse cuenta de que lo anterior logra el objetivo si recordamos que hay una poltica de "la mejor correspondencia" para determinar el resultado final. ACTUALIZANDO: Anterior a la versin 1.5, los bloques solo se permitan en los cursos (y en Moodle 1.4, en la pgina frontal). Tambin, las palabras claves usadas para describir los formatos de curso vlidos en ese tiempo fueron cambiados ligeramente y tienen que ser cambiados para permitir una arquitectura ms abierta. Vaya al [#appendix_b Apndice B] para ms informacin sobre los cambios que los bloques viejos tienen que hacer para conformar el nuevo estndar.

Listas e conos
En esta parte final de la gua, discutiremos someramente una habilidad adicional del sistema de bloques de Moodle, a saber la capacidad de crear muy fcilmente bloques que le muestren una lista de opciones al usuario. Esta lista es mostrada con un tmem por lnea, y una imagen adicional (cono) prxima al tem. Un ejemplo de tal bloque de lista es el bloque estndar de Moodle "admin", el cual ilustra todos los puntos discutidos en esta seccin. Como hemos visto, los bloques usan de dos propiedades $this->content]: "text" y "footer". El texto es mostrado tal cual en el contenido del bloque, y el pie de pgina (N. del T. footer) va abajo en un tamao de fuente ms pequeo. Los bloques de lista usan $this->content>footer en exactamente la misma manera, pero ignoran $this->content->text. En su lugar, Moodle espera que tales bloques definan otras dos propiedades cuando se llama al mtodo get_content. $this->content->items y $this->content->icons. $this>content->items debe ser un arreglo indexado numricamente que contiene elementos que representan el HTML de cada tem de la lista que va a ser mostrada. Usualmente estos tems sern etiquetas anclas de HTML los cuales dan un enlace a alguna pgina. $this>content->icons debe ser tambin un arreglo indexado numricamente con exactamente tantos tems como tiene $this->content->items. Cada uno de estos tems debe ser una etiqueta HTML <img> totalmente calificada, con los atributos "src", "height", "width" y "alt". Obviamente, tiene sentido conservar las imgenes pequeas y de un tamao uniforme.

Para decirle a Moodle que queremos un bloque de lista en lugar del estndar bloque de texto, necesitamos hacer un pequeo cambio en nuestra declaracin de la clase bloque. En lugar de extender la clase block_base nuestro bloque extender la clase block_list. Por ejemplo:
class block_my_menu extends block_list { // El mtodo init() no necesita cambiar para nada }

Adems de hacer este cambio, por supuesto debemos modificar tambin al mtodo [#method_get_content get_content] para construir la variable $this->content como se discuti arriba:
function get_content() { if ($this->content !== NULL) { return $this->content; } $this->content = new stdClass; $this->content->items = array(); $this->content->icons = array(); $this->content->footer = 'Pie de pgina aqu...'; $this->content->items[] = '<a href="some_file.php">Menu Option 1</a>'; $this->content->icons[] = '<img src="images/icons/1.gif" width="16" height="16" alt="" />'; // Agrega ms tems a la lista aqu return $this->content; }

Para resumir, si queremos crear un bloque de lista en vez de un bloque de texto, solo tenemos que cambiar la declaracin de la clase bloque y el mtodo get_content. Al agregar el mtodo mandatorio init como se dijo antes nos dar nuestro primer bloque de lista en todos los tiempos!

Apndice A: Referencia
En este apndice se discutir la clase base block_base de la cual se derivan todas las otras clases de bloque, y presenta todos y cada uno de los mtodos que pueden ser sobrescritos por los desarrolladores de bloques en detalle. Los mtodos que no deben ser sobrescritos estn referidos explcitamente como tales. Despus de leer este apndice, tendrs un entendimiento claro de cada mtodo que deberas o podras sobrescribir para darle funcionalidad a tu bloque. Los mtodos estn divididos en tres categoras: aquellos que puedes usar y sobrescribir en tu bloque, los que no puedes sobrescribir pero puedes usar, y aquellos mtodos internos que

no debes usar ni sobrescribir. En cada categora, los mtodos se presentan en orden alfabtico.

Mtodos que puedes usar y sobrescribir libremente

applicable_formats
function applicable_formats() { // Caso por defecto: el bloque puede ser usado en cursos y // en el index del sitio, pero no en las actividades return array('all' => true, 'mod' => false); }

Este mtodo te permite controlar a cuales formatos puede ser agregado tu bloque. Los formatos de pgina son formulados de la direccin completa que el script que es usado para mostrar la pgina. Debes retornar un arreglo con claves que sean los nombres de los formatos de pgina y los valores booleanos (true o false). Tu bloque solo ser permitido en aquellos formatos donde el valor es true. Ejemplos de nombres de formatos son: courseview, site-index (este es una excepcin, se refiere a la pgina frontal del sitio de Moodle), course-format-weeks (se refiere a un formato especfico de curso), mod-quiz (se refiere al mdulo quiz) y all (este ser usado para aquellos formatos a los que no te has referido explicitamente). Todas las reglas de correspondencia son:
y

Los prefijos de un nombre de formato corresponder al nombre del formato; por ejemplo, mod corresponder a todos los mdulos de actividades. course-view corresponder a cualquier curso, sin importar el formato del curso. Y finalmente, site tambin corresponder a la pgina frontal (recuerda que el nombre de formato completo es site-index). Entre ms especializado sea un nombre que se corresponde con nuestro pgina, ms alta precedencia tiene cuando se decide si el bloque ser permitido. Por ejemplo, mod, mod-quiz y mod-quiz-view corresponden todas a la pgina de vista de quiz. Pero si todas estn presentes, mod-quiz-view tendr precedencia sobre las otras dos porque tiene una mejor correspondencia. El carcter * puede ser usado en lugar de cualquier palabra. Por ejemplo, mod y mod-* son equivalentes. En el momento que esto documento fue escrito, no hay ninguna razn para utilizar este "comodn de correspondencia" pero existe para un uso fturo. El orden en que aparezcan los nombres de formato no hace ninguna diferencia.

config_print
function config_print() { // Comportamiento por defecto: muestra el archivo config_global.html // No necesitas sobrescribirlo si ests satisfecho con lo anterior if (!$this->has_config()) { return false; } global $CFG, $THEME; print_simple_box_start('center', '', $THEME->cellheading); include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html'); print_simple_box_end(); return true; }

Este mtodo te permite escoger como mostrar la pantalla de configuracin global para tu bloque. Esta es la pantalla que se le presenta al administrador cuando escoge "Configuracin..." para un bloque especfico. Sobrescrbelo si necesitas algo mucho ms complejo de lo que la implementacin por defecto te permite hacer. Sin embargo, mantn estos puntos en mente:
y

1. Si guardas tus opciones de configuracin en $CFG, probablemente necesitars usar $CFG global; antes de incluir cualquier pantalla de configuracin HTML. 2. Los elementos HTML <input> que incluyas en la salidas de los mtodos automticamente sern encerrados en un elemento <form> No tienes que preocuparte acerca de cuando y como este formulario es enviado; sin embargo debes proveer una manera de enviarlos (esto es un <input type="submit" />). Debes retornar un valor booleano que denote el xito o la falla de las acciones de tu mtodo. config_save
function config_save($data) { // Comportamiento por defecto: guarda todas las variables como propiedades $CFG // No necesitas sobrescribirlo si ests satisfecho con lo anterior foreach ($data as $name => $value) { set_config($name, $value); } return true; }

Este mtodo te permite sobrescribir el mecanismo de almacenamiento de los datos de configuracin. El argumento recibido es un arreglo asociativo, siendo las claves los nombres de la configuracin y los valores los valores de configuracin. La implementacin por defecto guarda todo como variables de Moodle $CFG.

Nota que $data no contendr todos los datos POST enviados puesto que Moodle agrega algunos datos escondidos al formulario para poder procesarlos. Sin embargo antes de llamar a este mtodo quita los campos escondidos de los datos recibidos y as cuando se llama este mtodo solo los datos de configuracin "real" se mantienen. Debes retornar un valor booleano que denote el xito o la falla de las acciones de tu mtodo. get_content
function get_content() { // Debe ser implementado por la clase derivada. return NULL; }

Al ser llamado, este mtodo debera poblar la variable [#variable_content $this->content] de tu bloque. Poblar la variable significa: YA SEA definir $this->content->text y $this->content->footer si tu bloque se deriva de block_base. Estos dos deben ser strings, y pueden contener cdigo HTML arbitrario. O definir $this->content->items, $this->content->icons y $this->content->footer si tu bloque se deriva de block_list. Los dos primeros deben ser arreglos numricamente indexados con exactamente el mismo nmero de elementos. $this->content->items es un arreglo de strings que pueden contener HTML arbitrario mientras $this->content->icons tambin debe contener strings, pero estos deben ser HTML <img> totalmente calificadas y nada ms. $this->content->footer es un string, como en el anterior. Si pones todas todas estas variables en su valor por defecto "vaco" (arreglos vacos para los arreglos y strings vacos para los strings), el bloque no se mostrar en lo absoluto excepto para los usuarios editores. Esta es una buena manera de que tu bloque se esconda a si mismo si no hay razn para mostrarlo. Antes de comenzar a poblar $this->content, tambin debes incluir un simple chequeo del cache. Si $this->content es exactamente igual a NULL, entonces proceda normalmente, mientras que si no lo es, retorne el valor existente en lugar de calcularlo una vez ms. Si no haces esto, Moodle sufrir una cada en su desempeo. En cualquier caso, tu mtodo debe retornar la variable $this->content completamente construida.

has_config

function has_config() { return false; }

Este mtodo debe retornar un valor booleano que denota si tu bloque quiere presentar una interfaz de configuracin al administrador del sitio o no. La configuracin que esta interfaz ofrece impactar a todas las instancias del bloque igualmente. Para realmente implementar la interfaz de configuracin, necesitars ya sea confiar en mtodo config_print por defecto, o sobrescribirlo. La gua completa contiene ms informacin al respecto. hide_header
function hide_header() { //Por defecto, false--> se muestra la cabecera return false; }

Este mtodo debe retornar un valor booleano que denota si nuestro bloque quiere esconder su cabecera (o ttulo). As, si lo sobrescribes para que retorne true (N. del T verdadero), tu bloque no mostrar un ttulo a menos que el usuario actual est en modo de edicin. html_attributes
function html_attributes() { // Caso por defecto: un id con la instancia y una clase con nuestro nombre en ella return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name()); }

Este mtodo debe retornar un arreglo asociativo de atributos HTML que le sern entregados al elemento contenedor de tu bloque cuando Moodle construya la salida HTML. No se realizara ninguna limpieza en el cdigo. Si quieres sobrescribir este mtodo, debes retornar los atributos por defecto tanto como los que tu agregaste. La forma recomendada de hacer esto es:
function html_attributes() { $attrs = parent::html_attributes(); // Agrega tus propios atributos aqu, por ejemplo: // $attrs['width'] = '50%'; return $attrs; }

init

function init() { $this->title = get_string('simplehtml', 'block_simplehtml'); $this->version = 2004111200; }

Este mtodo debe ser implementado para todos los bloques. Tiene que asignarles valores significativos a las variables objeto $this->title, y $this->version (la cual es usada por Moodle para realizar actualizaciones automticas cuando esten disponibles). No se espera un valor de retorno de este mtodo. instance_allow_config
function instance_allow_config() { return false; }

Este mtodo debe retornar un valor booleano. True indica que tu bloque quiere tener una configuracin por instancia, mientras false significa que no. Si quieres implementar la configuracin de instancia, necesitars algunos pasos adicionales aparte de sobrescribir este mtodo; refirete a la gua completa para ms informacin. El valor retornado por este mtodo es irrelevante si instance_allow_multiple retorna verdadero; se asume que si quieres mltiples instancias entonces cada una necesita su propia configuracin. instance_allow_multiple
function instance_allow_multiple() { // Vas a permitir mltiples instancias de cada bloque? // Si s, entonces se asume que el bloque USAR configuracin por instancia return false; }

Este mtodo debe retornar un valor booleano, indicando si quieres permitir mltiples instancias de este bloque en una misma pgina o no. Si permites mltiples instancias, se asume que dars configuracin por instancia para el bloque. As que necesitars algunos pasos adicionales aparte de sobrescribir este mtodo; refirete a la gua completa para ms informacin.

instance_config_print

function instance_config_print() { // Comportamiento por defecto: muestra el archivo config_instance.html // No necesitas sobrescribirlo si ests satisfecho con lo anterior if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) { return false; } global $CFG, $THEME; if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) { print_simple_box_start('center', '', $THEME->cellheading); include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html'); print_simple_box_end(); } else { notice(get_string('blockconfigbad'), str_replace('blockaction=', 'dummy=', qualified_me())); } return true; }

Este mtodo te permite seleccionar como mostrar la pantalla de configuracin de instancia para tu bloque. Sobrescribelo si necesitas algo mucho ms complejo de lo que la configuracin por defecto te permite hacer. Ten en mente que cualquier cosa que pongas de salida de config_print, ser encapsulada en un formulario HTML automticamente. Solo necesitas tener una forma de enviar el formulario. Debes retornar un valor booleano que denote el xito o la falla de las acciones de tu mtodo. instance_config_save
function instance_config_save($data) { $data = stripslashes_recursive($data); $this->config = $data; return set_field('block_instance', 'configdata', base64_encode(serialize($data)), 'id', $this->instance->id); }

Este mtodo te permite sobrescribir el mtodo de almacenamiento para los datos de configuracin de tu instancia. El argumento recibido es un arreglo asociativo, siendo las claves los nombres de configuracin y los valores los valores de configuracin. La configuracin debe ser almacenada en el campo "configdata" del registro en la base de datos tal que Moodle pueda autocargarlos cuando tu bloque es construido. Sin embargo an puedes querer sobrescribir este mtodo si necesitas hacer algo aparte de guardar datos. En ese caso, debes hacer el procesamiento de datos que quieras y luego llamar a

parent::instance_config_save($data) con tu nuevo arreglo $data. Esto evitar que nuestro bloque se rompa si la implementacin por defecto de instance_config_save cambia en el futuro. Nota que $data no contendr todos los datos POST enviados puesto que Moodle agrega algunos datos escondidos al formulario para poder procesarlos. Sin embargo, antes de llamar a este mtodo quita los campos escondidos de los datos recibidos y as cuando se llama este mtodo solo los datos de configuracin "real" se mantienen. Si quieres actualizar la copia guardada de los datos de configuracin mientras corre (por ejemplo para mantener algunos cambios que hiciste programticamente), no debes usar este mtodo. El procedimiento correcto para tal propsito es llamar a instance_config_commit. Debes retornar un valor booleano que denote el xito o la falla de las acciones de tu mtodo. preferred_width
function preferred_width() { // Caso por defecto: el bloque quiere un ancho de 180 pixeles return 180; }

Este mtodo debe retornar un valor entero, el cul es el nmero de pxeles de ancho que tu bloque quiere tomar cuando sea mostrado. Moodle tratar de respetar tu peticin, pero esto realmente depende de la implementacin del formato de pgina en la que tu bloque est siendo mostrado asi que no hay garantas. Realmente puedes tener exactamente lo quieres o cualquier otro ancho que el formato decida darte, aunque obviamente se har un esfuerzo por acomodar tu bloque. En este punto la principal lgica de despliegue, es posicionar el mximo ancho pedido por los bloques que van a ser mostrados, limitndolos tanto por encima como por debajo para evitar que un bloque con mal comportamiento dae el formato. refresh_content
function refresh_content() { // Nada especial aqu, depende de content() $this->content = NULL; return $this->get_content(); }

Este mtodo debe hacer que tu bloque recalcule su contenido inmediatamente. Si sigues los lineamientos para get_content, los cuales dicen que hay que respetar valor actual del contenido a menos que este sea NULL, entonces la implementacin por defecto har su trabajo bastante bien. Debes retornar el nuevo valor de $this->content despus de refrescarlo.

specialization
function specialization() { // Solo para asegurarse de que este mtodo existe. }

Este mtodo es llamado automticamente por el framework inmediatamente despus de que tus datos de instancia (los cules incluyen el tipo de pgina, el id y todos los datos de configuracin de la instancia) son cargados de la base de datos. Si hay algo que necesites hacer tan pronto como estos datos estn disponibles y que no puede ser hecho antes, debes sobrescribir este mtodo. Los datos de instancia estarn disponibles en las variables $this->instance y $this->config. Este mtodo no debe retornar nada en absoluto.

Mtodos que no debes sobrescribir pero puedes querer usar:

instance_config_commit
function instance_config_commit() { return set_field('block_instance', 'configdata', base64_encode(serialize($this>config)), 'id', $this->instance->id); }

Este mtodo guarda el contenido acutal de $this->config en la base de datos. si necesitas hacer un cambio en la confuguracin de una instancia de bloque mientras est corriendo (y no a travs del camino usual de dejar al usuario cambiarlo), solo haz los cambios que quieres en $this->config y luego llama este mtodo. get_content_type
function get_content_type() { return $this->content_type; }

Este mtodo retorna el valor de $this->content_type, y es la manera preferida de acceder a esta variable. Se garantiza que siempre funcionar, ahora y siempre. No se recomienda acceder directamente a la variable; cambios futuros en las librerias podran romper la compatibilidad con el cdigo que hace esto.

get_title
function get_title() {

return $this->title; }

Este mtodo retorna el valor de $this->title, y es la manera preferida de acceder a esta variable. Se garantiza que siempre funcionar, ahora y siempre. No se recomienda acceder directamente a la variable; cambios futuros en las librerias podran romper la compatibilidad con el cdigo que hace esto. get_version
function get_version() { return $this->version; }

Este mtodo retorna el valor de $this->version, y es la manera preferida de acceder a esta variable. Se garantiza que siempre funcionar, ahora y siempre. No se recomienda acceder directamente a la variable; cambios futuros en las librerias podran romper la compatibilidad con el cdigo que hace esto. is_empty Para bloques que extienden la clase block_base:
function is_empty() { $this->get_content(); return(empty($this->content->text) && empty($this->content->footer)); }

Para bloques que extienden la clase block_list:

function is_empty() { $this->get_content(); return (empty($this->content->items) && empty($this->content->footer)); }

Este mtodo retorna un valor booleano verdadero/falso, dependiendo de si el bloque tiene cualquier contenido para mostrar. Los bloques sin contenido no son mostrados por el framework.

name
function name() {

static $myname; if ($myname === NULL) { $myname = strtolower(get_class($this)); $myname = substr($myname, strpos($myname, '_') + 1); } return $myname; }

Este mtodo retorna el nombre interno de tu bloque dentro de Moodle, sin el prefijo block_. Obtener el nombre del objeto bloque es til algunas veces porque puede ser usado para escribir cdigo que no conoce el nombre del bloque (y as es ms genrico y reusable). Para un ejemplo de esta tcnica, vea el mtodo config_print.

Mtodos que no debes sobrescribir ni usar para nada:

_self_test Este es un mtodo privado, no se da descripcin. _add_edit_controls Este es un mtodo privado, no se da descripcin. _load_instance Este es un mtodo privado, no se da descripcin. _print_block Este es un mtodo privado, no se da descripcin. _print_shadow Este es un mtodo privado, no se da descripcin. La clase block_base tambin tiene unas pocas variables miembros estndar que son manipuladas por sus mtodos. Estas variables, el propsito de cada una y el tipo de datos que se espera guarde son explicadas en la prxima seccin de este apndice.

Variables de clase:

$this->config Esta variable guarda todos los datos especializados de configuracin de instancia que han sido dadas para esta instancia de bloque especfica (objeto). Es un objeto de tipo stdClass, con variables miembros que corrresponden directamente con los elementos HTML <input> en el archivo de bloque config_instance.html. La variable es inicializada justo despus de que se construye el objeto bloque, inmediatamente antes de que [#method_specialization specialization] sea llamado por el objeto. Es posible que el bloque no tenga configuracin de instancia, en cuyo caso la variable ser NULL. Es obvio que hay una relacin directa entre esta variable y el campo configdata en la tabla mdl_block_instance. Sin embargo, se recomienda fuertemente que te refrenes de acceder por ti msmo el campo configdata. Si es absolutamente necesario que actualices su valor en cualquier momento, se recomienda que llames al mtodo instance_config_commit para hacer el trabajo real. $this->content_type Esta variable le dice a Moodle sobre que tipo de contenido debe asumir que tenga el bloque y es usada para diferenciar los bloques de texto de los bloques de lista. Es esencial que tenga un valor significativo, ya que Moodle depende de esto para mostrar el bloque correctamente en la pantalla. Consecuentemente, esta variable est cercanamente relacionada con la variable $this->content. Se espera que la variable tenga un valor vlido despus de el framework llama el mtodo init para cada bloque. Los nicos valores vlidos para esta variable son las dos constantes llamadas BLOCK_TYPE_TEXT y BLOCK_TYPE_LIST. $this->content Esta variable guarda el contenido real que se muestra dentro de cada bloque. Los valores vlidos son o NULL, o un objeto de clase stdClass, el cual debe tener variables miembros especficos como se explica ms abajo. Normalmente, comienza su vida con un valor de NULL y queda completamente construido (esto es, un objeto) cuando se llama get_content. Despus de que estn completamente contruido, se espera que este objeto tenga ciertas propiedades, dependiendo del valor de $this->content_type. Especficamente:

Si $this->content_type es BLOCK_TYPE_TEXT, entonces se espera que $this>content tenga los siguientes miembros variables:

text Este es un string de longitud y contenido arbitrario. Se muestra dentro del rea del bloque, y puede contener HTML.

footer Este es un string de longitud y contenido arbitrario. Se muestra debajo del texto, usando un tamao de fuente pequeo. Tambin puede contener HTML

Si $this->content_type es BLOCK_TYPE_LIST, entonces se espera que $this>content tenga los siguientes miembros variables: o items Este es un arreglo de strings indexado numricamente, los cuales guardan un ttulo por cada tem en la lista que ser mostrada en el rea del bloque. Dado que usualmente tales listas funcionan como mens, el ttulo para cada tem normalmente es una etiqueta HTML <a> completamente calificada.
o

icons Este es un arreglo de strings indexado numricamente el cual representa las imgenes mostradas antes de cada tem de la lista. Se sigue de aqu que debe tener exactamente el mismo nmero de elementos que el miembro variable items. Cada item en este arreglo debe ser una etiqueta HTML <img> completamente calificada.

footer Este es un string de longitud y contenido arbitrario. Se muestra debajo del texto, usando un tamao de fuente pequeo. Tambin puede contener HTML.

$this->instance Este miembro variable guarda toda la informacin especfica que diferencia una instancia de bloque (esto es, el objeto PHP que lo incorpora) de otra. Es un objeto del tipo stdClass recuperado al llamar get_record en la tabla mdl_block_instance. Sus miembros variables, entonces, se corresponden directamente con los campos en esa tabla. Se inicializa inmediatamente despus de que el mismo objeto bloque es contruido. $this->title Esta variable es un string que contiene el nombre entendible por los humanos del bloque. Es usado para referirse a bloques de ese tipo a travs de Moodle, por ejemplo en la pantanlla del administrador de configuracin del bloque y en el men de aadir bloques en

la edicin del profesor. Tambin es el ttulo que se pone cuando el bloque es mostrado en la pantalla, aunque los bloques pueden especfcamente cambiar su ttulo por algo ms si lo desean (ver abajo). Se espera que la variable tenga un valor vlido despus de que el framework llama el mtodo init para cada objeto. En el caso de los bloques que pueden querer configurar sus ttulos dinmicamente a travs de la configuracin de instancia, es un esencial dar un ttulo vlido dentro de init. Este puede ser sobrescrito cuando el mtodo specialization es llamado por el framework:
function specialization() { // En este punto, $this->instance y $this->config estn disponibles // para su uso. Ahora podemos cambiar lo que sea que queramos. $this->title = $this->config->variable_holding_the_title; }

$this->version Esta variable debe guardar el nmero de la versin del bloque en la forma YYYYMMDDXX, por convencin a travs de Moodle. El nmero de versin es usado por Moodle para detectar cuando ha sido mejorado un bloque y consecuentemente se necesita correr el cdigo de actualizacin del bloque para llevar la versin "vieja" de los datos del bloque al da. Se espera que la variable tenga un valor vlido despus de que el mtodo init es llamado para cada bloque. La mayora de los bloques no guardan datos propios complejos en la base de datos de la manera que lo hacen los mdulos, as que en la mayora de los casos realmente no pasa nada durante la actualizacin de la versin de un bloque. Sin embargo, el nmero de la versin se muestra en la interfaz de administracin de los bloques. As que es buena prctica cambiar el nmero de versin de tu bloque cuando este gana nuevas funcionalidades o se le hacen correcciones de bugs importantes, para permitirles a los adminsitradores de sitios identificar fcilmente la versin exacta del bloque con la cual estn trabajando. Apareciendo a travs del cdigo relacionado con la API de bloque, hay un nmero de constantes predefinidas que son usadas para evitar el uso de "numeros mgicos" en el cdigo. Estas constantes son:

Constantes nombradas:
BLOCK_TYPE_LIST Este es uno de los dos valores vlidos para el miembro variable $this->content_type de cada bloque. Su valor especfica los requerimientos exactos que Moodle tendr para $this>content. BLOCK_TYPE_TEXT

Este es uno de los dos valores vlidos para el miembro variable $this->content_type de cada bloque. Su valor especfica los requerimientos exactos que Moodle tendr para $this>content.

Apndice B: Diferencias con la API de los bloques para versiones anteriores a Moodle 1.5
Este apndice discutir que cambios fueron introducidos en la API de los bloques de Moodle 1.5 y que necesitan hacer los desarrolladores para actualizar sus bloques para que sean completamente compatibles con Moodle 1.5. Desafortunadamente, con estos cambios se ha roto la compatibilidad hacia atrs; esto significa que los bloques de Moodle 1.4 no funcionarn nunca con 1.5 y viceversa.

Cambiaron las convenciones de nombres

En Moodle 1.4, se requera que todas las clases bloque tuvieran un nombre como CourseBlock_algo y la clase base de la cual se derivaban era MoodleBlock. Esto cambio en Moodle 1.5, para poner las convenciones de nombres en lnea con otros aspectos orientados a objetos de Moodle (por ejemplo hay clases enrolment_base, resource_base, etc). Las nuevas clases deben entonces llamarse block_algo y derivarse de block_base. Esto significa que con el objeto de hacer un bloque compatible con Moodle 1.5, necesitas cambiar la definicion de clase de
class CourseBlock_online_users extends MoodleBlock { ... }

A
class block_online_users extends block_base { ... }

Una exepcin a lo anterior es el caso especial donde se quiere que el bloque muestre una lista de tems en lugar de texto arbitrario; en ese caso la clase bloque debe derviarse de la clase block_list, as:
class block_admin extends block_list { ... }

Constructor versus init()

En Moodle 1.4, en cada clase de bloque era mandatorio definir un constructor el cual aceptaba un registro de datos como argumento (el ejemplo es del bloque real de Usuarios online):
function CourseBlock_online_users ($course) { $this->title = get_string('blockname','block_online_users'); $this->content_type = BLOCK_TYPE_TEXT; $this->course = $course; $this->version = 2004052700; }

En contraste, Moodle 1.5 se olvida del constructor y te pide que definas un mtodo init() que no recibe argumentos:
function init() { $this->title = get_string('blockname','block_online_users'); $this->version = 2004111600; }

Por supuesto, esto te deja sin acceso al objeto $course, el cual puedes necesitar realmente. Puesto que probablemente se necesitar dentro de get_content, la manera de recuperarlo es usando este cdigo:
$course = get_record('course', 'id', $this->instance->pageid);

Si vas a necesitar acceso a $course desde otros mtodos aparte de get_content, puedes traer el objeto $course dentro del mtodo specialization y guardarlo como una variable de clase para su uso posterior, con el fin de evitar realizar la misma consulta varias veces:
function specialization() { $this->course = get_record('course', 'id', $this->instance>pageid); }

Bloques con configuracin

En Moodle 1.4, los bloques solo podan tener lo que ahora (en Moodle 1.5) se llama opciones de "configuracin global", para diferenciarlo de las nuevas opciones de "configuracin de instancia". Si tu bloque tiene soporte para configuracin, necesitas hacer esto: 1. Renombra tu archivo config.html como config_global.html. 2. Edita el archivo recientemente renombrado y quita completamente la etiqueta <form> (Moodle ahora envuelve tu configuracin en un formulario automticamente). 3. Si estas usando cualquier etiqueta HTML <input> diferentes a aquellas que afectan directamente tu configuracin (por ejemplo, "sesskey"), QUITALAS tambin (Moodle las agregar automticamente si se necesitan)./li>

4. Si has sobrescrito print_config, renombra tu mtodo como config_print. 5. Si has sobrescrito handle_config, renombra tu mtodo como config_save.

Bloques con formatos aplicables personalizados

La forma correcta de especificar los formatos en que quieres permitir o no que exista tu bloque ha sido re-hecha para Moodle1.5 para tomar en cuenta que los los bloques ya no estan restringidos solo a los cursos. Para que los bloques mantengan el comportamiento esperado, debes cambiar estos nombres de formato (claves de arreglos en el valor que retorna applicable_formats) si son usados en tu bloque:
y y y

social debe convertirse en course-view-social topics debe convertirse en course-view-topics weeks debe convertirse en course-view-weeks

Tambin debes tener en cuenta que ahora est la posibilidad de que los bloques se muestren tambin en otras pginas, como la pgina introductoria que los usuarios ven cuando entran en un mdulo de actividad. Puedes entonces necesitar hacer la especificacin para los formatos aplicables ms restrictiva para mantener a tu bloque fuera de las pginas donde no se supone que est. Tambin hay cambios sutiles en la manera en que la decisin final de permitir o no un bloque se hace. Para detalles tcnicos refirete a la definicin de applicable_formats, y para un ejemplo ms extenso lee la seccin dedicada a este asunto. Esto es todo; ahora tu bloque estar listo para usarse en Moodle 1.5!