# Guida alla creazione di un modulo AVANZATO

Loovi usa lo stesso standard in uso per la creazione dei gadget di Google.

## Sommario

- Proprietà di un modulo : titolo, descrizione e altezza del modulo
- Opzioni di un modulo : opzioni di personalizzazione fornite agli utenti del modulo
- Contenuti del modulo :
  - Tipo del modulo
  - Contenuto HTML del modulo
  - Contenuto Javascript del modulo
- Templates
- Esempi
- Test del modulo

Un modulo è un file XML:
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="module name" description="module 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[ module HTML content <script type="text/javascript"> module javaScript content </script> ]]> </Content> </Module>
Questa guida si divide in tre parti dettagliate qui sotto:

- proprietà del modulo (ModulePrefs tag)
- Opzioni del modulo (UserPref tag)
- Contenuti del modulo (Content tag)

## Proprietà del modulo

Il tag ModulePrefs viene usato per definire le proprietà del modulo:
<ModulePrefs title="my module" description="it is my module" height="200" />

- title : nome del modulo (obbligatorio). Stringa (30 car. max.).
- description : descrizione del modulo (opzionale). Stringa (250 car. max.).
- height : altezza del modulo in pixel (obbligatorio). Intero compreso tra 20 e 400. Se l'altezza del contenuto del modulo è variabile, dovrai usare la funzione _IG_AdjustIFrameHeight nella sezione di contenuto javascript del modulo.

## Opzioni del modulo

I tag UserPref sono usati per definire le opzioni del modulo, che permetteranno agli utenti di personalizzarlo. Queste sono le opzioni mostrate quando si clicca su 'configura' nella testata del modulo.
<UserPref name="variable1" datatype="enum" default_value="value1" display_name="variable n°1 :" >

- name : ID dell'opzione. Stringa senza spazi bianchi.
- datatype : tipo dell'opzione
  Il tipo dell'opzione può essere:
  - string
    <UserPref name="name" datatype="string" default_value="Will Smith" display_name="Your name :" >
  - bool : check box. Il valore di default può essere "true"(checked) o "false"(unchecked)
    <UserPref name="thumb" datatype="bool" default_value="true" display_name="Show the thumbnails ?" />
  - enum : Select box. Ciascun elemento sarà definito da un "EnumValue" tag.
    <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 :valore di default dell'opzione (usanto nella prima visualizzazione del modulo agli utenti).
- display_name : etichetta visualizzata.

## Contenuto del modulo

Il tag Content definisce il tipo di modulo, e il codice HTML e javascript del modulo.
<Content type="html"><![CDATA[ <div id="examplediv"></div> <script type="text/javascript"> function init(){ var div=_gel("examplediv"); div.innerHTML="Hello World !"; } _IG_RegisterOnloadHandler(init); </script> ]]> </Content>

- L'attributo "type" definisce il tipo di modulo :
  - type="html" : Il modulo è memorizzato sui nostri server. Se è possibile usate sempre questo tipo di modulo.
    <Content type="html"><![CDATA[ <div id="examplediv"></div> <script type="text/javascript"> function init(){ var div=_gel("examplediv"); div.innerHTML="Hello World !"; } _IG_RegisterOnloadHandler(init); </script> ]]> </Content>
  - type="URL" : Il modulo è memorizzato sul vostro server. E' possibile usare questo tipo di modulo se i contenuti sono dinamici (aggiornati ad ogni visualizzazione con informazioni sul vostro database) e se non potete usare le funzioniY _IG_FetchContent e _IG_FetchXmlContent .
    <Content type="url" href="http://www.mywebsite.com/mymodule.php" />
    Per questo tipo di modulo il tag è vuoto perché il codice del modulo è nel file specificato dall'attributo URL.
    Attenzione: se avete la necessità di usare le funzioni javascript descritte più sotto, e il CSS di Loovi, inserite le seguenti istruzioni nel tag del vostro modulo:
    <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>
- HTML per il modulo (tranne che per il tipo URL)
  Inserite qui l'HTML del vostro modulo. L'output verrà formattato dal nostro CSS
- Codice javascript per il modulo (tranne che per il tipo URL)
  Inserire il codice javascript del modulo in un unico tag <script type="text/javascript"></script>.
  E' possibile usare le seguenti funzioni:

  Funzioni di programmazione
  _IG_RegisterOnloadHandler(FUNCTION) | Chiama la funzione FUNCTION al caricamento del modulo. esempio: function init(){ alert('hello world'); } _IG_RegisterOnloadHandler(init);
  _IG_AdjustIFrameHeight() | Regola l'altezza del modulo come l'altezza dei contenuti. Usarla se l'altezza del modulo può cambiare.
  _IG_FetchContent(URL, FUNCTION) | Carica il contenuto di un file definito dal suo URL e manda il risultato alla funzione FUNCTION. Utilizzare per applicazioni AJAX. Esempio: function treatFile(responsetxt){ var obj=_gel("mydiv"); obj.innerHTML=responsetxt; } _IG_FetchContent('http://www.mysite.com/mydoc.csv',treatFile);
  _IG_FetchXmlContent(URL, FUNCTION) | Carica il contenuto di un file XML definito dal suo URL e manda il risultato alla funzione FUNCTION. Utilizzare per applicazioni AJAX. Esempio: 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);
  Funzioni per l'accesso alle opzioni
  _IG_Prefs(__MODULE_ID__) | Invia le opzioni ad un oggetto. Esempio: var pref = _IG_Prefs(__MODULE_ID__);
  .getString("variable") | Recupera il valore di un'opzione "string". Esempio: var name = pref.getString("yourname");
  .getInt("variable") | Recupera il valore intero di un'opzione "string".
  .getBool("variable") | Recupera il valore di un'opzione "bool".
  .set("variable","value") | Modifica il valore dell'opzione specificata. Esempio: pref.set("yourname","John Wayne");
  .open() | Apre il box di modifica delle opzioni. Esempio: <A href=# onclick="return pref.open()">Modify the options</A>
  Altre funzioni
  _gel("object") | Recupera l'oggetto il cui ID è "object". Example : var obj=_get("mydiv");obj.innerHTML='Hello world !';
  _gelstn("object") | Wrapper attorno al metodo javascript .getElementByTagName().
  _esc("string") | Wrapper attorno al metodo javascript .escape().
  _unesc("string") | Wrapper attorno al metodo javaScript .unescape().
  _uc("string") | Ritorna la stringa "string" in maiuscole.
  _lc("string") | Ritorna la stringa "string" in minuscole.
  _min(value1,value2) | Ritorna il minimo tra value1 e value2.
  _max(value1,value2) | Ritorna il massimo tra value1 e value2.
  _args("string") | Trasforma la stringa "name=john&age=12&sex=m" nell'array {"name":"john","age":"12","sex":"m"}
  _trim("string") | Rimuove gli spazi bianchi in eccesso.

## Templates

<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="name of module" description="description of the module" 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 module (optional) function init(){ } _IG_RegisterOnloadHandler(init); </script> ]]> </Content> </Module>

## Esempi

Per verificare il funzionamento degli esempi, copia/incollare nel box di test
Hello World !
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Hello world !" description="my first portaneo module" height="100" /> <Content type="html"><![CDATA[ <h2>Hello world !</h2> ]]> </Content> </Module>
Colored box
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="colored box" description="test module" 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>

## Test dei moduli

Dopo ogni modifica al modulo si prega di provarne il funzionamento corretto tramite il box di test (disponibile nella pagina di creazione di modulo esperto) prima di sottometere il modulo per l'approvazione.