iWidget support in the Home page 

   

This section deals with the specifics of implementing widgets for the Home page.  

In the Home page, the administrator makes the widgets available to end-users using the Administration tab in the Home page user interface. (See "Adding widgets to the Home page" in the Lotus Connections Information Center for more information.) End-users can then customize the Home page by adding new widgets to their page from the widget palette. The administrator can also specify which widgets are open by default for new users. For more information, see "Managing widgets" in the Lotus Connections Information Center.  

Widgets can be added to the following placement areas in the Home page:  

• On the Updates tab (which shows the "river of news") - users can add widgets to the sidebar, under the MY STATUS widget.
   
  
  

 

• On the My Page tab (the legacy Widgets page from Lotus Connections 2.0) - the entire page is a placement area where users can place widgets.
   
   

Accessing Lotus Connections components  
Due to different configurations in the deployment of the IBM® Lotus® Connections features, the URL of each feature might not be known at widget development time. To overcome this limitation, the Home page provides a functionality that inserts the root URL of the different Lotus Connections features into the XML descriptor dynamically.
The following variables can be used in your iWidget XML descriptor. These variables will be substituted automatically with the real URL of the component.Typically, you might want to use these variables in an ItemSet to get the value in the JavaScript™ code of your widget.  

Component	Variable
Activities	{activities}
Blogs	{blogs}
Dogear	{dogear}
Profiles	{profiles}
Communities	{communities}
Homepage	{homepage}
Wikis	{wikis}
Files	{files}
Real XML file path	{widgetContextRoot}

For example  


will be substituted with the following code  

Widget action title bar and modes  
A set of actions is associated with each widget in the Home page. The end-user can interact with the actions using a drop-down list that can be opened from the title bar of the widget.  

The drop-down list containing the actions is built automatically by the Home page and includes the following actions.  

• 2 types of actions display for all widgets:  
• Remove - this action closes the widget and returns it to the widget palette.  
• Move - a set of move actions for moving the widget to rearrange the layout of the page.
• 2 additional actions display depending on the actions supported by the widget:  
• Edit - displays edit preferences for the widget, if supported.
• Help - displays help documentation, if provided.

The Home page runtime determines which actions to display, depending on the modes declared in the XML definition of the widget in the supportedModes attribute of the XML descriptor.
   
The following example defines the Edit and Help modes in the supportedModes attribute:
   
When the user selects the Edit or Help actions in the drop-down list, the standard predefined onModeChanged iEvent is fired against the iWidget with the following payload: {"newMode": "edit"} (resp. help)  

As a result, the iWidget framework loads the appropriat e markup for this mode automatically (iw:content mode="edit" or "help") and calls a method named “onedit” (resp. “onhelp”) on the iScope of your iWidget, if such a method is defined. This is typically the place to include custom code that is executed after disp laying the new markup of the mode.  

Note: The iWidget developer is responsible for providing a way to return to the normal (or any other) view for the edit/help view. For example, this can be done by publishing the onModeChanged event from the code of the widget using the following code:
this.iContext.iEvents.fireEvent("onModeChanged", null, "{newMode: 'view'}");  
In the Home page, preferences are persisted on a per-user and per-widget basis.  
   
For more information on persisting widget parameters across user sessions, see "Persisting widget preferences using managed itemSets" in Common iWidget support in Lotus Connections.  
 


Parent topic  
Lotus Connections iWidget Development Guide  
   
Related topics  
iWidget Overview  
Common iWidget support in Lotus Connections  


iWidget support in Profiles and Communities  
Best practices for iWidget development  
   
   
Authors: Vincent Burckhardt and Ronny Pena