Widget para sitios web
Una extensión tipo widget para un sitio web amplía las etiquetas nv de Navigate CMS añadiendo más funcionalidad. Los creadores del tema pueden escribir llamadas a este tipo de widgets para generar código HTML o ejecutar ciertas acciones.
Vamos a explicar dos ejemplos tomando una simplificación de sus widgets.
Contenido aleatorio
Echemos un vistazo a la definición de extensión (random_content.plugin):
{
"title": "Random content",
"version": "1.0",
"author": "Naviwebs",
"website": "http://www.naviwebs.com",
"description": "Choose a random item associated to a category and redirect the browser",
"type": "website"
}
No hay opciones de configuración, eventos o permisos. Se trata de una definición de extensión muy simple. Lo que hace esta extensión es buscar todos los elementos de una categoría, seleccionar uno mediante un algoritmo aleatorio y devolver su ruta de acceso.
La extensión añade un nuevo tag nv que se puede llamar de la siguiente manera:
<a href="{{nv object="nvweb"
name="random_content_plugin"
categories="7,45"}}">Random</a>
La llamada a la extensión sólo tiene en cuenta un atributo: "categories", que es una lista separada por comas de identificadores de categorías reales que se utilizarán para seleccionar un elemento.
En este ejemplo hemos simplificado la extensión; la versión original admite otro atributo llamado "mode". En este ejemplo vamos a suponer que mode="href".
Vamos a analizar el fichero PHP simplificado de la extensión (random_content.php). La estructura es:
<?php
function nvweb_random_content_plugin($vars=array())
{
[buscar un elemento de forma aleatoria de entre las categorías]
[recuperar la ruta/enlace para ese elemento]
[devolver el enlace]
}
?>
Bastante simple, ¿no? Así que todas las llamadas a <nv object="web" name="random_content_plugin" /> acaban por ejecutar esta función y devolver algo de código HTML.
Observa que la función recibe sólo un parámetro: un array asociativo. En nuestro ejemplo, el parámetro se denomina $vars y tiene los atributos adicionales que figuran en la plantilla HTML.
En cada llamada al widget, Navigate CMS siempre incluye un elemento especial a la matriz: "nvweb_html", que es la plantilla de la página analizada y procesada justo hasta el punto antes de llamar al widget. En este caso, el array $vars contiene:
$vars = array(
"categories" => "7,45",
"nvweb_html" => "<!DOCTYPE html><html><head>[...]</body></html>"
);
A continuación, el código PHP completo con comentarios:
<?php
function nvweb_random_content_plugin($vars=array())
{
// $vars contiene todos los atributos de la llamada nv
// recuperar las variables globales $website y $current
global $website; // propiedades del sitio web actual
global $current; // propiedades de la petición en curso
// $out contendrá el código HTML que vamos a devolver
$out = '';
// separar la lista de categorías
$categories = explode(',', $vars['categories']);
// crear una instancia del objeto item
$item = new item();
// llamar al método cargar aleatoriamente un elemento
// de entre una lista de categorías (función propia de item)
$item->load_random($categories);
// recuperar la ruta al elemento seleccionado
// en el idioma usado en esta petición
$item_path = $item->paths[$current['lang']];
// crear una ruta URL absoluta tomando la raíz del sitio web
// y añadiendo la ruta relativa al elemento
$out = $website->absolute_path() . $item_path;
// devolver el enlace HTTP para reemplazar la llamada nv
return $out;
}
?>
La verdadera extensión "random_content" tiene una funcionalidad adicional, la posibilidad de incluir todas las subcategorías asociadas a las categorías indicadas así como varias comprobaciones para evitar errores. Eres libre de descargar la extensión y analizar el código.
Eso es todo. Para publicar la extensión tendremos que incluir un pequeño archivo de documentación (random_content.info.html) y una imagen de identidad de 160x100 píxeles (thumbnail.png).
Raty (plugin de votación)
Para el segundo ejemplo se ha elegido el contenedor de Naviwebs para el Plugin jQuery Raty, una biblioteca que permite a los visitantes de un sitio web otorgar una puntuación a un contenido. Para mantener esto claro vamos a poner aquí una versión reducida del plugin.
Para mostrar el widget en una plantilla simplemente tenemos que escribir la llamada a su etiqueta nv:
<nv object="nvweb"
name="raty_plugin"
mode="stars"
number="5"
callback="voting_result"
/>
El atributo mode="stars" indica al plugin mostrar iconos de estrellas. number indica cuántas estrellas se tiene que mostrar. callback es el nombre de la función de JavaScript de nuestro sitio web que se ejecutará después de que el voto haya sido emitido; este callback se utiliza para indicar el éxito o el fracaso de la votación emitida para el usuario.
Tal vez pienses que la plantilla debe cargar la biblioteca jQuery Raty colocando el código apropiado en la sección head, pero esto no es necesario con Navigate CMS. La propia extensión agregará todo el código necesario. Vamos a ver cómo se logra esto.
Navigate CMS comunica a cada extensión instalada que se va a iniciar una carga de una plantilla. Este evento puede ser capturado por cualquier extensión con sólo escribir una función llamada "nvweb_NOMBRE_EXTENSIÓN_event":
function nvweb_raty_event($event, $html)
{
if($event == 'before_parse')
{
$code = '';
if(strpos($html, 'jquery')===false)
$code.= '<script language="javascript" type="text/javascript"
src="https://ajax.[...]/jquery.min.js"></script>';
if(strpos($html, 'jquery.raty.')===false)
$code.= '
<script language="javascript" type="text/javascript"
src="'.NAVIGATE_URL.'/plugins/raty/jquery-raty/js/jquery.raty.min.js">
</script>
';
nvweb_after_body("html", $code);
}
return $html;
}
Así que, cuando Navigate CMS envía el evento "before_parse", la extensión comprobará si la plantilla ya utiliza la librería jQuery y la biblioteca jQuery.raty. Si una o ambas no se encuentran, la extensión pide a Navigate CMS que añada algo de código HTML al final de la plantilla, justo después de cerrar <body>.
Como nota al margen, la función nvweb_extension_event también es llamada para el evento "after_parse".
Ahora estamos seguros de tener las librerías javascript cargadas. El siguiente paso es escribir la función principal de la extensión. Hemos incluido comentarios para entender mejor el código.
function nvweb_raty_plugin($vars=array())
{
global $website;
global $current;
// $out es el código HTML que reemplaza la llamada nv
$out = '';
// si la etiqueta nv no determina un número de estrellas, asignamos 5
if(empty($vars['number'])) $vars['number'] = 5;
// si no se ha indicado un callback, lo dejamos en false
if(empty($vars['callback'])) $vars['callback'] = 'false';
// calcular la puntuación media otorgada a este contenido
$score = 0;
if($current['object']->votes > 0)
$score = $current['object']->score / $current['object']->votes;
// generar un ID único para evitar duplicados en el código HTML
$uid = uniqid();
// generar el código HTML que se va a devolver
// jQuery Raty sólo necesita un div de posición
$out = '<div class="raty-plugin-'.$uid.'"></div>';
// separaremos el código javascript y lo añadiremos
// al final de la plantilla. En otras palabras, ejecutaremos el
// plugin jquery raty cuando el DOM esté listo
$js = ' $(document).ready(function()
{
$(".raty-plugin-'.$uid.'").raty(
{
path: "'.NAVIGATE_URL.'/plugins/raty/jquery-raty/img",
number: '.$vars['number'].',
start: '.number_format($score, 2, '.', '').',
targetKeep: true,
hintList: [],
click: function(score, evt)
{
nvweb_votes_plugin_vote(score, '.$vars['callback'].');
}
});
});
';
// pedir a Navigate CMS que incluya código javascript en la plantilla
nvweb_after_body("js", $js);
// devolver el código HTML para sustituir la llamada nv
return $out;
}
Ambas funciones deben escribirse en el archivo principal de la extensión PHP: raty.php
Esto completa los ejemplos de extensión de widgets para sitios web.
0 Comentarios