# Advanced widget creation guide

Portaneo is using the Google widget standard.

## Table of Contents

- widget properties : title, description and widget's height
- widget options : personalization options given to widget's users
- widget content :
  - widget type
  - widget HTML content
  - widget javaScript content
  - Translation / internationalization
- Templates
- Samples
- Test your widget

Your widget is an XML file :
<?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>
The document has 3 parts, each will be fully explained below :

- widget's properties (ModulePrefs tag)
- widget's options (UserPref tag)
- widget's content (Content tag)

## widget's properties

The ModulePrefs tag is used to define the properties of the widget :
<ModulePrefs title="my widget" description="it is my widget" height="200" />

- title : widget's name (required). String (30 car. max.).
- description : widget's description (optional). String (250 car. max.).
- height : widget's pixel height (required). Integer between 20 and 400. If the widget content height is changing, you will use the _IG_AdjustIFrameHeight function in the widget javaScript content.

## widget's options

The UserPref tags are used to define the widget's options, that will give personalization to users. These are the options that show up when you click on "configure" button in the widget's header.
<UserPref name="variable1" datatype="enum" default_value="value1" display_name="variable n.1 :">...</UserPref>

- name : option's ID. String without whitespaces.
- datatype : option's type
  The option type can be :
  - string
    <UserPref name="name" datatype="string" default_value="Will Smith" display_name="Your name :" />
  - password : string, all characters are replaced by * to hide the value
    <UserPref name="password" datatype="password" default_value="" display_name="Password :" />
  - bool : check box. The default_value can be "true"(checked) or "false"(unchecked)
    <UserPref name="thumb" datatype="bool" default_value="true" display_name="Show the thumbnails ?" />
  - enum : Select box. Each selected element will be defined by an "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 :default option value (used on first widget display for a user).
- display_name : label displayed.

## widget's content

The Content tag regroups the widget's HTML and javaScript code.
<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>

- The "type" attribute defines the widget's type :
  - type="html" : widget stored on our servers. If you have the choice, always use this type.
    <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" : widget stored on your servers. You can use this type if your widget's content is dynamic (refreshed on each display with you database information) and if you can not use the _IG_FetchContent and _IG_FetchXmlContent functions.
    <Content type="url" href="http://www.mywebsite.com/mywidget.php" />
    For this type of widget, the tag is empty because your widget's code is in the file specified by the URL attribute.
    Attention : If you need to use the javascript functions mentionned below and our CSS file, insert the following rows in the tag of your widget :
    <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>
- The widget's HTML (except for URL type)
  Type the HTML of your widget. It will be formatted by our CSS
- The javaScript code of your widget (except for URL type)
  In a unique tag <script type="text/javascript"></script>, type the javaScript of your widget.
  You can use the following functions :

  Code functions
  _IG_RegisterOnloadHandler(FUNCTION) | Call the FUNCTION function on the widget loading. example : function init(){ alert('hello world'); } _IG_RegisterOnloadHandler(init);
  _IG_AdjustIFrameHeight() | Adjust the widget height to the widget content. Use it if the widget's height change.
  _IG_FetchContent(URL, FUNCTION) | Load the content of a file defined by its URL and send the results to the FUNCTION function. Using of asynchronous Ajax. Example : function treatFile(responsetxt){ var obj=_gel("mydiv"); obj.innerHTML=responsetxt; } _IG_FetchContent('http://www.mysite.com/mydoc.csv',treatFile);
  _IG_FetchXmlContent(URL, FUNCTION) | Load the content of an XML file defined by its URL and send the results to the FUNCTION function. Using of asynchronous Ajax. Example : function treatXml(responsexml){ var str="name : "+responsexml.getElementsByTagName("name")[0].firstChild.nodeValue+" age : "+responsexml.getElementsByTagName("age")[0].firstChild.nodeValue; var obj=_gel("mydiv"); obj.innerHTML=str; } _IG_FetchXmlContent('http://www.mysite.com/myxmlfile.xml',treatXml);
  Function that use options
  _IG_Prefs(__MODULE_ID__) | Send the options to an object. Example : var pref = new _IG_Prefs(__MODULE_ID__);
  .getString("variable") | Retrieve the value of a "string" option. Example : var name = pref.getString("yourname");
  .getInt("variable") | Retrieve the integer value of a "string" option.
  .getBool("variable") | Retrieve the value of a "bool" option.
  .set("variable","value") | Modify the value of a specified option. Exemple : pref.set("yourname","John Wayne");
  .open() | Open the options configuration box. Example : <A href=# onclick="return pref.open()">Modify the options</A>
  Tabs management
  _IG_Tabs(__MODULE_ID__,"default selection") | Initialize tab management. Return tabs object, used to execute functions below. "default selection" is the name of the selected tab (optional). Example : var tabs = new _IG_Tabs(__MODULE_ID__);
  .tabsContainer | Optional. Define the object that will contain the tabs. Example : tabs.tabsContainer=_gel("tabsdiv"); (if you have created an object <div id="tabsdiv"></div>)
  .addTab("tabname","divid","function") | Create a new tab, with "tabname" name, inside "divid" div object, calling "function" function when clicked. Example : tabs.addTabs("tab 1","tabdiv","displayTab1Content");
  .setSelectedTab("tabIndex") | Define the selected tab."tabIndex" is the index of the tab (start with 0).
  Other functions
  _bringToFront(__MODULE_ID__) | Bring a widget to front, above the others.
  _gel("object") | Get the object which ID is "object". Example : var obj=_get("mydiv");obj.innerHTML='Hello world !';
  _gelstn("object") | A wrapper around the javaScript .getElementsByTagName() method.
  _esc("string") | A wrapper around the javaScript .escape() method.
  _unesc("string") | A wrapper around the javaScript .unescape() method.
  _uc("string") | Return uppercase value of "string" string.
  _lc("string") | Return lowercase value of "string" string.
  _min(value1,value2) | Return the lesser value of value1 and value2.
  _max(value1,value2) | Return the greater value of value1 and value2.
  _args("string") | Transforms the string "name=john&age=12&sex=m" to the array {"name":"john","age":"12","sex":"m"}
  _trim("string") | Remove the useless whitespaces.

- Translation / internationalisation
  Get the user language selection :
  Use the variable __lang in javascript part of your widget. The language is 2 digits long (eg: en for english, fr for french, ...). The lang must be configured in posh (language directory available in /l10n and AVLANGS parameter updated in adm_config table).
  Translate your widget automatically :
  You can use the __ function to translate texts of your widgets. The dictionary used is the file /l10n/en/lang.js. If words are missing, add them in this file, or ask us to add them for next posh version.
  Example :
  The function __("lblClose") displays "close" or "fermer", depending on the users language.
  widgets options' name are automatically translated with dictionary /l10n/en/lang.js

## Templates

<?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>

## Examples

For the example overviews, copy / paste the codes in the widget tester
Hello World !
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Hello world !" description="my first portaneo widget" 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 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>
Read an HTML file
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="read HTML" description="test widget" height="50" /> <Content type="html"><![CDATA[ <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>
Read and treat an XML file
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="read XML" description="test widget" height="50" /> <Content type="html"><![CDATA[ <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>

## Test your widget

After each widget modification, test it with the tester before asking for publication (tool available on the Advanced widget page). Ready? GO!