How to build a Tuiyo Widget

Written by Administrator Wednesday, 01 July 2009 19:25

Attention: open in a new window. PDF | Print | E-mail

Before i delve into the simple technicalities of writing a Tuiyo™ Widgets, i will go through a brief introduction on what Tuiyo™ widgets are, and other broader aspects you will need to consider when writing your first Tuiyo widgets. This tutorial will go through the requirements, process and code used in the creation of a New-York Times widget as shown in the screen shot above. Tuiyo widgets are greatly inspired by web portals such as netvibes, iGoogle, and myYahoo.

A Tuiyo™ Widget is a single UTF-8 encoded well-formed XML file, with no external CSS or JavaScript file (though the later is to the discretion of the developer). Widget files are all stored in the widgets sub-directory of the front end component i.e components/com_tuiyo/widgets

The goal is simple, "to provide users with a wall, for external content of all types from, from feeds, to videos, to bookmarks and lots more on their personal joomla profile". This requirement, though simple as it sounds, entails various challenges and thus requires the greatest amount of flexibility possible. One such problem is the potential amount of content we will be dealing with and the processing as well as security implications of this to the host platform.

Tuiyo™ Widgets therefore employs robust technologies (mainly AJAX) to build powerful and flexible widgets. In this tutorial, the goal is to explain the basic structure of a Tuiyo widget and how to use the accompanying AJAX/jQuery based framework for its manipulation.

1. Defining the basic XML structure of Tuiyo widget 

<?xml version="1.0" encoding="utf-8"?>
<widget version="1.0.0">
    <widgetdata>
        <meta name="author" content="Jane Doe" />
        <meta name="email" content="jane+@doe.org" />
        <meta name="website" content="www.doe.org" />
        <meta name="description" content="A widget to grab nyt content" />
        <meta name="version" content="1.0.1" />
        <meta name="keywords" content="news, blog, feed" />
        <meta name="screenshot" content="nyt64.png" />
        <meta name="autorefresh" content="10" />
        <meta name="allowmultiple" content="true" />
        <link href="/nyt16.png" rel="icon/favicon" />
        <link href="/nyt48.png" rel="icon/rich" />
        <title>New York Times Widget</title>
    </widgetdata>
    <widgetparams><!--See section on Params--></widgetparams>
    <widgetstyles><!--See section on Styles--></widgetstyles>
    <widgetbody><!--<![CDATA[HTML widget body, wrap in]]> --></widgetbody>
    <widgetevents><!--<![CDATA[See section on Events]]> --><widgetevents>
</widget>

Saving the above file, with the name of your widget as file name, e.g nyt.xml gives you a functional Tuiyo widget

2. Important and required aspects of the widget XML file

  1. Widget xml files are wrapped in widget tags
  2. Meta elements define various information about the widget. Though you could specify your own meta name labels for use in your widgets processing, the ones shown in the code listing above are absolutely required for your widget to be successfully installed and used,
    1. author: Specifies the author of the widget
    2. email: Specifies the email of the author of the widget authors
    3. website: Specifies the URL to the website of the widget authors
    4. description: A short description for your widget
    5. version: The widget version
    6. keywords: Key words to allow for quick widget identification in searches
    7. screenshot: Specifies a URL to a 64pxx64px image of your widget
    8. autorefresh: Defines an integer representing the number of minutes before which the widget is auto refreshed
    9. allowmultiple: A Boolean value describing if a user can have multiple occurrences of the same widget
  3. You are then required to specify two icons for your widget. A 16px x 16px favicon and a 48px x 48px icon as reference in the link elements
  4. The widgetparams element is optional for your widget, should u not require saving user defined values to Tuiyo, there is no need to specify these element. However widgetparams definition is XML based and each param element must have a name, type and default attribute. Based on the param type other attributes might be required as described below
    1. The text type attribute defines a string and is validated as such
    2. The list type attribute defines a drop down list, a param with of this type is required to have child option elements, with value attributes, just as a normal form select element would
    3. The password type attribute defines a password text field
    4. The text type attribute defines a string and is validated as such
  5. Any addition widget styling, which is not done inline is added to the widgetstyles element. This is an optional element but if specified, every style property should be defined as attributes to the style element. An example of which is shown below 
    <widgetstyles>
    <el name="div.wsjItems">
       <elproperty name="font-color" value="#356AA0" />
       <elproperty name="font-family" value="Segoe UI" />
       <elproperty name="font-size" value="13px" />
    </el>
    <!--additional el style definitions -->
</widgetstyles>
  6. The widgetbody is another optional element of your widget, should you wish to define an initial HTML structure for your widget, prior content loading via Ajax. If you intend to user crude HTML code in this section, a responsible tip will be to wrap all the contents of this node as 
    <![CDATA[ your html here ]]>

3. HTML output of the final widget

Its important for us to stop for a minute to understand the basic physical appearance and xHTML 'structure' of the final widget, as this will be necessary, though not crucially important when loading data via AJAX. Also for design implications, we strongly advice against modifying the outputted widget. It is important that you keep your JavaScript manipulation to the data you are handling, as this provides a better user experience. Below is a basic map of the final widget tuiyoWidgetStructure

4. Defining your Widget Events

There are four Tuiyo widget Events, i.e onLoad, onEdit, onRefresh, onRemove These events are triggered in response to either a user activity or parent platform events/actions. All events are defined in the widgetevents element with each of the four as child elements as shown in the code listing below 

<widgetevents>
    <onload>
         <!--<![CDATA[ onLoad JavaScipt(do not wrap in a function) ]]> -->
    </onload>
    <onclose>
         <!--<![CDATA[ onClose JavaScipt(do not wrap in a function) ]]> -->
    </onclose>
    <onedit>
         <!--<![CDATA[ onEdit JavaScipt(do not wrap in a function) ]]> -->
    </onedit>
    <onremove>
         <!--<![CDATA[ onRemove JavaScipt(do not wrap in a function) ]]> -->
    </onremove>
<widgetevents>

All widgetevents child element contents should be entirely in pure native JavaScript or the beautiful jQuery and responsibly wrapped in CDATA tags. Mootools code (or another framework), will NOT work here. In addition, there is a reserved widget JavaScript object which you could now use directly in your script to obtain any information about the widget. This is described below

  1. Say for instance we wanted to grab a web feed on widget Load (onLoad), and output the content in the widgetContentBox (i.e div.tuiyoWidgetContent ). We could use the following code. NOTE: the following example uses a customized jFeed jQuery plug-in which is bundled with Tuiyo Widgets, so you could use it too in your widgets to save time otherwise native Ajax works just fine. More information on using the customized jFeed plug-in is described elsewhere 
    <onload>
  <![CDATA[
      $.getFeed({
          url:feedURL.xml,
          success: function(feed){
             $.each(feed.items, function(f, story){
                 //NOTE the use of widget.id below to get the current widgetID
                 $('<a href="'+story.link+'">'+story.title+'</a>')
                 .appendTo($("div#"+widget.id).find("div.tuiyoWidgetContent") );
             });
          }
      });
  ]]>
</onload>
  2. As indicated above, information about the current widget is available in the widget [object]
    1. widget.id: The current widget unique identification string, e.g (w126)
    2. widget.title: The user defined title of the current widget e.g New York Times Widget
    3. widget.params: A JavaScript object containing previously saved user widget preferences.

5. And the Final product

tuiyoWidgetCapture

Last Updated on Monday, 10 August 2009 02:56

 

© 2006, 2007, 2008, 2009, 2010 drstonyhills · Powered by Joomla · Released under the General Public Licence v2.1