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.
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
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.
See Section 91.1, "Before You Begin" for links to additional resources regarding the authoring of gadget descriptor XMLs.
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
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
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'