93 Gadgets: Creating Your Own Gadgets

This chapter contains the following sections:

93.1 Creating Gadgets on Different CM Sites

The sample gadgets must be enabled on FirstSiteII. Developers will be interested in creating gadgets on different CM sites. The following steps outline the steps for enabling gadget support on additional CM sites:

  1. Enable the FW_CSGadget asset type and its start menu items on the CM site. (By default, the start menu items are accessible to users with the Designer, Site Admin, or General Admin role.)

  2. Share the following Template assets to the site:

    FW_CSGadget/GenerateGadgetXML and FW_CSGadget/ListSiteGadgets

(If you are reusing the sample gadgets, share their templates from FirstSiteII, enable the relevant asset types, and if necessary share the assets. For example, if you are reusing the RSS Feed Gadget, share the FW_CSGadget/G_RSS Template asset from FirstSiteII and enable the FW_RSS asset type.)

93.2 Custom Gadgets

In addition to having a knowledge of sample gadget architecture, it is helpful to see what other gadgets of type FW_CSGadget can be created. This section outlines the requirements for creating different types of gadgets. This section also provides information about the parameters defined in the descriptor XML of the RSS feed sample gadget.

This section contains the following topics:

93.2.1 New Gadget, WebCenter Sites Generates Only XML

You may want to create a new gadget where the only additional content is from another website. The RSS Feed Gadget is an example of a gadget that functions in this way. See Section 91.3.4, "RSS Feed Gadget."

Requirements in this scenario are:

  • A gadget of type FW_CSGadget referencing the template and asset listed below.

  • FW_CSGadget template that generates the body of the gadget descriptor XML (for example, FW_CSGadget /G_RSS).

  • An asset that specifies the URL to be requested in the gadget.

93.2.2 New Gadget, WebCenter Sites Generates XML and Fields Additional Requests

In this scenario, you will populate a gadget with content directly from one of WebCenter Sites' CM sites. The List, ThumbList, and Slideshow gadgets are examples of gadgets that function in this way. See Figure 92-1 and Figure 92-2.

Requirements in this scenario are:

  • A gadget of type FW_CSGadget referencing the template and asset listed below.

  • FW_CSGadget template (such as G_List) for rendering the body of the gadget descriptor XML.

  • Template(s) for rendering data to be returned in response to the additional requests made by the gadget code (for example, the G_JSON templates included with the sample gadgets).

  • Assets to be referenced by the gadget (or its additional requests).

93.2.3 Same Gadget Logic, Different Content

You can create gadgets that have the same functionality but pull different sets of content. Requirements in this scenario are:

  • An FW_CSGadget asset that references a pre-existing FW_CSGadget template.

  • Assets that provide the gadget with content.

93.2.4 Analyzing the Sample RSSFeed Gadget

A gadget's descriptor XML contains all the data defined for the gadget within the Module tag. This tag holds information about the gadget's dependencies, user preferences (if any), appearance settings, functionality, and so on.

This section analyzes the descriptor XML files of FW_CSGadget assets, using code snippets from the sample RSSFeed gadget as an example.

Analyzing the code of the RSSFeed gadget's descriptor XML file

These lines specify the properties and dependencies of the gadget:

<ModulePrefs title="FatWire RSS" height="350">
screenshot="http://localhost:8100/cs/FirstSiteII/gadgets/RSS/screenshot.png"
thumbnail="http://localhost:8100/cs/FirstSiteII/gadgets/RSS/thumbnail.png">
<Require feature="dynamic-height"/>
</ModulePrefs>

The following lines define the gadget's user preferences, which are values for the gadget that visitors can modify. In this code snippet, visitors will be able to select the number of news feeds that the RSSFeed gadget displays at one time:

<UserPref name="max" display_name="Number of Items" 
datatype="enum" default_value="5">
   <EnumValue value="1" display_value="1"/>
   <EnumValue value="3" display_value="3"/>
   <EnumValue value="5" display_value="5"/>
   <EnumValue value="10" display_value="10"/>
</UserPref>

The Content tag contains all of the content for the RSSFeed gadget's descriptor XML file, including the gadget's CSS file, which defines the gadget's appearance, and the gadget's JavaScript (contained within the <script> tag), which specifies the interactive components and initialization functionality of the gadget.

For example, the CSS file defined within the RSSFeed gadget's Content tag looks as follows:

<style type="text/css">
/* === generic styles === */
body #container {
   padding: 15px;
   padding-bottom: 5px; /* 5 plus 10 from bottom-most entry */
   margin: 0;
}
body #container * {
   padding: 0;
   margin: 0;
   font-size: 11px;
   font-family: Tahoma,Arial,Helvetica,sans-serif;
   color: #666;
}
body #container a, body #container * a {
   text-decoration: none;
   color: #555;
}
body #container a:hover, body #container * a:hover {
   color: #3b9cce;
}
.error {
  background-color: #fcc;
  color: #c00;
}
/* === gadget-specific styles === */
#container .list {
   padding-left: 1em; /* provide proper indentation space for bullets */
}
#container .list li {
   padding-bottom: 10px;
}
#container .headline {
   font-weight: bold;
}
</style>

93.3 Prerequisites for Registering Gadgets

For gadgets to be recognized by the Gadgets application, they must be registered (typically by administrators of the Gadgets application). A gadget is accessed via the WebCenter Sites URL that generates the gadget descriptor XML. This URL can be quickly obtained for every FW_CSGadget asset on the content management site by querying the FW_CSGadget/ListSiteGadgets template. The template can be easily accessed in one of the following ways:

  • In the WebCenter Sites Advanced interface, preview any FW_CSGadget asset on the site. In the InSite window, select ListSiteGadgets from the Template drop-down list.

Or:

  • Open a browser and navigate directly to

     http://<host>:<port>/<application context>/wem/<sitename>/FW_CSGadget/ListSiteGadgets

    (where host, port, and application context correspond to the WebCenter Sites installation, and sitename is the name of the content management site where the gadget exists).

The list of sample gadgets and their corresponding URLs is shown in the following figure.

Description of gadgetlist.png follows
Description of the illustration gadgetlist.png