Overview: Developing a dynamic UI configuration

Overview: Developing a dynamic UI configuration

Only standard portlets can launch dynamic UIs. IBM portlets, however, can be launched as dynamic portlets and receive properties. Standard portlets can also launch dynamic pages containing a mixture of standard and IBM portlets.
Planning. Determine the requirements of the dynamic UI configuration. The following are some of the questions that can help you in the planning process.

What is the layout of the page definition?

Should the page definitions be viewable by users? If not, where in the portal topology should they be placed?

Where should the extension node be placed in the portal topology?

What information needs to be passed to each dynamic UI? How will the portlets use that information?

How will the UI be closed? Should we use tags to allow the user to close dynamic pages and dynamic portlets? If not, is it the responsibility of the calling portlet or a dynamic portlet to close the UI?

Create the extension node for dynamic pages.

Create the page to be used for containing dynamic UIs.

Assign a unique name to the node. To do this, use the Unique names portlet.

Open a command prompt.

cd WP_PROFILE/ConfigEngine.

Run the following configuration task:
./ConfigEngine.sh action-enable-page-as-extension-node-wp.dynamicui.config -DPageUniqueName=pageUniqueName [-DVirtualPortalContext=vpContext]

where pageUniqueName is the unique name of the extension node and vpContext is the context of the virtual portal the specified page is part of. The -DVirtualPortalContext flag is needed only in the case where a virtual portal is used. This command designates the page as an extension node. If we subsequently need to remove the extension node designation, run the command using the action-disable-page-as-extension-node-wp.dynamicui.config task.
Develop the portlet definition for dynamic portlets. Any existing portlet can be used as the definition for a dynamic portlet. For standard portlets, be sure to set the ID attribute for the <portlet-app/> element in portlet.xml. The launching portlet uses this value, plus the <portlet-name/>, to obtain the object ID of the portlet definition. For IBM portlets, the uid attribute of the <portlet-app/> element is used. Determine what properties need to be passed to the portlet.
Portlet deployment descriptor considerations
To receive portlet properties, the com.ibm.portal.context.enable preference parameter must be set in the portlet.xml with a value of true. By default, this value is set to false.
For standard portlets:
<portlet-preferences>
    ...
    <preference>
    <name>com.ibm.portal.context.enable</name>
    <value>true</value>
   </preference>
   ...
</portlet-preferences>
For IBM portlets
...
   <config-param>
      <param-name>com.ibm.portal.context.enable</param-name>
      <param-value>true</param-value>
   </config-param>
... 
Additionally, we must also modify the file web.xml for IBM portlets to receive portlet properties. The servlet class entry should specify the com.ibm.wps.pb.wrapper.PortletWrapper class. SeePackaging, deploying and compiling cooperative portlets for more information and an example.
Considerations for retrieving context
Standard portlets receive page properties on the processAction() method using the com.ibm.portal.context request attribute. The value of this attribute is a Map storing the context entries. Each property value is obtained by name. The name and value of each property value is determined by the requirements of the dynamic UI configuration. Use the following code sample to get a value for the property with the name propertyName:
public void processAction (ActionRequest request, ActionResponse response)              throws PortletException, java.io.IOException
{
           // perform application specific action handling    ...
              // perform page context processing        String specialAction = request.getParameter("com.ibm.portal.action");
     if (specialAction != null &&
       specialAction.equals("com.ibm.portal.context.receive"))     {
      //this indicates context was passed to the launched page       java.util.Map contextMap = (java.util.Map)
      request.getAttribute("com.ibm.portal.context");
       Object propertyValue =  (Object) contextMap.get(<propertyName>);
             portletSession.setAttribute(<propertyName>, propertyValue);
            }
 }
IBM portlets implement the PropertyListener interface that provides the setProperties() method, which provides the page properties as an array of PropertyValue objects. In this sample, a loop is used to scan the array for the task properties.
public void setProperties(PortletRequest request, PropertyValue contextArray[])
{
          Object propertyValue;
    for (int i = 0; i < contextArray.length; i++)     {
      String propertyName = contextArray[i].getProperty().getName();
       if(propertyName.equals(<propertyName>))
      {
         propertyValue = (Object)contextArray[i].getValue();
      }
            }
    request.getSession().setAttribute(<propertyName>, propertyValue);
       }
IBM portlet considerations

To receive portlet properties, the com.ibm.portal.context.enable configuration parameter is specified in the portlet.xml. This parameter plays the same functional role as the standard portlet preference. Additionally, we must also modify web.xml to receive portlet properties. The servlet class entry should specify the com.ibm.wps.pb.wrapper.PortletWrapper class. See the Packaging, deploying and compiling cooperative portlets section for more information.
Develop the page definition for dynamic pages.

Create the layout and content of the page definition from which dynamic pages are launched. For development purposes, use Manage Pages as we work with the visual layout.

Assign a unique name to the page using the Unique names portlet. The portlet uses this name to lookup the object ID of the page definition.
Develop the dynamic UI launching portlet
Use JNDI lookup, obtain a reference to the required portlet services.
private DynamicUIManagementFactoryService dynamicUIManagerFactoryService;
private RedirectURLGeneratorFactoryService redirectService;
PropertyFactory propertyFactory;
...
 // Obtain a reference to the Dynamic UI Management Factory service PortletServiceHome dynamicUIManagerFactoryServiceHome = (PortletServiceHome)     ctx.lookup("portletservice/com.ibm.portal.portlet.service.dynamicui.DynamicUIManagementFactoryService");  dynamicUIManagerFactoryService = (DynamicUIManagementFactoryService)     dynamicUIManagerFactoryServiceHome.getPortletService(DynamicUIManagementFactoryService.class);
 // Obtain a reference to the property factory PortletServiceHome serviceHome = (PortletServiceHome)     ctx.lookup("portletservice/com.ibm.portal.propertybroker.service.PropertyFactory");     propertyFactory =       (PropertyFactory)serviceHome.getPortletService(com.ibm.portal.propertybroker.service.PropertyFactory.class);
 // If the dynamic UI should be displayed immediately upon launch, // obtain a reference to the RedirectURLGeneratorFactory service     PortletServiceHome redirectServiceHome = (PortletServiceHome)        ctx.lookup("portletservice/com.ibm.portal.portlet.service.state.RedirectURLGeneratorFactoryService");
   redirectService = (RedirectURLGeneratorFactoryService)     redirectServiceHome.getPortletService(RedirectURLGeneratorFactoryService.class);
Obtain the object ID of the page definition or portlet definition. This can be done using either a unique name (for a page or portlet definition) or portlet name + portlet-app ID (portlet definition only).

Use a unique name:

Context ctx = new InitialContext(); ... Name uniqueName = new CompositeName("portal:uniquename"); uniqueName.add(yourUniqueName); ObjectID oidForName = (ObjectID) ctx.lookup(uniqueName);

Use portlet name + porlet-app id:

Context ctx = new InitialContext(); ... Name portletName = new CompositeName("portal:config/portletdefinition"); portletName.add(appID); portletName.add(portletName); ObjectID portletDefOID = (ObjectID) ctx.lookup(portletName);
Obtain an instance of the DynamicUICtrl interface from the factory. The factory expects the Render/ Action Request/Response followed by the configuration name (String) as input parameters. The DynamicUICtrl returned is parameterized with the request/response. The DynamicUICtrl must be obtained once per request and should not be stored.
DynamicUICtrl DynamicUICtrl =      dynamicUIManagerFactoryService.getDynamicUICtrl(request, response, extensionNode);
Create the properties that need to be passed to the dynamic UI.
PropertyController property1 = propertyFactory.createProperty(config);  property1.setName(propertyKey);
property1.setClassname("java.lang.String");
property1.setDirection(Direction.OUT);
 PropertyValue value =      propertyFactory.createPropertyValue(request, property1, propertyValue);
PropertyValue[] propertyValues = new PropertyValue[1];
propertyValues[0] = value;  
Launch the dynamic UI using the addPage() or addPortlet methods and passing the object ID of the page/portlet definition. Example of launching a page:
DynamicUICtrl.addPage(pageDefinitionID,  new LocalizedImpl(title,description), propertyValues);
Optional: Navigate the user to the newly launched page using a redirect.
RedirectURLGenerator redirector =      redirectService.getURLGenerator(request, response);
EngineURL redirectURL = redirector.createPortletURL(launchedPortlet);
 response.sendRedirect(redirectURL.toString());
Provide controls for closing dynamic UIs. In many cases we can allow the user to explicitly close a dynamic UI from a theme or skin. These icons are enabled using the <portal:closePage/> and <portal:closePortlet/> tags. See Tags used by the portal theme JSPs for more information.
As an alternative, the launching portlet can close a dynamic UI using the removePage() or removePortlet() methods of the DynamicUICtrl interface, providing the object ID of the dynamic UI as input on the call. If removing a dynamic portlet, the calling portlet must be on the same page.

Test the configuration. Each dynamic UI configuration has its own requirements, design, and implementation, and therefore, a different set of test cases. However, we should always verify the following general behaviors.

Pages and portlets are created and removed successfully.

Each time a dynamic UI is launched, a new instance of the page or portlet is created or, in the case of shared dynamic UIs, the user is returned to an existing instance.

Properties are passed and processed by the dynamic portlets as expected.

As portlets are added and removed from a dynamic page, the page maintains a balanced layout.

Deploy the configuration When the dynamic UI configuration is ready to be promoted to a production level server, create the xmlaccess.sh scripts containing the necessary page and portlet definitions. Use the Manage Pages portlet to export the page configuration to xmlaccess, including any wires or unique names used by the configuration.
Parent Dynamic user interfaces