eXo Platform 3.0

- Prev
- Next

## Chapter 5. Create Your Own Portal

When working with eXo, it is important not to modify the source code. This will ensure compatibility with future upgrades, and support will be simplified. To customize your portal, you need to create an extension project by providing your own artifacts as a set of wars/jars/ears.

## Create your extension project

A custom extension contains two mandatory items:

1. extension webapp contains resources and kernel configurations.

2. extension activator jar identifies your webapp as a dependency of the portal container.

To see the sample extension package, go to here.

Once you have modified the sample extension to build your own portal, use "mvn clean install" to create the archive files.

To deploy your extension in Tomcat, do as follows:

Step 1: Add the file sample-ext.war from the `sample/extension/war/target/` to the directory `tomcat/webapps`.

Step 2: Add the folder `starter` from `starter/war/target/` to the directory `tomcat/webapps`.

Step 3: Rename the directory (unzipped folder) `starter` to `starter.war`.

### Note

This will only work if the starter.war is the last .war file to be loaded, so you may need to rename it if your war files are loaded in the alphabetical order.

Step 4: Add the .jar file `exo.portal.sample.extension.config-X.Y.Z.jar` from `sample/extension/config/target/` to the `tomcat/lib` directory.

Step 5: Add the .jar file `exo.portal.sample.extension.jar-X.Y.Z.jar` from `sample/extension/jar/target/` to the `tomcat/lib` directory.

For JBoss deployment and more details, refer to Reference Guide on here.

## Structure of portal, pages and menus

You can create multiple pages within a single portal. Permissions can be defined to make them visible only to specific groups and/or users. This chapter describes how to define this structure.

### Page layout

The configuration of "classic" portal can be found in the `/src/main/webapp/WEB-INF/conf/sample-ext/portal/portal/classic` directory of your extension webapp.

Portal:

The `portal.xml` file describes the layout and portlets common to all pages of the portal.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <portal-config
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0"
        xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0">
      <portal-name>classic</portal-name>
      <locale>en</locale>
      <access-permissions>Everyone</access-permissions>
      <edit-permission>*:/platform/administrators</edit-permission>
      <properties>
        <entry key="sessionAlive">onDemand</entry>
      </properties>

         <portal-layout>
          <portlet-application>
          <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>BannerPortlet</portlet-ref>
            <preferences>
              <preference>
                <name>template</name>
                <value>par:/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</value>
                <read-only>false</read-only>
              </preference>
            </preferences>
          </portlet>
          <access-permissions>Everyone</access-permissions>
            <show-info-bar>false</show-info-bar>
          </portlet-application>

          <portlet-application>
          <portlet>
           ...
          </portlet>
          </portlet-application>

          <portlet-application>
          <portlet>
            ...
          </portlet>
          </portlet-application>

          <page-body> </page-body>

         <portlet-application>
           <portlet>
             ...
           </portlet>
         </portlet-application>
      </portal-layout>
    </portal-config>

As you can see, each portlet can be configured with a set of preferences, which will be further detailed in Chapter 6. The tag <page-body> </page-body> is a placeholder for the different pages of your portal. When the user opens a new portal page, all portlets of the portal layout (portal.xml) are remained, whereas the content of <page-body> switches to the page opened by the user.

Pages:

The `pages.xml` file is used to describe the content of pages of your portal. In other words, pages of your portal will be inside the <page-body> tag of the `portal.xml` file above.

This is the example of pages.xml of the classic portal.

    <page>
        <name>homepage</name>
        <title>Home Page</title>
        <access-permissions>Everyone</access-permissions>
        <edit-permission>*:/platform/administrators</edit-permission>
        <container id="ClassicBody" template="system:/groovy/portal/webui/container/UITableColumnContainer.gtmpl">
          <access-permissions>Everyone</access-permissions>
          <container id="ClassicLeft" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
            <access-permissions>Everyone</access-permissions>
            <portlet-application>
              <portlet>
                <application-ref>presentation</application-ref>
                <portlet-ref>SingleContentViewer</portlet-ref>
                <preferences>
                  <preference>
                    <name>repository</name>
                    <value>repository</value>
                    <read-only>false</read-only>
                  </preference>
                  ...
                  <preference>
                    <name>ShowTitle</name>
                    <value>false</value>
                    <read-only>false</read-only>
                  </preference>
                </preferences>
              </portlet>
              <title>Introduce</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>
          </container>
        </container>
      </page>

### Note

See Chapter 6 to learn more about the portlet configuration within the pages.xml file.

Navigation:

The navigation.xml is used to associate the links in your navigation with your portal pages. The navigation is a tree structure of "navigation nodes". Each navigation node points to one page (called the page node). The tree structure corresponds to a hierarchy of menus and sub-menus of a site.

If the pattern #{} is used, the link label will be loaded from the portal resource bundle. To learn more, refer to Internationalization Configuration.

    <node-navigation>
    <owner-type>portal</owner-type>
    <owner-id>classic</owner-id>
    <priority>1</priority>
    <page-nodes>
    <node>
    <uri>home</uri>
    <name>home</name>
    <label>#{portal.classic.home}</label>
    <page-reference>portal::classic::homepage</page-reference>
    </node>
    <node>
    <uri>webexplorer</uri>
    <name>webexplorer</name>
    <label>#{portal.classic.webexplorer}</label>
    <page-reference>portal::classic::webexplorer</page-reference>
    </node>
    </page-nodes>
    </node-navigation>

This navigation tree is shown and reused in different portlets, such as sitemap, navigation or breadcrumbs. The breadcrumbs portlet renders the position of the current navigation node.

### Note

For the top nodes, the URI and the navigation node name must have the same value. For other nodes, the URI is composed like <uri>contentmanagement/fileexplorer</uri> where 'contentmanagement' is the name of the parent node and 'fileexplorer' is the name of node (<name>fileexplorer</name>).

### Visibility of pages

You can easily restrict the visibility of selected pages and navigation nodes to certain groups and users. You just need to create `pages.xml` and `navigation.xml` files in folders named after the group and user to which you want to give permission:

sample-ext/portal/group/group-name/your files

sample-ext/portal/user/username/your files

## Add/remove languages

All languages are put in the myextension.war/WEB-INF/conf/common/locales-config.xml directory. Each language consists of information related to key, output-encoding, input-encoding, description and orientation. Different languages will be defined in corresponding resource bundle files with keys specified in the locale-config.xml file.

All languages defined in the locale-config.xml file are listed in Interface Language Settings.

### Add a new language

To add a new language, you need to add the corresponding language node in the locale-config.xml file. Next, you must create a new resource bundle file containing the suffix name as key of the added node.

For example, to add Italian, do as follows:

Step 1: Add the following node to the locale-config.xml file.

    <locale-config>
        <locale>it</locale>
        <output-encoding>UTF-8</output-encoding>
        <input-encoding>UTF-8</input-encoding>
        <description>Default configuration for Italian locale</description>
    </locale-config>

Step 2: Create a new resource bundle as webui_it.properties in the myextension.war/WEB-INF/classes/locale/portal folder.

### Note

This step is necessary because the Resource Bundle Service of the portal will find keys and values in the resource bundle of each corresponding language.

Step 3: Restart the server.

To check if the added language takes effect, simply click the Change Language button on the top right corner of the portal. In the Interface Language Setting window, you will see Italian as shown:

Illustration 1: Italian display on Interface Language Setting

### Remove languages

To remove an existing language, you need to delete the relevant language node in the locale-config.xml file and all files containing the suffix name as the key of language.

For example, to remove French, do as follows:

Step 1: Find and remove the following node from the locale-config.xml file.

    <locale-config>
        <locale>fr</locale>
        <output-encoding>UTF-8</output-encoding>
        <input-encoding>UTF-8</input-encoding>
        <description>Default configuration for france locale</description>
    </locale-config>

Step 2: Continue removing all resource bundle files containing the suffix name as fr in all folders.

### Note

It is recommended to do this step to delete unnecessary data in the application.

Step 3: Restart the server.

To check if the French removal takes effect, simply click the Change Language button on the top right corner of the portal. In the Interface Language Setting window, French which is shown in the Illustration 1 has not existed on the Interface Language Setting window.

Illustration 2: Interface Language Setting without French

## Create custom look and feel

### Structure stylesheet

#### Page skin elements

The complete skinning of a page can be decomposed into three main parts:

Portal skin

The portal skin contains styles for html tags (for example, div, th, td) and the portal UI (including the toolbar). This should include all UI components, except for window decorators and portlet specific styles.

Window styles

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

Portlet skins

The portlet skins affect how portlets are rendered on the page. The portlet skins can affect in two main ways:

##### Portlet Specification CSS Classes

The portlet specification defines a set of CSS classes that should be available to portlets. Platform provides these classes as a part of the portal skin. This enables each portal skin to define its own look and feel for these default values.

##### Portlet skins

Platform provides a means for portlet CSS files to be loaded that is based on the current portal skin. This enables a portlet to provide different CSS styles to better match the current portal's look and feel.

### Note

The window decorators and the default portlet specification CSS classes should be considered as separate types of skinning components, but they need to be included as a part of the overall portal skin. The portal skin must include CSS classes of these components or 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 portlets web application.

#### Best practices to customize a skin

The skin folder structure must be prepared once you start the design. Follow these conventions and best practices to ease the integration of your design in Platform.

#### Name files and folders

The id and class names are defined after the WebUI components name and portlets name with the 'UI-' as prefix. The same rule is applied for folder that contains components and portlets. It will help you find and edit correct files easily. For example, the UI portlet will be named as UIFooterPortlet, or UIBannerPortlet and the UI component will be named as UIToolbarContainer, or UIVerticalTab.

#### Folder structure

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 enables the portal skin to be transfered more quickly as a single file instead of many smaller files included with every page render.

The general folder structure for portal skin:

`/webapp/skin/NameOfPortalSkin/portal`

For example:

`/webapp/skin/DefaultSkin/portal`

The main entry CSS file:

The main entry CSS file should be placed right in the main portal skin folder. The file is the main entry point to the CSS class definitions for the skin:

`/webapp/skin/NameOfPortalSkin/Stylesheet.css`

For example:

`/webapp/skin/SkinBlue/Stylesheet.css`

The folder structure for WebUI components:

`/webapp/skin/SkinBlue/webui/component/YourUIComponentName`

For example:

`/webapp/skin/SkinBlue/webui/component/UIToolbarContainer`

Window decorator CSS is put in:

`webapp/skin/PortletThemes/Stylesheet.css`

Where to put images for portal skin?

The images for portal skin should be put in the background folder right in the Portal skin folder and for each UI component.

For example:

`/webapp/skin/SkinBlue/webui/component/UIProfileUser/SkinBlue/background`

In summary, the folder structure for a new portal skin should be:

webapp

- skin

  - NameOfPortalSkin

    - stylesheet.css

    - webui

      - component

        - UIComponentName

          - NameOfPortalSkin.css

          - NameOfPortalSkin

            - background

For example:

webapp

- skin

  - DefaultSkin

    - stylesheet.css

    - webui

      - UISpaceSearch

        - DefaultSkin.css

        - DefaultSkin

          - background

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. The link ID will be named like {}}}portletAppName}}}}}}}{~}~}}PortletName}}}}}}}. For example, ContentPortlet in `content.war` will give `id="contentContentPortlet"`.

General folder structure for portlet skin:

`/webapp/skin/portlet/webui/component/YourUIPortletName`

and for the Groovy skin: `/webapp/groovy/portlet/webui/component/YourUIPortletName/`

For example:

`/webapp/skin/portlet/webui/component/UIBannerPortlet`

`/webapp/groovy/portlet/webui/component/UIBannerPortlet`

Portlet images folder:

`/webapp/skin/portlet/YourUIPortletName/PortalSkinName/background`

For example:

`/webapp/skin/portlet/UIBannerPortlet/BlueSkin/background`

Portlet themes

Main entry CSS:`/webapp/skin/PortletThemes/Stylesheet.css`

`/webapp/skin/PortletThemes/background`

`/webapp/skin/PortletThemes/icons`

### Configure skin in GateIn

GateIn 3.1 provides support for skinning the entire User Interface (UI) of portal, including all common portal elements, custom skins and window decorator for individual portlets. Skins are designed to help you pack and reuse common graphic resources.

#### Select skins within the configuration files

The default skin can be set in the portal configuration files. The skin configured as default is used by GateIn as the administrator starts/restarts the server. To change the default skin, add a skin tag to the portal.war/WEB-INF/conf/portal/portal/classic/portal.xml configuration file. To change the skin to MySkin, do as follows:

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

#### Skins in the page markup

The GateIn 3.1 skin not only contains CSS styles for the portal's components, but also shares components that may be reused in portlets. When GateIn 3.1 generates the page markup of portal, it inserts stylesheet links in the page's head tag. There are two main types of CSS links which appear in the head tag: one to the portal skin CSS file and the other to the portlet skin CSS file.

1. Portal Skin appears as a single link to a CSS file. This link contains contents from all portal skin classes merged into one file. The portal skin will be transfered more quickly as a single file instead of multiple smaller files.

2. Portlet Skin only appears as the link on the page if that portlet is loaded on the current page. A page may contain many CSS links of portlet skins or none.

In the code fragment below, you can see 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 portlet specification CSS classes are included within the portal skin.

#### SkinService

SkinService in GateIn 3.1 is to manage various types of skins. It is used to discover and deploy skins into the portal.

##### Configure skins

GateIn 3.1 automatically discovers web archives that contain a file descriptor for skins (WEB-INF/gatein-resources.xml). This file is to specify which portal, portlet and window decorators will be deployed into the skin service. The full schema can be found in the lib directory: exo.portal.component.portal.jar/gateinresources10.xsd. Here is an example where we define a skin (MySkin) with its CSS location, and specify a few window decorator skins:

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

     <!-- 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>
     </window-style>

    </gatein-resources>

##### ResourceRequestFilter

With the Right-To-Left support, you need to retrieve all CSS files through a Servlet filter and to configure the web application to activate this filter. This has been already done for the eXoResources.war web application which contains the default skin. Any new web applications containing skinning CSS files need to have the following added to their web.xml:

    <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 configuration of Portlet Skin takes an optional parameter application-name, which is the web application wrapping skinned portlet. Hence, the display-name element in web.xml need to be coherent with the application-name in the gatein-resources.xml file.

    <portlet-skin>

       <!-- the application-name must be identical to display-name of the web application wrapping HomePagePortlet portlet -->
       <application-name>web</application-name>
       <portlet-name>HomePagePortlet</portlet-name>
       <skin-name>Default</skin-name>
       <css-path>/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css</css-path>
    </portlet-skin>

#### Default skin

The default skin of GateIn 3.1 is located as part of the eXoResource.war. The main files associated with the skin include:

1. WEB-INF/gatein-resources.xml: defines the skin settings to use.

2. WEB-INF/web.xml: contains the resource filter with the display-name set.

3. skin/Stylesheet.css: contains the CSS class definitions for this skin.

The following block of CSS illustrates content of the Stylesheet.css file:

    @import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css); (1)
    @import url(DefaultSkin/webui/component/Stylesheet.css); (2)
    @import url(PortletThemes/Stylesheet.css); (3)
    @import url(Portlet/Stylesheet.css); (4)

In which, (1) Skin of portal page. UIPortalApplicationSkin.css defines CSS classes shared by all the portal pages. (2) Skins of various portal-owned components, such as WorkingWorkspace, MaskWorkspace, PortalForm, and more. (3) Window decorator skins. (4) The portlet specification CSS classes. (The CSS styles defined in Portlet Specification JSR286)

To make a default skin flexible and highly reusable, instead of defining all CSS classes in this file, CSS classes are arranged in nested stylesheet files, based on the @import statement. This makes easier for new skins to reuse parts of the default skin. To reuse a CSS stylesheet from the default portal skin, you need to refer to the default skin from eXoResources. For example, to include the window decorators from the default skin within a new portal skin, you need to use the following import:

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

### Note

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

#### Create new skins

##### Create new portal skins

It is required to add a new skin to the portal through the skin service. Web applications containing the skin need to be properly configured for the skin service to discover them, meaning that the gatein-resources.xml must be configured correctly.

###### Configure portal skins

You need to specify the new portal skin in the gatein-resources.xml file. You also need to specify the name of new skin, where to locate its CSS stylesheet file and whether to overwrite the 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 the eXoResources.war/WEB-INF/gatein-resources.xml.

### Note

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

###### Portal skin preview icon

You can preview the appearance of portal skin when selecting it. To display the preview image of deployed skins, the current skin must be aware of all those icons. Hence, each skin must contain preview images of all other skins.

For any portal skin, the paths to preview images are specified in CSS class UIChangeSkinForm:

eXoResources/src/main/webapp/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css

For the portal named MySkin, it is required to define the following CSS classes:

    .UIChangeSkinForm .UIItemSelector .TemplateContainer .MySkinImage

The default skin would be aware of skin icons if the preview screenshot is placed in: eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background.

The CSS stylesheet for the default portal needs to have the following updated with the preview icon CSS class. For the skin named MySkin, it is required to update the following: eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css. For now, amending deployed package eXoResources is inevitable (modifying default war/jar breaches development convention of GateIn-based products). The problem would be resolved in future GateIn versions in which different skin modules are fully independent, for example, there will be no preview image duplication.

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

##### Create new window styles

Window style is the CSS applied to the window decorator. When the administrator selects a new application to add to a page, he can decide which style of decorator surrounding the window if any.

###### Configure window styles

Window style is defined within the gatein-resources.xml file used by the SkinService to deploy the window style into the portal. Window styles can belong to a window style category. This category and window styles need to be specified in the resources file. The following gatein-resource.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 of the default skin is configured in the eXoResources.war/WEB-INF/gatein-resources.xml file.

### Note

When a window style is defined in the gatein-resources.xml file, it will be available to all portlets regardless of whether the current portal skin supports the window decorator or not. When a new window decorator is added, it should be added to all portal skins or the portal skins should share a common stylesheet for window decorators.

###### Window style CSS

In order for the SkinService to display the window decorators, it must have CSS classes with the specific naming related to the window style name. The service will try and display CSS based on this naming. The CSS class must be included as part of the current portal skin for the window decorators to be displayed. The window decorator CSS classes for the default portal theme are located at: eXoResources.war/skin/PortletThemes/Stylesheet.css

###### Set the default window style

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

### Note

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

##### Create new portlet skins

Portlets often require additional styles that may not be defined by the portal skin. GateIn 3.1 defines additional stylesheets for each portlet and will append the corresponding link tags to the head. The ID attribute of <link> element will be in the form `portletAppName/PortletName`. For example, the ContentPortlet in content.war takes "content/ContentPortlet" as ID. To define a new CSS file to be included whenever a portlet is available on a portal page, the following fragment needs to be added in the gatein-resources.xml file.

    <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 action will load DefaultStylesheet.css or OtherSkinStylesheet.css when the DefaultSkin or OtherSkin is used respectively.

### Note

If the current portal skin is not defined as part of the supported skins, the portlet CSS class will not be loaded. The portlet skins should be updated whenever a new portal skin is created.

##### Change portlet icons

Each portlet can be represented by an unique icon that you can see in the portlet registry or page editor. This icon can be changed by adding an image to the directory of portlet web application: skin/DefaultSkin/portletIcons/iconname.png. The icon must be named after the portlet. For example, the icon of account portlet must be named AccountPortlet and located at: skin/DefaultSkin/portletIcons/AccountPortlet.png

### Note

You must use skin/DefaultSkin/portletIcons/ for the directory to store the portlet icon regardless of using any skins.

##### Configure right-to-left skins

The SkinService handles stylesheet rewriting to accommodate the orientation. It works by appending -lt or -rt to the stylesheet name. For instance, /web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css will return the same stylesheet as /web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css but processed for the RT orientation. The -lt suffix is optional. Stylesheet authors can annotate their stylesheet to create content that depends on the orientation.

Example 1. In this example, we need to use the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right:

    float: left; /* orientation=lt */
    float: right; /* orientation=rt */
    font-weight: bold;
    text-align: center;
    white-space: nowrap;

The LT produced output will be:

    float: left; /* orientation=lt */
    font-weight: bold;
    text-align: center;
    white-space: nowrap;

The RT produced output will be:

    float: right; /* orientation=rt */
    font-weight: bold;
    text-align: center;
    white-space: nowrap;

Example 2. In this example, we need to modify the padding based on the orientation:

    color: white;
    line-height: 24px;
    padding: 0px 5px 0px 0px; /* orientation=lt */
    padding: 0px 0px 0px 5px; /* orientation=rt */

The LT produced output will be:

    color: white;
    line-height: 24px;
    padding: 0px 5px 0px 0px; /* orientation=lt */

The RT produced output will be:

    color: white;
    line-height: 24px;
    padding: 0px 0px 0px 5px; /* orientation=rt */

#### Override skins with extension

The extension mechanism of GateIn 3.1 enables the skin definition to be replaced with the skin resource configured in the extension-deployed web application. This is the example where the CSS path of default portal skin needs to be modified without touching the GateIn's files.

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

To do so, do as follows:

Step 1: Create a web application whose gatein-resources.xml contains the same content as the above xml block, except the element <css-path> is modified.

Step 2: Register the artifact in the dependencies list of extended Portal Container.

Step 3: Ensure that once the server has deployed the artifact, it does not load any web application with gatein-resources.xml configuring the same portal skin.

By the time those lines are written out, the control of loading order required in the third step relies totally on the Web Container Integration (WCI), hence the conflict may occur. That would be resolved by the concept of portal skin priority introduced in the coming version of GateIn.

### Configure skin in WCM

#### Goal

This tutorial will help you to create a new layout and skin, and give some best practices you should know and respect when creating a new layout and skin for your portal and page.

#### Assumptions

- You have an extension named "MyPortal", and you need to create a site called "MySite" inside this portal.

- The }}}<myportal_path>}}} below is replaced by the based path of your "MyPortal" extension.

- If you see any folder/file which does not exist, you should create a new one.

#### Customize portal's layout

### Note

This section is related to the configuration. You can see a sample here. You can leave all the portlet's preferences as blank, that means the default value will be taken and you do not need to care about it at this time.

- For example, you will have a layout like this:

In which:

- Branding: A branding application

- Top navigation: A top navigation application

A table column container with three nested containers:

- Left Column and Right Column: contain one application for each.

- Main content: contains the page body.

And here is the "short version" of `portal.xml` .

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/portal/portal/mysite/portal.xml

    <!-- ... -->

      <portlet-application>
        <!-- Branding application. You can use WCM web content *exo:webContent* for the content and SCV portlet to display -->
      </portlet-application>

      <portlet-application>
        <!-- navigation application. You can use WCM web content *exo:webContent* for the content and SCV portlet to display -->
      </portlet-application>

      <container id="MySite" template="system:/groovy/portal/webui/container/UITableColumnContainer.gtmpl">
        <container id="LeftColumn" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
          <!-- One or more application(s) here -->
          <portlet-application>
          </portlet-application>
        </container>

        <container template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
          <page-body>
          </page-body>
        </container>

        <container id="RightColumn" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
          <!-- One or more application(s) here -->
          <portlet-application>
          </portlet-application>
        </container>
      </container>

      <portlet-application>
        <!-- Footer application. You can use WCM web content *exo:webContent* for the content and SCV portlet to display -->
      </portlet-application>

    <!-- ... -->

As you see in the portal.xml file above, every container tag has an id attribute, for example "<container id = 'RightColumn'>". When you create a CSS file, the property applied for this container should have the following name manner:

    ${container_id}TDContainer

and the details of this container:

    RightColumnTDContainer

The reason is, when you have a look in the file system:/groovy/portal/webui/container/UITableColumnContainer.gtmpl_* shown above, you will see this code fragment:

     <table class="UITableColumnContainer" style="table-layout: fixed; margin: 0px auto; $style">
    	<tr class="TRContainer">
    		<% for(uiChild in uicomponent.getChildren()) {%>
    			<td class="${uiChild.id}TDContainer TDContainer"><% uicomponent.renderUIComponent(uiChild) %></td>
    		<% } %>
    	</tr>
    </table>

So, in the table element (which represents the outer container), there are many td elements, each of which has the class attribute that equals to the id of the corresponding child component plus the "TDContainer" string literal.

To learn more, see Customize portal and page's style.

#### Customize page's layouts

### Note

This section is related to the configuration. You can see a sample here. You can leave all the portlet's preferences as blank, that means the default value will be taken and you do not need to care about it at this time.

- Like `portal.xml` , you can define the layout for each page in your site as shown in the following example:

    <!-- ... -->

      <portlet-application>
        <!-- A custom document for content and SCV portlet to display -->
      </portlet-application>

      <portlet-application>
        <!-- A CLV portlet with a custom template. -->
      </portlet-application>

      <portlet-application>
        <!-- A CLV portlet with another custom template. -->
      </portlet-application>

    <!-- ... -->

#### Customize portal and page's style

If you want your skin to be applied for every page, do as follows:

Step 1: Go to Sites Explorer portlet > Shared drive > CSS folder. Step 2: Create a new CSS document which contains your stylesheet. You can use any name for this document and put a priority number.

If you want your skin to be applied for your MySite page only, do as follows:

Step 1: Open the browser > Sites Explorer portlet > Sites management drive > MySite/css folder. Step 2: Create a new CSS document which contains your stylesheet for the portal and the page layout. You can use any name for this document and put a priority number.

### Warning

This document should contain ONLY the stylesheet for the page and portal level.

The following is one sample stylesheet:

    /* ... */

    .LeftColumnTDContainer {
      /* ... */
    }
    .RightColumnTDContainer {
      /* ... */
    }

    /* ... */

### Note

The order of applying CSS files (of site and web content) depends on their own priority property value. It means that we can apply the site CSS first and then web content CSS, or vice versa.

#### Customize CLV portlet's template

### Note

This section is related to the configuration. You can see a sample here

- Apply your HTML/Groovy template code for this template. For example:

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/template/list/ACustomizedCLVTemplate.gtmpl

    <div id="$uicomponent.id" class="ACustomizedCLVTemplate">
      <div class="ListContents">
        <!-- something here -->
      </div>
    </div>

- Now, we need to import this template to the database.

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/template/configuration.xml

      <external-component-plugins>
        <target-component>org.exoplatform.services.cms.views.ApplicationTemplateManagerService</target-component>
        <component-plugin>
          <name>ACustomizedCLVTemplate</name>
          <set-method>addPlugin</set-method>
          <type>org.exoplatform.services.cms.views.PortletTemplatePlugin</type>
          <description>This is a sample customized CLV template</description>
          <init-params>
            <value-param>
              <name>portletName</name>
              <value>Content List Viewer</value>
            </value-param>
            <value-param>
              <name>portlet.template.path</name>
              <value>war:/conf/myportal/customized/template</value>
            </value-param>
            <object-param>
              <name>default.folder.list.viewer</name>
              <description>Default folder list viewer groovy template</description>
              <object type="org.exoplatform.services.cms.views.PortletTemplatePlugin$PortletTemplateConfig">
                <field name="templateName">
                  <string>ACustomizedCLVTemplate.gtmpl</string>
                </field>
                <field name="category">
                  <string>list</string>
                </field>
              </object>
            </object-param>
          </init-params>
        </component-plugin>
      </external-component-plugins>

#### Customize CLV template's style

To customize CLV template's style, do as follows:

Step 1: Go to Sites explorer portlet > Sites management drive > MySite/css folder. Step 2: Create a new CSS document which contains your stylesheet for the portal and the page layout. You can use any name for this document and put a priority number.

### Warning

This document should contain ONLY the stylesheet for THIS template. If you have another template, you should create a new CSS document.

- The following is one sample stylesheet:

    /* ... */

    .ACustomizedCLVTemplate {
      /* ... */
    }
    .ListContents {
      /* ... */
    }

    /* ... */

Step 3: Export the document and now you have an XML file.

Please check out this tutorial to know how to import this XML into database.

#### Customize Document's skin

### Note

This section is related to the configuration. You can see a sample here.

- First, you need to create a new document definition.

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/document/ACustomizedDocument.xml

    	node type name :exo:customizedDocument
    	properties: exo:name(type : String), exo:title(type : String), exo:content(type : String)

You also need to configure it to make sure it is imported to the database.

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/document/definition-configuration.xml

    <external-component-plugins>
        <target-component>org.exoplatform.services.jcr.RepositoryService</target-component>
        <component-plugin>
          <name>ACustomizedDocument</name>
          <set-method>addPlugin</set-method>
          <type>org.exoplatform.services.jcr.impl.AddNodeTypePlugin</type>
          <priority>200</priority>
          <init-params>
            <values-param>
              <name>autoCreatedInNewRepository</name>
              <description>ACustomizedDocument document definition</description>
              <value>war:/conf/myportal/customized/document/ACustomizedDocument.xml</value>
            </values-param>
          </init-params>
        </component-plugin>
      </external-component-plugins>

- Now it is time to create the templates for this document, including:

- Dialog: see the sample here)

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/document/dialog.gtmpl

    <div class="UIForm ACustomizedDocument">
      <% uiform.begin() %>
        <!-- Document dialog content is here -->
      <% uiform.end() %>

- View: see the sample here)

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/document/view.gtmpl

     <style>
       <% _ctx.include(uicomponent.getTemplateSkin("exo:customizedDocument", "Stylesheet")); %>
    </style>
    <!-- Document view template content is here -->

- Stylesheet: see the sample here)

### Warning

This document should contain ONLY the stylesheet for THIS template.

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/document/stylesheet.css

    /* ... */

    .ACustomizedDocument {
      /* ... */
    }

    /* ... */

- You also need to import them to database.

<myportalpath>/src/main/webapp/WEB-INF/conf/myportal/customized/document/template-configuration.xml

    <external-component-plugins>
        <target-component>org.exoplatform.services.cms.templates.TemplateService</target-component>
        <component-plugin>
          <name>addTemplates</name>
          <set-method>addTemplates</set-method>
          <type>org.exoplatform.services.cms.templates.impl.TemplatePlugin</type>
          <init-params>
            <value-param>
              <name>autoCreateInNewRepository</name>
              <value>true</value>
            </value-param>
            <value-param>
              <name>storedLocation</name>
              <value>war:/conf/myportal/customized/document</value>
            </value-param>
            <value-param>
              <name>repository</name>
              <value>repository</value>
            </value-param>
            <object-param>
              <name>template.configuration</name>
              <description>configuration for the localtion of nodetypes templates to inject in jcr</description>
              <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig">
                <field name="nodeTypes">
                  <collection type="java.util.ArrayList">
                    <value>
                      <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$NodeType">
                        <field name="nodetypeName">
                          <string>exo:customizedDocument</string>
                        </field>
                        <field name="documentTemplate">
                          <boolean>true</boolean>
                        </field>
                        <field name="label">
                          <string>Customized Document</string>
                        </field>
                        <field name="referencedView">
                          <collection type="java.util.ArrayList">
                            <value>
                              <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                                <field name="templateFile">
                                  <string>view.gtmpl</string>
                                </field>
                                <field name="roles">
                                  <string>*</string>
                                </field>
                              </object>
                            </value>
                          </collection>
                        </field>
                        <field name="referencedDialog">
                          <collection type="java.util.ArrayList">
                            <value>
                              <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                                <field name="templateFile">
                                  <string>dialog.gtmpl</string>
                                </field>
                                <field name="roles">
                                  <string>webdesigner:/platform/web-contributors</string>
                                </field>
                              </object>
                            </value>
                          </collection>
                        </field>
    		    <field name="referencedSkin">
                          <collection type="java.util.ArrayList">
                            <value>
                              <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                                <field name="templateFile">
                                  <string>stylesheet.css</string>
                                </field>
                                <field name="roles">
                                  <string>*</string>
                                </field>
                              </object>
                            </value>
                          </collection>
                        </field>
                      </object>
                    </value>
                  </collection>
                </field>
              </object>
            </object-param>
          </init-params>
        </component-plugin>
      </external-component-plugins>

- Finally, you should create some initial contents and export them to XML files.

To import this XML into database, you can set up for the deployment like this:

    <external-component-plugins>
     <target-component>org.exoplatform.services.wcm.deployment.WCMContentInitializerService</target-component>
     <component-plugin>
      <name>Content Initializer Service</name>
      <set-method>addPlugin</set-method>
      <type>org.exoplatform.services.wcm.deployment.plugins.XMLDeploymentPlugin</type>
      <description>XML Deployment Plugin</description>
      <init-params>
       <object-param>
        <name>ACME Logo data</name>
        <description>Deployment Descriptor</description>
        <object type="org.exoplatform.services.deployment.DeploymentDescriptor">
         <field name="target">
          <object type="org.exoplatform.services.deployment.DeploymentDescriptor$Target">
           <field name="repository"><string>repository</string></field>
           <field name="workspace"><string>collaboration</string></field>
           <field name="nodePath"><string>/sites content/live/acme/web contents/site artifacts</string></field>
          </object>
         </field>
         <field name="sourcePath"><string>war:/conf/wcm/artifacts/site-resources/acme/Logo.xml</string></field>
        </object>
       </object-param>
      </init-params>
     </component-plugin>
    </external-component-plugins>

.

### Create and apply Global stylesheet

Global stylesheet is the shared stylesheet which is applied to your entire site or a set of pages, depending on your configuration. When you want to make changes for your site, you only need to create a new global stylesheet, or edit the existing global stylesheet.

Global stylesheets of eXo Platform are put into the CSS folder to manage the stylesheet of your desired site. This section aims at showing you how to create and apply your own global stylesheet by Content Explorer and by configuration.

#### Create and apply the global stylesheet by Content Explorer

Do as follows:

Step 1: Select My Spaces → Content Explorer → Sites Management.

Step 2: Select one site node in the Sites Management pane, for example acme, and then select the CSS folder.

Illustration 1: Sites Management

Step 3: Click Add Document to open the form to create the new global stylesheet.

Illustration 2: Form to create the new global stylesheet

Step 4: Enter the name of global stylesheet into the Name field, for example GlobalStylesheetOrgange.

Step 5: Set the value as "True" to activate your global stylesheet for your site in the Active field. By default, "True" will be set when you create a new global stylesheet. If you select "False", your newly created global style will be disabled.

Step 6: Input one positive integer into the Priority field, for example "10".

### Note

The successful application of your newly created global stylesheet depends on values in both Active and Priority fields. If "True" is set in many global stylesheets, the system will automatically render all global stylesheets in the CSS folder in the descending order and get the stylesheet with the highest priority. Thus, after selecting "True", you need to pay attention to the priority level so that the selected priority of your stylesheet is higher than those of other global stylesheets in the CSS folder.

The default global stylesheet will be automatically created in the CSS folder when you create a new site. However, this global stylesheet can be overwritten by either setting "False" for its Active field or setting the higher priority for other global stylesheet than that of the default global stylesheet.

Step 7: Define your styles in the CSS data field. Here, you can directly enter your CSS rules, or copy and paste them from your favorite text editor.

For example, you can define your styles with the following information:

Step 8: Click the Save as Draft button to save your newly created global stylesheet. You will see your global stylesheet in the Sites Management pane.

To edit your global stylesheet or predefined global stylesheets, simply select the corresponding file and click Edit Document on the action bar to open the Edit form. To rename the document, right-click the corresponding global stylesheets in the Sites Management pane, then select Rename.

#### Create and apply the global stylesheet by configuration

After being created as mentioned above, your desired global stylesheet can be initialized automatically when the application is started by doing as follows:

Step 1: Open the CSS folder.

Step 2: Select System and click Export Node on the action bar.

Step 3: Copy and paste the file you have exported, for example StylesheetOrange.xml, into the folder containing all stylesheets for your site, such as "/acme-website/WEB-INF/conf/acme-portal/wcm/artifacts/site-resources/acme/".

Step 4: Add the code below to the file where all global stylesheets will be initialized for your site, such as acme-deployment-configuration.xml in the folder "/acme-website/WEB-INF/conf/acme-portal/wcm/deployment/".

       <object-param>
              <name>ACME Stylesheet Green data</name>
              <description>Deployment Descriptor</description>
              <object type="org.exoplatform.services.deployment.DeploymentDescriptor">
                <field name="target">
                  <object type="org.exoplatform.services.deployment.DeploymentDescriptor$Target">
                    <field name="repository">
                      <string>repository</string>
                    </field>
                    <field name="workspace">
                      <string>collaboration</string>
                    </field>
                    <field name="nodePath">
                      <string>/sites content/live/acme/css</string>
                    </field>
                  </object>
                </field>
                <field name="sourcePath">
                  <string>war:/conf/acme-portal/wcm/artifacts/site-resources/acme/StylesheetOrange.xml</string>
                </field>
                <field name="cleanupPublication">
                  <boolean>true</boolean>
                </field>
              </object>
            </object-param>

Step 5: Save the file where you have added the code in Step 4 and clean data created in the previous start-up.

Step 6: Start eXo Platform. After accessing the Content Explorer page, you will find your global stylesheet in the CSS folder of the relevant site.

#### Check display of global stylesheets

You can have several global stylesheets in one site. To see differences when applying various global stylesheets, for example GlobalStylesheetBlue and GlobalStylesheetOrange, do as follows:

Step 1: Activate the GlobalStylesheetBlue and GlobalStylesheetOrange by turns.

Step 2: Click My Spaces on the administration bar and select the relevant site, for example "acme".

If you activate GlobalStylesheetBlue, your site will be displayed as below:

Illustration 3: The "acme" site when applying GlobalStylesheetBlue

If you activate "GlobalStylesheetOrange", your site will be displayed in such a different way:

Illustration 4: The "acme" site when applying GlobalStylesheetOrange"

### How to customize the Admin bar

#### Change the color scheme

The current color of Admin bar is dark blue and yellow. However, you can change the color to match your brand colors. Read below to find out how.

The Admin bar looks like this:

The style of Admin bar is defined in the stylesheet.css located in `src/main/webapp/skin/officeSkin/UIToolbarContainer`

The CSS code below shows how to modify the Admin bar to look like this:

    /*toolbar background color*/
    .UIWorkingWorkspace .UIToolbarContainer .NormalContainerBlock .ToolbarContainer {
    	background: #20263f;
    	height: 31px;
    	border: none;
    }

    /*toolbar text color*/
    .UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer a.TBIcon {
    	color: white;
    	font-weight: normal;
    	padding: 0 12px;
    	display: block;
    	white-space: nowrap;
    	background: none;
    	margin-left: 0;
    	zoom: 1;
    }
    /*toolbar text color when hover*/
    .UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer a:hover {
    	color: #8F8F8F;
    }

    /*background color of drop-down menu*/
    .UIWorkingWorkspace .UIToolbarContainer .UITab .MenuItemContainer {
    	border: 1px solid transparent;
    	background: #20263f;
    	margin-top: 0;
    }

    /*background color and border color of drop-down menu*/
    UIWorkingWorkspace .UIToolbarContainer .UITab .MenuItem {
    	border-top: 1px solid #414760;
    	border-bottom: none;
    	background: #20263f;
    	opacity: 1;
    	height: 28px;
    	line-height: 28px;
    	text-align: left;
    }

    /*text color of menu items*/
    .UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer .UITab .MenuItemContainer .MenuItem a {
    	padding: 0 24px 0 35px; /* orientation=lt */
    	padding: 0 35px 0 24px; /* orientation=rt */
    	font-family: "Lucida Sans";
    	font-size: 12px;
    	color: white;
    	display: block;
    	font-weight: normal;
    	white-space: nowrap;
    }

    /*text color of menu items when hover*/
    .UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer .UITab .MenuItemContainer .MenuItem a:hover {
    	color: #92918f;
    	background-color: transparent;
    }

    /*color of title bar text and background in drop-down menu*/
    .UIWorkingWorkspace .UIToolbarContainer .TitleBar {
    	color: #20263f;
    	background: #92a9b9;
    	font-weight: bold;
    	padding: 0px 5px;
    }

#### Change the content of the Admin bar

Portlets on Admin bar

The Admin bar is a special container composed of portlets. It is defined in `WEB-INF/conf/portal/portal/sharedlayout.xml`. In the illustration above, each circle represents a portlet defined in the Admin bar and configured in sharedlayout.xml

It is possible to override the whole Admin bar, by adding it into an extension at : `custom-extension.war!WEB-INF/conf/portal/portal/sharedlayout.xml`.

The sharedlayout.xml configures the current displayed portlets on the Admin bar. For example, to remove the dashboard menu, you will need to remove the following block:

    ...
       <container id="UserToolBarDashboardPortlet" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
          <portlet-application>
             <portlet>
                <application-ref>exoadmin</application-ref>
                <portlet-ref>UserToolbarDashboardPortlet</portlet-ref>
             </portlet>
             <access-permissions>Everyone</access-permissions>
             <show-info-bar>false</show-info-bar>
          </portlet-application>
      </container>
    ...

.}}}

## Add JavaScript to your portal

This can be done entirely within your extension by customizing the gatein-resources.xml configuration.

To add a JavaScript library, for example jQuery, do as follows:

Step 1: Create war:/WEB-INF/gatein-resources.xml_ file.

Step 2: Add the following line to the gatein-resources.xml file.

     <javascript>
      <param>
       <js-module>jQuery</js-module>
       <js-path>/javascript/jQuery.js</js-path>
       <js-priority>0</js-priority>
      </param>
     </javascript>

Details:

<js-module> is the namespace of your JavaScript.

<js-path> is the path to your JavaScript file.

<js-priority> is an optional tag. This tag is used to indicate the loading order of JavaScript files across all the platform. Its value is integer type. If its value is not negative (>=0), the loading priority is sorted by the descending order. If its value is negative (<0), the loading priority of the JavaScript file depends on the loading order of the web app (the .war file) containing that JavaScript file.

- Prev
- Up
- Home
- Next