Programming guidelines

Refer to the programming guidelines to ensure the portlets adhere to the required standards.

Guidelines for markup, JavaScript, and URLs

Follow these guidelines:

• Adhere to iWidget programming guidelines. For details refer to the Lotus Mashups documentation.

• Keep the portlet markup well-formed and compliant with HTML specification - as portlet markup is injected dynamically into Document Object Model (DOM).

• JavaScript in portlet markup should not access markup of surrounding page or markup of other portlets or iWidgets.

• Use Dojo instead of plain or native JavaScript

• Use HTML link elements or forms to embed URLs into portlet markup. This enables the browser to properly resolve relative URLs.

• Do not directly pass the string representation of a URL to a JavaScript function; instead, retrieve the element from the DOM element that represents the link, for example <a href=”...” onclick=”myfunction(this.href, ...); ... ” ...>

Guidelines for the usage of portlet URLs

Follow the guidelines given by this table:

URL type	HTML elements	HTTP verbs	Comments
Action URL	(GET)”> (<a>)	POST, (GET)	This must not be used for Ajax requests or XHR.
Render URL	<a> <form method=”GET”>	GET	This must not be used for Ajax requests or XHR.
Resource URL	<a> <form> XHR	GET, HEAD, PUT, POST, DELETE	—

Guidelines for Ajax portlet development

Depending on the use case, follow the guidelines given here:

Portlet loads data.

Example: Refreshing stock values in a market report application

Recommended solution:

• Send an HTTP GET Ajax request to the resource URL or to the external REST service to load the data. Use the Ajax proxy if required.

• Update the DOM (Document Object Model).

Portlet loads markup fragment or data from the server to change its view.

Example: Switching to a new tab in a tabbed container; content of the selected tab is loaded dynamically using an Ajax request.

Recommended solution:

• Send an HTTP GET Ajax request to the resource URL or to the external REST service to load the markup fragment or data.

• Update the DOM.

• Use the iWidget or Enabler API to publish the new navigational state:

  • iWidget API: onNavStateChanged, onModeChanged, onWindowStateChanged

  • Enabler API: NavigationalStateModel

Portlet changes its view without communicating with the server.

Example: Hide or blend in parts of the portlet markup that are already part of the DOM using CSS.

Recommended solution:

• Update the DOM.

• Use the iWidget or Enabler API to publish the new navigational state:

  • iWidget API: onNavStateChanged, onModeChanged, onWindowStateChanged

  • Enabler API: NavigationalStateModel

Portlet changes its view dynamically and sets a public render parameter.

Example: A navigator portlet that shows a list of items. When a user selects one of these items, a second portlets shows details for the selected item.

Recommended solution:

• Send an HTTP GET Ajax request to the resource URL or to the external REST service to load the markup fragment or data.

• Update the DOM.

• Use the iWidget or Enabler API to publish the new public render parameter:

  • iWidget API: Shared item set “PublicRenderParameters”

  • Enabler API: ShareableParameterSetAccessor

Portlet changes its view and spawns an event.

Example: A navigator portlet that shows a list of items. When a user selects one of these items, a second portlets shows details for the selected item.

Recommended solution:

• Send an HTTP GET Ajax request to the resource URL or to the external REST service to load the markup fragment or data.

• Update the DOM.

• Use the iWidget or Enabler API to publish the new navigational state:

  • iWidget API: onNavStateChanged, onModeChanged, onWindowStateChanged

  • Enabler API: NavigationalStateModel

• Use the iWidget or Enabler API to fire the event:

  • iWidget API: iEvents.fireEvent

  • Enabler API: EventService

Portlet modifies portlet preferences

Example: A paging component that allows for configuring the maximum number of items that are displayed.

Recommended solution:

• Send an HTTP GET Ajax request to the resource URL or to the external REST service to load the markup fragment or data.

• Update the DOM to reflect the change of the preferences change.

• Use the iWidget or Enabler API to update the preferenmces:

  • iWidget API: modify the item set “attributes”.

  • Enabler API: use the Preferences or ModifiablePreferences API)

Portlet modifies the session state

Example: Shopping cart

Recommended solution:

• Send an HTTP PUT or POST Ajax request to the resource URL.

• serveResource modifies the portlet session.

Portlets that we can use in client-side mode

In general, all portlets that are programmed to comply with one of the standard APIs JSR168 or JSR286 can be rendered in client side mode. Portlets that are programmed to comply with the older IBM Portlet API cannot be used in client side mode. However, standard portlets are subject to a few exceptions, where they cannot be rendered in client side mode. This includes cases where the following APIs are used:

• Eventing for JSR168 portlets with Property Broker

• Navigational state SPI

• PortalURLWriter API

• PortalStateParameterService SPI

• Impersonation API

Moreover, request attributes are not transmitted between portlet lifecycle phases.

Explicitly disabling portlets for client-side mode

As the portal cannot automatically detect the instances where portlets use APIthat are not compliant with client-side mode, we can use the portlet preference com.ibm.portal.preventRenderType to disable client-side rendering for standard portlets if you set one of the values to iwidget. We can set this preference on all customization levels. In the portlet.xml you declare this setting as follows:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app [...]>
    <portlet>
        [...]
        <portlet-name>NonClientSidePortlet</portlet-name>
        <portlet-class>my.server.side.Portlet</portlet-class>
        [...]
        <portlet-preferences>
         <preference>
          <name>com.ibm.portal.preventRenderType</name>
          <value>iwidget</value>
                        [...]
          <read-only>true</read-only>
         </preference>
       </portlet-preferences>
    </portlet>
    [...]
</portlet-app>

Parent: Programming model guidelines for client-side mode