An OpenSocial Gadget is specified in an XML document that has two parts. The first part of the document specifies meta-data declaring gadget dependencies, defining characteristics about the gadget, and specifying user preferences. The meta-data can be broken up into module preferences and user preferences. The second part of the document contains the gadget content, defining the gadget’s user interface and business logic. We’ll spend time going over all these facets of gadget XML.
Below is an example OpenSocial gadget XML file for a map gadget:
For the official documentation on Gadget anatomy, see Google’s Anatomy of a Gadget. For convenience, however, let’s consider gadget meta-data and content here to highlight their important aspects.
Gadget meta-data specifies characteristics of the overall gadget and specifies controls for the user to customize the gadget. Here is a simple breakdown of these two types of meta-data:
Gadget Preferences (required): Define characteristics of the gadget. They are specified as attributes of and nested elements in the gadget’s
User Preferences (optional): Store user configuration values and allow users to give input to the application. They are specified in
Now, let’s dive deeper into gadget preferences.
Gadget Preferences (ModulePrefs)
The gadget preferences (ModulePrefs) define characteristics of your gadget, including features that it uses, how it authenticates content, how it is displayed to the user, and how it is displayed in a gadget directory. The preferences are wrapped in
Within the ModulePrefs, you specify the gadget’s dependencies with
<Require/> tags and optional features with
<Optional/> tags. If you specify a feature in a
<Require/> tag, the gadget only renders itself if the feature is available. If you specify a feature in an
<Optional/> tag, the gadget renders despite feature availability.
ModulePrefs can also be used to configure important features such as PubSub and OAuth. The PubSub feature allows for communication between gadgets on the same page: they can publish and subscribe on message channels. Liferay also enables gadgets to communicate with portlets using the same mechanism. The OAuth feature provides secure connections between your portal and third-party sites. These are just a couple of useful features that can be defined in the ModulePrefs. You’ll learn more about them later in this chapter.
<ModulePrefs> element allows you to register your gadget on a gadget directory and establish settings and tools to use in your gadget’s business logic. For complete details on ModulePrefs, see Google’s Moduleprefs Elements and Attributes reference.
Next, let’s consider gadget user preferences.
User Preferences (UserPrefs)
When a gadget is configured to fit a specific page, it can really enhance the user’s experience. OpenSocial gadgets are capable of storing user preferences, allowing gadgets to present information and options tailored for individual pages. The title UserPrefs can also be referred to as application preferences, since the preferences being changed only apply to the single gadget and not to each user that uses it. A gadget’s user preferences are specified in
<UserPref>...</UserPref> tags in the gadget’s XML. The owner of a page can adjust permissions to allow certain users to change the user preferences. However, every time the UserPrefs are modified, every user that views the gadget has a modified gadget. As a user enters information and adjusts controls via a gadget’s user interface, those changes are persisted in the database for that gadget instance. Each time the gadget is reloaded, the UserPrefs are extracted from the database, fed back to the gadget, and rendered in the user interface.
Map gadgets, for example, are prime candidates for UserPrefs. When users first bring up map gadgets, they are typically interested in their current location or a location of interest–not some random distant land. Therefore, it makes sense for a map gadget to take the user’s location of interest as input. UserPrefs facilitate taking in this information, storing it, and processing it to present gadget user interfaces customized to the user. Here are the UserPrefs for our current map gadget:
<UserPref name="lat" display_name="Latitude" required="true" /> <UserPref name="lng" display_name="Longitude" required="true" />
lng UserPrefs of the map gadget. These user preferences take in the user’s latitude and longitude preferences, stores them, and displays them on the mapping interface.
Lastly, we’ll look at what a user sees in the gadget’s user interface when setting the Latitude and Longitude user preferences.
UserPrefs can be displayed in many different ways and help your gadget become more adaptable to your users’ ever changing expectations. And, there is an extensive variety of UserPref data types available to properly personalize your gadgets. For complete details on UserPrefs see Google’s User preferences reference.
To help you decide which content type is best for you, see Google’s Choosing a Content Type documentation. But for convenience, let’s consider basic aspects of these content types here.
HTML content type
HTML is the default content type for OpenSocial gadgets. Because HTML is so flexible and commonly used for gadgets, you may find yourself using it often.
Note that all HTML content must be specified in a
CDATA section within your gadget’s content. The following simple content example demonstrates proper
<Content type="html"> <![CDATA[ "Your HTML goes here" ]]> </Content>
Also, it is forbidden to use
<html> tags in your HTML content, as these tags conflict with the ones automatically generated by the container for your gadget.
URL content type
This content type is convenient when you just want to reference content within an existing URL, and nothing more. When using this content type, specify the URL as your
href attribute value. The gadget assumes all programming and user interface logic resides in your specified URL. Therefore, when using the
Here is a sample of what the URL content type looks like for an example gadget:
<Content type="url" href="http://www/cgi-bin/example/gadgets/mystats.cgi" />
Both HTML and URL content types offer beneficial traits and can be used effectively. The content type you use for your gadgets depends on your needs and preferences.
Now that you’re fundamentally sound on the gadget basics, let’s explore what gadgets offer you in Liferay Portal.