This chapter describes the flow of template execution, using the List Gadget as an example.
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:
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.
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.
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).
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.
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.
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.
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.
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).
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.
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).
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:
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.
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).