Chapter 13. Skinning the Portal

⁠Chapter 13. Skinning the Portal

13.1. Skin Components

13.2. Skin Selection

13.2.1. Skin Selection Through the User Interface
13.2.2. Setting the Default Skin within the Configuration Files

13.3. Skins in Page Markups

13.4. The Skin Service

13.4.1. Skin configuration
13.4.2. Resource Request Filter

13.5. The Default Skin

13.6. Creating New Skins

13.6.1. Creating New Skins
13.6.2. Creating a New Portal Skin
13.6.3. Creating a New Window Style
13.6.4. How to Create New Portlet Skins
13.6.5. Create New Portlet Specification CSS Classes

13.7. Tips and Tricks

13.7.1. CSS Hosted on CDN
13.7.2. Easier CSS Debugging
13.7.3. Some CSS Techniques

A portal visual identity is made of HTML produced as a result of portal aggregation (the components that make a page like columns and rows combined with the content produced by the portlets) and associated CSS files.

Red Hat JBoss Portal (JBoss Portal) allows to deploy multiple skins consisting of CSS files, which makes it possible to apply styling to the page compositions and components of a page (portlets). Different skins can be applied to the different websites, also if made available to the users, they can choose their preferred skin.

JBoss Portal provides robust skinning support for the entire portal User Interface (UI). This includes support for skinning all of the common portal elements as well as being able to provide custom skins and window decoration for individual portlets. This has been designed with common graphic resource reuse and ease of development in mind.

⁠13.1. Skin Components

The skin of a page is composed of three separate parts:

Portal Skin

The portal skin contains the CSS styles for the portal and its various UI components. This must include all UI components, except for window decorators and portlet-specific styles.

Window Styles

The CSS styles associated with the portlet window decorators. The window decorators contain the control buttons and borders surrounding each portlet. Individual portlets can have their own window decorator selected or be rendered without one.

Portlet Skins

The portlet skins dictate how portlets are rendered on the page. There are two ways they can be implemented:

Portlet Specification CSS Classes: The portlet specification defines a set of CSS classes available to portlets. The portal provides these classes as part of the portal skin. This allows each portal skin to define its own look and feel for these default values.
Portlet Skins: The portal provides a means for portlet CSS files to be loaded based on the current portal skin. This allows a portlet to provide different CSS styles to better match the current portal look and feel. Portlet skins provide a much more customizable CSS experience in contrast to using the portlet specification CSS classes.

CSS Classes

The window decorators and the default portlet specification CSS classes are separate types of skinning components. They must be included as part of the overall portal skin otherwise they will not be displayed correctly.

A portlet skin does not need to be included as part of the portal skin, and can be included within the portlet's web application.

⁠13.2. Skin Selection

⁠13.2.1. Skin Selection Through the User Interface

The easiest way to change a skin is to select it through the user interface. An administrator can change the default skin for the portal, or a logged in user can select which skin they would prefer to be displayed.

For more information about changing skins, see the User Guide.

⁠13.2.2. Setting the Default Skin within the Configuration Files

The default skin can also be configured using the portal configuration files. This allows the portal to have the new default skin ready for use when first started.

The default skin of the portal is called Default. To change this value add a skin tag in the $JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/portal/portal/classic/portal.xml configuration file.

Example 13.1. Changing a Skin Name

To change the skin to MySkin make the following changes:

<portal-config>
    <portal-name>classic</portal-name>
    <locale>en</locale>
    <access-permissions>Everyone</access-permissions>
    <edit-permission>*:/platform/administrators</edit-permission>
    <skin>MySkin</skin>
    ...
</portal-config>

⁠13.3. Skins in Page Markups

A skin contains CSS styles for the portal's components, but also shares components that may be reused in portlets. When the portal generates a portal page markup, it inserts stylesheet links in the page's head tag.

There are two main types of CSS links that will appear in the head tag: a link to the portal skin CSS file and a link to the portlet skin CSS files.

Portal Skin: The portal skin will appear as a single link to a CSS file. This link will contain contents from all the portal skin classes merged into one file. This allows the portal skin to be transferred as a single file instead of multiple smaller files.
Portlet Skin: Each portlet on a page may contribute its own style. The link to the portlet skin will only appear on the page if that portlet is loaded on the current page. A page may contain many portlet skin CSS links or none.

In the code fragment below you can see the two types of links:

<head>
...
<!-- The portal skin -->
<link id="CoreSkin" rel="stylesheet" type="text/css" href="/eXoResources/skin/Stylesheet.css" />

<!-- The portlet skins -->
<link id="web_FooterPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css" />
<link id="web_NavigationPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UINavigationPortlet/DefaultStylesheet.css" />
<link id="web_HomePagePortlet" rel="stylesheet" type="text/css" href= "/portal/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css" />
<link id="web_BannerPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UIBannerPortlet/DefaultStylesheet.css" />
...
</head>

Note

Window styles and the portlet specification CSS classes are included within the portal skin.

⁠13.4. The Skin Service

The skin service manages the various types of skins. It is responsible for discovering and deploying skins into the portal.

⁠13.4.1. Skin configuration

The portal automatically discovers web archives that contain a file descriptor for skins ($JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/gatein-resources.xml). This file is responsible for specifying the portal, portlet and window decorators to be deployed into the skin service.

The full schema is available from http://www.gatein.org/xml/ns/gatein_resources_1_2.

Example 13.2. Sample Skin

This example shows where to define a skin (MySkin) with its CSS location, and how to specify some window decorator skins.

<gatein-resources>
  <portal-skin>
    <skin-name>MySkin</skin-name>
    <css-path>/skin/myskin.css</css-path>
    <overwrite>false</overwrite>
  </portal-skin>
</gatein-resources>

  <!-- window style -->
  <window-style>
    <style-name>MyThemeCategory</style-name>
    <style-theme>
      <theme-name>MyThemeBlue</theme-name>
    </style-theme>
    <style-theme>
      <theme-name>MyThemeRed</theme-name>
    </style-theme>
    ...

⁠13.4.2. Resource Request Filter

Because of the portal's Right-To-Left support, all CSS files need to be retrieved through a Servlet filter and the web application must be configured to activate this filter. This is already done for the $JPP_HOME/gatein/gatein.ear/eXoResources.war web application which contains the default skin.

Any new web applications containing skinning CSS files will need to have the following added to the web.xml file:

<filter>
    <filter-name>ResourceRequestFilter</filter-name>
    <filter-class>org.exoplatform.portal.application.ResourceRequestFilter</filter-class>
    </filter>
   
    <filter-mapping>
    <filter-name>ResourceRequestFilter</filter-name>
    <url-pattern>*.css</url-pattern>
    </filter-mapping>

Note

The display-name element must be specified in the web.xml for the skinning service to work properly with the web application.

⁠13.5. The Default Skin

The default skin is located as part of the $JPP_HOME/gatein/gatein.ear/eXoResources.war. The main files associated with the skin are:

WEB-INF/gatein-resources.xml

For the default portal skin, this file contains definitions for the portal skin, the window decorations that this skin provides as well as defining some JavaScript resources which are not related to the skin. The default portal skin does not directly define portlet skins. Portlet skins must be provided by the portlets themselves.

WEB-INF/web.xml

For the default portal skin, the web.xml of the eXoResources.war contains information which is mostly irrelevant to portal skinning.

skin/Stylesheet.css

This file is the main portal skin stylesheet. It is the main entry point to the CSS class definitions for the skin. The main content points of this file are:

/* Skin for the main portal page */
@import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css);
/* Skins for various portal components */
@import url(DefaultSkin/webui/component/Stylesheet.css);
/* Window decoration skins */
@import url(PortletThemes/Stylesheet.css);
/* The portlet specification CSS classes */
@import url(Portlet/Stylesheet.css);

This method imports other CSS stylesheet files (some of which may also import further CSS stylesheets) instead of defining all the CSS classes in this one file. Splitting the CSS classes between multiple files allows new skins to reuse parts of the default skin.

To reuse a CSS stylesheet from the default portal skin you would need to reference the default skin from eXoResources. For example; to include the window decorators from the default skin within a new portal skin you would need to use this import:

@import url(/eXoResources/skin/Portlet/Stylesheet.css);

Note

When the portal skin is added to the page, it merges all the CSS stylesheets into a single file.

⁠13.6. Creating New Skins

⁠13.6.1. Creating New Skins

⁠13.6.2. Creating a New Portal Skin

New portal skins will need to be added to the portal through the skin service. Therefore, the web application which contains the skins will need to be properly configured for the skin service to discover them. This means properly configuring the ResourceRequestFilter and gatein-resources.xml.

⁠13.6.2.1. Portal Skin Configuration

The gatein-resources.xml will need to specify the new portal skin. This will include the name of the new skin, where to locate its CSS stylesheet file and whether to overwrite an existing portal theme with the same name.

<gatein-resources>
  <portal-skin>
    <skin-name>MySkin</skin-name>
    <CSS-path>/skin/myskin.css</CSS-path>
    <overwrite>false</overwrite>
  </portal-skin>
</gatein-resources>

The default portal skin and window styles are defined in $JPP_HOME/gatein/gatein.ear/eXoResources.war/WEB-INF/gatein-resources.xml.

CSS

The CSS for the portal skin needs to contain the CSS for all the window decorations and the portlet specification CSS classes.

⁠13.6.2.2. Portal Skin Preview Icon

It is possible to see a preview of what the portal will look like when selecting a new skin. This functionality relies on the current skin being updated with skin icons for all other available skins. Otherwise it will not be able to show the previews.

It is recommended that preview icons of any other skins are included when creating a new portal skin and that the other skins are updated with your new portal skin preview.

Screenshot of the Skin Setting window, with the JppSkin selected in the Skins List.

Figure 13.1. Portal_Skin_Change

The portal skin preview icon is specified through the CSS of the portal skin. In order for the current portal skin to be able to display the preview it must specify a specific CSS class and set the icon as the background.

For a portal named MySkin, it must define the following CSS class:

.UIChangeSkinForm .UIItemSelector .TemplateContainer .MySkinImage

In order for the default skin to display the skin icon for a new portal skin, the preview screenshot must be placed in

$JPP_HOME/gatein/gatein.ear/eXoResources.war/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background

.

The CSS stylesheet for the default portal must have the following updated with the preview icon CSS class. For a skin named MySkin, the following must be updated

$JPP_HOME/gatein/gatein.ear/eXoResources.war/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css

.

.UIChangeSkinForm .UIItemSelector .TemplateContainer .MySkinImage {
  margin: auto;
  width: 329px; height:204px;
  background: url('background/MySkin.jpg') no-repeat top;
  cursor: pointer ;
}

⁠13.6.3. Creating a New Window Style

Window styles are the CSS applied to window decorations. An administrator can decide which style of decoration is applied to the window when they add a new application or gadget to a page.

The Decoration Themes tab selected, with the Simple Style collection highlighted.

Figure 13.2. Window Styles

⁠13.6.3.1. Window Style Configuration

Window Styles are defined within a gatein-resources.xml file which is used by the skin service to deploy the window style into the portal. Window styles can belong in a window style category. This category and the window styles will need to be specified in resources file.

The following gatein-resources.xml fragment will add MyThemeBlue and MyThemeRed to the MyTheme category.

<window-style>
  <style-name>MyTheme</style-name>
  <style-theme>
    <theme-name>MyThemeBlue</theme-name>
  </style-theme>
  <style-theme>
    <theme-name>MyThemeRed</theme-name>
  </style-theme>
</window-style>

The windows style configuration for the default skin is configured in: $JPP_HOME/gatein/gatein.ear/eXoResources.war/WEB-INF/gatein-resources.xml.

Window Styles and Portal Skins

When a window style is defined in gatein-resources.xml file, it will be available to all portlets regardless of whether the current portal skin supports the window decorator or not.

It is recommended that when a new window decorator is added that it be added to all portal skins or that all portal skins share a common stylesheet for window decorators.

⁠13.6.3.2. Window Style CSS

In order for the skin service to display the window decorators, it must have CSS classes specifically named in relation to the window style name. The service will try and display CSS based on this naming convention. The CSS class must be included as part of the current portal skin for the window decorators to be displayed.

The location of the window decorator CSS classes for the default portal theme is located at: JPP_HOME/gatein/gatein.ear/eXoResources.war/skin/PortletThemes/Stylesheet.css.

Create the CSS file:

/*---- MyTheme ----*/
.MyTheme .WindowBarCenter .WindowPortletInfo {
    margin-right: 80px; /* orientation=lt */
    margin-left: 80px; /* orientation=rt */
}

.MyTheme .WindowBarCenter .ControlIcon {
    float: right; /* orientation=lt */
    float: left; /* orientation=rt */
    width: 24px; 
    height: 17px;
    cursor: pointer;
    background-image: url('background/MyTheme.png');
}

.MyTheme .ArrowDownIcon {
    background-position: center 20px;
}

.MyTheme .OverArrowDownIcon {
    background-position: center 116px;
}

.MyTheme .MinimizedIcon {
    background-position: center 44px;
}

.MyTheme .OverMinimizedIcon {
    background-position: center 140px;
}

.MyTheme .MaximizedIcon {
    background-position: center 68px;
}

.MyTheme .OverMaximizedIcon {
    background-position: center 164px;
}

.MyTheme .RestoreIcon {
    background-position: center 92px;
}

.MyTheme .OverRestoreIcon {
    background-position: center 188px;
}

.MyTheme .NormalIcon {
    background-position: center 92px;
}

.MyTheme .OverNormalIcon {
    background-position: center 188px;
}

.MyTheme .Information {
    height: 18px; line-height: 18px;
    vertical-align: middle; font-size: 10px;
    padding-left: 5px; /* orientation=lt */
    padding-right: 5px; /* orientation=rt */
    margin-right: 18px; /* orientation=lt */
    margin-left: 18px; /* orientation=rt */
}

.MyTheme .WindowBarCenter .WindowPortletIcon {
    background-position: left top; /* orientation=lt */
    background-position: right top; /* orientation=rt */
    padding-left: 20px; /* orientation=lt */
    padding-right: 20px; /* orientation=rt */
    height: 16px;
    line-height: 16px;
}

.MyTheme .WindowBarCenter .PortletName {
    font-weight: bold;
    color: #333333;
    overflow: hidden;
    white-space: nowrap;
}

.MyTheme .WindowBarLeft {
    padding-left: 12px;
    background-image: url('background/MyTheme.png');
    background-repeat: no-repeat;
    background-position: left -148px;
}

.MyTheme .WindowBarRight {
    padding-right: 11px;
    background-image: url('background/MyTheme.png');
    background-repeat: no-repeat;
    background-position: right -119px;
}

.MyTheme .WindowBarCenter {
    background-image: url('background/MyTheme.png');
    background-repeat: repeat-x;
    background-position: left -90px;
    height: 21px;
    padding-top: 8px;
}

.MyTheme .MiddleDecoratorLeft {
    padding-left: 12px;
    background: url('background/MMyTheme.png') repeat-y left;
}

.MyTheme .MiddleDecoratorRight {
    padding-right: 11px;
    background: url('background/MMyTheme.png') repeat-y right;
}

.MyTheme .MiddleDecoratorCenter {
    background: #ffffff;
}

.MyTheme .BottomDecoratorLeft {
    padding-left: 12px;
    background-image: url('background/MyTheme.png');
    background-repeat: no-repeat;
    background-position: left -60px;
}

.MyTheme .BottomDecoratorRight {
    padding-right: 11px;
    background-image: url('background/MyTheme.png');
    background-repeat: no-repeat;
    background-position: right -30px;
}

.MyTheme .BottomDecoratorCenter {
    background-image: url('background/MyTheme.png');
    background-repeat: repeat-x;
    background-position: left top;
    height: 30px;
}

⁠13.6.3.3. How to Set the Default Window Style

To set the default window style to be used for a portal you will need to specify the CSS classes for a theme called DefaultTheme.

Note

You do not need to specify the DefaultTheme in gatein-resources.xml.

⁠13.6.4. How to Create New Portlet Skins

Portlets often require additional styles that may not be defined by the portal skin. The portal allows portlets to define additional stylesheets for each portlet and will append the corresponding link tags to the head.

The link ID will be of the form {portletAppName}{PortletName}.

For example: ContentPortlet in content.war, will give id="contentContentPortlet".

To define a new CSS file to include whenever a portlet is available on a portal page, the following fragment is required in gatein-resources.xml.

<portlet-skin>
  <application-name>portletAppName</application-name>
  <portlet-name>PortletName</portlet-name>
  <skin-name>Default</skin-name>
  <css-path>/skin/DefaultStylesheet.css</css-path>
</portlet-skin>

<portlet-skin>
  <application-name>portletAppName</application-name>
  <portlet-name>PortletName</portlet-name>
  <skin-name>OtherSkin</skin-name>
  <css-path>/skin/OtherSkinStylesheet.css</css-path>
</portlet-skin>

This will load the DefaultStylesheet.css when the Default skin is used and the OtherSkinStylesheet.css when the OtherSkin is used.

Updating Portlet Skins

If the current portal skin is not defined as one of the supported skins, then the portlet CSS class will not be loaded. It is recommended that portlet skins are updated whenever a new portal skin is created.

⁠13.6.4.1. Define a Custom CSS File

The portal does not serve CSS files directly, but uses a filter as well as a skin service in order to:

Cache the CSS files.
Merge them into one file if possible.
Add support for Right-To-Left (RTL) languages.

This causes the portal to create a non-functioning CSS link in html-src-code.

Procedure 13.1. Resolving a non-functioning CSS link

Add the following files to the custom portlet application:

WEB-INF/gatein-resources.xml:

<portlet-skin>
        <application-name>custom</application-name>
        <portlet-name>test</portlet-name>
        <skin-name>Default</skin-name>
        <css-path>/css/main.css</css-path>
</portlet-skin>

The value of the <application-name> element must match the value of the <display-name> element in web.xml.

The value of the <portlet-name> element must match the value of the <portlet-name> element in $JPP_HOME/standalone/configuration/gatein/portlet.xml.

WEB-INF/web.xml:


<display-name>custom</display-name>

<filter>
    <filter-name>ResourceRequestFilter</filter-name>
    <filter-class>org.exoplatform.portal.application.ResourceRequestFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>ResourceRequestFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

The value of the <display-name> element must match the value of the <application-name> element in gatein-resources.xml.

The ResourceRequestFilter must be added to the custom portlet application for proper CSS file handling within the Portal container.

WEB-INF/portlet.xml:

<portlet-name>test</portlet-name>

The value of the <portlet-name> element must match the value of the <portlet-name> element in gatein-resources.xml.

The final portlet application will be structured as illustrated below:

custom.war
  ├── css
  │   └── main.css
  └── WEB-INF
      ├── classes
      │     [... custom portlet class ...]
      ├── gatein-resources.xml
      ├── portlet.xml
      └── web.xml

⁠13.6.4.2. Change Portlet Icons

Each portlet can be registered by a unique icon in the portlet registry or page editor. This icon can be changed by adding an image to the directory of the portlet web application:

skin/DefaultSkin/portletIcons/portlet_name.png.

To be used correctly the icon must be named after the portlet.

For example; the icon for an account portlet named AccountPortlet would be located at:

skin/DefaultSkin/portletIcons/AccountPortlet.png

Portlet Icons Directory

You must use skin/DefaultSkin/portletIcons/ for the directory to store the portlet icon regardless of what skin is going to be used.

⁠13.6.5. Create New Portlet Specification CSS Classes

The portlet specification defines a set of default CSS classes that should be available for portlets. These classes are included as part of the portal skin. Please see the portlet specification for a list of the default classes that should be available.

For the default portal skin, the portlet specification CSS classes are defined in: $JPP_HOME/gatein/gatein.ear/eXoResources.war/skin/Portlet/Stylesheet.css.

⁠13.7. Tips and Tricks

⁠13.7.1. CSS Hosted on CDN

Red Hat JBoss Portal permits Cascading Stylesheet (CSS) to be loaded from external sources using a Content Delivery Network (CDN).

Declaring external CSS sources is achieved by using @import statements in CSS files that reference the external source (CDN).

Important

Import statements can not be declared in the <css-path> element of the gatein-resources.xml, and must be declared using @import statements directly in CSS files.

Example 13.3. Example CSS Import Statements

In this example, the URLs map to the page protocol that embeds the Cascading Stylesheet


@import url('//my-fast-cdn.com/my-favorite-framework/1.2.3/cool-theme.css');


@import url('//another-cdn.com/another-dir/another-style.css');

⁠13.7.2. Easier CSS Debugging

By default, CSS files are processed during deployment so that @import and url(...) statements are replaced by the content returned by the imported URLs. These imports are merged into a single CSS file that is stored in a cache and used by SkinService. This reduces the number of HTTP requests from the browser to the server.

Although the optimization is useful for a production environment, it may be easier to deactivate this optimization while debugging stylesheets. Set the Java system property exo.product.developing to true to disable the optimization.

For example, the property can be passed as a JVM parameter with -D option when running the portal.

Warning

This option may cause display bugs in some browsers.

./bin/standalone.sh -Dexo.product.developing=true

⁠13.7.3. Some CSS Techniques

It is recommended that users have some experience with CSS before studying Red Hat JBoss Portal (JBoss Portal) CSS.

JBoss Portal relies heavily on CSS to create the layout and effects for the user interface. Some common techniques for customizing JBoss Portal CSS are explained below.

⁠13.7.3.1. Decorator Pattern

The decorator is a pattern to create a contour or a curve around an area. In order to achieve this effect you need to create nine cells. The BODY is the central area to decorate. The other eight cells are distributed around the BODY cell. You can use the width, height and background image properties to achieve any desired decoration effect.

A diagram of the Decorator with the BODY cell in the center of a nine-grid pattern. Each cell surrounding the BODY cell describes a different position relative to the BODY cell.

Figure 13.3. Decorator Pattern

<div class="Parent">
  <div class="TopLeft">
    <div class="TopRight">
      <div class="TopCenter"><span></span></div>
    </div>
  </div>
  <div class="CenterLeft">
    <div class="CenterRight">
      <div class="CenterCenter">BODY</div>
    </div>
  </div>
  <div class="BottomLeft">
    <div class="BottomRight">
      <div class="BottomCenter"><span></span></div>
    </div>
  <div>
</div>

⁠13.7.3.2. Left Margin Left Pattern

Diagram explaining how Left Margin Left Pattern works, which is described below.

Figure 13.4. Left Margin Left Pattern

Left margin left pattern is a technique to create two blocks side by side. The left block will have a fixed size and the right block will take the rest of the available space. When the user resizes the browser the added or removed space will be taken from the right block.

<div class="Parent">
  <div style="float: left; width: 100px">
  </div>
  <div style="margin-left: 105px;">
  <div>
  <div style="clear: left"><span></span></div>
</div>