Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

Handling different skins in a portlet

Each WebUI component has the proper graphic template, JavaScript codes, and skin, so it's very simple to assign a different configuration for a single component. The same portal is managed by WebUI so it has configurable skins, JavaScript, and template too. In this recipe, you will see how to add a skin to a component inside the portal.

Getting ready

You will start with the previous example. You will add a new skin to the MyPortlet example by adding a new configuration file. The skin contains CSS files and images. For convenience, you will use the existing skin for the UISiteMap component.

How to do it...

Carry out the following steps to add a new skin to the project:

Create the gatein-resources.xml in the folder MyApplication.war/WEB-INF/conf:
```
<portlet-skin>
  <application-name>
     MyApplication
  </application-name>
  <portlet-name>MyPortlet</portlet-name>
  <skin-name>Default</skin-name>
  <css-path>
/skin/portal/webui/component/My/DefaultStylesheet.css
  </css-path>
</portlet-skin>
```
This file activates a service, the Skin Service, which registers the styles for the portlet signed in the portlet-name of the application signed in the application-name. The deployment of the gatein-resources.xml generates events captured by different deployers. In the case of the skin, the GateInSkinConfigDeployer captures the events and passes the skins to the Skin Service to register.
It is important in this service to use the tag display-name of the web.xml file. You are forced to use the name of the application; otherwise, you will receive an exception:
```
<display-name>MyApplication</display-name>
```

You need also to add a filter in your WEB-INF/web.xml file, which interrogates the Skin Service and renders dynamically the respective CSS 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>/*</url-pattern>
</filter-mapping>

Create the /skin/portal/webui/component/My folder where we will put the style file with the images. For convenience, copy the contents of the main portal application folder: web/skin/portal/webui/component/UISiteMap/.
The skin is called by the views through the CSS class or ID. It is good practice to create the CSS classes with the name of the WebUI component. If you open the current DefaultStyleSheet.css, you will see the defined CSS class UISitemap. Rename all definitions with the name of your new component, My.
Now you need to call the CSS class in your view. For this, use a new Groovy template. The previous example used was the UISitemapTree.gtmpl template. We can rewrite it and pass it the new skin. To achieve this, create a new folder in your application using the same path of the folder as of the main portal application. In this folder, the main portal application has several groovy pages: /groovy/webui/core, and copy the existing UISitemapTree.gtmpl from the $PORTAL_ROOT/groovy/webui/core folder.

The only thing to do in the file is to point the main div to the new CSS class so:

<div id="$uicomponent.id" class="My" >
   <div class="ClearFix">
      <div class="CollapseAll FloatLeft" onclick="$actionCollapseAll">
         <%=_ctx.appRes(siteMapPortlet.getName() + ".label.CollapseAll")%>
      </div>
   </div>
   <div class="SitemapContent">
      <div class="UISiteTree">
         <% TreeNode treeNodeRoot = uicomponent.getTreeNodes() ;%>
         <% renderNodes(treeNodeRoot,nodeURL,useAJAX); %>
      </div>
   </div>
</div>

In the previous example, you have called this Groovy script dynamically from the constructor of the portlet. Actually, it calls the script from the system path, so the new script doesn't override it. To allow the override, you have to change the schema from system to app in the following way:
- app:/groovy/webui/core/UISitemapTree.gtmpl instead of system:/groovy/webui/core/UISitemapTree.gtmpl.
Here is the result:
The remaining steps will allow you to modify the skin from the web console.
Click on the GateIn logo button and click on Change Skin.
From the resultant window, select one of the two available skins; for example, we will select the Simple skin.
This is the result:

How it works...

A new configuration file is shown here, the gatein-resources.xml. The following screenshot shows the root configuration:

Three Deployers catch this file:

org.exoplatform.web.application.javascript.JavascriptConfigDeployer: This reads the configuration of the JavaScript. It will be exposed in the next recipe.
org.exoplatform.portal.resource.GateInSkinConfigDeployer: This reads the configuration of the skin.
org.exoplatform.portal.resource.GateInSkinConfigRemoval: Removes the configuration of the skin from the context

GateInSkinConfigDeployer takes the skin configuration and processes it. If the validation is ok, it passes the skin to the Skin Service.

The Skin Service is provided by the org.exoplatform.portal.resource.SkinService class. It maintains all the skin configurations in a registry, categorized by the skin ID.

There are two types of skins in the default portal: the Portal skin and the Portlet skin. The only difference between them is that the Portlet skin is categorized by application ID and portlet ID. You can set a skin for a portlet or for the whole application.

The Portal skin is categorized by a portal ID. It makes no sense for a portlet to use a Portal skin because the graphic is completely different, but if you would do it, you simply need to declare the Portal skin as Portlet skin in the gatein-resources.xml.

The ResourceRequestFilter has a big role. This filter receives the URL of the resources requested by pages and renders them. The resources can be CSS, images, or JavaScript. For the rendering of the CSS, the renderCSS method of the Skin Service is used.

The URL of the CSS resource is calculated through the parameters declared in the skin configuration of the gatein-resources.xml in the following way:

application-name + css-path

Moreover, orientation is added in the CSS, –lt or –rt according the used language. For the example, the URL of the skin is:

/MyApplication/skin/portal/webui/component/My/DefaultStylesheet-lt.css

The skin-name tag in the gatein-resources.xml is very important. It links the portlet to the Portal skin. It's important to know the Portal skin when you add a new Portlet skin. If the skin-name is not an existing Portal skin, you won't see the results declared in your custom Portlet skin.

The list of the available Portal skins can be found in the WEB-INF/gatein-resources.xml file of the applications. Each application can rewrite them or add new skins through a new gatein-resources.xml file. You have two Portal skins:

eXoResources/WEB-INF/gatein-resources.xml:

<portal-skin>
  <skin-name>Default</skin-name>
  <css-path>/skin/Stylesheet.css</css-path>
  <css-priority>0</css-priority>
</portal-skin>

gatein-sample-skin/WEB-INF/gatein-resources.xml:

<portal-skin>
   <skin-name>SimpleSkin</skin-name>
   <css-path>/skin/Stylesheet.css</css-path>
   <css-priority>0</css-priority>
</portal-skin>

There's more...

Here we extend some discussions from earlier.

Deployers

The deployers in GateIn are event listeners. They extend the org.gatein.wci.WebAppListener interface as follows:

public interface WebAppListener
{

   /**
    * Signal a web application event to the listener.
    *
    * @param event the web application event
    */
   void onEvent(WebAppEvent event);
}

The received events can be:

ADDED: The new resource is added
REMOVED: The resource is undeployed

The WCI passes the events to the deployers.

The other deployer is the org.gatein.pc.portlet.impl.deployment.PortletApplicationDeployer. All portal applications are intercepted by this deployer and installed by assigning a lifecycle.

The window style

Another part of the gatein-resources.xml is the Window Style. It represents the graphic assigned to the windows of the portal. If you go to the Edit Page window and select a portlet and click on the Edit Portlet button, you can see on the left the default Window Styles available for the portlet:

The configuration and the use are very similar to the skin. GateIn supports many Window Styles configured in the exoResources application in the file exoResources/WEB-INF/gatein-resources.xml. Here is one example of the Simple window style:

<window-style>
   <style-name>Simple</style-name>
   <style-theme>
      <theme-name>SimpleBlue</theme-name>
   </style-theme>
   <style-theme>
      <theme-name>SimpleViolet</theme-name>
   </style-theme>
   <style-theme>
      <theme-name>SimpleOrange</theme-name>
   </style-theme>
   <style-theme>
      <theme-name>SimplePink</theme-name>
   </style-theme>
   <style-theme>
      <theme-name>SimpleGreen</theme-name>
   </style-theme>
</window-style>

If you open exoResources/skin/Stylesheet.css, there is an import of the images folder of the Window Styles:

@import url(PortletThemes/Stylesheet.css);

Each Window Style contains a set of themes that can be chosen by the web console for a single window. Here is an example of a CSS class declaration of the SimpleBlue theme in the PortletThemes/Stylesheet.css:

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

The styles take part in the decoration process. By default, no window uses the styles.

The configuration of the decoration can be done through a web console or through an XML file with the pages.xml file. In this configuration, you can declare all the pages of the portal and its properties so they will be created automatically on the first boot of the portal. See the properties of the home page in the configuration of the root portal in the $ROOT_PORTAL/WEB-INF/conf/portal/portal/classic/pages.xml:

<page>
    <name>homepage</name>
    <title>Home Page</title>
    ...
    <portlet-application>
      <portlet>
        <application-ref>web</application-ref>
        <portlet-ref>HomePagePortlet</portlet-ref>
        ...
      </portlet>
      <title>Home Page portlet</title>
      <access-permissions>Everyone</access-permissions>
      <show-info-bar>false</show-info-bar>
      <show-application-state>false</show-application-state>
      <show-application-mode>false</show-application-mode>
    </portlet-application>
  </page>

This file creates a page and associates an existing portlet to it.

We have three properties here:

show-info-bar: Shows the base window.
show-application-state: Basically, this shows the buttons for minimizing and maximizing the portlet.
show-application-mode: Shows the list of modes for the portlet, for example, the help page, edit page, and view page. Click inside to select the preferred mode.

If you set the three properties to true, you will see the default theme on the portlet.

The default theme is declared directly in the Stylesheet.css file through the section DefaultTheme. There is no way to choose the theme through XML.

Carry out the following steps to choose it through the web console:

Choose a page, for example the SiteMap, and select Edit Page as shown in the following screenshot:
Click on Edit Portlet:
On the Portlet Setting tab, flag all three checkboxes so you can see the whole window:
In Decoration Themes, choose the window style, for example Mac Style.
Click on Save and Close and then on the Finish button.