91 About Developing Gadgets

This chapter provides guidelines for creating gadgets based on WebCenter Sites template code.

This chapter contains the following sections:

• Section 91.1, "Before You Begin"

• Section 91.2, "Gadget Specifications"

• Section 91.3, "Sample Gadgets"

• Section 91.4, "Asset Structure"

91.1 Before You Begin

Users of this section of the guide must have:

• A developer's knowledge of WebCenter Sites' basic and flex asset models and templating.

• The Google Gadget API. Related resources are available at the following URLs:

  • The API Reference is available at:

    http://code.google.com/apis/gadgets/docs/reference/

  • The API Developer's Guide is available at:

    http://code.google.com/apis/gadgets/docs/dev_guide.html

• Familiarity with OpenSocial Standards, used to create the environment that enables gadget users to set preferences. OpenSocial documentation is available at:

  http://wiki.opensocial.org/

• The Gadgets application's sample gadgets installed on the WebCenter Sites FirstSiteII sample site. For Gadgets application installation and configuration details, see the Oracle Fusion Middleware WebCenter Sites Installation Guide For more information on the Gadgets application, see the Oracle Fusion Middleware WebCenter Sites User's Guide.

91.2 Gadget Specifications

Four sample gadgets are included with the Gadgets application. They are enabled on the FirstSiteII sample site. You can develop your own gadgets, using the processes outlined in this guide. The sample gadgets are:

• List Gadget, which presents a listing of headlines and article summaries, linking to their respective full articles.

• ThumbList Gadget, which presents a list of products, with a thumbnail accompanying each product's description.

• Slideshow Gadget, which renders a series of product images into a slideshow, where the user can click on a thumbnail to view a larger image, then click the larger image to open the page containing full details on the product.

• RSS Feed, which presents a list of headlines retrieved from an RSS feed. Each headline links to a full article.

The rest of this chapter provides information about the gadgets' major components and describes the sample gadgets in detail.

This section contains the following topics:

• Section 91.2.1, "Asset Model and Templates"

• Section 91.2.2, "Sample Assets"

• Section 91.2.3, "Auxiliary Files"

91.2.1 Asset Model and Templates

Installing the sample gadgets on FirstSiteII installs the basic components for creating and rendering gadgets. The components are the data model, templates, and sample assets that provide the gadgets' content:

• FW_CSGadget asset type (its description is CS-Based Gadget ). All sample gadgets are of type FW_CSGadget .

• FW_RSS asset type (its description is RSS Feed ). This asset type is used to specify a URL as the source of content for the RSS Feed gadget.

• FW_CSGadget/GenerateGadgetXML template, which is accessed by the Gadgets application. This template is used to render the gadget descriptor XML (also referred to as gadget specification XML).

• FW_CSGadget/ListSiteGadgets template, which provides a gadget descriptor URL for each gadget on the current content management site.

91.2.2 Sample Assets

The sample assets either provide content for the gadgets or they render the gadgets. The sample assets are referenced by the sample gadgets as described below:

• Gadget content is provided by:

  • Content assets of type Content_C (with parent of type Content_P), representing sports articles. These assets are used by the List Gadget.

  • Product assets of type Product_C (with parent of type Product_P), representing sports products. These assets are used by the ThumbList and Slideshow gadgets.

  • Media assets of type Media_C (with parent of type Media_P), representing images used by the Product assets. These assets are used by the ThumbList and Slideshow gadgets.

  • Recommendation (AdvCols) assets, encapsulating the Content and Product assets. Recommendation assets are used by the List, ThumbList, and Slideshow sample gadgets.

  • Content of type FW_RSS , which specifies a URL as the source of content for the RSS Feed gadget.

• Templates render the gadgets:

  • The GenerateGadgetXML template is accessed by the Gadgets application and calls the templates listed below.

  • An FW_CSGadget -typed template exists for each of the sample gadgets. Each of these templates outputs the body of a gadget descriptor XML understandable by the Gadgets application. The templates are G_List, G_RSS, G_Slideshow, and G_ThumbList .

  • A typed template named G_JSON exists for each of the asset types referenced by the sample gadgets: Content_C , Media_C , Product_C , and Recommendation (AdvCols ). These templates provide JSON-formatted output containing data necessary to render the HTML for each asset that is displayed in the gadgets. The templates are invoked via remote requests made in the gadget code.

91.2.3 Auxiliary Files

The following image files are used by the sample gadgets:

• Scroller arrow images used by the Slideshow gadget (Figure 91-1 and Figure 91-2). These static images are located in the FirstSiteII/gadgets subdirectory under the WebCenter Sites web application.

• Images used as icons, thumbnails, and previews to represent a gadget's various sections. The default images are located in the sample/GadgetImages directory in the gadgetserver.zip installation package.

  Figure 91-1 Images used by sample gadgets

  
  Description of "Figure 91-1 Images used by sample gadgets "
  
  

  Figure 91-2 Images used by sample gadgets

  
  Description of "Figure 91-2 Images used by sample gadgets "
  
  

91.3 Sample Gadgets

This section outlines the WebCenter Sites sample gadgets and the assets they use. Each asset is listed in the same order in which it is called by the Gadgets application when the Gadgets application initiates the request. This section of the guide uses the List Gadget in particular to illustrate various concepts.

This section contains the following topics:

• Section 91.3.1, "List Gadget"

• Section 91.3.2, "ThumbList Gadget"

• Section 91.3.3, "Slideshow Gadget"

• Section 91.3.4, "RSS Feed Gadget"

91.3.1 List Gadget

The List Gadget renders a Recommendation asset containing a list view of Content assets. Each headline links to its full article.

Description of the illustration listgadget.png

The List Gadget asset references the Recommendation asset to be rendered in the gadget and the template (G_List ) that will render the gadget. The relevant assets are:

• The ListGadget asset of type FW_CSGadget, referencing the Recommendation asset to be rendered.

• The G_List template, which produces the body of the gadget descriptor XML used by the Gadgets application to render the gadget. This process is outlined in Chapter 92, "Gadgets: Template Flow."

• G_JSON templates, which render the Recommendation asset and its content:

  AdvCols/G_JSON and Content_C/G_JSON
  

• The Recommendation (AdvCols) asset to be rendered in the gadget.

• Content assets included in the Recommendation.

91.3.2 ThumbList Gadget

The ThumbList Gadget is similar to the List Gadget in that it also renders a Recommendation asset. The gadget contains a list view of Product assets. Each headline links to its product page. However, in this gadget, each product is accompanied by a thumbnail image from a Media asset, which is associated with the Product assets via their "Image" attribute.

Description of the illustration thumblist.png

The relevant assets are:

• The ThumbListGadget asset of type FW_CSGadget , referencing the Recommendation to be rendered and the template (G_ThumbList ) that will render the gadget.

• The G_ThumbList template which produces the body of the gadget descriptor XML used by the Gadgets application to render the gadget.

• G_JSON templates, which render the Recommendation asset and its content:AdvCols/G_JSON , Product_C/G_JSON , and Media_C/G_JSON

• The Recommendation (AdvCols) asset to be rendered in the gadget.

• Product assets included in the Recommendation asset.

• Media assets referenced by the "Image" attribute of each of the Product assets.

91.3.3 Slideshow Gadget

The Slideshow gadget uses the same content as the ThumbList gadget, but presents the content in an entirely different manner. This gadget displays a thumbnail strip filled with product images. Clicking on an image in the strip displays the image at the maximum size allowed by the gadget area. Clicking the full-size image opens the product's detail page.

Description of the illustration strip.png

The relevant assets are:

• The SlideshowGadget asset referencing the Recommendation asset to be rendered and the template (G_Slideshow ) that will render the gadget.

• The G_Slideshow template which produces the body of the gadget descriptor XML used by the Gadgets application to render the gadget.

• G_JSON templates which render the Recommendation asset and its content:AdvCols/G_JSON , Product_C/G_JSON , and Media_C/G_JSON

• The Recommendation (AdvCols) asset to be rendered in the gadget.

• Product assets included in the Recommendation asset.

• Media assets referenced by the "Image" attribute of each Product asset.

91.3.4 RSS Feed Gadget

The RSS Feed gadget displays the most recent items from an RSS feed, utilizing the Google Gadget API for its built-in feed-reading functionality.

Description of the illustration rss.png

The relevant assets are:

• The RSSGadget asset of type FW_CSGadget referencing the feed (FW_RSS ) to be requested and the template (G_RSS ) that will render the gadget.

• The G_RSS template which produces the body of the gadget descriptor XML used by the Gadgets application to render the gadget.

• An FW_RSS asset containing the feed URL to be requested in the gadget.

91.4 Asset Structure

The sample gadgets are based on a new asset type, FW_CSGadget , which is used to specify information required for rendering the gadgets. It is a basic asset type, containing the following attributes:

• Name of descriptor template is used to specify the name of the FW_CSGadget template that will be invoked to generate the gadget's descriptor XML. For the List Gadget, the template is FW_CSGadget/G_List (hence, G_List is specified in this field and later resolved as a typed template).

• The DataAsset association is a single, any-type asset association. This association references the asset that provides the main content of the gadget. For example, the DataAsset association for the List Gadget references a Recommendation asset containing a static list of Content assets to be rendered by the gadget.

Description of the illustration cs_basedgadget.png

The descriptor template attribute is read by the FW_CSGadget/GenerateGadgetXML template. The DataAsset association is read by the descriptor template itself (for example, G_List).