+

Search Tips   |   Advanced Search


Theme policies

Theme policies are created using the xmlaccess and control how themes are rendered on a page.

Theme policies are applied to pages either through xmlaccess using the page metadata attribute...

...or using the Properties portlet.

Theme policy is inherited so it only needs to be set on a page which requires a different policy than its parent.

Page builder does not support theme policies.


Theme policy attributes

A theme policy is made up of several attributes. Each attribute controls one aspect of the theme.

For example, the Boolean renderBreadCrumb attribute controls whether the bread crumb will be displayed while the breadCrumbMaxLevels attribute controls the number of steps listed in the bread crumb when it is displayed.

The following table provides type and functional information on all available theme policy attributes. For a full listing, it is recommended that you export the theme policy. See the exporting a theme policy section of this topic for more information.

Attribute Type Function
renderMainMenu Boolean If true, the main menu is rendered
renderTopNavigation Boolean If true, top navigation is rendered
renderMainMenuActions Boolean If true, the main menu actions are rendered
renderSelfCare Boolean If true, Selfcare is rendered
renderBreadCrumbTrail Boolean If true, the bread crumb trail is rendered
renderSearch Boolean If true, search is rendered
renderToolBar Boolean If true, the tool bar is rendered
renderContentPalette Boolean If true, the portlet palette is rendered
renderPeoplePalette Boolean If true, the people palette is rendered
renderContextMenus Boolean If true, context menus are render
renderSideNavigation Boolean If true, side navigation is rendered
renderTaskBar Boolean If true, the task bar is rendered
renderFavorites Boolean If true, favorites is rendered
renderExtensions Boolean If true, extensions are rendered
renderBannerTitleGraphic Boolean If true, the banner title graphic is rendered as long as one exists
renderPortletFragmentIDAnchor Boolean Used to determine if the user is on a palette page
renderBannerTitle Boolean If true, the banner title is rendered as long as one exists
breadCrumbMaxLevels Integer Indicates the number of steps listed in the bread crumb trail
breadCrumbStartLevel Integer Indicates which level to start the bread crumb trail
rootNavigationStartLevel Integer Indicates the start level for root navigation
rootNavigationStopLevel Integer Indicates the stop level for root navigation
topNavigationNumRows Integer Indicates the number of rows to render for top navigation
topNavigationStartLevel Integer Indicates the start level for top navigation
topNavigationStopLevel Integer Indicates the stop level for top navigation
sideNavigationStartLevel Integer Indicates the start level for side navigation
isCustomizable Boolean If true, the policy can be edited in the Theme Customizer portlet.
isDeletable Boolean If true, the policy can be deleted in the Theme Customizer portlet. xmlaccess ignores this attribute.
colorPalette String

If specified, the value in this attribute is the name of the color palette.

The search order for the name of the color palette used on the page is:

  1. the value of the colorPalette page meta data attribute
  2. the value of the colorPalette attribute in the policy assigned to the current page
  3. the string "default"

The name of the color palette must be the name of a properties file provided in the theme without the .properties extension.

colorPaletteProperties String Color Palette information. This is a stored java.util.Properties object created by the Theme Customizer portlet.

The theme first loads the color palette for the page and then overwrites those values with any that may be present in this attribute.

graphicFilesMimeData String If specified, graphic files uploaded through the Theme Customizer portlet. This attribute is a standard multipart/mixed MIME text stream containing attachments encoded with Base64 encoding.
styleVersion Integer The version number of the policy. This value is incremented each time the Theme Customizer portlet saves the policy so updates to the policy can be loaded without clearing the browser cache.
bannerTitleText String

Indicates the text that is to be displayed as the title in the banner and browser title bar.

If this value is empty, the bannerTitleTextResourceBundle and bannerTitleTextResourceKey attributes are used to determine the title text.

bannerTitleTextResourceBundle String Indicates the resource bundle containing the title text.
bannerTitleTextResourceKey String Indicates the resource bundle key that is to be used to locate the title
bannerTitleGraphic String

Indicates the URI of the title graphic to be displayed in the banner. This value is passed on the uri attribute of the portal-resolver:url tag.

Values created by the Theme Customizer portlet are of the form: "themeGraphic:policy:filePath:xxx" where xxx is the name of the attachment stored in the graphicFilesMimeData attribute.

renderBannerQuickLinks Boolean If true, banner quick links are rendered
renderHelpLink Boolean If true, the help link is rendered
renderQuickLinksShelf Boolean If true, the quick links shelf is rendered
quickLinksShelfStyle Integer

Style attributes for the quick links shelf.

This is a bitmask field. If bit 1 is turned on, the quick links shelf default state is expanded. If bit 2 is turned on, the expand/collapse link is hidden.

As such, the following values are supported:

  • 0 = default shelf state is collapsed and the expand/collapse link is shown
  • 1 = default shelf state is expanded and the expand/collapse link is shown
  • 2 = default shelf state is collapsed and the expand/collapse link is hidden
  • 3 = default shelf state is expanded and the expand/collapse link is hidden

Numbers other than 0, 1, 2, or 3 are reserved for future use.

renderApplicationName Boolean If true, the application name is rendered
renderCustomizeThemeLink Boolean If true, the theme customizer link is rendered


Provided theme policies

WebSphere Portal provides ten policies that may be used without alteration. The following information provides lists of each policy along with the corresponding attributes, values, and types.

The Federation, SingleTopNavLevel2, and Palette theme policies should not be modified. Default

SingleTopNav

SingleTopNavMinimal

DoubleTopNav

DoubleTopNavMinimal

SideNavOnly

SideNavOnlyMinimal

NoTheme

Federation

The Federation theme policy cannot be applied to a page either through the XML configuration interface using the page attribute com.ibm.portal.ThemePolicy or the Properties portlet.

SingleTopNavLevel2

Palette

Custom theme attributes

In addition to the attributes in each policy above, you can add an attribute to the theme policies and then use it in your JSP or JSPF. The following code samples show how the custom attribute renderTestAttribute is added to theme policy and how it is accessed in a JSP or JSPF. The main theme policy must have the attribute and a lock attribute. This is added to the root theme policy as follows:

<policyValue
      Name="renderTestAttribute"
      Factory="com.ibm.wps.policy.parse.BooleanFactory">
      <value>true</value>
</policyValue>
<policyValue
      Name="renderTestAttributeLock"
      Factory="com.ibm.wps.policy.parse.BooleanFactory">
      <value>false</value>
</policyValue>

The policy value sets consisting of attributes and their values can be nested. Child attributes can either inherit or override the values from the parent attribute. When you specify the value of a lock attribute corresponding to a policy attribute as true, you lock the policy node. In this case, the child attributes necessarily inherit the values from parent attributes and cannot override these values. Use the following code to add the attribute to each theme policy that requires a value different from the root theme policy:

<policyValue
      Name="renderTestAttribute"
      Factory="com.ibm.wps.policy.parse.BooleanFactory">
      <value>false</value>
</policyValue>
Since this is a Boolean, the value would be set to true or false. Use the following code to access the attribute in a JSP or JSPF:

<% boolean isTestAttribute = themePolicy.getValueAsBoolean("renderTestAttribute", false);  if(isTestAttribute){%>      
<p> Display this paragrah if renderTestAttribute is true. </p>
<%}%>

In the above example, if the value of renderTestAttribute is true, the paragraph is displayed. themePolicy is defined in the Using theme policy in a JSP section of this topic. There are three accessor methods:

where key is the name of the attribute and defaultValue is the value that will be used if the attribute value can not be retrieved from the theme policy.


Setting theme policy on a page using the XML configuration interface

Theme Policy can be applied to a page through the XML configuration interface using the page metadata attribute com.ibm.portal.ThemePolicy. The following provides an example of an XML script that sets the page metadata for the theme policy for the page ThemePolicyPageTest:

<request type="update" 
         create-oids="true" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">

    <portal action="locate">
        <content-node action="update" 
                      ordinal="last" 
                      uniquename="ibm.portal.ThemePolicyPageTest" 
                      content-parentref="Content.Root" 
                      active="true" 
                      allportletsallowed="false" 
                      create-type="explicit" 
                      objectid="wp.theme.policytestpage" 
                      type="page">

            <supported-markup markup="html" update="set"/>

         <!--@LocaleData_1@-->
           <parameter name="com.ibm.portal.ThemePolicy" 
                      type="string" 
                      update="set">theme/SingleTopNavMinimal</parameter>
        </content-node>

    </portal>
</request>


Use theme policy in a JSP

You can also use a theme policy directly in a JSP. Use the following code to do this:

<themepolicy:initthemepolicy/>

<jsp:useBean id="themePolicy" 
             class="com.ibm.portal.theme.policy.ThemePolicyBean" 
             scope="page"/>

<% themePolicy.setValuesMap(portalThemePolicyMap);%>

In this code example, the theme bean is initialized which wrappers the theme policy attributes.

To use an attribute in the JSP, reference it with the following syntax: ${themePolicy.attribute) where the attribute would be, for example, renderSideNavigation.

The following code tests renderSideNavigation. If it is TRUE, the following code is executed:

<c-rt:if test = "${themePolicy.renderSideNavigation}">
<!-- following code -->
<….>
<….>
</c-rt:if>

The following code example sets startLevel to the value of the theme policy attribute sideNavigationStartLevel:

<portal:navigation  startLevel="${themePolicy.sideNavigationStartLevel}"


Creating your own theme policy

The following code example addThemePolicyNode.xml provides an example of how to create and add a new theme policy. This XML file would then be updated to reflect the location and name of the file which contains the theme policy XML definition.

<?xml version="1.0" encoding="UTF-8"?>

<request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
         create-oids="true" type="update" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <portal action="locate">
        <policy-node action="update" label="WebPage" type="" path="">
             <url>file:///c:/temp/addTestThemePolicyNode.xml</url>
        </policy-node>
    </portal>

</request>

Use the XML configuration interface to run addThemePolicyNode.xml which references the TestThemePolicy definition file addTestThemePolicyNode.xml listed as follows. This file represents the theme policy XML definition.

It is important that the following attributes in this file be set as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!--

Licensed Materials - Property of IBM, 5724-E76, 5655-R17, (C) Copyright IBM Corp. 2006 - All Rights reserved. --> <policyList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Policy.xsd"> <policy> <policyValue Name="Path" Factory="com.ibm.wps.policy.parse.StringFactory"> <value></value> </policyValue> <policyValue Name="Type" Factory="com.ibm.wps.policy.parse.StringFactory"> <value>theme</value> </policyValue> <policyValue Name="Description" Factory="com.ibm.wps.policy.parse.StringFactory"> <value>Test Theme Policy</value> </policyValue> <policyValue Name="Title" Factory="com.ibm.wps.policy.parse.StringFactory"> <value>TestThemePolicy</value> </policyValue> <policyValue Name="Editor" Factory="com.ibm.wps.policy.parse.StringFactory"> <value></value> </policyValue> <policyValue Name="NameResKey" Factory="com.ibm.wps.policy.parse.StringFactory"> <value></value> </policyValue> <policyValue Name="PznRule" Factory="com.ibm.wps.policy.parse.StringFactory"> <value></value> </policyValue> <policyValue Name="PznType" Factory="com.ibm.wps.policy.parse.StringFactory"> <value>TestThemePolicy</value> </policyValue> <policyValue Name="Remote" Factory="com.ibm.wps.policy.parse.StringFactory"> <value></value> </policyValue> <policyValue Name="PathType" Factory="com.ibm.wps.policy.parse.StringFactory"> <value>/theme</value> </policyValue> <policyValue Name="renderMainMenu" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderTopNavigation" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderMainMenuActions" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderSelfCare" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderBreadCrumbTrail" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>false</value> </policyValue> <policyValue Name="renderSearch" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderToolBar" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderContentPalette" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderPeoplePalette" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderContextMenus" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderSideNavigation" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderTaskBar" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderFavorites" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderExtensions" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderBannerTitleGraphic" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderBannerTitle" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="renderPortletFragmentIDAnchor" Factory="com.ibm.wps.policy.parse.BooleanFactory"> <value>true</value> </policyValue> <policyValue Name="breadCrumbMaxLevels" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>5</value> </policyValue> <policyValue Name="breadCrumbStartLevel" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>1</value> </policyValue> <policyValue Name="rootNavigationStartLevel" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>1</value> </policyValue> <policyValue Name="rootNavigationStopLevel" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>1</value> </policyValue> <policyValue Name="topNavigationNumRows" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>1</value> </policyValue> <policyValue Name="topNavigationStartLevel" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>2</value> </policyValue> <policyValue Name="topNavigationStopLevel" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>2</value> </policyValue> <policyValue Name="sideNavigationStartLevel" Factory="com.ibm.wps.policy.parse.IntegerFactory"> <value>3</value> </policyValue> <policyValue Name="Version" Factory="com.ibm.wps.policy.parse.StringFactory"> <value>1.0</value> </policyValue> </policy> </policyList>


Update a theme policy

If you are just updating a theme policy, use the following guidelines:

Extending and updating a theme policy When updating, if you are also extending a theme policy by adding attributes to it, the attribute(s) must also be added to the root theme policy.

Use the following guidelines to do this:

If you are just modifying the value of an attribute that already exists in a theme policy, use the following guidelines:


Export a theme policy

Use the following code example exportThemePolicyNode.xml to export a theme policy. The file specified is the location to where the exported information is written. The following example exports all theme policies.

<?xml version="1.0" encoding="UTF-8"?>

<request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
         create-oids="true" type="export" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <portal action="locate">
        <policy-node action="export" label="WebPage" 
                type="theme" path="">
             <url>file:///c:/temp/exportThemePolicies.xml</url>
        </policy-node>
    </portal>
</request>

The following example exports only the TestThemePolicy theme policy:

<?xml version="1.0" encoding="UTF-8"?>

<request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
         create-oids="true" type="export" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <portal action="locate">
        <policy-node action="export" label="WebPage" 
                type="theme" path="TestThemePolicy">
             <url>file:///c:/temp/exportTestThemePolicy.xml</url>
        </policy-node>
    </portal>

</request>


Deleting a theme policy

Use the following code example deleteThemePolicyNode.xml to delete a theme policy. path is the "PznType" of the child policy to be deleted. "PznType" is the identifier of the policy used in the XML file. Specifically, "PznType" is the actual JCR (Java Content Repository) XPath name of this child node. XPath is a search language designed for selecting elements from an XML document (such as a theme policy). A policy is located in a search by an XPath or something that resembles the following: Root/Child1/Child2.

<request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
         create-oids="true" type="update" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <portal action="locate">
        <policy-node action="delete" label="WebPage" 
                type="theme" path="TestThemePolicy">
        </policy-node>
    </portal>
</request>


Parent topic:

Layout of the portal page