92 Gadgets: Template Flow

This chapter describes the flow of template execution, using the List Gadget as an example.

• Section 92.1, "Template Flow for the List Gadget"

• Section 92.2, "Differences in Template Flow"

• Section 92.3, "Why Server Calls are Done Separately"

92.1 Template Flow for the List Gadget

By design, the only way to request a gadget's descriptor XML is by invoking the GenerateGadgetXML template on an FW_CSGadget asset. When the template is invoked, the rendering process begins, as shown in Figure 92-1 and outlined below:

Figure 92-1 Gadget XML Output

Description of "Figure 92-1 Gadget XML Output"

1. GenerateGadgetXML first outputs the XML declaration, a recommended feature for all XML documents. Outputting the XML declaration at the beginning of the process saves gadget developers from having to consider it in every gadget they write.

2. GenerateGadgetXML then loads the asset that corresponds to the passed c (FW_CSGadget) and cid (id of ListGadget) and looks up its descriptortemplate value.

   Note:

   Together, the c and cid point to a specific asset in the WebCenter Sites system. Parameter c is the type of asset and cid is the identifier of the asset. This information is required whenever a template is invoked.

3. GenerateGadgetXML invokes the template in the descriptortemplate field (FW_CSTemplate/G_List in the case of the List Gadget), passing it the same c and cid as in step 0

   Notice that the G_List template is in itself not externally callable (its SiteCatalog entry's pageletonly field is set to T). This setting prevents these templates from being called directly (for example, in cases where they are not designed to be called).

4. The called template, G_List , outputs the entire body of the gadget descriptor XML. At this point, the gadget descriptor XML is complete.

   Note:

   See Section 91.1, "Before You Begin" for links to additional resources regarding the authoring of gadget descriptor XMLs.

Once the gadget is rendered based on its descriptor XML, the gadget retrieves its content. Figure 92-2 illustrates how the List Gadget retrieves content. This process varies, depending on the gadget. The List Gadget retrieves articles from WebCenter Sites via the following JavaScript output by the G_List template (this line of code calls a Google Gadgets API function):

gadgets.io.makeRequest(url, handleJson, params);

The G_List template crafts an additional WebCenter Sites URL, pointing to this gadget's DataAsset (in this case a Recommendation), via the G_JSON template for that asset type. That URL is eventually fed to the gadgets.io.makeRequest function, which can be used to make additional remote server calls expecting various forms of data such as XML, JSON, or even Atom/RSS. This request initiates the process of retrieving content.

Figure 92-2 Retrieving Content

Description of "Figure 92-2 Retrieving Content"

1. Gadget code in the XML body invokes the AdvCols/G_JSON template and prepares the beginning of a JSON response. Since Recommendations contain lists of other assets, the template simply begins the output of a JSON array, then loops through the list of assets, expecting to call a respective G_JSON template on each.

2. In the case of the List Gadget, all of the children are Content assets, so Content_C/G_JSON is invoked for each asset in the Recommendation. For each invocation, the Content_C/G_JSON template outputs a complete JSON object representation containing relevant fields of the asset.

3. In between individual Content_C/G_JSON calls, AdvCols/G_JSON outputs a comma to properly delimit objects in the array it is constructing. After the loop is completed, the AdvCols/G_JSON template closes the array.

4. This array is received by the gadget code: (gadgets.io.makeRequest(url, handleJson, params);), which then executes the handleJson callback function as prescribed by the original makeRequest call. The handleJson function wraps the content in HTML, which renders that gadget's view (a list view in this example).

92.2 Differences in Template Flow

The previous section illustrated template flow for the List Gadget. While template flows for the other sample gadgets are very similar, differences in their WebCenter Sites template logic are worth noting.

92.2.1 ThumbList and Slideshow

Gadget rendering follows a path in WebCenter Sites that is very similar to the path of the List Gadget. The main difference is what is invoked by the AdvCols/G_JSON template. While the List Gadget references a Recommendation filled with Content assets, the ThumbList and Slideshow gadgets reference a Recommendation containing Product assets. These gadgets also inspect attributes specific to the response of the Product_C/G_JSON template (which includes data produced by the Media_C/G_JSON template).

92.2.2 RSS

The RSS Gadget's second request is fired straight to the URL of the RSS feed, which may or may not be on WebCenter Sites. The URL is read from the associated FW_RSS asset, which is loaded within the G_RSS template.

92.3 Why Server Calls are Done Separately

You may be asking why an additional server call is always involved. For instance, why not simply retrieve all of the articles for the List Gadget from the G_List template itself? The answer to this is twofold:

1. Gadget descriptor XML may be expected to be cacheable by the gadget container. This means that developers should avoid embedding volatile data in the XML.

2. An additional server call helps to separate presentation logic (for example, in G_List) from the underlying model (in the asset types' G_JSON templates).