Displaying a AR System form in a portlet

Required knowledge

To create a portlet to display a form view, you must be able to:

• Create a view in .
• Display a view in a browser using a  URL.
• Write a portlet in Java using the JSR 168 API. (An example portlet is included with  7.0.01.)
• Deploy a portlet in your portal server and administer the portal server.

Tested platforms

The methods described in this topic are illustrated in unsupported sample portlet code that you can find in the samples/portal directory in the  installation directory.

You can remove the sample directory content without impacting the  functionality.

• For UNIX:

  /usr/ar/mid-tier/samples/portal

• For Windows:

  C:\Program Files\AR System\Mid-Tier\samples\portal

The sample has been verified using:

•  7.0.01
• Portal servers:
  • BEA WebLogic Portal 8.1 on HP HP-UX, Linux, and Microsoft Windows Server 2003
  • IBM WebSphere Portal 5.1 on Microsoft Windows Server 2003
  • IBM WebSphere Portal 6.0 IBM AIX
  • Liferay 3.6.1 and Tomcat on IBM AIX, Linux, Microsoft Windows Server 2003, and Sun Solaris

Solution architecture

To display a form view, the  portlet must reference the view in the , so to display  content in a web portal, you must have:

• A browser to display the web portal.
• A portal server with a portlet container and web server to host the portal and the portlet.
• An  to display the form view in an IFRAME element in the portlet within the portal in the browser.
• An  to provide the view to the .
  

Components and communication

Portlet structure

Portlets are similar to servlets. The JSR 168 API is based on the servlet API and many portlet containers are extensions to servlet containers. But while a servlet produces a complete web page, a portlet produces an HTML fragment that the portal displays in a portlet window, aggregating it with other portlets.
A portlet usually has an EDIT mode. In EDIT mode, the user can set portlet preferences that can control the content and appearance of the portlet in VIEW mode. The portal can save the preferences so the user does not need to enter them for every use. A portlet can also have a HELP mode.
When you design the  portlet, you must decide which proprieties of the portal the user can control and which will be fixed or determined another way. For example, will the user be able to choose which  form, view, table, flashboard, or other data visualization field to display? If the user cannot set or change any properties, the portlet does not need an EDIT mode. You must also determine if it needs a HELP mode.
Because the  serves the form view displayed in the portlet, to achieve basic aggregation integration, you must include a reference to the view in the portal VIEW mode HTML fragment. Do this by including an HTML IFRAME element that references the URL of the form view in its src attribute. In the simple case, the fragment can consist of only the IFRAME element. An example of an IFRAME element follows.

See Specifying-parameters-in-URLs for more information about ViewFormServlet as used in the example.

Because the view in the portlet is displayed by the , it might not be consistent with the portal style. You can set the appearance properties of the view to hide the web toolbar, to make the view color consistent with the portal, and to provide content for the web header and footer. You can also change the  style sheets in the  to make the form view more consistent with the portal style.

Authentication solutions

Because the portal and the  have separate authentication,  portlets might require the user to log in twice and log out twice. This section describes ways to handle  login and logout.

To log in, the user must first log in to the portal and then log in to the . To log out, the user should log out of the portlet before logging out of the portal.

Login integration

A portlet solution can handle login to the  in the following ways:

• Require separate logins—No integration between the portal or the portlet and the  is required. After logging in to the portal, the user must also log in to the . The  displays the login form in the servlet before it displays the referenced view.
• Allow guest users to access your AR System server—If you permit guest users, you can grant the Public group access to the form and specify the guest user authentication information in parameters to ViewFormServlet and log in the user automatically.
• Save authentication information in portlet preferences—If the portlet gets the user name and password from the user in EDIT mode and saves them in portlet preferences, the portlet can specify the user authentication information in parameters to ViewFormServlet and log in the user automatically in VIEW mode. The portlet can encrypt and decrypt the password to provide more secure storage in the portlet preferences.
• Use the same single sign on (SSO) solution—If the portal server and the  use the same SSO solution for user authentication, you can configure them so that individual logins are not required.
• Customize the portal login—If you can customize your portal server, you can modify the portal login to perform the  login before it runs any portlets. In this case, the login process on the portal server logs in to the  instead of the portlet fragment in the portal on the browser computer. The portal login process must have access to the required authentication information.
• Use portal authentication information—You can code the portlet to log in the user automatically if:
  • You configure your portal and  to use the same authentication information.
  • You can customize your portal server.
  • You create portal server interfaces that the portlet can use to get the user name and password used to log in to the portal.

For example, the Liferay portal server can be customized by changing
/portal-ejb/src/com/liferay/portal/service/impl/ UserServiceImpl.java in the Liferay 3.6.1 installation directory. Replace
if (user.getPassword().equals(encPwd)) { authResult = Authenticator.SUCCESS;

with

For the example code that gets the password from the Liferay portal, see the sample portlet code in the  installation directory at /samples/portal/src/com/arsys/portal/LiferayARPortlet.java.

Logout integration

A user must log out of the  to release the license. A portlet solution can handle logout from the  in the following ways:

• Require separate logouts—No integration between the portal or the portlet and the  is required. Include a logout button on the form view displayed in the portlet as described in Installing and Administering 

   . Users logs out of the  using the button before they log out of the portal.

• Customize the portal logout—If you can customize your portal web page, you can change the logout behavior, so the portal logout button performs the  logout before it performs the portal logout. This does not affect portal users who are not using your  portlet because the logout is ignored.
• Customize the portlet API—JSR 168 does not include a call to the portlet when the portal exits. If you can customize your portal server, you can add this capability to the API and use it in your  portlet to log out of the .

As an example of customizing the portlet API, you can customize the Liferay portal server by making the following changes:

1. Add the following method and the required import to /portal-ejb/src/ com/liferay/portal/servlet/PortletContextPool.javain the Liferay 3.6.1 installation directory:
   public static Set getAllPortletID() { return Collections.unmodifiableSet(_instance._portletContextPool.keySet());}
2. Compile /samples/portal/src/com/arsys/portal/LogoutCallback.java in the  installation directory into the /portal-ejb/classes directory in the Liferay 3.6.1 installation directory.
3. Append com.remedy.arsys.portal.LogoutCallback to the logout.events.post property in the /portal-ejb/classes/ portal.properties file in the Liferay 3.6.1 installation directory. For example, the modified property might be:
   logout.events.post=com.liferay.portal.events.LogoutPostAction, com.liferay.portal.events.GarbageCollectorAction, com.remedy.arsys.portal.LogoutCallback

Best practices

Consider the following recommendations when you design and code the portlet. See the Form and Application Objects guide and the Installing and Administering   guide for more information.

Target use case

The most effective view for an  portlet contains only a table field or a flashboard or other data visualization field plus trim fields and active link control fields required for effective formatting and function. Avoid user input in the portlet view. For example, a flashboard that summarizes the status of interesting requests or a small table that lists relevant requests can be effective portlets.
For user interaction, provide a button or other active link control that opens a more complete view in a separate browser window, not in a portlet. The user must complete the interaction in the separate window before logging out of the  in the portal window.

Custom view

Create a separate view for the portlet. Set the Appearance properties of the view to hide the web toolbar.

Limitations

Be aware of the following possible limitations of  portlets:

• Like other portlets, an  portlet reinitializes when the browser Refresh command is run (or the portal web page is reloaded). For example, if you type in fields in a form and refresh the portal page, your entries are lost. For portlets that display status as recommended in Target use case, this is usually not a problem.
• If a portal contains more than one  portlet, some portlets might not display their content the first time they appear after  login. To prevent this problem, use an SSO solution or customize the portal login, as described in Login integration. Otherwise, if an  portlet does not initially display its content, use the browser refresh function to reload the portal.
• Similarly, when the portal is open in Microsoft Internet Explorer, a change in another portlet might cause an  portlet to blank out its content. To display the  portlet, use the browser refresh function to reload the portal.