En esta segunda parte ya entramos en materia creando nuestros propios plugin. Entre los ejemplos que ofrecemos, verán uno muy interesante, ya que agregaremos campos personalizados al formulario de registro al sitio, tema que siempre nos ha interesado. Haciendo de esta forma a las extensiones flexibles y potentes.

Antes de comenzar, es recomendable que lea la primera parte de esta serie, para que llegue con algunos conocimientos necesarios a tener en cuenta para desarrollar su propio plugin.

Al final del artículo ofrecemos en un archivo comprimido los tres ejemplo que verán a continuación, listos para su instalación. !Comencemos entonces¡

Primer Ejemplo

Ahora vamos a pasar un rato agradable. Vamos a crear un plugin sencillo que utilice el evento llamado onBeforeCompileHead. Este evento nos permite modificar el elemento head del HTML de la página justo antes de que se muestre. Así que podemos utilizar este evento para modificar cualquier elemento HTML que va en el head, incluyendo metadatos, títulos, enlaces, o script.

¿Cómo se va a ejecutar?

El evento onBeforeCompileHead se activa en el método fetchHead() de JDocumentRendererHtml (libraries/joomla/document/html/renderer/head.php). Este método lee la información del elemento head desde el objeto document y lo imprime en el búfer en formato de texto HTML. El siguiente código activa el evento:

// Trigger the onBeforeCompileHead event
$app = JFactory::getApplication();
$app->triggerEvent('onBeforeCompileHead');

¿Qué hace?

Si nos fijamos en el HTML del código fuente de la página principal de un sitio con los datos de muestra instalados, vemos una serie de metadatos dentro del elemento head:

<meta name="robots" content="index, follow" />
<meta name="keywords" content="My keywords." />
<meta name="rights" content="My rights." />
<meta name="language" content="en-GB" />

Nuestro plugin será sencillo. Agrega un atributo "revised" al elemento meta, basado en un parámetro que el usuario insertará a través del plugin. Por ejemplo, la salida de nuestro plugin podría ser como sigue:

<meta name="revised" content="Carlos Rodríguez, 10 Marzo 2013" />

donde el atributo “content” es el texto escrito en los parámetro del plugin.

Para ello, tendremos que entender cómo el objeto JDocumentHTML almacena los datos para el elemento HTML head. Vamos a hacer un poco de investigación. En el método fetchHead() de la clase JDocumentRendererHead que se dispara en el evento onBeforeCompileHead , vemos que tenemos una variable $document en los parámetros del método. Este es un objeto JDocumentHTML, que tiene un método denominado getHeadData() que devuelve los datos de la cabecera del documento o página. Si ponemos el comando:

var_dump($document->getHeadData());

en el método fetchHead() de esa clase (por ejemplo, justo antes del código que activa el evento) y luego vamos a la página principal del sitio, vamos a ver un volcado largo de la salida del getHeadData(), parte de los cuales se muestra a continuación.

array
  'title' => string 'Home' (length=4)
  'description' => string 'My description.' (length=15)
  'link' => string '' (length=0)
  'metaTags' =>
    array
      'http-equiv' =>
      array
        'content-type' => string 'text/html' (length=9)
        'standard' =>
        array
          'robots' => string 'index, follow' (length=13)
          'keywords' => string 'My keywords.' (length=12)
          'rights' => string 'My rights.' (length=10)
          'language' => string 'en-GB' (length=5)

Si lo comparamos con el código HTML fuente mostrado anteriormente, vemos que los elementos meta con atributos name se almacena en el objeto como un array asociativo almacenado en el elemento estándar en el interior del elemento metaTags. El valor del atributo name es la clave del array asociativo (por ejemplo, "robots"), y el valor del atributo content es el valor del array asociativo (por ejemplo, "index, follow").

Queremos que nuestro plugin añada un nuevo elemento meta con el atributo name de "revised" y el valor debe ser la opción indicada en los parámetros del plugin por el usuario. Queremos mantener todos los elementos meta existentes y añadir este como uno nuevo.

Nuestro código va a funcionar de la siguiente manera:

1. Leer los datos actuales de la cabecera del documento. Esto será un array como el que se mostró anteriormente.
2. Agregar un elemento al array asociativo que se almacena dentro del elemento estándar del array dentro del elemento metaTags . La clave para este array será "revised" y los datos será el valor introducido por el usuario en los parámetros.
3. Escribir de nuevo el array modificado del objeto document utilizando setHeaderData() (que es la imagen espejo del método getHeaderData()).
4. Por último, sólo queremos hacer esto si hay algún valor en el parámetro del plugin. Si está vacío, no hacemos nada.

Desarrollo del Plugin

1. Crear la carpeta del plugin. Vamos a llamar al plugin "mymeta", por lo que tenemos que crear una carpeta llamada plugins/system/mymeta en los archivos de nuestro sitio.
2. Para ahorrar tener que escribir, podemos copiar algunos archivos existentes y simplemente editar. Copie los archivos p3p.php y p3p.xml de la carpeta plugins/system/p3p a la nueva carpeta plugins/system/mymeta. A continuación, cambie el nombre del p3p.php y p3p.xml a mymeta.php y mymeta.xml.
3. Edite el archivo mymeta.xml como se muestra más abajo.

<?xml version="1.0" encoding="utf-8"?>
  <extension version="2.5" type="plugin" group="system">
  <name>Mi Meta Plugin</name>
  <author>Carlos Rodríguez</author>
  <creationDate>Marzo 2013</creationDate>
  <copyright>Copyright (C) 2013 Carlos Rodríguez. All rights reserved.</copyright>
  <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
  <authorEmail>E-mail</authorEmail>
  <authorUrl>URL</authorUrl>
  <version>2.5.0</version>
  <description>Mi Meta Plugin Descripción</description>

  <files>
    <filename plugin="mymeta">mymeta.php</filename>
  </files>
  <config>
    <fields name="params">
      <fieldset name="basic">
        <field name="revised" type="text"
          description="Texto para el atributo content del meta revised.
          label="Revised Content"
          default=""
          size="50"
      />
      </fieldset>
    </fields>
  </config>
</extension>

4. Llegados a este punto, tenemos el código para entrar el parámetro para nuestro plugin. Lo siguiente que necesitamos es escribir realmente   el plugin. Para ello abrimos nuestro archivo mymeta.php, y colocamos lo siguiente:

<?php
/**
 * @copyright Copyright (C) 2012 Carlos Rodríguez.
 * @license GNU General Public License version 2 or later; see LICENSE.txt
 */
// No permitir el acceso directo
defined('_JEXEC') or die;
jimport('joomla.plugin.plugin');
/**
 * Plugin "System" de ejemplo
 */
class plgSystemMyMeta extends JPlugin
{
  function onBeforeCompileHead()
  {
    if ($this->params->get('revised')) {
    $document = JFactory::getDocument();
    $headData = $document->getHeadData();
    $headData['metaTags']['standard']['revised'] =
    $this->params->get('revised');
    $document->setHeadData($headData); }
  }
}

Hemos cambiado el nombre de la clase a plugSystemMyMeta y nombró la función onBeforeCompileHead, que es el mismo evento que vamos a utilizar para el plugin. El código es simple, una vez que entienda la estructura del array del método getHeadData().

En primer lugar, comprobar si hay algo en el parámetro "revised" de nuestro plugin. Si no, nos saltamos todo el proceso.

Si existe algo en este parámetro, se procede. Obtenemos el objeto document y luego guardamos el resultado de getHeadData() en $headData.

Creamos un nuevo elemento para el array asociativo denominado "revised" y establecemos su valor con el valor del parámetro.

5. En este punto, nuestro plugin está completo y listo para funcionar. Sin embargo, nuestra instalación de Joomla no lo sabe todavía. Los archivos se encuentran en las carpetas correctas, pero no hay ninguna fila en la tabla # __extensions para el plugin. Así que, vaya a la administración de tu sitio Joomla, a Extensiones → Gestor de Extensiones y seleccione la pestaña Descubrir. A continuación, haga clic en el icono en la barra de herramientas Descubrir. Con esto debes ver algo similar a:

6. Ahora haga clic en la casilla de verificación de la izquierda y luego haga clic en el icono de instalación en la barra de herramientas. Un mensaje debe mostrar que indica que el plugin se ha instalado correctamente.

La instalación de la extensión crea una fila en la tabla # __extensions la cual almacena información sobre el plugin. Joomla sólo "conoce" las extensiones que están en esta tabla. El proceso de descubrimiento, busca extensiones que se encuentran en el sistema de archivos y no en la tabla # __extensions.

La forma normal de instalar una extensión es de un archivo de almacenamiento creado para ese propósito. En el siguiente ejemplo, se crea un plugin y creamos un archivo comprimido para que pueda ser instalado.

Ahora que nuestro plugin está instalado, vamos a probarlo. Vaya a Extensiones → Gestor de Plugins y filtrar por plugins de “system”. Verás listado en esa lista el plugin “Mi Meta Plugin”. Al hacer clic sobre el debe mostrar una pantalla como se muestra a continuación:

Cambia el plugin ha “Habilitado”, introduzca algo en “Revised Content”, a continuación guarde, y vaya a la página de inicio del sitio. En el explorador, seleccione la opción para mostrar el código HTML fuente de la página. Debería ver algo como lo siguiente. La línea añadida por el plugin está resaltada.

<meta name="robots" content="index, follow" />
<meta name="keywords" content="My keywords." />
<meta name="rights" content="My rights." />
<meta name="language" content="en-GB" />
<meta name="revised" content="Carlos Rodríguez, 10 Marzo 2013" />
<meta name="description" content="My description." />

Como prueba final, vuelve a editar el plugin y deja en blanco el valor de “Revised Content”. A continuación, vuelve a mostrar la página de inicio y comprueba el código fuente. Ahora no debería haber ningún metaTag con el nombre "revised", ya que no hay contenido para este tag.

Si damos un paso atrás por un momento, podemos apreciar lo fácil que era para nosotros hacer este cambio. Simplemente añade dos nuevos archivos al sistema y editar unas pocas líneas de código. Con esta pequeña cantidad de trabajo, hemos sido capaces de cambiar el contenido del elemento del head en todas las páginas de nuestro sitio.

Segundo Ejemplo

En nuestro segundo ejemplo, crearemos un plugin para la validación de dos nuevos campos insertados en el formulario de registro de Joomla. Se preguntaran ¿Qué campos?. Pues los campos nuevos son estos:

Estos campos los podemos crear haciendo uso de la técnica “override” de Joomla. Para lograrlo, vamos a la carpeta templates/mi_plantilla/html de nuestra plantilla en uso (si no existe, la creamos), en mi caso estoy usando la plantilla propia de Joomla beez_20. Dentro creamos una carpeta y una subcarpeta como les indico a continuación: com_users/registration/. Luego, copiamos dentro el archivo default.php que se encuentra en mi_sitio/components/com_users/views/registration/tmpl/, y lo abrimos para editarlo.

Verán que aproximadamente, a partir de la línea 24 a la línea 46 es la apertura y cierre respectivamente de una sentencia if. Pues insertaremos nuestro código override justo antes del cierre de la sentencia. Les debe de quedar de la siguiente forma:

.
.
.
<?php if (count($fields)):?>
  <fieldset>
    <?php if (isset($fieldset->label)):// If the fieldset has a label set, display it as the legend.?>
      <legend><?php echo JText::_($fieldset->label);?></legend>
    <?php endif;?>
    <dl>
      <?php foreach($fields as $field):// Iterate through the fields in the set and display them.?>
        <?php if ($field->hidden):// If the field is hidden, just display the input.?>
          <?php echo $field->input;?>
        <?php else:?>
          <dt>
            <?php echo $field->label; ?>
            <?php if (!$field->required && $field->type!='Spacer'): ?>
              <span class="optional"><?php echo JText::_('COM_USERS_OPTIONAL'); ?></span>
            <?php endif; ?>
          </dt>
          <dd><?php echo ($field->type!='Spacer') ? $field->input : "&#160;"; ?></dd>
        <?php endif;?>
      <?php endforeach;?>
    </dl>
  </fieldset>

  <fieldset>

    <legend><?php echo JText::_('Términos de Servicio')?></legend>
    <p><input type="checkbox" name="tos_agree" /> 
      <?php echo JText::_('Estoy de acuerdo con los términos del servicio de este sitio.')?> 
    </p>

    <p><input type="checkbox" name = "old_enough" />
      <?php echo JText::_('Tengo por lo menos 18 años de edad.')?> 
    </p>

  </fieldset>

 <?php endif;?>

.
.
.

<-Nota: Cuando se envía un formulario PHP con el método POST, los valores del formulario se guardan en la variable súper global de PHP llamada $ _REQUEST. Los valores se guardan en una matriz asociativa, donde la clave de la matriz es el atributo name de cada elemento input . Si un elemento input no tiene atributo name, no son salvados. En consecuencia, tenemos que añadir atributos name a los dos campos “check box”. En el código anterior, llamamos al primero tos_agree y al segundo old_enough.->

Les he resaltado en negrita el nuevo código añadido. Si vamos al sitio, ya podrán ver que tenemos nuestros campos visibles, al igual que la imagen de arriba.

Desarrollo del Plugin

A continuación, creamos los archivos PHP y XML del plugin. El nombre del plugin es "myregistration", y es un plug-in de usuario. Así que vamos a crear una carpeta llamada plugins/ user/myregistration y creamos nuestros dos archivos del plugin, myregistration.xml y myregistration.php, en esa carpeta.

myregistration.xml

<?xml version="1.0" encoding="utf-8"?>
  <extension version="2.5" type="plugin" group="user">
  <name>PLG_USER_MYREGISTRATION</name>
  <author>Carlos Rodríguez</author>
  <creationDate>Marzo 2013</creationDate>
  <copyright>Copyright (C) 2013 Carlos Rodríguez. All rights reserved.</copyright>
  <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
  <authorEmail>E-mail</authorEmail>
  <authorUrl>URL</authorUrl>
  <version>2.5.0</version>
  <description>PLG_USER_MYREGISTRATION_XML_DESCRIPTION</description>

  <files>
    <filename plugin="myregistration">myregistration.php</filename>
    <folder>language</folder>
  </files>
</extension>

Esto es similar al plugin del ejemplo anterior. Tenga en cuenta que estamos definiendo una subcarpeta de idioma para nuestro plugin.

myregistration.php

<?php

// No permitir el acceso directo
defined('_JEXEC') or die;

/**
 * Este es nuestra clase personalizada del plugin de registro. Se comprueba que el usuario a
 * marcado las casillas que indican que él / ella están de acuerdo con los términos del servicio
 * y tiene la edad suficiente para usar el sitio.
 */
class plgUserMyRegistration extends JPlugin
{
 /**
 *
 * @param array $previousData La información guardada actualmente para el usuario.
 * @param bool $isNew True si el usuario a ser guardado es verdadero.
 * @param array $futureData La nueva información a ser guardada por el usuario.
 *
 * @return bool True para permitir que el proceso de guardado continue,
 * False para detenerlo.
 *
 * 
 */

public function onUserBeforeSave($previousData, $isNew, $futureData)
 {
  // Inicializar las variables.
  $jinput = JFactory::getApplication()->input;
  $result = true;

  // Si no se está guardando un "nuevo" usuario (registro), o si no 
  // estamos en la parte pública del sitio, dejar que el
  // registro se lleve a cabo sin interrupción.
  if (!$isNew || !JFactory::getApplication()->isSite()) {
    return true;
  }

  // Load the language file for the plugin
  $this->loadLanguage();

  // Verificar que el checkbox "Estoy de acuerdo con los términos del servicio de este sitio."
  // esté marcado.
  if (!$jinput->getBool('tos_agree')) {
    JError::raiseWarning(1000,
    JText::_('PLG_USER_MYREGISTRATION_TOS_AGREE_REQUIRED'));
    $result = false;
  }

  // Verificar que el checkbox "Tengo por lo menos 18 años de edad."
  // esté marcado.
  if (!$jinput->getBool('old_enough')) {
    JError::raiseWarning(1000,
    JText::_('PLG_USER_MYREGISTRATION_OLD_ENOUGH_REQUIRED'));
    $result = false;
  }

  return $result;
 }
}

Las primeras líneas de código debería ser familiar. Primero nos aseguramos de que estamos dentro de Joomla. El nombre de la clase, sigue la convención de nombres requerida: "plg" más el tipo ("user"), más el nombre del plugin ("myregistration"). La clase hereda de JPlugin.

La clase tiene un método, que se nombra de acuerdo con el evento que los activa. En este caso, el método es onUserBeforeSave(). Este evento se activa cuando se intenta guardar un nuevo usuario en la administración o registrar un nuevo usuario en la parte pública.

Lo primero que debemos hacer es asegurarnos de que estamos creando un nuevo usuario en la parte delantera. Si no es así, simplemente devuelva true y omita el resto del procedimiento. Antes de esto hemos inicializado dos variables, $jinput (utilizada para gestionar la recuperación de datos desde el entorno de aplicación) $result (utilizada para en caso de que todo esté acorde a lo que queremos, pues simplemente devolvemos true en señal de que todo ocurrió correctamente).

Lo siguiente que hacemos es cargar el archivo de idioma. Esto carga el archivo administrator/ language/es-ES/es-ES.plg_user_myregistration.ini, que analizaremos más adelante.

La siguiente sección son bloques if. Usamos $jinput->getBool('tos_agree') para obtener el elemento tos_agree de la variable $ _REQUEST de PHP. Este método devuelve un booleano true o false. Como se trata de una casilla de verificación, se espera que tenga el valor "on" o no se definirá. Sin embargo, también somos conscientes de que un hacker puede manipular la variable $ _REQUEST y poner los valores de allí que no esperamos. Mediante el uso del método $jinput->getBool(), sabemos que siempre vamos a obtener un valor verdadero o falso, no importa lo que un hacker podría poner en ese campo.

Si la casilla está marcada, el $jinput->getBool('tos_agree') devolverá el valor true y la expresión (!$jinput->getBool('tos_agree')) será falsa (recordemos que "!" significa "not"). En este caso, no se ejecuta el código dentro del bloque.

Si la casilla no está marcada, entramos en el bloque de código. Aquí llevamos a cabo dos líneas de código. El primero llama al método JError::raiseWarning(). El primer argumento es el código de error, que no usamos en este ejemplo (lo que puede ser casi cualquier cosa). El segundo argumento es el texto del error. Aquí estamos utilizando la JText :: _ () para hacer que el texto de error sea traducible. Esto significa que tendrá que poner la constante PLG_USER_MYREGISTRATION_TOS_AGREE_REQUIRED en nuestro archivo de idioma. La segunda línea en el bloque de código establece la variable $result a false. Esto significa que el método devolverá el valor false, el cual detendrá el proceso de guardado.

La segunda instrucción if es idéntica a la primera. La última línea de código sólo devuelve la variable $result, que será true si ambos bloques de código se omiten. Si el usuario se olvidó de marcar ambas o una casilla de verificación, recibirá los mensajes de errorres, que es lo que queremos.

Añadir los archivos de idioma

El último paso antes de que podamos probar nuestro plugin es añadir los archivos de idioma. Recordemos que, en nuestro fichero XML nosotros añadimos las siguientes líneas:

<files>
  <filename plugin="myregistration">myregistration.php</filename>
  <folder>language</folder>
</files>

El elemento “folder” indica que habrá una subcarpeta llamada "language" en la carpeta de nuestro plugin.

Cuando creamos un plugin, se puede elegir si se desea que los archivos de idioma esten en la carpeta del plugin o en la carpeta adminstrator/languages. Para las extensiones de terceros, normalmente se recomienda conservar todos los archivos de esas extensión independientes de los archivos del núcleo, por lo que poner los archivos de idiomas en la carpeta de la extensión, normalmente se prefiere.

En nuestro ejemplo, vamos a tener dos archivos de idioma: es-ES.plg_user_myregistration.ini y es-ES.plg_user_myregistration.sys.ini . Estos archivos los vamos a ubicar en la carpeta plugins/user/myregistration/language/es-ES/ .

El primer archivo es el archivo de idioma principal y contiene las constantes del idioma que se utilizará cuando el código del plugin se ejecuta y también cuando el plugin se abre para su edición en el “Gestor de Plugin”. En este archivo ponemos todas las constantes que se necesitan para su visualización en la parte pública del sitio o para editar las opciones.

es-ES.plg_user_myregistration.ini

; Archivos para el idioma del plugin myregistration
PLG_USER_MYREGISTRATION_TOS_AGREE_REQUIRED="Debe aceptar los términos del servicio."
PLG_USER_MYREGISTRATION_OLD_ENOUGH_REQUIRED="Usted debe tener al menos 18 años de edad."

El segundo archivo (con el .sys en el nombre) se utiliza para traducir el nombre del plugin, cuando aparece en el Gestor de Extensiones o en el Gestor de Plugins. También ponemos la descripción del plugin en el archivo .sys para poder traducir la descripción en el mensaje que se muestra cuando el plugin se ha instalado. Esta convención se utiliza para todos los tipos de extensiones.

es-ES.plg_user_myregistration.sys.ini

; Archivos de idiomas sys para el plugin myregistration
; Los archivos .sys.ini se utilizan cuando se listan las extensiones en el Gestor de extensión
; o el Gestor de plugins
PLG_USER_MYREGISTRATION = "User - Mi registro"
PLG_USER_MYREGISTRATION_XML_DESCRIPTION = "Comprueba que el usuario haya marcado los términos de servicios y la regla de la edad mínima."

Probar el plugin

Llegados a este punto, podemos probar nuestro plugin. Una vez más, vaya a Extensiones → Gestor de extensiones → Descubrir y haga clic en el icono de la barra de herramientas Descubrir. Nuestro nuevo plugin debe aparecer con el texto traducido como "User - Mi registro" que hemos utilizado en el archivo de idioma .sys .

Una vez más, haga clic en la casilla de verificación para seleccionar el plugin y luego haga clic en el icono Instalar. Cuando lo hayamos instalado, tenga en cuenta que la descripción del plugin desde el archivo de idioma .sys debe mostrarse en el Gestor de extensiones.

Para probarlo, en primer lugar habilitarlo en el Gestor de plugin. A continuación, intenta registrar un nuevo usuario sin comprobar las dos casillas de verificación.

También debe probar los otros casos para asegurarse de que funcionan como se esperaba. Estos incluyen los siguientes:

• Marque una sola casilla de verificación (debe recibir un solo mensaje de error).
• Marque las dos casilla de verificación (debe funcionar correctamente).
• Crea un usuario desde la administración del sitio (Usuarios → Gestor de Usuarios → Añadir nuevos usuario debe funcionar correctamente)

Tercer Ejemplo

En el ejemplo anterior, hemos creado un plugin para validar los dos campos nuevos, añadidos a través de un override que le hicimos a com_users. Para transmitir esta funcionalidad, a otro sitio Joomla, necesariamente tendríamos que hacer este override. Sería mucho más fácil de manejar esto si pudiéramos hacer todo el trabajo en el plugin.

Mediante la clase JForm y el evento para los form agregado a partir de Joomla 1.6, se puede reemplazar el formulario de registro dentro del plugin. También podemos utilizar JForm para hacer la validación de nosotros, y así eliminar la necesidad del método onBeforeSave(). Con este enfoque, se puede empaquetar toda esta funcionalidad en un pequeño plugin y hacer que sea muy fácil de agregar esta capacidad a otro sitio web Joomla.

Vamos a llamar a esta versión del plugin myregistration2. Que contendrá los siguientes archivos:

• forms/form.xml: El archivo con la información de los campos JForm añadidos por el plugin
• language/es-ES/es-ES.plg_user_myregistration2.ini: Archivo de idioma principal
• language/es-ES/es-ES.plg_user_myregistration2.sys.ini: Archivos .sys del idioma
• myregistration2.php: Archivo principal del plugin
• myregistration2.xml: Archivo XML del plugin

Hagamos que el plugin cobre vida.

Crear el archivo XML del Plugin

Al igual que antes, creamos la carpeta para el plugin (plugins/user/myregistration2) y creamos nuestro archivo XML en esa carpeta.

myregistration2.xml

<?xml version="1.0" encoding="utf-8"?>
  <extension version="2.5" type="plugin" group="user">
  <name>PLG_USER_MYREGISTRATION2</name>
  <author>Carlos Rodríguez</author>
  <creationDate>Marzo 2013</creationDate>
  <copyright>Copyright (C) 2013 Carlos Rodríguez. All rights reserved.</copyright>
  <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
  <authorEmail>E-mail</authorEmail>
  <authorUrl>URL</authorUrl>
  <version>2.5.0</version>
  <description>PLG_USER_MYREGISTRATION2_XML_DESCRIPTION</description>

  <files>
    <filename plugin="myregistration2">myregistration2.php</filename>
    <folder>language</folder>
    <folder>forms</folder>
  </files>
</extension>

Este archivo es similar al ejemplo anterior. Además, hemos añadido un elemento “folder” para la carpeta “forms”.

Crear el archivo XML para el “form”

En este ejemplo, se utiliza la clase JForm para agregar nuestros dos campos al formulario de inscripción. Con JForm, podemos añadir campos a un “form” mediante una de estas dos técnicas:

• Cargar los campos a través de un archivo XML
• Cargar los campos desde un string (por ejemplo, dentro del archivo PHP del plugin)

El primer método se recomienda para la mayoría de los casos, ya que generalmente es más fácil de trabajar y mantener un archivo XML.

form.xml

<?xml version="1.0" encoding="utf-8"?>
  <form>
    <fieldset name="tos"
      label="PLG_USER_MYREGISTRATION2_TERMS_OF_SERVICE"
    >
    <field name="tos_agree" type="checkbox"
      default="0"
      filter="bool"
      label="PLG_USER_MYREGISTRATION2_AGREE"
      required="true"
      value="1"
    />

    <field name="old_enough" type="checkbox"
      default="0"
      filter="bool"
      label="PLG_USER_MYREGISTRATION2_AGE"
      required="true"
      value="1"
    />
    </fieldset>
  </form>

Este archivo define los dos “field” que deseamos agregar al formulario de registro de usuario. El elemento exterior se denomina “form” el cual creará un elemento HTML de formulario. Contiene un elemento fieldset. Un elemento HTML fieldset se utiliza para agrupar field en el “form”. Dentro del fieldset, tenemos nuestros dos elementos field.

Cada elemento field cuenta con los siguientes atributos:

• default: Valor por defecto (de no controlarse)
• filter: El filtro es usado para comprobar la entrada del field
• label: La etiqueta para este campo (tenga en cuenta que esto se traduce)
• required: Para decirle a JForm que este campo es obligatorio
• value: El valor en el form cuando la casilla está marcada

Los atributos “label” y “value” son atributos estándar del elemento HTML input. El atributo “filter” hace que JForm filtre el campo input usando uno de los valores de filtro estándar JHTML. En este caso, estamos filtrando para permitir valores booleanos true o false. Así que incluso si un usuario cambia el “form” en su navegador para presentar alguna otra información (por ejemplo, algún SQL maliciosos o código JavaScript), JForm filtrará esto y lo convertirá en un valor booleano.

El atributo “default” especifica el valor a enviar, si no se introduce ningún valor en el “input”, en este caso, si la casilla de verificación no está marcada. Se especifica un valor de "0", el cual se convertirá en un “false” booleano.

El atributo “required” hace que JForm exiga que este campo sea llenado. En el caso de una casilla de verificación, esto requiere que la casilla de verificación este activada. JForm no permitirá que el usuario se registre sin comprobar la casilla. Ya que JForm maneja esta validación automática, no es necesario el método onBeforeSave() que usamos en el plugin myregistration.

Crear el archivo PHP del Plugin

myregistration2.php

<?php

// No permitir el acceso directo
defined('_JEXEC') or die;

/**
 * Este es nuestra clase personalizada del plugin de registro. Se comprueba que el usuario a
 * marcado las casillas que indican que él / ella están de acuerdo con los términos del servicio
 * y tiene la edad suficiente para usar el sitio.
 */
class plgUserMyRegistration2 extends JPlugin
{

/**
 * Método para manejar el evento "onContentPrepareForm" y modificar el formulario de registro de usuario.
 * Vamos a comprobar para asegurarnos de que el formulario que se está preparando es el formulario de 
 * registro de usuario del componente com_users. Si esa es el "form" que estamos preparando, entonces
 * vamos a cargar nuestro archivo xml personalizado en el objeto form añadiendo nuestros campos 
 * personalizados.
 *
 * @param JForm $form El "form" a modificar.
 * @param array $data Los datos asociados al "form".
 *
 * @return bool
 *
 * @since 1.0
 */
 public function onContentPrepareForm($form, $data)
 {
  // Si no estamos en el formulario de registro, lo ignoramos.
  if ($form->getName() != 'com_users.registration') {
    return;
  }

  // Load the plugin language file
  $this->loadLanguage();

  // Carguamos nuestro archivo xml personalizado de registro, en el formulario de registro de usuario.
  $form->loadFile(dirname(__FILE__).'/forms/form.xml');
}
}

La primera parte es la misma que los plugins anteriores. Nos basamos en el cargador automático para importar la clase JPlugin y extendemos esa clase. Llamamos a la clase del plugin de acuerdo con la convención de nomenclatura, en este caso, plgUserMyRegistration2.

La clase tiene un método, onContentPrepareForm(). El evento onContentPrepareForm se activa en el punto donde JForm ha sido preparado, pero sin renderizar aún. En este punto somos capaces de modificar el objeto JForm en la memoria de trabajo justo antes de que se utilize para crear el “form”. Dos argumentos se pasan a la clase. La variable $form contiene el objeto JForm y la variable $data contiene un objeto estándar con todos los datos del form.

A continuación, nos aseguramos de que estamos procesando un formulario de inscripción. Si no lo es (lo que significa que estamos procesando algun otro), sólo lo dejaremos ahí. Así que probamos el nombre del formulario. Si no es igual a com_users.registration, retornamos sin hacer ningún procesamiento.

En este punto, sabemos que está procesando el formulario de registro de usuario. A continuación se carga el archivo de idioma para poder traducir el texto en nuestro formulario.

Luego, la última línea hace todo el trabajo para crear los dos nuevos campos. Se llama al método loadFile() de JForm con nuestro archivo form.xml como argumento. Esto hace que JForm fusione los campos del archivo form.xml con el “form” que ya está en la memoria de trabajo del archivo XML estándar (en este caso, components/com_users/models/forms/registration.xml). Puesto que los dos campos en nuestro archivo form.xml son campos nuevos (en otras palabras, tienen nombres diferentes de los demás campos del formulario), los dos campos nuevos se agregan al “form”.

Eso es todo lo que hay que hacer. En este punto, los campos en nuestro archivo form.xml se han añadido al “form” y se incluye en la salida. Como se mencionó anteriormente, debido a que usamos el atributo required en los campos, no necesitamos código adicional para asegurar que estas cajas están marcadas. JForm lo hace por nosotros.

Agregue los archivos de idioma

Al igual que antes, tenemos dos archivos de idioma, situados en la carpeta (plugins/user/myregistration2/language/es-ES). El archivo principal es es-ES.plg_user_myregistration2.ini.

es-ES.plg_user_myregistration2.ini

; Archivos para el idioma del plugin myregistration
PLG_USER_MYREGISTRATION2_TERMS_OF_SERVICE="Los campos añadidos para el Acuerdo de Términos de Servicios"
PLG_USER_MYREGISTRATION2_AGREE=" Acepto los términos."
PLG_USER_MYREGISTRATION2_AGE="Tengo al menos 18 años."

es-ES.plg_user_myregistration2.sys.ini

; Archivos de idiomas sys para el plugin myregistration
; Los archivos .sys.ini se utilizan cuando se listan las extensiones en el Gestor de extensión
; o el Gestor de plugins
PLG_USER_MYREGISTRATION2 = "User - Mi registro2"
PLG_USER_MYREGISTRATION2_XML_DESCRIPTION = "Comprueba que el usuario haya marcado los términos de servicios y la regla de la edad mínima."

Probar el plugin

Pruebe el plugin como lo hemos hecho en los ejemplos anteriores, utilizando el Gestor de extensiones y las funciones de descubrir e instalar.

<--Nota: Para probar el plugin, necesitarás deshabilitar el plugin myregistration (no el plugin myregistration2 ya que este es el que vamos a habilitar). También deberás eliminar el override que le hicimos, en el ejemplo anterior, al com_users, ya que que hacemos con el plugin todo ese trabajo. -->

Una vez configurado esto, veremos algo como esto:

Observe que los dos nuevos campos muestran el asterisco para indicar que son requeridos, al igual que los otros campos requeridos en el formulario. Si se pulsa el botón de registro, sin marcar las casillas de verificación, debería de ver el siguiente mensaje:

Este es el mensaje estándar que JForm muestra cuando el usuario envía un formulario que faltan campos obligatorios.

Añadir parámetros a nuestro Plugin

A continuación, vamos a añadir un parámetro a nuestro plugin. Supongamos que desea que el usuario pueda configurar si desea o no mostrar la segunda casilla de verificación. Para ello, tenemos que hacer tres cosas:

• Agregar un campo para los parámetros en el archivo XML de nuestro plugin
• Añadir la funcionalidad al plug-in para verificar el parámetro y quitar el campo si así se desea
• Agregue las constantes nuevas del idioma en el fichero principal para el idioma.

El campo para los parámetros se añade usando un “field” de JForm, similar al que añadimos en nuestro archivo form.xml. El código para el elemento de configuración se muestra a continuación:

<config>
  <fields name="params">
    <fieldset name="basic" >
      <field name="show_age_checkbox" type="radio"
        label="PLG_USER_MYREGISTRATION2_SHOW_AGE"
        description="PLG_USER_MYREGISTRATION2_SHOW_AGE_DESC"
        default="0">
        <option value="0">JHIDE</option>
        <option value="1">JSHOW</option>
      </field>
    </fieldset>
  </fields>
</config>

Se utiliza para agregar las opciones cuando editamos este plugin. En nuestro primer ejemplo, se puede apreciar el lugar donde se inserta este código en nuestro archivo XML.

Creamos un elemento fields con el atributo name igual a "params" para contener nuestros elementos fieldset y field y colocarlo dentro del elemento config.

Necesitamos el elemento fields con el atributo name en nuestro archivo, de lo contrario las opciones no se mostrarán en la pantalla de edición del plugin. Esto es debido a que el archivo del diseño que se encarga de crear el “form” de la parte de edición del plugin (administrator/components/com_plugins/views/plugin/tmpl/edit_options.php) busca un elemento “fields” con el nombre “params” e incluye los elementos “fieldset” contenidos, como opciones en el “form”. Si no tenemos este elemento “fields”, las opciones no aparecerán en la vista de edición del plugin. Esto también es válido para los componentes, módulos y plantillas.

Tenga en cuenta que no necesitamos este elemento “fields” cuando creamos nuestro archivo form.xml. Sólo se requiere cuando estamos añadiendo parámetros al archivo XML de instalación en una extensión.

Dentro del elemento fieldset se define un nuevo field con un type “radio” con dos elementos opcionales, "0" para ocultar y "1" para mostrar. Observe que usamos las constantes JHIDE y JSHOW. Estas son las constantes del lenguaje estándar utilizados en Joomla, por lo que no hay que añadirlas a nuestro archivo de idioma del plugin. Observe también que cada opción es un elemento separado. Los tipos de campo que proporcionan una lista de opciones, como radio o list, utiliza una serie de elementos option, una para cada elemento de la lista.

El siguiente paso es añadir las dos nuevas constantes en el archivo de idioma. Lo añadimos al archivo es-ES.plg_user_myregistration2.ini (no a .sys.ini) porque éstos se utilizan al editar individualmente el plugin en el Gestor de plugin. El atributo label debe ser corto, ya que se utiliza para etiquetar el campo. El atributo description puede ser mayor y se mostrará cuando se pasa el ratón sobre el campo.

Las nuevas constantes son las siguientes:

PLG_USER_MYREGISTRATION2_SHOW_AGE="Mostrar verificación de edad"
PLG_USER_MYREGISTRATION2_SHOW_AGE_DESC="Para mostrar o ocultar la casilla de verificación de la edad. Si es mostrada, será necesario marcarla."

Observe que, si tenemos el Depurador del idioma activado en Configuración global → Sistema veremos dos “**” en torno a los campos de texto para indicar que están bien traducidos.

El último paso es cambiar el código del plugin para verificar el nuevo parámetro y actuar en consecuencia. El código para el método onContentPrepareForm() es el siguiente:

public function onContentPrepareForm($form, $data)
 {
  // Si no estamos en el formulario de registro, lo ignoramos.
  if ($form->getName() != 'com_users.registration') {
    return;
  }

  // Load the plugin language file
  $this->loadLanguage();

  // Carguamos nuestro archivo xml personalizado de registro, en el formulario de registro de usuario.
  $form->loadFile(dirname(__FILE__).'/forms/form.xml');
  if (!$this->params->get('show_age_checkbox', '1')) {
    $form->removeField('old_enough');
  }
 }

El único código nuevo es la declaración if al final del método. Esta función obtiene el nuevo parámetro y lo utiliza como un valor booleano dentro de la condición if. Si la opción Mostrar fue seleccionada, el parámetro será true. Debido a que utilizamos un not ("!") en la condición if, el bloque de código dentro del if no se ejecutará cuando el parámetro es true. Por lo tanto, si hemos seleccionado Mostrar, vamos a saltar el bloque if y todo el formulario se mostrará.

Si ha seleccionado Ocultar, la declaración

$form->removeField('old_enough');

se ejecutará. Este utiliza el método removeField() de la clase JForm para eliminar el campo denominado "old_enough" del “form”. Eso es todo lo que tenemos que hacer. Una vez realizados estos cambios, prueba de que el parámetro funciona como se esperaba.

Hay algunos otros métodos útiles en JForm que podemos utilizar para modificar los formularios en un plugin. Uno de ellos es cambiar algún atributo de “field”. Por ejemplo, supongamos que quería tener la opción de elegir si desea o no hacer un “field” required. Podríamos utilizar el comando

$form->setFieldAttribute('old_enough', 'required', 'false');

para cambiar que el field “old_enough” ya no sea requerido.

Lo importante a recordar es esto: Podemos utilizar el evento onContentPrepareForm para interceptar el objeto JForm antes de que el formulario se muestre. Entonces podemos utilizar los métodos de JForm para agregar, quitar o modificar los campos en el formulario. Esto nos da la oportunidad de adaptar el “form” a nuestras necesidades.

Conclusiones

Aunque con estas dos partes de esta serie hemos abarcado la mayoría de las cosas básicas para construir y desarrollar nuestros propios plugin, incluiremos una tercera parte y final, para algunos puntos un tanto más avanzado en el desarrollo de los plugin. Hablaremos de algunas cosas poderosas que los plugins nos permiten hacer, incluyendo la sobreescritura de models, tables, y otras clases estándar de Joomla. Luego terminamos discutiendo algunas de las mejores prácticas para el desarrollo y uso de plugins. Por lo que recomiendo su futura lectura.