h1. Platform skin elements  {anchor:id=DEV.CreateYourOwnPortal.PageSkinElemnets}
h2. Overview

* line 1
* line 2
** line 3
*** line 4
* line 1
* line 2

{note}
* line 1
* line 2
{note}

{tip}
* line 1
* line 2
{tip}

{warning}
* line 1
* line 2
{warning}

Platform provides support for skinning the entire portal User Interface (UI) including your own portlets. Skins are designed to help you pack and reuse common graphic resources.

The complete skinning of can be decomposed into three main parts: Portal skin, Window style, Portlet skin.

{docbook}
<citetitle>
<para>
<emphasis role="bold">Portal skin</emphasis>
</para>
</citetitle>
{docbook}

The portal skin contains styles for the 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.

{docbook}
<citetitle>
<para>
<emphasis role="bold">Window style</emphasis>
</para>
</citetitle>
{docbook}
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.

!images/window_decoration.jpg|align="center" width="100mm" fo:scalefit="1" html:scalefit="0"!

{docbook}
<citetitle>
<para>
<emphasis role="bold">Portlet skin</emphasis>
</para>
</citetitle>
{docbook}

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

*Portlet Specification CSS Classes* {anchor:id=DEV.CreateYourOwnPortal.PortletSpecificationCSSClasses}

The [portlet specification|http://jcp.org/en/jsr/detail?id=286] defines a set of CSS classes that should be available to portlets.
eXo 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* {anchor:id=DEV.CreateYourOwnPortal.PortletSkins}

eXo 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 a part of the portal skin and can be included within the portlets web application.
{note}

h2. SkinService {anchor:id=DEV.CreateYourOwnPortal.SkinService}
Platform skin is processed by the SkinService. It is used to discover and deploy skins into the portal.

* *Configure skins* {anchor:id=DEV.CreateYourOwnPortal.ConfigureSkins}

In eXo Platform 3.5 has a file descriptor for skins (WEB-INF/gatein-resources.xml) which is to specify which portal, portlet and window decorators will be deployed into the skin service. Platform can automatically discover web archives containing this file gatein-resource.xml.
The full schema can be found in the lib directory: _exo.portal.component.portal.jar/gatein\_resources\_1\_0.xsd_.

Here is the _gatein-resources.xml_ file of a sample skin (called "MySkin") which defines the portal skin with its CSS location, window style and its portlet skins:

{code:xml}
<gatein-resources>
<!-- define the portal skin -->
<portal-skin>
    <skin-name>MySkin</skin-name>
    <css-path>/skin/myskin.css</css-path>
    <overwrite>false</overwrite>
</portal-skin>

<!-- define the portlet skin -->

<portlet-skin>
  <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>
    <overwrite>false</overwrite>
</portlet-skin>

  <!-- define the 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>
{code}

h2. ResourceRequestFilter {anchor:id=DEV.CreateYourOwnPortal.ResourceRequestFilter}
The ResourceRequestFilter is used to map process skin request mapping from portal, portlet to the exact skin that was defined in portal.
ResourceRequestFilter is configured in the _web.xml_ file in the skin web archive.

{code:xml}
<webapp>
<display-name>eXoResources</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>*.css</url-pattern>
</filter-mapping>
</webapp>
{code}

{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_ needs to be coherent with the application-name in the _gatein-resources.xml_ file.
{note}


h2. The default skin {anchor:id=DEV.CreateYourOwnPortal.DefaultSkin}
The default skin of eXo Platform 3.5 is in the _eXoResource.war_ file. The main files associated with the skin are:
* _WEB-INF/gatein-resources.xml_ defines the skin settings to use.
* _WEB-INF/web.xml_ contains the resource filter with the display-name set.
* _skin/Stylesheet.css_ contains the CSS class definitions for this skin.

{note}
To get a new portal skin declared in _gatein-resources.xml_ loaded successfully, _display-name_ of the extension webapp
(in _web.xml_) should be identical to the context path of the extension webapp.
{note}

The following block of CSS illustrates content of the _skin/Stylesheet.css_ file:

{code:css}
@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)
{code}

In which:

* (1) Skin of the portal page. The _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:

{code:css}
@import url(/eXoResources/skin/Portlet/Stylesheet.css);
{code}

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

h1. Override skins with extension {anchor:id=DEV.CreateYourOwnPortal.OverrideSkinsWithExtension}

The extension mechanism of eXo Platform 3.5 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 Platform's files.

{code:xml}
<gatein-resources>
  <portal-skin>
    <skin-name>Default</skin-name>
    <css-path>/skin/Defaultskin/Stylesheet.css</css-path>
    <overwrite>false</overwrite>
    <css-priority>0</css-priority>
  </portal-skin>
</gatein-resources>
{code}

(The css-path specifies the stylesheet of the new skin.)

{docbook}
<para>
<citetitle>
<para><emphasis role="bold">Override skins with extension</emphasis></para>
</citetitle>
</para>
{docbook}

*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.

*2.* 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.

h1. Create new skins {anchor:id=DEV.CreateYourOwnPortal.CreateNewSkins}

h2. Create a new skin web archive
{docbook}
<para xml:id="DEV.CreateYourOwnPortal.CreateNewPortalSkins">
<citetitle>
<emphasis role="bold">Create new portal skins</emphasis>
</citetitle>
</para>
{docbook}
To create a new skin (called "MySkin"), you should create a new skin web archive with the following structure:

!images/FolderStructure.png|align="center" fo:scalefit="1" html:scalefit="0"!

* The _web.xml_ is the file that you will define the ResourceRequestFilter.
* The _gatein-resource.xml_ will define your new skin (for portal, portlet or window style).
* The *skin* folder will contain images and stylesheets of your skin.

*Configure portal skins* {anchor:id=DEV.CreateYourOwnPortal.ConfigurePortalSkins}

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.

{code:xml}
<gatein-resources>
  <portal-skin>
    <skin-name>MySkin</skin-name>
    <css-path>/skin/myskin.css</css-path>
    <overwrite>false</overwrite>
    <css-priority>0</css-priority>
  </portal-skin>
</gatein-resources>
{code}

The default portal skin and window styles are defined in the _eXoResources.war/WEB-INF/gatein-resources.xml_ file.

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

eXo Platform provides the "CSS priority" concept  which controls the loading order of skins. The skin with lower "css-priority" value will be loaded first.
{note}

h2. Create the skin preview icon {anchor:id=DEV.CreateYourOwnPortal.PortalSkinPreviewIcon}

When selecting a skin it is possible to see a preview of what the skin will look like. The current skin needs to know about the skin icons for all the available skins, otherwise it will not be able to show the previews. When creating a new portal it is recommended to include the preview icons of the other skins and to update the other skins with your new portal skin preview.

!images/Skin_preview.png|align="center" fo:scalefit="1" html:scalefit="0"!

For any portal skin, the paths to the 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:

{code:css}
.UIChangeSkinForm .UIItemSelector .TemplateContainer .MySkinImage
{code}

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_.

Now, amending the deployed package eXoResources is inevitable (modifying the default war/jar breaches development convention of Platform-based products). The problem would be resolved in future eXo Platform versions in which different skin modules are fully independent, for example, there will be no preview image duplication.

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

h2. Skin the window style {anchor:id=DEV.CreateYourOwnPortal.Skin_the_window_style}

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* {anchor:id=DEV.CreateYourOwnPortal.ConfigureWindowStyles}

Window style is defined within the _gatein-resources.xml_ file used by the SkinService to deploy the window style. Window styles can belong to a window style category. This category and window styles need to be specified in the resources file.
For example, the following _gatein-resource.xml_ fragment will add MyThemeBlue and MyThemeRed to the MyTheme category.

{code:xml}
<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>
{code}

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.
{note}

*Window style CSS* {anchor:id=DEV.CreateYourOwnPortal.WindowStyleCSS}

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* {anchor:id=DEV.CreateYourOwnPortal.SetDefaultWindowStyle}

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.
{note}

h2. Configure the right-to-left skin {anchor:id=DEV.CreateYourOwnPortal.Configure_RTL_skin}

The SkinService handles stylesheet rewriting to accommodate the orientation. It works by appending _-lt_ or _-rt_ to the stylesheet name.
For example, _/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. This example uses the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right:

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

The LT produced output will be:

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

The RT produced output will be:
{code:css}
float: right; /* orientation=rt */
font-weight: bold;
text-align: center;
white-space: nowrap;
{code}

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

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

The LT produced output will be:

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

The RT produced output will be:

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

h1. Skin the portlet {anchor:id=DEV.CreateYourOwnPortal.Skin_the_portlet}

Portlets often require additional styles that may not be defined by the portal skin. eXo Platform 3.5 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 _portletAppName/PortletName_ form.
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.

{code: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>
{code}

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.
{note}

{docbook}
<para xml:id="DEV.CreateYourOwnPortal.ChangePortletIcons">
<citetitle>
<emphasis role="bold">Change portlet icons</emphasis>
</citetitle>
</para>
{docbook}

Each portlet can be represented by a 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/icon\_name.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.
{note}

h1. Configure Platform skin {anchor:id=DEV.CreateYourOwnPortal.Configure_portlet_skin}
h2. Select skins within the configuration files {anchor:id=DEV.CreateYourOwnPortal.SelectSkinWithinConfigurationFiles}
The default skin can be set in the portal configuration files. The skin configured as default is used by Platform as the administrator starts/restarts the server.

Simply add a skin tag to the _portal.war/WEB-INF/conf/portal/portal/classic/portal.xml_ configuration file.

To change skin to YourSkin, use the following code:

{code:xml}
<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>
{code}


h2. Skins in the page markup {anchor:id=DEV.CreateYourOwnPortal.SkinsInThePageMarkup}
The eXo Platform 3.5 skin not only contains CSS styles for the portal's components, but also shares components that may be reused in portlets. When eXo Platform 3.5 generates the page markup of portal, stylesheet links will be inserted 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.
* *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 transferred more quickly as a single file instead of multiple smaller files.
* *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:

{code:html}
<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>
{code}

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

h2. Customize portal's layout {anchor:id=DEV.CreateYourOwnPortal.CustomizePortalLayout}

{note}
This section is related to the configuration. You can see a sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/ecmdemo/webapp/src/main/webapp/WEB-INF/conf/sample-portal/portal/portal/acme/portal.xml] 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.
{note}

For example, you will have a layout like this:

!images/samplelayout.jpg|align="center" width="100mm" fo:scalefit="1" html:scalefit="0"!

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: Contain the page body.

And here is the fragment of _portal.xml_ located in this path: _<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/portal/portal/mysite/portal.xml_.

{code: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>

<!-- ... -->
{code}

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:

{code}
${container_id}TDContainer
{code}

and the details of this container:

{code}
RightColumnTDContainer
{code}

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:

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

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-portal-and-page-style].

h2. Customize page's layouts {anchor:id=DEV.CreateYourOwnPortal.CustomizePageLayout}

{note}
This section is related to the configuration. You can see a sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/ecmdemo/webapp/src/main/webapp/WEB-INF/conf/sample-portal/portal/portal/acme/pages.xml] 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.
{note}

* Like _portal.xml_, you can define the layout for each page in your site as shown in the following example:

!images/sample_page.jpg|align="center"  width="80mm" fo:scalefit="1" html:scalefit="0"!

{code:xml}
<!-- ... -->

<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>

<!-- ... -->
{code}

h2. Customize the Admin bar
h3. sharedlayout.xml    {anchor:id=DEV.CreateYourOwnPortal.Sharedlayout}
The *Admin* bar is a special container composed of portlets and defined in _WEB-INF/conf/portal/portal/sharedlayout.xml_.

If you want to redefine these portlets, you need to override this file by creating your own _sharedlayout.xml_ located into your extension: _custom-extension.war!WEB-INF/conf/portal/portal/sharedlayout.xml_.

Followings are two examples of configuration, one to remove a portlet, the other to add a new portlet to the *Admin* bar.

h3. Remove a content from the Admin bar {anchor:id=DEV.CreateYourOwnPortal.RemoveAdminbarContent}

!images/admin_bar_portlets.png|align="center" width="150mm" fo:scalefit="1" html:scalefit="0"!

*Portlets on the Admin bar*

In the illustration above, each circle represents a portlet defined in the *Admin* bar and configured in _sharedlayout.xml_.

The _sharedlayout.xml_ file configures the current displayed portlets on the *Admin* bar. For example, to remove the *Dashboard* menu, you will need to remove the following block:

{code:xml}
...
<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>
 ...
{code}

h3. Add a content to the Admin bar {anchor:id=DEV.CreateYourOwnPortal.AddAdminbarContent}

*Add a portlet to the Admin bar to logout user*

In the same way you removed a portlet from the admin bar, you can add your own portlet by editing your _sharedlayout.xml_.

{code:xml}
...
<container id="UILogoutPortlet" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
  <access-permissions>*:/platform/users</access-permissions>
  <portlet-application>
    <portlet>
      <application-ref>platformNavigation</application-ref>
      <portlet-ref>UILogoutPortlet</portlet-ref>
    </portlet>
    <access-permissions>*:/platform/users</access-permissions>
    <show-info-bar>false</show-info-bar>
  </portlet-application>
</container>
...
{code}

Style of portlet container can be changed by editing this css file:

_eXoResources/skin/DefaultSkin/portal/webui/component/view/UIToolbarContainer/Stylesheet.css_

{code:css}
.UIToolbarContainer .UILogoutPortletTDContainer {
	float: right; /* orientation=lt */
	float: left; /* orientation=rt */
}
{code}

h3. Change the color scheme {anchor:id=DEV.CreateYourOwnPortal.ChangeColorScheme}
The current color of the *Admin* bar is gray gradient. However, you can change the color to match your brand colors.

The default *Administration* style:

!images/admin_bar.png|align="center" width="150mm" fo:scalefit="1" html:scalefit="0"!

The style of the *Admin* bar is defined in the *stylesheet.css* located in _extension/resources/src/main/webapp/skin/platformSkin/UIToolbarContainer_.

Edit this CSS file to customize the *Admin* bar to your preferred color scheme.

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

!images/modified_admin_bar.png|align="center" width="150mm" fo:scalefit="1" html:scalefit="0"!

{code:css}
.UIWorkingWorkspace #UIToolbarContainer .HomeLinkTDContainer {
	line-height: 31px;
    margin: 0px 5px;
    vertical-align: middle;
}

.UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer {
	/*background: url(background/BgToolbarContainer.gif) repeat-x left top;*/
	height: 31px;
	border: none;
}

.UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer .UITab .MenuItemContainer .MenuItem a {
	padding: 0 22px 0 22px;
	font-size: 12px!important;
	color: #4c4c4c;
	display: block;
	font-weight: normal;
	white-space: nowrap;
}

.UIToolbarContainer .ToolbarContainer .PinLink {
    padding: 0px;
}

.UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer a.TBIcon {
	/*color: #2f3334;*/
	font-weight: normal;
	padding: 0 20px;
	display: block;
	white-space: nowrap;
	background: none;
	margin-left: 0;
	zoom: 1;
	font-size:14px!important;
	font-family: verdana;
	border: 1px solid transparent;
	border-bottom: none;
	line-height: 29px;
	height: 29px;
}

.UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer a.SetupMenuItem  {
	padding: 0 8px;
	line-height:25px;
 }
{code}


h1. Configure skin in WCM

This tutorial will help you to create a new layout and skin, and give some best practices when creating a new layout and skin for your portal and page.
Instructions described here are based on the following 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 with the based path of your "MyPortal" extension.
* If you see any folder/file which does not exist, you should create a new one.

h2. Customize CLV portlet's template {anchor:id=DEV.CreateYourOwnPortal.CustomizeCLVPortletTemplate}

{note}
This section is related to the configuration. You can see a sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/wcm-artifacts/application-templates/content-list-viewer/list-by-folder/TwoColumnsCLVTemplate.gtmpl]
{note}

* Apply your HTML/Groovy template code for this template.

For example:

_<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/template/list/ACustomizedCLVTemplate.gtmpl_

{code:html}
<div id="$uicomponent.id" class="ACustomizedCLVTemplate">
  <div class="ListContents">
    <!-- something here -->
  </div>
</div>
{code}

* Now, you need to import this template to the database.

_<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/template/configuration.xml_

{code: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>
{code}

h2. Customize CLV template's style {anchor:id=DEV.CreateYourOwnPortal.CustomizeCLVTemplateStyle}

*1.* Go to *Sites explorer* portlet *--> Sites management* drive *--> MySite/css* folder.

*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.

{note}
This document should contain ONLY one stylesheet for THIS template. If you have another template, you should create a new CSS document.
{note}

* The following is the sample stylesheet:

{code:css}
/* ... */
.ACustomizedCLVTemplate {
/* ... */

}

.ListContents {
/* ... */

}

/* ... */
{code}

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

Please check out [this tutorial|http://wiki.exoplatform.com/xwiki/bin/view/WCM/How+to+create+and+deploy+pre-defined+contents+in+WCM] to know how to import this XML into the database.

h1. Customize Document's skin {anchor:id=DEV.CreateYourOwnPortal.CustomizeDocuemntSkin}

{note}
This section is related to the configuration. You can see a sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/wcm-extension/wcm/nodetypes-configuration.xml]
{note}

First, you need to create a new document definition.

* _<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/ACustomizedDocument.xml_

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

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

* _<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/definition-configuration.xml_

{code: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>
{code}

Next, create the templates for this document, including:

* Dialog: see the sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/dms-extension/dms/artifacts/templates/article/dialogs/dialog1.gtmpl]

_<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/dialog.gtmpl_

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

* View: see the sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/dms-extension/dms/artifacts/templates/article/views/view1.gtmpl]

_<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/view.gtmpl_

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

* Stylesheet: see the sample [here.|http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/dms-extension/dms/artifacts/templates/article/skins/Stylesheet-lt.css]

{note}
This document should contain ONLY the stylesheet for THIS template.
{note}

_<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/stylesheet.css_


{code:css}
/* ... */

.ACustomizedDocument {
  /* ... */
}

/* ... */
{code}

* You also need to import them to the database.

_<myportal\_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/template-configuration.xml_

{code: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>
{code}

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

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

{code:xml}
<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>
{code}





h1. Best practices to customize a skin {anchor:id=DEV.CreateYourOwnPortal.BestPracticeToCustomizeSkin}
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 eXo Platform.

*Name files and folders* {anchor:id=DEV.CreateYourOwnPortal.NameFiles&Folder}

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* {anchor:id=DEV.CreateYourOwnPortal.FolderStructure}
{docbook}
<citetitle>
<para>
<emphasis role="bold">Portal skins</emphasis>
</para>
</citetitle>
{docbook}

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 transferred 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:

{code}
webapp
|- skin
|--- NameOfPortalSkin
|----- stylesheet.css
|------- webui
|---------- component
|------------ UIComponentName
|--------------- NameOfPortalSkin.css
|--------------- NameOfPortalSkin
|------------------ background
{code}

{docbook}
<citetitle>
<para>
<emphasis role="bold">Portlet skin</emphasis>
</para>
</citetitle>
{docbook}

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 have the _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_