Markup guide
One of the goals in writing portlet markup is to provide a consistent, clean, and complete user interface. The portal server page is displayed using skins and themes defined by the portal designer or administrator. For portlets to appear integrated with an organization's portal or user's customized portal, they should generate markup that invokes the generic style classes for portlets, rather than using tags or attributes to specify colors, fonts, or other visual elements. See Portal style classes for more information.
This section provides information for using HTML, WML, and cHTML markup fragments. Portlets are allowed to render only markup fragments, which are then assembled by the portlet framework for a complete page. Portlet output should contain complete, well-structured, and valid markup fragments. This helps to prevent the portlet's HTML code, for example, from corrupting the portal's aggregated HTML code. You should use a validation tool for your markup, such as the W3C HTML Validation Service or a tool from a markup editor, such as WebSphere Studio. Refer to Portlet Development Best Practices and Coding Guidelines for additional information about portlet output guidelines.
HTML
- Use standard HTML. For the official HTML specification, refer to http://www.w3.org.
- Use only elements that can be rendered properly in an HTML table cell (<td>). Frames, for example, do not appear when inserted in a table. Document-level tags such as <html> and <body> are not valid in this context.
- Watch out for unterminated, extraneous, or improperly nested tags. The behavior of pages with improperly terminated tags is unpredictable.
- Do not use deeply nested tables as they make performance slower on older Netscape browsers.
- Avoid lengthy, complex HTML. Portlets share a page with others and the more content each portlet generates, the more the browser has to do before it can display anything.
- Use the portal server's stylesheets. If you hard code the fonts and colors, your portlet may look out of place when the user changes the page style settings. For information on using CSS in the portal, refer to Portal style classes.
- Do not use CSS for absolute positioning. This could defeat the portal features that allow users and administrators to place content on the page.
- Keep portlet content concise. Do not try to expose full screen content through a small portlet.
- Do not create fixed-width HTML tables in portlets as there is no way of knowing how wide a column your portlet has.
- Avoid long, unbroken lines of text; the result is similar to what happens with wide fixed-width tables.
- Check portlet behavior when resizing the page to ensure that your portlet works with different browser sizes.
- Check portlet behavior when the default browser font is changed; your portlet should handle these situations seamlessly.
- Do not draw portlet banners, such as title bars, as they are provided by the portal aggregation.
- Make sure any Javascript provided by a portlet does not interfere with the properties of the portal page, browser window, or other portlets on the page. Also, use <portletAPI:encodeNamespace value="function" /> in JSPs that produce Javascript to prevent Javascript function and variable name conflicts with other portlets on the portal page. For more information, see Portlet API tag quick reference for more information.
WML
- Use standard WML. For information, refer to http://www.wapforum.org.
- When designing your portlet, assume that it could be displayed alone or with other portlets.
- Watch out for unterminated and extraneous tags; the behavior of pages with improperly terminated tags is undefined.
- Use only elements that can be included into a card (probably together with other portlets and elements) and do not create separate cards.
- Do not set the card title.
- Do not use templates.
- Avoid lengthy, complex WML as the buffer length can be restricted by the user agent and portlets may share a page with others.
- Avoid using images too often. When using images, define a meaningful alt name, as this is necessary for the devices that do not support images, or if the image cannot be fetched. If possible, define localsrc.
- Do not use intrinsic events as these events (such as oneventforward and oneventbackward) may be added only by the aggregation level.
- Avoid using timers.
- Use user-triggered events only if necessary, and always define label and name parameters explicitly. Prefix the name with the portlet's unique identifier, otherwise conflict is possible between different portlets on one page. Use meaningful names for labels.
- Do not create fixed-width WML tables or images in portlets.
- Avoid long, unbroken lines of unwrapped text to help prevent unnecessary scrolling.
Compact HTML (cHTML)
- Use standard cHTML. For information on i-mode compatible HTML, refer to Compact HTML for Small Information Appliances .
- Assume when designing your portlet that it could be displayed alone or with other portlets.
- Watch out for unterminated, extraneous, or improperly nested tags. The behavior of pages with improperly terminated tags is unpredictable.
- Use only elements that can be included into a body; do not use <head> or
<body>tags.- Avoid lengthy, complex cHTML as portlets may share a page with others.
- Avoid using images too often and do not use alignment and positioning parameters with images.
- Do not exceed a length of 24 symbols for the phone numbers used as references in the <a> tag.
- Do not use URLs that are longer than 200 bytes.
See also