Vistas

Gadget development guide

De MorfeoWiki

Tabla de contenidos

[editar]

Introduction

In a Mashup based application like EzWeb, the gadgets are the main element:

  • Shape the user operational environment.
  • User chooses gadgets that best meet his needs.
  • Centralized the interaction between user and system, as well as among other gadgets.
[editar]

Gadgets Conceptual Design

  • Gadgets are supposed to be small, reusable and user centric web applications.
  • Generic gadgets are desirable, but ad-hoc solutions are allowed too if they are quick&cheap enough.
  • Gadgets should be adapted to real problems.
  • Gadgets are elements of the front-end layer (View). It's not desirable for gadgets to perform back-end layer functions (controller or model) because they can be provided by the platform (persistent state).
  • In gadgets development can be used any of the technologies accepted by the Web Browser (XHTML, JavaScript, SVG, Flash, applets, etc.).
[editar]

Gadgets Developement

Gadgets are formed by two different files:

  • Template, or declarative part (XML).
  • Implementation (HTML).
[editar]

Template

Template is a XML document that defines the gadget behavior with its environment (user, platform, other gadgets ,...), allowing the gadget can share information in a standardized, declarative and semantic way. Moreover, it is possible to define several templates for the same gadget implementation, depending on which you want to be its behavior.

Template is divided into two main conceptual blocks:

  1. Description. Contains all the gadget contextual information. An unique element belonging to this block must be in the XML document, which must have the word Catalog as prefix. Specifically, the XML element is this:
    • Catalog.ResourceDescription. Contains all the information related to the gadget. It's composed of the following fields:
      • Vendor. The distributor of the gadget.
      • Name. Name of the gadget.
      • Version. Current version of the gadget. 
        Note: These three fields form the gadget's identifier.

        

        

      • Author. Person who has developed a gadget.

      • Mail. E-mail address for contact with the author

      • Description. 	A short description of the gadget

      • ImageURI. URL where is the image that will appear later in the catalog

      • WikiURI. Entry to a Wiki where to find a complete description of the gadget

      

      <Catalog.ResourceDescription>

          <Vendor>Morfeo</Vendor>

          <Name>Localizador</Name>

          <Version>1.0</Version>

          <Author>lmayllon</Author>

          <Mail>lmayllon@tid.es</Mail>

          <Description>

              This gadget shows the location of a specific adress on the map

          </Description>

          <ImageURI>

              http://ezweb.hi.inet/gadgets/img/compass.gif

          </ImageURI>

          <WikiURI>

              http://ezweb.hi.inet/wiki/locator

          </WikiURI>

      </Catalog.ResourceDescription>

      

      

    

    

  2. Integration Variables and Platform Elements. The variables that uses the gadget to interact with the environment, associating concepts with aspects are defined in this block. Likewise, also defines some other elements of the interface, such as the size of the gadget. All of them are managed by the platform, which will ensure that be persistent.

    The XML document (i.e. the Template) should be composed of several elements belonging to this block, all of them with the word Platform as prefix. Specifically, the elements that should appear are:

    • Platform.Preferences. The user preferences, which may be changed through the platform interface. It's a mandatory element, consisting of several fields Preference, although it also may appear empty.

      • Preference. Defines a user preference. Must have the following attributes mandatorily:

        • name. Name of the variable.

        • type. Data type of the variable: text (string), number, boolean, password and list.

        • description. Descriptive text.

        • label. Label which the variable will be shown in the user interface

        • Option. Defines an item of the selection list (preference type equals list):

          • name. Specifies the text to display in the selection list.

          • value. Specifies the value when the option is selected.

          

        

      

      <Platform.Preferences>

          <Preference name="textcolor" type="text" description="descripcion" label="text color"/>

          <Preference name="bg" type="list" description="backgroud" label="background color">

              <Option name="Red" value="red"/>

              <Option name="Yellow" value="yellow"/>

              <Option name="Green" value="green"/>

              <Option name="Blue" value="blue"/>

          </Preference>

      </Platform.Preferences>

      

      

    • Platform.StateProperties. This element contains some variables that reflected the gadget state. The state can be any information that the gadget should make persistent (as a note, etc.). It is a mandatory element that defines a list of Property(the list could be empty).

      • Property . Defines a state variable. Must have the following attributes mandatorily:

        • name. Name of the variable.

        • type. Data type of the variable. So far only the typetext(string) is allowed.

        • label. Label which the variable will be shown in the user interface

        

      

      <Platform.StateProperties>

          <Property name="note" type="text" label="note"/>

      </Platform.StateProperties>

      

      

    • Platform.Wiring. Defines a list of variables, which the gadget uses to communicate with other gadgets. It may contain any number of these elements:

      • Event. Events produced by a gadget, which value will be received by other gadgets as slots. Must have the following attributes mandatorily:

        • name. Name of the variable.

        • type. Data type of the variable. So far only the typetext(string) is allowed.

        • label. Label which the variable will be shown in the user interface

        • friendcode. Label that defines the slots with which the event is related, and which can be connected through a channel. When a user creates a channel, its inputs and outputs are suggested by the platform using this field (i.e. events and slots with the same friendcode value can be connected).

        

      • Slot. Define the variable where gadget receives the value of the event which another gadget has produced. Each slot must have the following attributes:

        • name. Name of the variable.

        • type. Data type of the variable. So far only the typetext(string) is allowed.

        • label. Label which the variable will be shown in the user interface

        • friendcode. similar to event.

        

      

      <Platform.Wiring>

          <Slot name="serviceHired" type="text" label="ServiceHired" friendcode="service"/>

          <Event name="deviceId" type="text" label="deviceId" friendcode="deviceId"/>

          <Event name="deviceStatus" type="text" label="deviceStatus" friendcode="deviceStatus"/>

      </Platform.Wiring>

      

      

    • Platform.Context. Element in which variables of context are defined. These variables provide gadgets with a context, which are managed by the platform. Like case before, is a mandatory element and can contain any number of the following two elements:

      • External. Defines a variable of context with platform scope (e.g. username, etc.)

      • Gadget. Defines a variable of context with gadget scope (e.g. height, width, etc.)

        Both of them must have the following attributes: 

        

        • name. Name of the variable.

        • type. Data type of the variable. So far only the typetext(string) is allowed.

        • concept. Label that provides variable with semantic. Must match with one of the concepts managed by the platform. Currently only are defined as external concepts username and language (as user_name and language respectively), and as gadget concepts height and width (as height and width respectively).

        

      

      <Platform.Context>

          <Context name="user" type="text" concept="user_name"/>

          <Context name="language" type="text" concept="language"/>

          <GadgetContext name="height" type="text" concept="height"/>

          <GadgetContext name="width" type="text" concept="width"/>

      </Platform.Context>

      

      

    • Platform.Link. Gadget source code related to the template. It's formed by an unique element called XHTML, in which attribute href defined the gadget source code URL.

      <Platform.Link>

          <XHTML href="http://ezweb.morfeo-project.org/gadgets/myGadgetCode.html"/>

      </Platform.Link>

      

      

    • Rendireing. Contains information about how to show the gadget. Must contain the attributes width and height.

      <Platform.Rendering width="1" height="11"/>

      

      

    

    




[editar]
Implementation




HTML file which defines what makes the gadget, using the elements declared in the template. In its development can be used any technology supported by Web browsers (JavaScript, Flash, SVG, etc.)

While the template variables are defined as many aspects (preference, event, slot, context ,...), towards implementation there are only two types of variables: read and write, so that all the variables defined in the template are related to one of these categories:



  • Read Only variables:

    • SLOT

    • PREFERENCE

    • EXTERNAL CONTEXT 

    • GADGET CONTEXT

    

  • Read-Write variables:

    • EVENT

    • PROPERTY

    



[editar]
Declaration and Variable Usage


To make use of variables declared in the template, it's necessary to declare previously the variables in code using the EzWebAPI (see below EzWebAPI). Subsequently, we can make use of them by its methods get and set (obviously, the method set will be available only for read-write variables).



  • Read Only variables (RGadgetVariable):

    function setColorbg(color){

       ...	

    }

    var backgroundColor = EzWebAPI.createRGadgetVariable("background", setBackgroundColor);

    ...

    document.getElementById('layer').style.background=backgroundColor.get();

    

    setColorbg is a handler that the developer must define, and which will be executed by the platform when the value of the variable has been changed.

    

  • Read-Write variables (RWGadgetVariable):

    var phoneNumber = EzWebAPI.createRWGadgetVariable("phone");

    ...

    phoneNumber.set("913378986");

    ...

    var currentPhone = phoneNumber.get();

    

    



[editar]
EzWebAPI


EzWebAPI is a JavaScript API used by gadgets. Through this API, gadgets can exploit the functionality provided by the platform, which basically are:



  • Automatic management of variables (persistence, spreading events, etc.)

  • HTTP communication avoiding AJAX Cross-Domain 



Functions declared in EzWeb:



  • createRGadgetVariable. Creates a new read-only variable. Receives as parameters:

    • name. Variable name in template file.

    • handler. Handler which will be executed by the platform when the value of the variable has been changed.

    

    EzWebAPI.prototype.createRGadgetVariable = function(name, handler);

    

    

  • createRWGadgetVariable. Creates a new read-write variable. Receives as parameters:

    • name. Variable name in template file.

    

    EzWebAPI.prototype.createRWGadgetVariable = function(name);

    

    

  • send_get. Send a HTTP request using the GET method. Receives as parameters:

    • url. Target URL, where the request is sent. When using parameters, they must be encoded along with the URL as follows:

       url?param1=value1&param2=value2& ... & paramN=valueN

      

      

    • context. Due to loss of current context executing JavaScript, it's necessary to provide a pointer to this in such methods in order to call the callback function.

    • successHandler. Callback function. Will be executed when the request was made successfully.

    • errorHandler. Callback function. Will be executed during the petition when there has been some error or exception.

    

    EzWebAPI.prototype.send_get = function(url, context, successHandler, errorHandler);

    

    

  • send_post. Send a HTTP request using the POST method. Receives as parameters:

    • url. Target URL, where the request is sent. 

    • parameters. HTTP request parameters, they must be encoded as a string in the next way:

       parameters = "param1=value1&param2=value2& ... &paramN=valueN";

      

      

    • context. Pointer to this. Similar to case before.

    • successHandler. Callback function. Will be executed when the request was made successfully.

    • errorHandler. Callback function. Will be executed during the petition when there has been some error or exception.

    

    EzWebAPI.prototype.send_post = function(url, parameters, context, successHandler, errorHandler);

    

    

  • Samples







Obtenido de "http://forge.morfeo-project.org/wiki/index.php/Gadget_development_guide"