# Guía avanzada de creación de módulos

Portaneo utiliza el estandard de los módulos de Google.

## Tabla de contenidos

- Propiedades de los módulos : título, descripción y altura de los módulos
- Opciones de los módulos : opciones de personalización de los módulos que se ofrecerán a los usuarios
- Contenido de los módulos :
  - tipo de módulo
  - contenido HTML del módulo
  - contenido javaScript del módulo
  - Traducción / internacionalización
- Plantillas
- Ejemplos
- Testea tus módulos

Tu módulo es un fichero XML :
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="widget name" description="widget description" height="200" /> <UserPref name="variable1" datatype="enum" default_value="value1" display_name="variable n.1 :"> <EnumValue value="value1" display_value="value n.1" /> <EnumValue value="value2" display_value="value n.2" /> <EnumValue value="value3" display_value="value n.3" /> <EnumValue value="value4" display_value="value n.4" /> <EnumValue value="value5" display_value="value n.5" /> </UserPref> <Content type="html"><![CDATA[ widget HTML content <script type="text/javascript"> widget javaScript content </script> </Content> </Module>
El documento tiene 3 partes, cada una estará explicada más bajo :

- propiedades del módulo (etiqueta ModulePrefs)
- opciones del módulo (etiqueta UserPref)
- contenido del módulo (etiqueta Content)

## propiedades del módulo

La etiqueta ModulePrefs se utiliza para definir las propiedades del módulo :
<ModulePrefs title="my widget" description="it is my widget" height="200" />

- title : nombre del módulo (obligatorio). Texto (30 car. max.).
- description : descripción del módulo (opcional). Texto (250 car. max.).
- height : Altura en pixeles del módulo (Obligatorio). Número entre 20 y 400. Si la altura del contenido del módulo va cambiando, utiliza la función _IG_AdjustIFrameHeight en el contenido javaScript del módulo.

## opciones de los módulos

Las etiquetas UserPref se utilizan para definir las opciones del módulo,estas permitiran a los usuarios personalizarlo. Estas serán las opciones que se mostrarán cuando el usuario pulse en el botón "configurar" en la cabecera del módulo.
<UserPref name="variable1" datatype="enum" default_value="value1" display_name="variable n.1 :">...</UserPref>

- name : ID de las opciones. Texto (string) sin espacios en blanco.
- datatype : tipo de las opciones
  Los tipos de las opciones pueden ser:
  - string
    <UserPref name="name" datatype="string" default_value="Will Smith" display_name="Your name :" />
  - password : string, todos los carcateres se substituirán por * para ocultar su valor
    <UserPref name="password" datatype="password" default_value="" display_name="Password :" />
  - bool : check box. El default_value puede ser "true"(marcado) o "false"(desmarcado)
    <UserPref name="thumb" datatype="bool" default_value="true" display_name="Show the thumbnails ?" />
  - enum : Select box. Cada elemento seleccionado se definirá por una etiqueta "EnumValue".
    <UserPref name="color" datatype="enum" default_value="blue" display_name="background color :"> <EnumValue value="red" display_value="Red" /> <EnumValue value="blue" display_value="Blue" /> <EnumValue value="green" display_value="Green" /> <EnumValue value="yellow" display_value="Yellow" /> </UserPref>
- default_value :valor de la opción por defecto (utilizado en la primera visualización del módulo por el usuario).
- display_name : etiqueta mostrada.

## contenido d elos módulos

La etiqueta Content reagrupa el código HTML y javaScript del módulo.
<Content type="html"><![CDATA[ <div id="examplediv"></div> <script type="text/javascript"> function init(){ var div=_gel("examplediv"); div.innerHTML="Hola Mundo !"; } _IG_RegisterOnloadHandler(init); </script> </Content>

- El atributo "type" define el tipo de módulo :
  - type="html" : módulo guardado en nuestros servidores. Si puedes elegir, utiliza siempre este tipo.
    <Content type="html"><![CDATA[ <div id="examplediv"></div> <script type="text/javascript"> function init(){ var div=_gel("examplediv"); div.innerHTML="Hola Mundo !"; } _IG_RegisterOnloadHandler(init); </script> </Content>
  - type="URL" : módulo integrado en un IFRAME y guardado en tus servidores. Puedes utilizar este tipo si el contenido de los módulos es dinámico (se actualiza cada vez que se muestra con la información de tu base de datos) y si no puedes utilizar las funciones _IG_FetchContent y _IG_FetchXmlContent.
    <Content type="url" href="http://www.mywebsite.com/mywidget.php" />
    Para este tipo de módulo, la etiqueta está vacia porque el código de tu módulo está en el fichero especificado por el atributo URL.
    Atencióon : Si necesitas utilizar las funciones javascript mencionadas más abajo y nuestro fichero CSS, inserta las siguientes filas en la etiqueta de tu módulo :
    <link rel="stylesheet" type="text/css" media="screen" title="default" href="http://www.portaneo.com/styles/module.css" /> <script type="text/javascript" src="http://www.portaneo.com/includes/modules.js"></script>
- Los módulos HTML (excepto los de tipo URL)
  Introduce el HTML de tu módulo. Se formateará según nuestro CSS
- El código javaScript de tu módulo (excepto los de tipo URL)
  En una sóla etiqueta <script type="text/javascript"></script>, introduce el javaScript de tu módulo.
  Puedes utilizar las siguientes funciones:

  Código de las funciones
  _IG_RegisterOnloadHandler(FUNCTION) | Llama a la función FUNCTION al cargar el módulo. ejemplo : function init(){ alert('hola mundo'); } _IG_RegisterOnloadHandler(init);
  _IG_AdjustIFrameHeight() | Ajusta la altura del módulo según el contenido de éste. Utilizalo si la altura va cambiando.
  _IG_FetchContent(URL, FUNCTION) | Carga el contenido de un fichero definido por su URL URL y envía los resultados a la función FUNCTION . Utilizando Ajax asíncrono. Example : function treatFile(responsetxt){ var obj=_gel("mydiv"); obj.innerHTML=responsetxt; } _IG_FetchContent('http://www.mysite.com/mydoc.csv',treatFile);
  _IG_FetchXmlContent(URL, FUNCTION) | Carga el contenido de un fichero XML definido por su URL y envia los resultados a la función FUNCTION . Utilizando Ajax asíncrono. Example : function treatXml(responsexml){ var str="name : "+responsexml.getElementByTagName("name").firstChild.nodeValue+" age : "+responsexml.getElementByTagName("age").firstChild.nodeValue; var obj=_gel("mydiv"); obj.innerHTML=str; } _IG_FetchXmlContent('http://www.mysite.com/myxmlfile.xml',treatXml);
  Función que utiliza opciones
  _IG_Prefs(__MODULE_ID__) | Envía las opciones a un objeto. Ejemplo : var pref = new _IG_Prefs(__MODULE_ID__);
  .getString("variable") | Devuelve el valor de una opción "string". Ejemplo : var name = pref.getString("yourname");
  .getInt("variable") | Devuelve el valor numérico de una opción "string".
  .getBool("variable") | Devuelve el valor de una opción "bool".
  .set("variable","value") | Modifica el valor de una opción determinada. Ejemplo : pref.set("yourname","John Wayne");
  .open() | Abre la caja de configuración de las opciones. Ejemplo : <A href=# onclick="return pref.open()">Modificar las opciones</A>
  Gestión de pestañas
  _IG_Tabs(__MODULE_ID__,"default selection") | Inicializa la gestión de pestañas. devuelve el objeto pestañas, se utiliza para ejecutar las funciones indicadas más abajo. "default selection" es el nombre de la pestaña seleccionada (opcional). Ejemplo : var tabs = new _IG_Tabs(__MODULE_ID__);
  .tabsContainer | Opcional. Define el objeto que contendrá las pestañas. Ejemplo : tabs.tabsContainer=_gel("tabsdiv"); (Si tu has creado un objeto <div id="tabsdiv"></div>)
  .addTab("tabname","divid","function") | Crear una nueva pestaña, con el nombre "tabname" , dentro del objeto div "divid", llamando a la función "function" cuando se pulse la pestaña. Ejemplo : tabs.addTabs("tab 1","tabdiv","displayTab1Content");
  .setSelectedTab("tabIndex") | Define la pestaña seleccionada."tabIndex" es el índice de la pestaña (empieza con 0).
  Otras funciones
  _bringToFront(__MODULE_ID__) | Llevar un módulo al frente, por encima de los otros.
  _gel("object") | Llama al objeto con el ID "object". Ejemplo : var obj=_get("mydiv");obj.innerHTML='Hello world !';
  _gelstn("object") | Un contenedor alrededor del método javaScript .getElementByTagName().
  _esc("string") | Un contenedor alrededor del método javaScript .escape().
  _unesc("string") | Un contenedor alrededor del método javaScript .unescape().
  _uc("textoprueba") | Devuelve el valor del string "textoprueba" en mayúsculas.
  _lc("textoprueba") | Devuelve el valor del string "textoprueba" en minúsculas.
  _min(value1,value2) | Devuelve el menor valor de value1 y value2.
  _max(value1,value2) | Devuelve el mayor valor de value1 y value2.
  _args("string") | Transforma el string "name=john&age=12&sex=m" a la matriz {"name":"john","age":"12","sex":"m"}
  _trim("string") | Elimina los espacios en blanco.

- Traducción / internacionalización
  Obtener la selección de idioma del usuario :
  Usa la variable__lang en la parte javascript de tu módulo. El lenguaje tiene una longitud de 2 caracteres (ej: en para el inglés, fr para francés,es para español...). El idioma debe configurarse en posh (directorio de idiomas disponible en /l10n y el parámetro AVLANGS actualizado en la tabla adm_config).
  Traduce tu módulo automáticamente :
  Puedes utilizar la función __ para traducir los textos de tus módulos. El diccionario utilizado es el fichero /l10n/es/lang.js. Si no se encuentran las palabras, añádelas a este fichero, o pregúntanos para que las añadamos a la siguiente version de posh.
  Ejemplo :
  La función __("lblClose") muestra "close", "fermer" o "cerrar", dependiendo del idioma de los usuarios.
  El nombre de las opciones del módulo se traduce automáticamente con el diccionario /l10n/en/lang.js

## Plantillas

<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="name of widget" description="description of the widget" height="200" /> <UserPref name="variable1" datatype="enum" default_value="value1" display_name="variable n.1 :"> <EnumValue value="value1" display_value="value n.1" /> <EnumValue value="value2" display_value="value n.2" /> </UserPref> <UserPref name="variable2" datatype="string" default_value="value1" display_name="variable n.2 :"> <UserPref name="variable3" datatype="bool" default_value="true" display_name="variable n.3" /> <Content type="html"><![CDATA[ <!-- HTML content --> <script type="text/javascript"> //javaScript content //init function of your widget (optional) function init(){ } _IG_RegisterOnloadHandler(init); </script> </Content> </Module>

## Ejemplos

Para visualizar los ejemplos, copia / pega los códigos en el testeador de módulos
Hola Mundo!
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Hello world !" description="my first portaneo widget" height="100" /> <Content type="html"><![CDATA[ <h2>Hola mundo !</h2> </Content> </Module>
Caja coloreada
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="colored box" description="test widget" height="130" /> <UserPref name="color" datatype="enum" default_value="blue" display_name="box color :"> <EnumValue value="blue" display_value="Blue" /> <EnumValue value="red" display_value="Red" /> <EnumValue value="yellow" display_value="Yellow" /> </UserPref> <Content type="html"><![CDATA[ <div style='padding:6px'> <table width='100%'> <tr> <td>Click on a color :</td> <td></td> <td bgcolor='blue' onclick='changeColor("blue")' style='text-align:center;width:50px;cursor:hand;cursor:pointer;'>Blue</td> <td></td> <td bgcolor='red' onclick='changeColor("red")' style='text-align:center;width:50px;cursor:hand;cursor:pointer;'>Red</td> <td></td> <td bgcolor='yellow' onclick='changeColor("yellow")' style='text-align:center;width:50px;cursor:hand;cursor:pointer;'>Yellow</td> <td></td> </tr> <tr> <td colspan=8> </td> </tr> <tr> <td colspan=8 id='box' style='height:80px'> </td> </tr> </div> <script type="text/javascript"> function init(){ var pref=new _IG_Prefs(__MODULE_ID__); var color=pref.getString("color"); var obj=_gel('box'); obj.style.backgroundColor=color; } function changeColor(v_color){ var obj=_gel('box'); obj.style.backgroundColor=v_color; // Save the new default color var pref=new _IG_Prefs(__MODULE_ID__); pref.set("color",v_color); } _IG_RegisterOnloadHandler(init); </script> </Content> </Module>
Leer un fichero HTML
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="read HTML" description="test widget" height="50" /> <Content type="html"> <a href="#" onclick="return loadFile()">Display HTML</a><br /> <div id="mondiv"></div> <script type="text/javascript"> function treatFile(responsetxt) { var obj=_gel("mondiv"); obj.innerHTML=responsetxt; _IG_AdjustIFrameHeight(); } function loadFile() { _IG_FetchContent('http://www.portaneo.com/examples/html_include.html',treatFile); } </script> </Content> </Module>
Leer y tratar un fichero XML
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="read XML" description="test widget" height="50" /> <Content type="html"> <div id="mondiv"></div> <script type="text/javascript"> function treatXml(responsexml) { var str=""; var i=0; while (responsexml.getElementsByTagName("eleve")[i]) { var eleve=responsexml.getElementsByTagName("eleve")[i]; str+=eleve.getElementsByTagName("prenom")[0].firstChild.nodeValue+" "+eleve.getElementsByTagName("nom")[0].firstChild.nodeValue+" got the note of "+eleve.getElementsByTagName("note")[0].firstChild.nodeValue+"/20 for his exams.<br />"; i++; } var obj=_gel("mondiv"); obj.innerHTML=str; } function init() { _IG_FetchXmlContent('http://www.portaneo.com/examples/eleves.xml',treatXml); } _IG_RegisterOnloadHandler(init); </script> </Content> </Module>

## Testea tu módulo

Después de cada modificación del módulo, pruebalo con el testeador antes de solicitar su publicación (herramienta disponible en la página de módulos Avanzados. Preparado? ADELANTE!