JSP Coding Guidelines for Portlets

Introduction
Almost every one concentrates on using coding guidelines for Java code. Wondered if any one considered using coding guidelines for JSP page which contributes in creating the final HTML source which passes to the client.

Below is the list of guidelines which I have prepared for JSP (particulary JSP used in portlet applications) from my experience in different projects. Suggestions are welcomed to improve the list.

JSP Coding Guidelines for Portlets
a) Use Java style comments instead of HTML style
HTML comments will remain in the rendered content, adding to the document size and the amount of data that passes to the client. If you use Java style comments within your JSPs, instead, they are removed from the rendered source, along with the rest of the Java code. You must embed these comments within scriptlets:
<%//comments%>

b) Always use Upper case for HTML components
Eventhough HTML is case insentive, but w3c standars suggest to use always the upper case for HTML components. So in JSP all the HTML components should be in Upper case.
Eg: <TABLE>

c) Use Unique id for HTML components
Always use a unique id for a HTML or any components that are used inside JSP. Avoid using id for applying a style to a HTML components. Instead use class for applying same stye class to different HTML components

d) Make pages fully accessible
To allow end users with disabilities to be able to use your portlet, the JSPs should be fully enabled for keyboard-only control and other assistive technologies. Examples of accessibility enablement features include:

• Use ALT attribute with images to define descriptive text of the image content.
• Use <LABEL>tags to associate labels with form input controls, so that page readers will be able to associate prompts with inputs.
• Do not use color alone to denote state or information. For example, using red to emphasize text does not help those who are color blind. Use bold or italics instead, or use color in conjunction with graphic changes.
• Do not use voice or other sounds to convey information.
• Final HTML page created out of JSP should not contain more than one H1 tag. (Again it is w3c standards)

e) URIs, HTML element name attributes, and JavaScript resources must be namespace encoded
Since many portlets can exist on a page, and it is possible that more than one portlet will produce content with like-named elements, there is a risk of namespace collision between elements, causing functional problems with the page.
Use the <portlet:namespace/>tag to encode such resources with the portlet instance name. For example, to add the tag to a FORM name:
<FORMname="”<portlet:namespace" method="post">form1” action=”<%=actionUrl%>”>
When the portlet is rendered on the page, the above tag would look something like this: <FORM action="”/wps/myportal/.cmd/ad/.ar/19807697/.c/201/.ce/502/.p/502”" name="”PC_202_form1”" method="POST">

f) Use IFRAMEs with caution
IFRAMEs are an easy way to include external content within a portlet, but undermine the whole portlet principle because the portlet API is just tunneled or side-stepped. Therefore, IFRAMEs should only be used for very special cases, such as surfacing legacy applications. Other potential issues to consider when using an IFRAME are:

• The IFRAME fills its content based on a URL. The URL must be addressable by the browser; therefore the server that is the target of the URL must be accessible by the browser.
• Not all browser levels support IFRAMEs.
• If the content is larger than the IFRAME region, then enable horizontal and vertical scrolling to let the user scroll through the embedded content. Content which contains scrolling regions itself can make it difficult for the end user to manipulate all scrolling regions to view all embedded content, causing usability problems.

IBM Portal Users:
If IFRAMEs are used for integrating external applications then try to use web-app integrator provided by IBM Websphere Portal depending upon the type of the application.

g) Do not use pop-ups
Interactions within the portal are state-based, which means that the portal tracks your trail through the pages and portlets. Using the browser’s back button, or creating pop-up browser instances containing portlets, can cause the portal to lose track of your current state and cause problems. Other than using JavaScript prompts, there is no safe way to spawn pop-ups within the portal, unless the new link takes you to an external page, outside the portal. The alternative is to link to an external page within a new browser window (using the TARGET attribute on the anchor), so that the user is left within the portal in the original browser window.

h) Use portlet style classes instead of specific style-oriented attributes
Portal administrators and users can affect the look and feel of the portal by changing the portal theme and the portlet skins. Portlets can pick up on style changes by using styles defined in the portal theme’s cascading style sheet (Styles.css). For example, instead of decorating an element yourself, refer to the theme’s input class definition:
<input class="”buttonText”" type="”submit”">
Styles.css is loaded by the theme and should not be reloaded by a portlet.

i) Include HTML fragments only in JSPs
Because portlets contribute to the content of a larger page, they should only provide HTML fragments and should not have <TABLE>,<LABEL> , or <HTML>tags.
Make sure the fragments are well-formed to prevent unbalanced pages. Also, remember that the HTML fragment is being added to a table cell (<TD>) in the portal page.

j) Design the view to fit on a page with other portlets
Unlike servlet-based applications, portlets contribute a portion of a larger page. The size of the JSPs (in terms of horizontal and vertical span) can determine how easily the portlet can fit on a page with multiple columns and other portlets. A large portlet will “squeeze” other portlets off the screen and create large scrolling regions, resulting in usability issues.
Therefore, when designing a portlet’s JSPs, avoid unnecessary layout elements, focus the portlet’s view on the pertinent information, and consider whether the portlet is intended to be placed on pages with other portlets.
Use JSP for displaying the data/information to the user, try to move all your Business logic into Java code.

k) Minimize dependencies on JavaScript
Open Source Javascript brains will not accept this point. The point is not using the js completely instead try to use the standard js library like DOJO, JQuery, etc. which provides excellent browser compatability and also inbuilt widgets for rich UI.

If you are using your own java script implementations please read below:
Because JavaScript implementations and behavior differ widely among browser types and versions, the more your portlet depends on JavaScript, the more browser-dependent your portlet becomes. Additionally, the more of the page that is rendered using JavaScript, the more difficult it is to maintain and to extend to markups other than HTML. Also, it is more difficult to namespace encode JavaScript resources and nearly impossible to properly encode (response.encodeUrl()) URLs built using JavaScript.

l) Don't include css and js file in Portlet JSP
Since portlet contributes a small portion in a portal page never include css and js file from Portlet JSP, instead move all the code into themes code where it will be part of the <HEAD>.

Particulary this will be usefull when including the dojo.js file. Including the dojo.js file in each portlet will create an separate instance of the dojo which causes issues. So it always better to place the css and js inclusion code in <HEAD>ie, themes of the portal.

m) Remove Client Aggregation Code from Portlet
If you are using RAD/RSA 7.5 and above, creating a JSR168 portlet will also include client side aggregation piece of code in portlet JSP. Remove the pieces of code if you are not using client side aggregation option.

n) Use taglibs whenever possible
Encapsulating Java code within taglibs not only lets you easily reuse common view functions, it keeps the JSPs clean and makes them more like normal HTML pages. The page designer can concentrate on layout and decoration, and you reduce the possibility of breaking the embedded Java code.

0) Use JSTL instead of re-inventing common tags
The Java Standard Tag Library (JSTL) defines many commonly needed tags for conditions, iterations, URLs, internationalization and formatting.

p) Avoid updating HTML components on the fly
Try to avoid updating the HTML components on fly ie while the DOM tree is constructed out of the HTML components available in JSP.

Will explain about this one in detail in a separate topic as this common issue is faced by many developers while using javascript.

Regards,
Elango