17 Working with Pagelets and Gadgets

Use Oracle WebCenter Portal's Pagelet Producer to create pagelets.

Topics:

• Working with OpenSocial Gadgets

• Working with Pagelet Chrome for WSRP and Oracle PDK-Java Portlets

Working with OpenSocial Gadgets

Any OpenSocial gadget reachable by the Pagelet Producer server can be registered as a pagelet and used in any Web application, including a portal. To support OpenSocial gadgets, you must first define an OpenSocial container as described in How to Configure OpenSocial Settings.

Pagelet Producer supports most of the standard OpenSocial APIs excluding OAuth. The complete OpenSocial API reference documentation can be found here:

http://docs.opensocial.org/display/OSD/Specs

Pagelet Producer also allows gadgets to store preferences, retrieve WebCenter Portal profile and connection information, and access a user's activity stream using OpenSocial APIs.

This section contains the following topics:

• How to Configure Authentication

• How to Store User Preferences

• How to Access WebCenter Portal Profile Information

• How to Access a User's Activity Stream

• How to Use Gadget Eventing

• Example: How to Consume an External OpenSocial Gadget

• Example: How to Consume a Local OpenSocial Gadget

How to Configure Authentication

In order for gadgets to request user-level data (preferences or people connections), the end user's identity must be established. If any OpenSocial gadgets need to access user-level data from the server, you must configure a security policy for the parent OpenSocial resource in the Pagelet Producer Console (see How to Configure Policy Settings). The first time a user accesses an OpenSocial gadget, a login page will be presented. After the initial login, subsequent requests for OpenSocial gadgets will use the established user identity.

How to Store User Preferences

OpenSocial gadgets may use user preferences to store data at the container. User preferences are scoped to a particular user and may optionally be scoped to an appId (the gadget appId is the pagelet context ID). If you choose to use the OpenSocial gadget.Prefs API, the user preferences will be scoped to the user and pagelet instance. Alternatively, you may use the opensocial.DataRequest API to manage preferences at the user level that can be shared with other pagelets.

When registered as a pagelet, a gadget's user preferences are treated as pagelet preferences. In WebCenter Portal, for example, non-hidden user preferences can be edited by the end user using the Personalize button. Additionally, to simulate preferences shared between users, you may pass in user preferences via pagelet parameters. Note that a pagelet preference, if set, will always override the corresponding pagelet parameter (in other words, personalization takes precedence over customizations).

Outside of WebCenter Portal, gadget-backed pagelets are provided with a simple chrome that displays the gadget title and buttons for accessing the preference editor and minimizing/maximizing the gadget. The chrome may be suppressed by passing in the value of 'none' to the chrome parameter in the Pagelet Inject API. The preference editor UI supports all four types of user preferences:

• string: rendered as a text field

• bool: rendered as a checkbox

• enum: rendered as a dropdown list

• list: rendered as a text field (values must be separated with a pipe "│" character)

How to Access WebCenter Portal Profile Information

OpenSocial gadgets can query the current user's profile data and people connections via the standard OpenSocial API. To use this feature, you must manually target the WebCenterDS data source to the WC_Portlet server as described in Managing the Pagelet Producer in Administering Oracle WebCenter Portal.

Note:

The OpenSocial API cannot be used to update profile or connection information.

The supported user profile fields are listed in Table 17-1.

Table 17-1 User Profile Fields

OpenSocial Field	Type	Description
aboutme	string	A general statement about the person.
addresses	Plural-Field <Address>	A physical mailing address for the person.
appData	Plural-Field <AppData>	A collection of AppData keys and values, used for preferences.
birthday	Date	The birthday of the person. The value must be a valid Date. The year may be set to 0000 when the age of the person is private or the year is not available.
emails	Plural-Field <string>	Email address for the person.
location	string	Physical address for the person.
name	Name	The broken-out components and formatted version of the person's real name.
organizations	Plural-Field <Organization>	Current or past organizational affiliation of the person.
phoneNumbers	Plural-Field <string>	Phone number for the person. In addition to the standard canonical values for type, this field defines the additional values mobile, fax, and pager.
photos	Plural-Field <string>	URL to a photo of the person. The value must point to an actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a Web page containing an image. Note that this field should only be used to download profile photos of the contact suitable for display when describing the contact.
preferredUsername	string	The preferred username of this person on sites that ask for a username (e.g., jsmarr or daveman692).
status	string	The person's status, headline or shoutout.
thumbnailUrl	string	The person's photo thumbnail URL, specified as a string. This URL MUST be fully qualified.

How to Access a User's Activity Stream

OpenSocial gadgets can operate on a user's activity stream using OpenSocial APIs. The following operations are supported:

• get activities

• create activity

The following operations are not supported:

• update activity

• delete activity

The supported activity stream fields are listed in Table 17-2.

Table 17-2 Activity Stream Fields

OpenSocial Field	Type	Description
appId	Object-Id	The application with which the activity is associated.
body	string	An optional expanded version of the activity. Bodies may only have the following HTML tags: <b> <i>, <a>, <span>, but this formatting may be ignored.
externalId	Object-Id	An optional ID generated by the posting application.
id	Object-Id	An ID that is permanently associated with the activity.
postedTime	string	The time at which the activity took place in milliseconds since the epoch.
priority	number	A number between 0 and 1 representing the relative priority of the activity in relation to other activities from the same source.
title	string	The primary text of the activity. Titles may only have the following HTML tags: <b> <i>, <a>, <span>, but this formatting may be ignored.
userId	Object-Id	ID of the user for whom the activity is defined.

How to Use Gadget Eventing

Pagelet Producer supports the OpenSocial pubsub inter-gadget eventing model. A gadget may publish events over any number of arbitrary channels (defined by simple string names) in JavaScript. On the receiving end, a gadget may subscribe to receive events over any number of channels, again in JavaScript, and take appropriate actions based on the events.

function connSelected(element) {
var connId =element.id;
 var connName =element.lastChild.textContent;
 gadgets.pubsub.publish(channel, {id: connId, name: connName});

For a complete JavaScript reference to the supported eventing API, see:

http://docs.opensocial.org/display/OSD/Specs

Example: How to Consume an External OpenSocial Gadget

The example that follows is simplified for illustration. To support OpenSocial gadgets, you must first define an OpenSocial container as described in How to Configure OpenSocial Settings.

1. Using the Pagelet Producer Console, create a new Resource and choose OpenSocial as the type. Define URLs and policies as necessary. Save the new Resource.

2. Using the Pagelet Producer Console, create a new pagelet and enter the location of the gadget XML schema in the Gadget URL field.

   • To import the gadget name and any user preferences defined for the gadget, click the Import Gadget Metadata button. If any of the preferences are editable, Pagelet Producer will create a preference editor using the imported preferences.

   • To configure or customize the generated preference editor, go to the Pagelet Parameters page.

3. Go to the Documentation page to view sample code to access the pagelet and preference editor using either the JavaScript or REST API.

4. Save the new pagelet.

Example: How to Consume a Local OpenSocial Gadget

The example that follows is simplified for illustration. To support OpenSocial gadgets, you must first define an OpenSocial container as described in How to Configure OpenSocial Settings.

1. Using the Pagelet Producer Console, create a new Resource and choose OpenSocial as the type. Define URLs and policies as necessary. Save the new Resource.

2. Create or upload the gadget file.

   Note:

   If you choose to host OpenSocial gadget XML files, the files must be placed under an anonymous resource (with no security policy) or gadget functionality will not work correctly.

   1. Select the Files section under the resource and click the Create icon in the toolbar.

   2. On the General page, enter the relative path to the file in the Name field. Do not use a leading forward-slash ("/"). For example, "gadgets/activities.xml". Any path and name can be used; the path is a ‘virtual’ URL that Pagelet Producer will use to serve the file. The visual directory structure of the Files collection in the navigator is updated to match the path to the file.

   3. Go to the Content page to upload or create the gadget file.

      To upload a gadget file, enter the path to the file or click the Browse button to navigate to the file, then click the Upload button to upload the file to the Pagelet Producer server.

      To create a gadget file, use the editor on the Content page to enter and edit content.

   4. Click the Save icon in the navigator toolbar.

3. Create or upload any other files required by the gadget (JavaScript, images, etc.) in the Files section of the resource. Define paths for the files that match the paths in the gadget code. For example, if the gadget uses JavaScript files in a subfolder called "js", include that directory in the Name field when you upload the files, (for example, "gadgets/js/activities.js".)

4. Using the Pagelet Producer Console, create a new pagelet and enter the relative path to the gadget XML schema (created or uploaded in step 2) in the Gadget URL field. For local files, this is the same path defined in the Name field for the file object (for example, "gadgets/activities.xml").

   • To import the gadget name and any user preferences defined for the gadget, click the Import Gadget Metadata button. If any of the preferences are editable, Pagelet Producer will create a preference editor using the imported preferences.

5. Go to the Documentation page to view sample code to access the pagelet and preference editor using either the JavaScript or REST API.

6. Save the new pagelet.

Working with Pagelet Chrome for WSRP and Oracle PDK-Java Portlets

Pagelet Producer can be used to present WSRP and Oracle PDK-Java portlets for use in any web application. This section explains how to use pagelet chrome to modify markup at runtime in WSRP or Oracle PDK-Java portlets. For details on configuring the Pagelet Producer to connect to a WSRP or Oracle PDK-Java portlet producer, see Managing Pagelet Producer in Administering Oracle WebCenter Portal.

A pagelet chrome template is an HTML file that specifies:

• How portlet markup should be rendered stylistically

• How to display the portlet title

• How to render mode switching options

The default chrome template displays the portlet name and a dropdown menu that allows the user to switch into different modes. The dropdown menu is dynamically populated with all the standard modes supported by the underlying portlet. Templates use the following reserved tokens (see Table 17-3) to identify key portlet elements that Pagelet Producer then substitutes at runtime.

Table 17-3 Pagelet Chrome Template Tokens

Token	Description
$$PORTLET TITLE$$	Portlet title
$$REPEAT MENU ITEM$$	Used to indicate the beginning of a repeating section for navigational items
$$END REPEAT MENU ITEM$$	Used to indicate the end of a repeating section for navigational items
$$MENU ITEM URL$$	Navigation URL (to switch portlet modes or window states)
$$MENU ITEM$$	Display name of navigational item (for example, Customize)
$$TOKEN$$	Unique identifier for pagelet instance on the page
$$PORTLET CONTENT$$	Portlet content
pt://images	Tag used to indicate the imageserver URL

The example below is a very simple pagelet chrome template:

<script type="text/javascript">
function goto(url)
{
 document.location =url;
 return false;
}
</script>
<div style="border: 1px solid">
<span><b><!-- $$PORTLET TITLE$$ --></b></span>
<span style="align: right">
 Switch Mode:
 <select size="1" name="mode">
 <!-- $$REPEAT MENU ITEM$$ -->
 <option onclick="goto('$$MENU ITEM URL$$')"><!-- $$MENU ITEM$$ --></option>
 <!-- $$END REPEAT MENU ITEM$$ -->
 </select>
 
</span>
</div>
<!-- $$PORTLET CONTENT$$ -->

Note:

The pagelet chrome template file must be hosted on the classpath of the Pagelet Producer web application.

If you configured Pagelet Producer to use an external image server, copy the files from ensemblestatic.war/imageserver/yahoo to your image server to properly render the default chrome template.

To implement the chrome template, add it as a parameter to the pagelet inject URL (REST or JavaScript). For details on pagelet inject URLs, see Adding a Pagelet to a Web Page. For example:

• REST: /inject/v2/pagelet/pagelet_lib/pagelet_name?chrome=mychrome.html

• JavaScript: injectpagelet(library, name, iframe_options, payload, params, context_id, element_id, is_in_community, chrome)

The value of the chrome parameter can be the name of the file containing the chrome template or the special reserved value "none", which suppresses all chrome and sends back portlet markup only. If the chrome parameter is omitted, the default chrome is returned with the portlet markup. The default chrome template uses YUI menu control to display a gradient title bar and a DHTML dropdown menu for switching modes. (When ADF content is detected, a different chrome template is used by default. This template can be overridden with a custom template or with the standard default template by setting chrome=chrometemplate.html.)