Gadget Description

The gadgets API consists of simple building blocks:

XML: is a general purpose markup language. It describes structured data in a way that both humans and computers can read and write.

XML is the language used to write gadget specifications. A gadget is an XML file, placed on the internet where Google can find it. The XML file that specifies a gadget contains instructions on how to process and render the gadget. The XML file contains all data and code for the gadget, or it can have references (URLs) on where to find the rest of the elements.

HTML: is the markup language used to format pages on the internet. The static content of a gadget is written in HTML. HTML looks similar to XML, but is used to format web documents rather than to describe structured data.

JavaScript: is a scripting language used to add dynamic behavior to your gadgets.

Gadget XML

A gadget and its XML are synonymous. The gadget XML contains all information needed to identify and render a web application. The XML gadget specification consists of the following:

Content

The <Content> section specifies the programming logic and the HTML elements that determine the appearance of the gadget. It defines the type of content, and either holds the content itself or has a link to external content. The gadget attributes and user preferences are combined with programming logic and formatting information to become a running gadget.

<Content> provides the actual HTML, CSS, and JavaScript to be rendered by the gadget. Code is provided directly in the gadget XML content section for rendering and control flow. The code is processed by a gadget server and rendered in an IFRAME.

Code Snippet

Copy<?xml version="1.0" encoding="UTF-8"?>
<Module>
    <ModulePrefs title="Sample Gadget"
      …
</ModulePrefs>
    <UserPref name="scheme" display_name="scheme" default_value="" datatype ="hidden"/>
    <UserPref name="host" display_name="host" default_value="" datatype ="hidden"/>
    <UserPref name="hostPort" display_name="hostPort" default_value="" datatype ="hidden"/>

    <Content type="html">
        <![CDATA[
            <!DOCTYPE html>
            <!-- Styling -->
            <link rel="stylesheet" href="SampleGadget_Final.css" type="text/css" />
            …
            …
            <script type="text/javascript">
            …
            </script>
        ]]>
     </Content>
</Module>

User Preferences

The <UserPrefs> section allows you to pass custom properties to the gadget from the gadget XML. The custom properties have to be suffixed with the datatype attribute as hidden.

For example, <UserPref name="myname" display_name="Name" required="true" datatype=“hidden” />.

The user preferences are defined in the XML specifications as follows:

Code Snippet

Copy<?xml version="1.0" encoding="UTF-8"?>
<Module>
    <ModulePrefs title="Sample Gadget"
      …
</ModulePrefs>
    <UserPref name="scheme" display_name="scheme" default_value="" datatype ="hidden"/>
    <UserPref name="host" display_name="host" default_value=""  datatype ="hidden"/>
    <UserPref name="hostPort" display_name="hostPort" default_value=""  datatype ="hidden"/>

    <Content type="html">
        <![CDATA[
            <!DOCTYPE html>
            <!-- Styling -->
            <link rel="stylesheet" href="SampleGadget_Final.css" type="text/css" />
<!-- Finesse Library -->
 <script type="text/javascript" src="__UP_scheme__://__UP_host__:__UP_hostPort__/desktop/assets/js/finesse.min.js"></script>
            …
            …
            <script type="text/javascript">
            …
            </script>
        ]]>
     </Content>
</Module>

Note that for each User Preference, “hangman variables” can be substituted into supported gadget specification fields. Hangman variables are of the form __<TYPE>_<ID>__, and are replaced with string values. For each provided User Pref with key foo and value bar, hangman expansion __UP_foo__ = bar. Hence, in the above code user preference scheme is available as __UP_scheme__. Similarly, for other User Preferences the hangman variables are dynamically substituted. Also, as the datatype value is specified as hidden, the user preferences pop up for the agent to enter their own data does not show up on the gadget.

User preferences are accessed from your gadget using the user preferences JavaScript API, for example:

Code Snippet

Copy<script type="text/javascript">
  var prefs = new gadgets.Prefs();
  var someStringPref = prefs.getString("StringPrefName");
  var someIntPref = prefs.getInt("IntPrefName");
  var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Gadget JavaScript

Contains the business logic for the gadget. It can be written inside the gadget XML under the content section or an external JavaScript file can be created which can then be referred to using the src attribute in the <script> tag.

Gadget CSS

Contains the complete styling of the gadget. Similar to the JavaScript, CSS can also be referred to as an external file using href attribute in <link> tag.

Gadget Behavior

Rendering a gadget at the page level removes the title bar from the gadget layout.

Components

Components are simple scripts that are loaded into the desktop directly at predefined positions as directed by the layout, without an enclosing frame and its document.

Components have been introduced in the desktop to overcome a few rendering limitations and performance considerations inherent to gadgets.

Components are listed in the desktop layout using the <component> tag. Currently, the layout validations prevent custom components from being created. Hence, only default components are allowed in the desktop layouts. The default desktop functionalities are currently registered as components to provide flexibility and to reduce the load on the server.