20071029

Nuevo widget UWA para ipsojobs.com

Esta semana hemos estado preparando un widget UWA en ipsojobs, UWA significa "Universal Widget API" y es una especie de standard creado por netvibes para poder crear Widgets en cualquier plataforma (Netvibes, igoogle, opera, iPhone) una especie de "write once, run everywhere" que prometia Sun con Java en su momento pero aplicado al mundo de los Widgets.

Ya puestos a crear un widget, lo hemos creado con UWA, aunque es posible que si salen incompatibilidades debamos crear n-widgets para las n-plataformas sobre las que queramos desarrollar.

Ipsojobs UWA Widget in action

El widget pretende ser algo un poco más complejo que un simple lector de RSS, en concreto los objetivos del widget son:


  • Permitir seleccionar fácilmente la ciudad sobre la que queremos consultar las ofertas de trabajo de ipsojobs.

  • La selección de la ciudad debe ser "dinámica" dado que cada día aparecen ciudades nuevas no puede ser una lista estática.

  • Cuando estas viendo las ofertas de una ciudad siempre podrás cambiar a otra ciudad fácilmente.

  • El número de ofertas por ciudad debe ser personalizable.

  • Una vez seleccionada una ciudad el widget debe "recordar la preferencia" y mostrar las ofertas de la ciudad hasta que el usuario decida cambiarla.


Si quereis probarlo simplemente podéis visitar http://www.ipsojobs.com/widgets/uwa.html

El código del widget UWA es relativamente sencillo, se basa en un sólo fichero XHTML con todos los javascripts y los CSS incrustados.

Declaración:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:widget="http://www.netvibes.com/ns/" >
<head>


<meta name="author" content="Agusti Pons, omatech.com" />
<meta name="description" content="ipsojobs.com find jobs easy in your city" />


<meta name="apiVersion" content="1.0" />
<meta name="autoRefresh" content="20" />
<meta name="debugMode" content="true" />


<link rel="stylesheet" type="text/css" href="http://www.netvibes.com/themes/uwa/style.css" />
<script type="text/javascript" src="http://www.netvibes.com/js/UWA/load.js.php?env=Standalone">


De esta parte, sólo cabe destacar que se debe modificar el autor y la descripción así como el parámetro debugMode, que en producción deberá ser false. El debugMode=true es muy practico porque manda los mensajes de error a la consola del navegador y se puden consultar con el Firebug por ejemplo.

Javascripts útiles:


<script type="text/javascript">
<![CDATA[
function showhide(e)
{
//el = document.getElementById(e);
el = widget.body.getElementsByClassName(e)[0];
el.style.display = el.style.display == "block" ? "none" : "block";
}


function getlang()
{
return widget.lang.substr(0, 2);
}


function link(url)
{
if (widget && widget.openURL)
{
widget.openURL(url);
}
}


function getSelected(ctrl)
{
for(i=0;i
{
if(ctrl[i].checked)
{
return ctrl[i].value;
}
}
return '';
}


function setcity(url)
{
widget.setBody('<p>...</p>');
widget.setValue('url', url);
UWA.Data.getFeed(widget.getValue('url')+'?lang='+getlang(), ipsowidget.display);
}


function selectcity()
{
widget.setTitle('ipsojobs.com widget - setting...');
UWA.Data.getText('http://www.ipsojobs.com/api/controller.php?action=zones_sites_list&xsl=netvibes〈='+getlang(), ipsowidget.zones_sites_processor);
}


function replace(texto,s1,s2)
{
return texto.split(s1).join(s2);
}


function get_change_city()
{
var lang = getlang();
if (lang=='es')
{
return 'Cambiar ciudad';
}
if (lang=='ca')
{
return 'Canviar ciutat';
}
if (lang=='fr')
{
return 'Changer de ville';
}
else
{
return 'Select city';
}
}
]]>
</script>


Las dos funciones más interesantes son setcity() y selectcity() que detallo a continuación:


function setcity(url)
{
widget.setBody('<p>...</p>');
widget.setValue('url', url);
UWA.Data.getFeed(widget.getValue('url')+'?lang='+getlang(), ipsowidget.display);
}


Recibe como parámetro la url del RSS que nos han clicado en la pagina de selección de la ciudad, primero ponemos unos puntos suspensivos para indicar que estamos cargando (widget.setBody('<p>...</p>');) posteriormente actualizamos el valor de la preferencia url (recordad que es oculta y el usuario no la puede ver) con la instrucción widget.setValue('url', url); y finalmente cargamos el feed RSS en el body, fijaos que utilizamos la url de la preferencia que acabamos de actualizar pero le añadimos el parámetro lang basándonos en el language del navegador del usuario UWA.Data.getFeed(widget.getValue('url')+'?lang='+getlang(), ipsowidget.display);.

Para mostrar el RSS feed en el body fijaros que llamamos a la función display del widget que veremos más abajo declarada como ipsowidget.display = function(feed) esta función es muy parecida a la que se explica en el HOWTO de como mostrar un RSS en la web de Netvibes.


function selectcity()
{
widget.setTitle('ipsojobs.com widget - setting...');
UWA.Data.getText('http://www.ipsojobs.com/api/controller.php?action=zones_sites_list&xsl=netvibes〈='+getlang(), ipsowidget.zones_sites_processor);
}


La función selectcity, sólo tiene dos lineas, la primera modifica el título del widget widget.setTitle('ipsojobs.com widget - setting...'); indicando que no estamos en ningúna ciudad sino en la pantalla de setting. La segunda linea carga una url especial de ipsojobs que genera el html necesario para mostrar el seleccionable de las distintas zonas y ciudades UWA.Data.getText('http://www.ipsojobs.com/api/controller.php?action=zones_sites_list&xsl=netvibes〈='+getlang(), ipsowidget.zones_sites_processor); con el html resultante se llama a la función ipsowidget.zones_sites_processor que veremos más abajo y simplemente machaca el body con el nuevo html. Cabe destacar que el html contiene la lista de zonas y sus ciudades ocultas, al clicar sobre la zona se llama a la función showhide para mostrar las ciudades de esta zona. Con iGoogle he comprovado que el desplegado y el plegado no funcionan muy bien porque el widget no se redimensiona correctamente, en cambio si arrastras el titulo del widget como si lo fueses a reposicionar, entonces se recalcula la altura del mismo correctamente.

Preferencias y CSSs:


<title>ipsojobs.com widget
<link rel="icon" type="image/png" href="http://www.netvibes.com/favicon.ico" />


<widget:preferences>
<preference name="url" type="hidden" label="URL" defaultValue="" />
<preference name="limit" type="range" label="Number of items to display" defaultValue="10" step="1" min="1" max="25" />
</widget:preferences>


<style type="text/css">
/* your CSS rules */


body {
height: 400px;
}


a:hover {
cursor: pointer;
}


h2 {
color: #8CC402;
}


h3 {
color: #8CC402;
}


</style>

Aquí podemos ver que creamos una preferencia llamada url de tipo hidden, es la que nos servira para almacenar la url del recurso RSS de la ciudad seleccionada. También creamos el parametro limit que permitirá al usuario seleccionar el numero de ofertas a mostrar en el rango de 1 a 25.

El meollo de la cuestión:


<script type="text/javascript">
<![CDATA[
var ipsowidget = {}


ipsowidget.feed = false;

ipsowidget.display = function(feed)
{
// get the number of items to display
widget.preferences[1].max = feed.items.length;


var toolbar=widget.createElement('h2');
var website_url=replace(widget.getValue('url'), '/rss/controller.php', '');
toolbar.setHTML(''+feed.title+'');


var toolbar2=widget.createElement('h3');
toolbar2.setHTML(''+get_change_city()+'');


widget.setTitle('ipsojobs.com - '+feed.title);

// create the 'ul' element, applying it the CSS class 'nv-feedList'
var feedList = widget.createElement('ul');


// your 'ul' element MUST make use of the 'nv-feedList' class
// to ensure your widget uses the UWA UI library
feedList.className = 'nv-feedList';


// number of parsed items
var j = 0;


// loop through the downloaded items
for(var i=0; i < feed.items.length; i++)
{
// if the limit is reached, stop looping
if (j >= widget.getValue('limit')) break;


// for each item, create the 'li' element
var item = feed.items[i];
var li = widget.createElement('li');


// create and fill the 'a' element of the item with the item's link
var a = widget.createElement('a');
a.href = item.link;


// fill the 'a' element with the item's title
var displayTitle = item.title;
a.innerHTML = displayTitle;


// build the title from the 255 first characters of the content
// remove the content's HTML tags along the way
var title = item.content.stripTags().truncate(255);
a.title = title;


// set a tooltip on the 'a' element, with the item's content
a.onmouseover = function()
{
UWA.Utils.setTooltip(this, this.content, 250);
}


// finally append the 'a' element we just filled, into the 'li' element
li.appendChild(a);


// ...and append the 'li' element to the main 'ul' element
feedList.appendChild(li);
j++;
}


var general=widget.createElement('div');
general.appendChild(toolbar);
general.appendChild(toolbar2);
general.appendChild(feedList);
// once the needed items have been parsed,
// send the main 'ul' element to the HTML body tag
widget.setBody(general);
}


ipsowidget.zones_sites_processor = function(text)
{
widget.setBody(text);
}


widget.onLoad = function()
{
if (widget.getValue('url')=='')
{
selectcity();
}
else
{
//alert(getlang());
UWA.Data.getFeed(widget.getValue('url')+'?lang='+getlang(), ipsowidget.display);
}
}
]]>
</script>


La mayoría de este código es muy parecido al HOWTO de como hacer un RSS widget con UWA (solucionando algún pequeño bug) con las siguientes diferencias:


var toolbar=widget.createElement('h2');
var website_url=replace(widget.getValue('url'), '/rss/controller.php', '');
toolbar.setHTML(''+feed.title+'');


var toolbar2=widget.createElement('h3');
toolbar2.setHTML(''+get_change_city()+'');


widget.setTitle('ipsojobs.com - '+feed.title);


En este fragmento creamos el elemento DOM que nos muestra el nombre de la ciudad seleccionada (con un link a la misma) y el elemento que nos permite cambiar de ciudad. En la última linea también actualizamos la barra de título del widget con el nombre de la ciudad seleccionada.

Al final, hemos añadido los fragmentos DOM creados.

var general=widget.createElement('div');
general.appendChild(toolbar);
general.appendChild(toolbar2);
general.appendChild(feedList);
// once the needed items have been parsed,
// send the main 'ul' element to the HTML body tag
widget.setBody(general);


El onLoad también esta un poco tuneado, en el ejemplo siempre carga la url, pero en nuestro caso puede ser que el widget se haya instalado por primera vez y no tengamos ninguna url en concreto, por eso hacemos lo siguiente:


widget.onLoad = function()
{
if (widget.getValue('url')=='')
{
selectcity();
}
else
{
//alert(getlang());
UWA.Data.getFeed(widget.getValue('url')+'?lang='+getlang(), ipsowidget.display);
}
}


Simplemente detecta si ya tenemos una url fijada y sino llamamos a selectcity que ya se encarga de hacer la llamada AJAX correspondiente para mostrar el selector de ciudades. En caso contrario (este usuario ya tenia la preferencia url fijada para este widget) simplemente la cargamos llamando a UWA.Data.getFeed, fijaros que obtengo el lenguaje del navegador y intento llamar con el lenguaje más apropiado al RSS que me interesa.

Finalmente el body de la página


</head>
<body>
<p>Welcome to the ipsojobs.com widget </p>
<p>...</p>
</body>
</html>


Esta parte no tiene misterio, simplemente mostramos un body, que en seguida se machacará con la función widget.onLoad, que hemos visto más arriba.