Creating a Portlet Template (Editable Portlet)

A portlet template is a portlet from which users can create their own portlet instances. When created, the new portlet instance belongs to the user. By clicking the portlet's Edit icon, the user can change the portlet's behavior as enabled by the editor action that is associated with the portlet.

The portal Web application is delivered with three portlet templates: the Collection Portlet template, the WebDAV Navigator Portlet template, and the URL Display Portlet template. The Add a Portlet function of the portal Web application enables users who have the appropriate permissions to create new instances of these portlets. Users can then edit the portlets that they have created.

The SAS Web Infrastructure Kit enables you to develop and deploy additional portlet templates. After you deploy a new portlet template, the template name appears in the drop-down box on the Create a New Portlet dialog box along with the Collection Portlet and the WebDAV Navigator Portlet.

To create a new portlet template, use the following steps:

1. Code the portlet deployment descriptor file to support replication and editing capabilities.

2. Code the editor action class.

3. Code the editor JSP page.

4. Create resource bundles to support localized text.

Step 1: Code the Portlet Deployment Descriptor File

To support replication and editing capabilities, code the portlet deployment descriptor file (portlet.xml) as follows:

1. In the local-portlet element, specify the attribute value editorType="portlet". This value indicates that portlets created from the template are to be editable.

   Note: If you specify this attribute value, you must also specify a portlet action with the attribute editor="true", as described in Step 1-c, which follows. Otherwise, the portlet deployer will send a warning to the server log and will not deploy the portlet.

2. In the deployment element, specify the attribute value userCanCreateMore="true". This value indicates that the portlet is a template and can be replicated by portal users.

3. Code the action elements as follows:

   • Code a default action to specify processing that is to occur before the portlet's JSP page renders, as in this example:

     <portlet-action name="display" default="true">
       <type>com.mycompany.portlets.NavigatorAction</type>
     </portlet-action>
     

   • You must code an <action> element to specify the editor action which is to be invoked when a user clicks the portlet's Edit icon. Use the attribute value editor="true" to indicate that the action is for this purpose, as in the following example:

     <portlet-action name="editor" editor="true" >
       <type>com.mycompany.portlets.EditorAction</type>
     </portlet-action>
     

   • Code <action> elements to specify the actions that are to be invoked when the user clicks buttons on the editor JSP page, as in the following example:

     <portlet-action name="ok" default="false" >
       <type>com.mycompany.portlets.ReturnAction</type>
     </portlet-action>
     <portlet-action name="cancel" default="false" >
       <type>com.mycompany.portlets.CancelAction</type>
     </portlet-action>
     

Step 2: Code the Editor Action Class

Code the editor action class, which is the class that is to be invoked when a user clicks the portlet's Edit icon. In the portlet deployment descriptor file, the name of this action class must be specified in the <action> element with the attribute value editor="true", as described previously in Step 1-c. The editor action class should do the following:

1. The action class should place the portlet's navigation path into the PortletContext object so that it can be used by the portlet's JSP page.

2. The action class should use the com.sas.portal.portlet.NavigationUtil class to create URLs for buttons on the JSP page (for example, OK and Cancel). You can place the URLs into either the HttpServletRequest object or in the PortletContext object.

3. When editing is complete, the action class should display the portlet again using the default display action. (This is necessary because the portlet takes over the entire page as its display mode when it is in edit mode.) To reset the display, use these steps:

   1. Check to see that edit mode is active. This is necessary because the editor might have delegated control to other portlet actions that use the default display.

   2. If edit mode is active, call the PortletContext's resetMode() method to reset the display mode from full page to the default display action.

A complete example of an editor action class follows:

public String service(HttpServletRequest request,
  HttpServletResponse response, PortletContext context) throws Exception
{
InformationServicesSelector infoSelector = (InformationServicesSelector)
    context.getAttribute("myISSKey");
String path = infoSelector.getPath();
//put the path into the portlet's context object
	context.setAttribute("myISS_InitialPath", path);

//create the URLs for the OK and Cancel buttons.
request.setAttribute("Return_URL",
	NavigationUtil.buildBaseURL(context, request, "ok"));

request.setAttribute("Cancel_URL",
	NavigationUtil.buildBaseURL(context, request, "cancel"));

//prepare the localized resources for use by the jsp.
try {
    NavigationUtil.prepareLocalizedResources(
	"com.mycompany.portlets.NavigatorResources",
	 request, context);
}
  catch (java.io.IOException ioe) {
	  Logger.error(ioe.getMessage(), _loggingContext, ioe);
}
// be sure we are in edit mode, then call reset.
if (context.getMode().equals(PortletContext.EDIT_MODE)) {
context.resetMode();
}
}

Step 3: Code the Editor JSP Page

When a portlet goes into edit mode, it takes over the entire page as its display area. Code the JSP page for this area as follows:

1. Obtain the portlet's navigation path from the portlet context so that the page can be displayed to the user, as in the following scriptlet code example:

   PortletContext context = (PortletContext) request.getAttribute (
   com.sas.portal.portlets.PortletConstants.CURRENT_PORTLET_CONTEXT );
   String path = (String) request.getAttribute ( "myISS_InitialPath" );
   

2. Create buttons (for example, OK and Cancel) with the appropriate form actions. Obtain URLs for these buttons from the HttpServletRequest or the PortletContext object (as described previously in Step 2-b), and assign them to the action attribute. To localize the button text, you can use the message tag from the JSTL tag library, as in the following scriptlet code example:

   <form method="post"
      action = "<%= (String)
        request.getAttribute("myISS_InitialPath") %>">
        <input class="button" type="submit" value= "<fmt:message
        key="action.ok.txt"/>" name="submit" >
   </form>
   

3. Code the visual elements of the page as desired.

For a complete example of an editor JSP page, see Sample: Portlet Template, or Editable Portlet (DisplayURL).

Step 4: Create Resource Bundles to Support Localized Text

To ensure that the portlet can display localized text, create a NavigatorResources.properties file, and then create localized versions of the same file. These files should contain the appropriate key-value pairs that are needed to obtain localized text. For more information, see Creating a Localized Portlet.