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 in your portlet JSPs. 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.
These guidelines are based on the JSP coding guidelines for standard portlets and for IBM portlets. See the corresponding best practices guide for the type of portlet you are developing on the WebSphere Portal Zone for complete information about portlet output guidelines.
HTML
Use standard HTML. For the official HTML specification, see http://www.w3.org.
Use only HTML fragments. Because portlets contribute to the content of a larger page, they should only provide HTML fragments and should not have , , or tags.
Use only elements that can be rendered properly in an HTML table cell (...). Frames, for example, do not appear when inserted in a table.
Make sure the fragments are well-formed to prevent unbalanced pages. Watch out for unterminated, extraneous, or improperly nested tags. The behavior of pages with improperly terminated tags is unpredictable.
Avoid lengthy, complex HTML. Portlets share a page with others and the more content each portlet generates, the more the browser has to process before it can display anything.
Use portlet classes in the portal server's style sheet, Styles.css. If you hard code the fonts and colors, the portlet's appearance will look out of place when the user changes the page style settings. Portal administrators and users can affect the appearance 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 with the style attribute, refer to the theme's input class definition:
Portlet style classes are marked with the following comment:
/* Styles used in portlets
This section of the style sheet has a mixture of classic IBM style classes and the standard WSRP style classes. When available, use the WSRP style classes, which are prepended with a portlet- prefix. See CSS Style Definitions in the WSRP specification.
Do not use CSS for absolute positioning. This could defeat the portal features that allow users and administrators to place content on the page.
Limit the size of the portlet output. 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 forces other portlets off the screen and creates 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. In particular, take notice of image size, pre-formatted text (
tag), and absolute widths on elements, such as tables.
Use Java style comments instead of HTML style. HTML comments 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 imbed these comments within scriptlets:
<% // this is a comment %>
Make pages fully accessible. To allow portal users with disabilities to be able to use your portlet, the JSPs should be fully enabled for keyboard-only control and other assistive technologies. Follow these general guidelines:
Use the alt attribute with images to define descriptive text of the image content.
Use
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.
URIs, HTML element name attributes, and JavaScript resources must be namespace encoded. Use (standard portlet API) or function" /> (IBM portlet API) for named elements to prevent name conflicts with other portlets on the portal page.
Test the portlet output in different browsers. 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.
Minimize dependencies on JavaScript. 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.
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.
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.
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. See Using JSTL in portlet JSPs for more information.
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.
The font style definitions affect the font attributes only (i.e. font face, size, color, style, etc.).
Style
Description
Example
portlet-font
Font attributes for the "normal" fragment font. Used for the display of non-accentuated information.
Normal Text
portlet-font-dim
Font attributes similar to the portlet-font but the color is lighter.
Dim Text
If a Portlet author wants a certain font type to be larger or smaller, they should indicate this using a relative size.
Example1:
Important information
Example2:
Small and dim
9.5.3 Messages
Message style definitions affect the rendering of a paragraph (i.e. alignment, borders, background color, etc.) as well as text attributes.
Style
Description
Example
portlet-msg-status
Status of the current operation.
Progress: 80%
portlet-msg-info
Help messages, general additional information, etc.
Info about ...
portlet-msg-error
Error messages.
Portlet not available
portlet-msg-alert
Warning messages.
Timeout occurred, try again later
portlet-msg-success
Verification of the successful completion of a task.
Operation completed successfully
9.5.4 Sections
Section style definitions affect the rendering of markup sections such as div and span (i.e. alignment, borders, background color, etc.) as well as their text attributes.
Style
Description
portlet-section-header
Section header
portlet-section-body
Normal text
portlet-section-alternate
Text in every other row in the section
portlet-section-selected
Text in a selected range
portlet-section-subheader
Text of a subheading
portlet-section-footer
Section footer
portlet-section-text
Text that belongs to the section but does not fall in one of the other categories (e.g. explanatory or help text that is associated with the section).
9.5.5 Tables
Table style definitions affect the rendering (i.e. alignment, borders, background color, etc.) as well as their text attributes.
Style
Description
portlet-table-header
Table header
portlet-table-body
Normal text in a table cell
portlet-table-alternate
Text in every other row in the table
portlet-table-selected
Text in a selected cell range
portlet-table-subheader
Text of a subheading
portlet-table-footer
Table footer
portlet-table-text
Text that belongs to the table but does not fall in one of the other categories (e.g. explanatory or help text that is associated with the table).
9.5.6 Forms
Form styles define the look-and-feel of the elements in an HTML form.
Style
Description
portlet-form-label
Text used for the descriptive label of the whole form (not the labels for fields
portlet-form-input-field
Text of the user-input in an input field
portlet-form-button
Text on a button
portlet-icon-label
Text that appears beside a context dependent action icon
portlet-dlg-icon-label
Text that appears beside a "standard" icon (e.g. Ok, or Cancel)
portlet-form-field-label
Text that appears beside a form field (e.g. input fields, checkboxes, etc.)
portlet-form-field
Text for a field which is not input field (e.g. checkboxes, etc)
9.5.7 Menus
Menu styles define the look-and-feel of the text and background of a menu structure. This structure may be embedded in the aggregated page or may appear as a context sensitive popup menu.
Style
Description
portlet-menu
General menu settings such as background color, margins, etc
portlet-menu-item
Normal, unselected menu item
portlet-menu-item-selected
Selected menu item
portlet-menu-item-hover
Normal, unselected menu item when the user's pointer (typically a mouse) hovers over it
portlet-menu-item-hover-selected
Selected menu item when the user's pointer hovers over it
portlet-menu-cascade
General sub-menu settings such as background color, margins, etc
portlet-menu-cascade-item
A normal, unselected sub-menu item
portlet-menu-cascade-item-selected
Selected sub-menu item
portlet-menu-cascade-item-hover
Normal, unselected sub-menu item when the user's pointer hovers over it
portlet-menu-cascade-item-hover-selected
Selected sub-menu item when the user's pointer hovers over it
portlet-menu-separator
Separator between menu items
portlet-menu-cascade-separator
Separator between sub-menu items
portlet-menu-content
Content for a normal, unselected menu or sub-menu item
portlet-menu-content-selected
Content for an selected menu or sub-menu item
portlet-menu-content-hover
Content for an unselected menu or sub-menu item when the user's pointer hovers over it
portlet-menu-content-hover-selected
Content for a selected menu or sub-menu item when the user's pointer hovers over it
portlet-menu-indicator
Indicator that a menu item has an associated sub-menu
portlet-menu-indicator-selected
Indicator when the associated menu item is selected
portlet-menu-indicator-hover
Indicator when the associated menu item has the user's pointer hover over it
portlet-menu-indicator-hover-selected
Indicator when the associated menu item is selected and has the user's pointer hover over it
portlet-menu-description
Descriptive text for the menu (e.g. in a help context below the menu)
0 comments:
Post a Comment