The portal Web 2.0 theme extends conventional JSP or servlet based portal themes by adding a Javascript-based
Client-Side Aggregation (CSA). Using AJAX techniques with Portal Model REST services, CSA provides a more responsive user experience and lower load on the server.
When the User first accesses a Portal page to which the portal Web 2.0 theme is assigned, the CSA aggregator is initialized via its Default.jsp
Once the page loads in the browser, the CSA aggregator is initialized via a JavaScript onload() function.
The CSA aggregator then makes multiple AJAX requests to the portal to retrieve the contents of the theme navigation elements, the page content layout, and then the contents of the portlets on the page themselves.
After the initial loading of the page, subsequent user actions are handled by the CSA aggregator. Rather than updating and refreshing the entire page on every user interaction, the CSA aggregator only updates the parts of the page that have actually changed.
Version 6.1 WebSphere Portal Express includes two new themes:'
Portal
The Portal theme is a new look and feel for the portal, and is compatible with the new Theme Customizer portlet, which allows end users to easily customize the visual styles and layout of the theme. It is a traditional JSP server side aggregated theme.
PortalWeb2
The PortalWeb2 theme is based on the Portal theme, but is enabled to use the CSA aggregator.
Whtz new in PortalWeb2
Default page markup
The primary difference in the theme JSPs is that the Portal theme renders the page navigation with custom JSP tags, whereas the PortalWeb2 theme simply includes empty division (
) tags that are later populated by the CSA aggregator.
head_csa.jspf
Changes to the theme required for CSA are consolidated as much as possible into the head_csa.jspf. This includes initialization and bootstrapping of the CSA aggregator, and all other variables or references required in CSA.
web2 dir
The common JavaScript framework for CSA is stored in a common location for use by all Web 2.0 themes and portlets. The path is [wps.war root]/web2. Reference: [link to javascript documentation]
Using the portal Web 2.0 theme
Assigning the portal Web 2.0 theme
The Web 2.0 theme is assigned to a page just like any other portal theme.
CSA and SSA modes
The portal Web 2.0 theme also supports server-side aggregation (SSA) mode.
In SSA mode, a full page refresh is performed to re-call the theme JSPs, and conventional JSP tag aggregation is performed. This useful in the following cases:
• Some pages, portlets, or browsers might be incompatible with the CSA aggregator.
• Javascript conflicts or non-standard coding practices might cause either the portlet to break in the portal Web 2.0 theme, or portlet errors might break the portal Web 2.0 theme itself.
• Some browsers might not have sufficient capabilities for the CSA aggregator to function. For example, Safari 2 does not support XSLT/XPath.
Forcing SSA mode
You can set a page to be rendered in SSA mode by assigning and setting a page parameter named
RenderMode = force_ssa.
The portal Web 2.0 theme checks this parameter, and if you set it to RenderMode=force_ssa, it will switch to SSA mode for this page.
If the user navigates to a page that dos not have this setting, the theme reverts back to CSA mode.
Finally , the portal Web 2.0 theme sets a page variable named isSSA, and its opposite, isCSA. in head_csa.jspf. If there are other circumstances in which SSA mode is required, you can add the logic to the setting of these page variables.
Customizing the Web 2.0 theme
The PortalWeb2 theme is based on the Portal theme and generates very similar HTML, therefore the process for modifying styles is identical. Specifically, modifying the CSS, color palettes, background images, etc., is the same for the PortalWeb2 theme.
Modifying the generated markup
You can modify the markup that PortalWeb2 theme generates in two different ways:
• The default page structure. This is generated by the theme JSPs, and can be modified just like a traditional Portal theme, with the qualification that the theme must contain the empty placeholder division tags (
head_csa.jspf
Changes to the theme required for CSA are consolidated as much as possible into the head_csa.jspf. This includes initialization and bootstrapping of the CSA aggregator, and all other variables or references required in CSA.
web2 dir
The common JavaScript framework for CSA is stored in a common location for use by all Web 2.0 themes and portlets. The path is [wps.war root]/web2. Reference: [link to javascript documentation]
Using the portal Web 2.0 theme
Assigning the portal Web 2.0 theme
The Web 2.0 theme is assigned to a page just like any other portal theme.
CSA and SSA modes
The portal Web 2.0 theme also supports server-side aggregation (SSA) mode.
In SSA mode, a full page refresh is performed to re-call the theme JSPs, and conventional JSP tag aggregation is performed. This useful in the following cases:
• Some pages, portlets, or browsers might be incompatible with the CSA aggregator.
• Javascript conflicts or non-standard coding practices might cause either the portlet to break in the portal Web 2.0 theme, or portlet errors might break the portal Web 2.0 theme itself.
• Some browsers might not have sufficient capabilities for the CSA aggregator to function. For example, Safari 2 does not support XSLT/XPath.
Forcing SSA mode
You can set a page to be rendered in SSA mode by assigning and setting a page parameter named
RenderMode = force_ssa.
The portal Web 2.0 theme checks this parameter, and if you set it to RenderMode=force_ssa, it will switch to SSA mode for this page.
If the user navigates to a page that dos not have this setting, the theme reverts back to CSA mode.
Finally , the portal Web 2.0 theme sets a page variable named isSSA, and its opposite, isCSA. in head_csa.jspf. If there are other circumstances in which SSA mode is required, you can add the logic to the setting of these page variables.
Customizing the Web 2.0 theme
The PortalWeb2 theme is based on the Portal theme and generates very similar HTML, therefore the process for modifying styles is identical. Specifically, modifying the CSS, color palettes, background images, etc., is the same for the PortalWeb2 theme.
Modifying the generated markup
You can modify the markup that PortalWeb2 theme generates in two different ways:
• The default page structure. This is generated by the theme JSPs, and can be modified just like a traditional Portal theme, with the qualification that the theme must contain the empty placeholder division tags (
) that the CSA aggregator uses to populate the theme navigation and page content.
• The markup rendered for the theme navigation elements and page layout: The CSA aggregator uses XSLT to render the navigation elements and page layout. In many cases you can achieve a desired customization by using only CSS style sheets, but for the cases where changes to the markup itself are truly required, below is the list of XSLT files that render each theme element:
Theme element XSLT file
main menu xsl/mainMenu.xsl
top navigation tabs xsl/topNavRender.xsl
side navigation tree xsl/sideNavRender.xsl
page layout (rows and columns) xsl/mainContentRenderLayout.xsl
IBM skin xsl/IBM.xsl
noSkin skin xsl/NoSkin.xsl
Adding new elements to the theme
To add a new navigation element to the theme, proceed as follows:
1. Add an empty division with a unique ID to the theme JSPs by using the
• The markup rendered for the theme navigation elements and page layout: The CSA aggregator uses XSLT to render the navigation elements and page layout. In many cases you can achieve a desired customization by using only CSS style sheets, but for the cases where changes to the markup itself are truly required, below is the list of XSLT files that render each theme element:
Theme element XSLT file
main menu xsl/mainMenu.xsl
top navigation tabs xsl/topNavRender.xsl
side navigation tree xsl/sideNavRender.xsl
page layout (rows and columns) xsl/mainContentRenderLayout.xsl
IBM skin xsl/IBM.xsl
noSkin skin xsl/NoSkin.xsl
Adding new elements to the theme
To add a new navigation element to the theme, proceed as follows:
1. Add an empty division with a unique ID to the theme JSPs by using the
tag.
2. Write a Javascript controller object that extends the navigation element com.ibm.portal.aggregation.theme.NavigationElement.
3. Register your new navigation Element with the CSA aggregator. To do this, proceed as follows:
a. Edit the file head_csa.jspf .
b. In the definition of the bootstrap() function, find the lines shown below and add a new, similar line for your navigation element:
portalAggregator.navigation.addNavigationElement( new com.ibm.portal.aggregation.theme.TopNavigation() );
portalAggregator.navigation.addNavigationElement( new com.ibm.portal.aggregation.theme.SideNavigation() );
portalAggregator.navigation.addNavigationElement( new com.ibm.portal.aggregation.theme.CrumbTrail() );
Adding Web 2.0 skins
In conventional portal skins, a Control.jsp implements the code to render the decoration around a portlet. With the portal Web 2.0 theme, the portal renders the pages on the client. Therefore, rather than invoke a JSP to render the skin, it requires to execute an XSLT transformation. To achieve this, the portlet needs to register the following at bootstrap time in head_csa.jspf: The skin name and xslt file path in a mapping for use by the CSA aggregator, along with its object ID, that is its internal identifier which it retrieves from the portal model.
At runtime, the page layout model stores the object ID of the assigned skin. The CSA aggregator retrieves the XSLT path of the skin, then load and apply it to render the skin. If the XSLT path is empty or null, the default skin XSLT would be used.
To add a new skin, proceed as follows:
1. Implement an XSLT to render the desired markup.
2. Store the XSLT file in the /xslt directory of the theme, with the same name as the skin. For example, for the IBM skin this is xslt/IBM.xsl .
3. Register the new skin with the CSA aggregator as follows:
a. Edit the file head_csa.jspf .
b. In the definition of the bootstrap() function, find the lines shown below and add a new, similar line for your skin:
portalAggregator.page.addSkin(new
com.ibm.portal.aggregation.IbmSkin("IBM",skinResourceRoot2Id["IBM"],""),true);
portalAggregator.page.addSkin(new com.ibm.portal.aggregation.Skin("NoSkin",skinResourceRoot2Id["NoSkin"],""),false);
Troubleshooting Web 2.0 issues
Learn how to troubleshoot and debug issues that result from using the portal Web 2.0 theme.
As the CSA aggregator performs on the client rather than on the server, troubleshooting problems with the portal Web 2 theme requires a different approach than with traditional themes. If the error occurred on the server, an exception can be written to the server log. An error on the client is logged on the client. In order to view errors logged on the client proceed by the following steps: Load a portal page with the PortalWeb2 theme. 3. Once the page has completed loading, type the following into the browser's address bar and hit enter: javascript:toggleDebugForm(); This will display a form at the bottom of the page which will allow you to then launch the debug console in a new window. The debug console will now log debug/trace statements which will help identify the problem. 3rd party Javascript debugging tools are an invaluable resource in troubleshooting: Firebug, Firebug Lite, Fiddler. Can we reference these in the InfoCenter? Probably not. Are they FreeWare, or how are they available, by license ?
1. Make sure that debugging is enabled in the portal Web 2.0 theme. To do this, edit the file head_csa.jspf and ensure that djportalConfig and ibmPortalConfig contain isDebug:true.
2. Load a portal page that uses the PortalWeb2 theme.
3. After the page has completed loading, type the following into the browser address bar and press enter: javascript:toggleDebugForm() . As a result, the portal displays a form at the bottom of the page that allows you to launch the debug console in a new window. The debug console will then log debug and trace statements that help you identify the problem.
2. Write a Javascript controller object that extends the navigation element com.ibm.portal.aggregation.theme.NavigationElement.
3. Register your new navigation Element with the CSA aggregator. To do this, proceed as follows:
a. Edit the file head_csa.jspf .
b. In the definition of the bootstrap() function, find the lines shown below and add a new, similar line for your navigation element:
portalAggregator.navigation.addNavigationElement( new com.ibm.portal.aggregation.theme.TopNavigation() );
portalAggregator.navigation.addNavigationElement( new com.ibm.portal.aggregation.theme.SideNavigation() );
portalAggregator.navigation.addNavigationElement( new com.ibm.portal.aggregation.theme.CrumbTrail() );
Adding Web 2.0 skins
In conventional portal skins, a Control.jsp implements the code to render the decoration around a portlet. With the portal Web 2.0 theme, the portal renders the pages on the client. Therefore, rather than invoke a JSP to render the skin, it requires to execute an XSLT transformation. To achieve this, the portlet needs to register the following at bootstrap time in head_csa.jspf: The skin name and xslt file path in a mapping for use by the CSA aggregator, along with its object ID, that is its internal identifier which it retrieves from the portal model.
At runtime, the page layout model stores the object ID of the assigned skin. The CSA aggregator retrieves the XSLT path of the skin, then load and apply it to render the skin. If the XSLT path is empty or null, the default skin XSLT would be used.
To add a new skin, proceed as follows:
1. Implement an XSLT to render the desired markup.
2. Store the XSLT file in the /xslt directory of the theme, with the same name as the skin. For example, for the IBM skin this is xslt/IBM.xsl .
3. Register the new skin with the CSA aggregator as follows:
a. Edit the file head_csa.jspf .
b. In the definition of the bootstrap() function, find the lines shown below and add a new, similar line for your skin:
portalAggregator.page.addSkin(new
com.ibm.portal.aggregation.IbmSkin("IBM",skinResourceRoot2Id["IBM"],""),true);
portalAggregator.page.addSkin(new com.ibm.portal.aggregation.Skin("NoSkin",skinResourceRoot2Id["NoSkin"],""),false);
Troubleshooting Web 2.0 issues
Learn how to troubleshoot and debug issues that result from using the portal Web 2.0 theme.
As the CSA aggregator performs on the client rather than on the server, troubleshooting problems with the portal Web 2 theme requires a different approach than with traditional themes. If the error occurred on the server, an exception can be written to the server log. An error on the client is logged on the client. In order to view errors logged on the client proceed by the following steps: Load a portal page with the PortalWeb2 theme. 3. Once the page has completed loading, type the following into the browser's address bar and hit enter: javascript:toggleDebugForm(); This will display a form at the bottom of the page which will allow you to then launch the debug console in a new window. The debug console will now log debug/trace statements which will help identify the problem. 3rd party Javascript debugging tools are an invaluable resource in troubleshooting: Firebug, Firebug Lite, Fiddler. Can we reference these in the InfoCenter? Probably not. Are they FreeWare, or how are they available, by license ?
1. Make sure that debugging is enabled in the portal Web 2.0 theme. To do this, edit the file head_csa.jspf and ensure that djportalConfig and ibmPortalConfig contain isDebug:true.
2. Load a portal page that uses the PortalWeb2 theme.
3. After the page has completed loading, type the following into the browser address bar and press enter: javascript:toggleDebugForm() . As a result, the portal displays a form at the bottom of the page that allows you to launch the debug console in a new window. The debug console will then log debug and trace statements that help you identify the problem.
0 comments:
Post a Comment