Using Adrenaline Portlets to Energize Web Applications
Pages: 1, 2

IFrame Consumer Technique

Using an IFrame to insert a new feature into a Web page has become a common technique across the Internet. Many mashup sites rely on this approach, for example. The concept is simple: A developer edits an existing page, and then adds an <iframe> tag without disturbing the rest of the page. IFrames render within their own isolated frame, and so they cannot harm the surrounding page. For legacy Web applications that are risky to update, an IFrame is the right approach.

The IFrame tag is very easy to understand. The developer need only specify the source of the rendered content, and optionally some size and scrolling attributes:

<iframe src="http://wlp.bea.com/wlpBEAWeb/portlets/travel/customers/customers.portlet"

               width="350" height="450" frameborder="0" scrolling="auto"/>

The process of using the IFrame to render an Adrenaline portlet is easy. Follow these steps:

  1. Obtain the URL to the portlet. This can be determined by looking into the producer Web application, and creating a URL to the desired .portlet file—for example, http://[host]:[port]/[webappContextPath]/[relative path]/[portletName].portlet.
  2. Open the consumer Web page in an editor.
  3. Insert the <iframe> tag into the page where the portlet should be rendered, using the URL to the portlet as the source. Use the example shown above as a reference.

Ajax Snippet Consumer Technique

While using an IFrame to insert a portlet into a page is an effective technique, at times it is desirable to render a portlet inline onto a page. In certain cases, the portlet may wish to use JavaScript to interact with elements of the enclosing page. Also, rendering the portlet inline allows the portlet to consume as much screen area as it needs without the need for scrollbars.

With the Ajax consumer technique, all clicks within the portlet are routed to the producer asynchronously, and the returned HTML is inserted into the page. Therefore, the enclosing page is not refreshed for portlet events, which allows the portlet to operate independently without interfering with the application. Multiple Ajax rendered portlets may be used on the same page as long as each instance is given a unique id attribute.

The following is the snippet to use when rendering an Adrenaline portlet via Ajax. Notice how div tags define containers that control different pieces of the rendered portlet.

 0  <script type="text/javascript" src="/wlpBEAWeb/framework/features/js/async.js" />

 1  <div id="_cmbrowser" class="bea-portal-window-content-async">

 2          <br />

 3  </div>

 4  <div id="_cmbrowser_script"></div>

 5  <div id="_cmbrowser_load" class="bea-portal-window-content-async-load" style="position: absolute; visibility: hidden;">

 6          Loading...

 7  </div>

 8  <div id="_cmbrowser_error" class="bea-portal-window-content-async-error" style="position: absolute; visibility: hidden;">

 9          ERROR...

10  </div>

11  <script type="text/javascript">

12     bea.netuix.ajax.updateContents("_cmbrowser", "http://wlp.bea.com/wlpBEAWeb/portlets/travel/customers/customers.portlet?_nfpb=true&_portlet.contentOnly=true&_portlet.instanceLabel=_cmbrowser&_portlet.contentMode=FRAGMENT&_portlet.async=true");

13  </script>

The key to the Ajax snippet is the call to bea.netuix.ajax.updateContents() function. It is this function that will ultimately render the HTML contents from the portlet into the _cmbrowser div tag. The portlet is accessed via a URL to the .portlet file, which will trigger a servlet to render that portlet. The links and form actions in the rendered HTML will be correctly rewritten to submit through the XMLHttpRequest and will not cause a page refresh. The JavaScript code that powers Adrenaline is found within the file async.js, which is referenced at the top of the snippet.

Note that there is a significant limitation for using this approach. Browsers have a security feature that will not allow the portlet to come from a server in a different IP domain than the outer HTML page. Therefore, this approach will work only when the portlet and the Web application are hosted by the same organization.

To use this snippet to surface your portlet in your own Web application, follow these steps:

  1. Copy the above snippet into an HTML page in your Web application. You will need to remove the preceding line numbers.
  2. Search for the text cmbrowser within the snippet, and replace that text with a unique id for your portlet on the page.
  3. Obtain the URL to the WebLogic Server Web application in which your Adrenaline portlet is deployed. This will likely be a URL of the form
    http://[host]:[port]/[webappContextPath]
  4. Update the URL in snippet line 0 with the portlet Web application URL, as in
    /[webappContextPath]/framework/features/js/async.js.
  5. Obtain the relative path of the portlet descriptor within the WebLogic Server Web application, as in
    /[relative path]/[portletName].portlet.
  6. Update the URL in snippet line 12 with the portlet Web application URL and the relative path to the portlet, as in
    http://[host]:[port]/[webappContextPath]/[relative path]/[portletName].portlet?[keep the existing parameters shown above].

Ajax JSP Tag Consumer Technique

Adrenaline offers a JSP tag that may be embedded into any JSP page in a WebLogic Server Web application that has Adrenaline installed. The portlet to which it refers must also be deployed in the same Web application (for a local portlet) or it can be deployed remotely if using WSRP. Ultimately, Adrenaline must have a WebLogic Portal .portlet descriptor in the Web application for the portlet that is to be exposed.

To surface a portlet in a JSP page, the new Adrenaline portalFacet tag is inserted into the JSP page:

<%@taglib uri="http://www.bea.com/servers/portal/tags/netuix/render" prefix="render"%>

...

< render:portalFacet label="_customers" path="/portlets/travel/customers/customers.portlet" />

where the Web application has a file called sample.portlet deployed in the portlets subdirectory. The label tag attribute must be unique to all portalFacet tags on the page as it identifies the portlet instance. At runtime, the portalFacet tag will render the specified portlet on the page using the Ajax approach that has already been described. You may include multiple portlets on a single page by inserting multiple portalFacet tags with unique label attributes.

Configuring a WebLogic Server Web Application as a Portlet Producer

After reviewing the three techniques for consuming portlets into any Web application, it is important to focus on how to create the producer and its portlets. For customers with existing WebLogic Portal 9.2 Web applications, there is no work to be done. Any WebLogic Portal 9.2 Web application is automatically an Adrenaline portlet producer. Any portlet deployed within WebLogic Portal 9.2 can instantly be consumed using the three techniques above without any configuration or additional work. Customers deploying portlets on WebLogic Portal 8.1 will need to upgrade to version 9.2 to take advantage of this capability.

For WebLogic Server customers that are not currently building portlets on WebLogic Portal, it is a straightforward effort to take advantage of Adrenaline. The appendix contains a small set of steps to add Adrenaline to any WebLogic Server 9.2 Web application. However, note that there are three major prerequisites for building an Adrenaline portlet producer Web application:

  • WebLogic Server 9.2: The Adrenaline producer Web application must be deployed on WebLogic Server 9.2.
  • WebLogic Portal License: For the 9.2 release, the producer Web application requires a WebLogic Portal license.
  • Adrenaline Libraries: Certain WebLogic Portal JAR files must be installed in the producer Web application.

Downloading WebLogic Platform 9.2 provides WebLogic Server and a development license for WebLogic Portal. To configure the Adrenaline libraries, it is easiest to use WebLogic Workshop for WebLogic Platform following the steps in Appendix A of this article.

Adrenaline Considerations

Adrenaline will work with almost any portlet developed and deployed within WebLogic Portal 9.2. No special steps need to be taken to make a portlet Adrenaline compatible. However, several specific issues can affect the usability of a portlet through Adrenaline.

Why use Adrenaline portlets on the producer?

The IFrame technique could be accomplished without Adrenaline portlets; IFrames can consume any HTML source. You could add an IFrame to a legacy application that consumes www.bea.com, for example. In a similar way, using an Ajax toolkit, you can replicate the Ajax Snippet technique without Adrenaline. If this is true, why should you use Adrenaline portlets on the producer side?

What follows are the primary reasons for developing portlets on the producer side instead of plain Web applications:

  • Components, not pages: most Web applications would not fit well within a portlet-sized IFrame. What is needed are user interface components to consume, not entire pages.
  • Standard and pervasive: Portlet technology is a standard and pervasive approach to creating componentized Web user interfaces.
  • Reuse: By deploying a user interface component as a portlet, that same portlet can be exposed as Adrenaline, WSRP, and directly into portals.
  • Features: Adrenaline portlets have access to numerous portlet container features, such as caching, preferences, look and feels, entitlements, and so on.
  • Migration: Developing Adrenaline portlets provides an incremental approach for a migration from legacy Web applications to enterprise portals.

Inter-Portlet Communication

Inter-Portlet Communication (IPC) allows for one portlet to communicate with another portlet within a portal. In some cases, this feature is used by portlet writers to allow multiple portlets to collaborate. The Master-Detail pattern formalizes this idea by defining a Master portlet and a Detail portlet that appear on a single portal page. The Master portlet usually contains a list of topics, that when one is clicked, causes the Detail portlet to update and display the clicked content.

Because Adrenaline surfaces a single portlet on a consumer Web page, the Master-Detail pattern is not supported. Portlets that rely on IPC therefore should not be consumed using Adrenaline.

Authentication

When using any of the consumer techniques, it is always possible for the consumer and producer to be in the same Web application. For the portalFacet tag, this is actually required. There is an advantage with deploying in this manner. In this configuration, if a user authenticates with either the consumer Web page or the producer portlet, the authentication is automatically shared. This is due to the fact that the user is operating entirely within the boundaries of a single Web application.

When using the IFrame Consumer or Ajax Consumer techniques, it is common for the consumer and producer to be part of different Web applications. While this is a flexible approach, it is important to understand how this configuration affects authentication. Because the consumer and producer are in different Web applications, by default authentication will not be shared. Therefore, the user will be required to authenticate twice—once with the consumer and once with the producer.

This problem is not unique to Adrenaline. Forcing users to authenticate with many Web applications is commonly seen within the enterprise. To solve this issue, Single Sign-On (SSO) solutions have become widely deployed within the enterprise. SSO solutions commonly use cookies to maintain user identity across Web sites. As long as both consumer and producer are in the same network domain, these SSO solutions will work without issue with Adrenaline.

Adrenaline complements WSRP

Adrenaline is not the first portlet technology to allow consumers to surface remote producer portlets. A standard called Web Service for Remote portlets (WSRP) already exists to provide exactly this capability. WebLogic Portal contains the industry-leading implementation of WSRP, and continues to enhance its implementation. WSRP is an advanced technology that contains many features useful for creating federated portals. Features such as shared authenticated, inter-portlet communication, and interceptors make the WebLogic Portal WSRP solution very powerful.

BEA recommends WSRP as the primary portlet federation technology. However, in cases where WSRP is not available on the consumer side, Adrenaline is a great substitute. Fortunately, with WebLogic Portal, the same portlet can be deployed once on the producer, and then can be surfaced to some consumers using Adrenaline and others with WSRP. In this way, Adrenaline and WSRP are complementary, not competing technologies.

Conclusion

Adrenaline dramatically expands the reach and flexibility of portlet technology. Adrenaline can breathe life into legacy applications, and promotes the reuse of portlet user interface components throughout the enterprise. For WebLogic Portal customers, this new technology comes for free and enhances the return on existing investment in portlet development. For all others, Adrenaline offers a compelling reason to adopt WebLogic portlet technology.

Appendix A: Adding the Adrenaline Libraries to a WebLogic Server Web Application

This appendix describes the list of steps to add Adrenaline to a WebLogic Server Web application. You must add certain WebLogic Portal components to the Web application using Workshop for WebLogic Platform 9.2, following these steps:

  1. Ensure that the license.bea file in your BEA home folder contains a valid key for PortalFramework.
  2. Create a WebLogic Server domain if one is not already created using the Domain Configuration Wizard. The domain must include support for the WebLogic Workshop product. Rerun the Domain Configuration Wizard, and then choose to Extend the domain to verify the configuration.
  3. Launch Workshop for WebLogic Platform.
  4. Open an existing Workspace or create a new Workspace.
  5. Create an Enterprise Application Project if one is not already created. File->New->Project...
  6. Create a Dynamic Web Project if one is not already created. File->New->Project...
  7. Select the Enterprise Application Project in the Navigator pane.
  8. In the Project menu, select the Properties item.
  9. On the Properties dialog, select the J2EE Module Dependencies option in the left pane.
  10. Ensure that the Web Project has a checkmark to indicate that it is a component of the Enterprise Application.
  11. Select the Web Project in the Navigator pane.
  12. In the Project menu, select the Properties item.
  13. On the Properties dialog, select the Project Facets option in the left pane.
  14. Click the Add/Remove Project Facets button.
  15. Expand the WebLogic Portal node in the tree.
  16. Select the Portal Framework and Portal Framework Struts facets.
  17. To offer WSRP portlets, you must also add the WSRP Producer and Portal Customizations Framework facets.
  18. Click Finish.
  19. Configure the application to use the WebLogic Server domain created above by using the Servers view; see this page for more information.

Appendix B: Creating a Producer Portlet in a WebLogic Server Web Application with Adrenaline

To create a sample portlet to use within a WebLogic Server Web application, follow these steps in Workshop for WebLogic Platform 9.2:

  1. Configure the Web Project by following the steps above to add Adrenaline.
  2. Right-click on the WebContent folder in the Web Project.
  3. Under the New menu item, choose to create a new folder.
  4. Name it portlets, and then click Finish.
  5. Right-click on the portlets folder.
  6. Under the New menu item, choose to create a new JSP.
  7. Name it sample, and then click Finish.
  8. Edit the JSP to output a simple text message.
  9. Right-click on the sample.jsp in the Navigator pane.
  10. Under the New menu item, choose Other.
  11. Expand the WebLogic Portal section, and then choose Portlet.
  12. Provide the name as sample, and then click Finish.
  13. In the portlet wizard, specify the portlet type as JSP/HTML, and then click Next.
  14. Specify the title as Sample.
  15. For Content Path, browse to the JSP, or enter /portlets/sample.jsp.
  16. Click Create, and the sample.portlet file will be created.
  17. Consume the portlet using one of the three techniques above.

Peter Laird is the Managing Architect of the WebLogic Portal product.