Portlets for Web Developers

As a web developer, there are several things that you should know about developing portlets that make it different than normal web development.

This article will extend and expand upon the article How Portlet Development is Different from Servlet Development.

What is a portlet?

The simplest way to describe a portlet is that it represents only a portion of the final web page that gets delivered to a client's web browser. Usually, the portlet represents content or a mini-application that is running or displaying within a larger context (usually a portal). More concretely, portlets are often built to a specific portal's specification or a broader standard.

For the sake of this article we will be considering portlets written to the JSR-168 or uPortal channel specifications.

We will also be focusing on the area of web development that deals with the creation of the markup (HTML/XHTML), behavior (JavaScript), and style (CSS).

Markup (Content)

View Technology

It is possible to build portlets using a number of different approaches for generating the markup. For typical uPortal development the preferred techniques would probably include XSLT or JSP/JSTL.

XSLT

As uPortal was built around an XSLT rendering pipeline, it made since to build uPortal channels using the same technology. So many of the early uPortal channels were built using XSLT as the View technology (i.e. the V in MVC). uPortal also ships with default generic channels (CWebProxy Channel, RSS Channels, CGenericXSLT Channels, and Remote Channel Proxy) that can be customized by pointing an XML feed to an XSLT either provided or custom-made (depending on the channel type).

JSP / JSTL

With the emergence of the JSR-168 standard and portlet frameworks (e.g. Spring Portlet MVC), tag libraries have been built to help solve some of the portlet specific needs of web developers. Specifically, this means that tags are provided that can be used to easily generate links and unique ids.

Which do I use?

To arrive at the simplest solution, I would suggest seeing if the portlet that is desired can be built using one of the built-in channel types provided by uPortal. If it can, you may not need any development beyond some simple configuration. Or it may only require some minor changes to, or the creation of, a simple XSLT. Many applications now provide XML feeds of data which can then be easily converted into the desired appearance. XSLT is probably the easiest way to convert an XML document into the XHTML to send to the browser.

If the built-in channel types will not work for your project, or there is a lack of XSLT knowledge or experience to make it work, it makes sense to built a portlet to the JSR-168 portlet spec. If so, choosing JSP/JSTL with the portlet tag libraries may be the best approach to take.

Common Issues

Regardless of the view technology chosen, there are some common issues to be aware of when developing the markup for a portlet (or channel).

Only part of the page

As mentioned already, the most obvious difference between developing for a portlet and developing a normal web application, is that you are only building a part of the final page.

• You will not be writing markup directly to the <head/> element of the page.
  • This means that you will need to consider ways to work around placing <script />, <style />, and <link /> tags in the head.
• Consider the nesting within the portal before choosing to use a header element (h1 to h6).
  • In all likelihood the portal, display the channels within a certain context. <h1> suggests that it is a top level heading. (It sure would be nice if HTML provided a simple <h> element that nested appropriately. It looks like XHTML 2.0 will.)
  • A sample structure of the page might look something like: h1 = tab name, h2 = portlet name, h3 = portlet screen heading
• Consider wrapping your portlet content in at least one root element
  • Consider wrapping all of the portlet content in a <div/> with a class name tied to the portlet name
    • This is useful to allow portlet specific CSS to be written
    • We use a class attribute instead of an id, because it is possible to have more than one instance of the same portlet rendered on the page
  • Consider adding another wrapping <div/> with a class name tied to the particular portlet screen
    • This is useful for allowing screen specific CSS styling within the portlet, and for perhaps more easily identifying what template (e.g. JSP or XSLT) produced the screen.
  • For example,
    

          
          <div class="portlet-myportletname">
            <div class="portlet-myportletname-screenname">...</div>
          </div>
       

    • where myportletname is the name given to your portlet, and screenname is a name given to the particular screen that it is getting rendered.

Namespacing

It is important to recognize that markup that is written in the portlet may be duplicated elsewhere on the same page. It is entirely possible that multiple copies of the same portlet may be placed in the same page. Will your portlet content still behave as expected, or produce valid markup?

• Make sure ids are truly unique for the page, not just the portlet markup
  • The <portlet:namespace/> tag from the portlet tag library can be used to get unique string representing that portlet instance. This means that two of the same portlets on the same page should get two different values when rendered. This unique string can then be concatenated with other strings to get values that can be used as ids within the markup.
• Use CSS classes instead of ids for styling
  • Ids are intended to be unique. If you create a truly unique id for your portlet you will not be able to reliably "guess" what that id is for styling. Instead use a CSS class.

Building links and forms

If you are writing a JSR-168 portlet, you are forbidden to construct your own URLs. You must ask the portal to provide you the URL. Again, the portlet tag library provides convenient ways to specify the type of URL that you would like to construct, and it will be constructed correctly during execution.

If you are using a different view technology like XSLT, you would need to either have all of the links pre-constructed and passed into the transform, make use of an XSLT extension to retrieve the URL during execution (this approach is done within the uPortal 3 sandbox code), or pass in a single URL and construct everything as a form with a method of POST.

It is forbidden to use a form with the method of GET within a portlet (unless it is targeted to something other than the portal) because the browser will create a URL by adding the form elements to the end of the URL, which may or may not be a legitimate URL for the portal.

If you are doing uPortal channel development, these restrictions do not apply. It is left to the channel to take a base action URL and add what parameters is desired to that. So the channel is expected to build the URL in a way similar to normal web development.

Scripts (Behavior)

Common Issues

Only part of the page

As mentioned above, it will be necessary to add <script/> tags to the <body/> of the HTML page instead of the <head/>.

Script tags can be added within the body of the page and it will execute normally. Ideally you will use an external file to hold all of your static JavaScript code, and inline script to hold any dynamic values that needs to be made available for the external script.

For external files, if it is a uPortal channel you will want to place the script within a JavaScript or media folder within the portal web application. If it is a portlet, you will probably want to "package" the script within the portlet's web application. This is useful for when you may need to deploy it within a different portal container.

Namespacing

Again it is important to be aware of JavaScript namespacing issues. Proper JavaScript namespacing should be a practice followed in normal web development anyway so that the page's behavior can be enhanced later without fear of name collisions. In portlet development, it is especially critical.

• Make sure global variables are sufficiently unique or make use of a good namespacing approach
  • The Yahoo! UI Library provides an excellent example of doing this, and even provides a function to help with that.
  • This also means function names, and scripts that change core BOM (browser object model) and DOM (document object model) objects
  • A simple example,
    

          
          UNICON = {}; 
          UNICON.newFunction1 = function(param1, ... , paramN) { ... }; 
          UNICON.newFunction2 = ...;
       

    • This has the affect of creating only 1 global level entry ("UNICON" at window.UNICON)
• Make sure your code is such that it can be loaded more than 1 time on the same page and it will function.
  • Again, your portlet may be added 2 or more times to the same page. Will it work?
• Be aware of overloading or overwriting the window.onload function
  • A lot of scripts depend on executing "onload" of the page.
  • Originally, this was accomplished through assigning an event handler directly to window.onload. If the portal defines an onload event handler this way, and any of the portlets overwrite this value then the portal or other portlets may not function as desired.
  • Instead, see if the script can be executed as the page loads. If it must be executed onload, make use of the addEventListener method (and corresponding IE method), or an existing JavaScript framework which has provided cross-browser event handling.
• Make sure that ids that are referenced by scripts are actually unique to the portal page. See above note about using <portlet:namespace/> tag.

Styles (Presentation)

Common Issues

The area of providing style for portlets is an interesting area of discussion. In theory, portlets are "styled" by the portal more so than by the portlet. That is, in an ideal world, the portal will provide one or more skinning options. Each option will potentially affect how the portlet contents look. WSRP and JSR-168 specify a handful of CSS classes that are expected to be used to allow the portal to consistently apply style across portlets. It turns out that the Java Portlet specification is trying to stay close to the WSRP portlet CSS classes, so you will not need to learn competing CSS classes to work with either of these. uPortal channels, however, have their own set of CSS classes to style them.

Although this sounds ideal, the reality is that the specifications are not clear enough about what the styles mean to make it so that a skin creator would know enough of the context to apply very specific styles to these classes, and expect some unknown portlet to be added and still look good. Similarly, a portlet creator would not know whether to apply a class to a given element, not knowing how a skin designer might have interpreted the style. Added to this is the real world expectation of having visually appealing portlets. Using simple spec CSS classes will not achieve this.

Only part of the page

As mentioned previously, it will be necessary to import any additional stylesheets needed by the portlet within code inserted to the body of the page (instead of the <head/>). The common ways to import CSS style is through the <link/> or <style/> elements. Both of these elements are only valid within the <head/> of the page.

In reality, most browsers will still honor the <style/> element within the body of the document. So, the easiest way to include additional style would be to still use the <style/> within your portlet content. However, doing so will mean the end document will not technically be valid. So, it depends how much of a concern that is. Otherwise, you can insert additional elements into the <head /> through javascript.

For example,

      
// Will only load the stylesheet one time no matter how many times portlet appears on page
if (!myportletname) {
    var myportletname = {};
    myportletname.loadStyleSheet = function () { 
        var newstyle = document.createElement('link'); 
        newstyle.rel = 'stylesheet';
        newstyle.href = 'whatever.css';
        newstyle.type = 'text/css'; 
        document.getElementsByTagName("head")[0].appendChild(newstyle); 
    }; 
    myportletname.loadStyleSheet(); 
}