<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Skinning_Portal">
  <title>Skin the portal</title>
   <highlights>
       <itemizedlist>
           <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Skin_Configuration-Types_of_Styles">Skin components</link></emphasis></para>
             <para>Overall information about 3 main components of a complete skin, including <emphasis>Portal Skin</emphasis>, <emphasis>Window Styles</emphasis> and <emphasis>Portlet Skins</emphasis>.</para>
           </listitem>
           <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Skin_Configuration-Skin_Switching">Skin selection</link></emphasis></para>
			<para>Ways to select a skin via the User Interface and set the default skin within the configuration file.</para>
           </listitem>
           <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Skin_Configuration-Skins_in_Page_Markups">Skins in page markups</link></emphasis></para>
			   <para>Introduction to the skins in page markups with 2 main types of CSS links.</para>
			</listitem>
           <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guid-Skin_Configuration-Skin_Service">Skin Service</link></emphasis></para>
				<para>Knowledge of <emphasis>Skin Service</emphasis>, including skin configuration and resource request filter.</para>
           </listitem>
           <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Skin_Configuration-Default_Skin">Default Skin</link></emphasis></para>
			   <para>Details of main files associated with the default skin, including <filename>gatein-resources.xml</filename>, <filename>web.xml</filename>, and <filename>Stylesheet.css</filename>.</para>
           </listitem>
            <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin">Create new skins</link></emphasis></para>
				<para>Instructions on how to create a new portal skin, windows style, portlet skin and portlet specification CSS class.</para>
           </listitem>
            <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Skin_Configuration-Tips_and_Tricks">Tips and tricks</link></emphasis></para>
			   <para>Knowledge of CSS techniques and tips for easier CSS debugging.</para>
           </listitem>
       </itemizedlist>
   </highlights>

    <para>&PRODUCT;
      provides robust skinning support for the entire portal User
      Interface (UI). This includes support for skinning all of the
      common portal elements and being able to provide custom skins and window decoration for individual portlets.
      It is designed to common graphic resource reuse and ease of development.
    </para>
     <para>
    <prompt>
        <emphasis role="bold">See also</emphasis>
    </prompt>
   </para>
		<itemizedlist>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Default_Portal_Configuration">Default Portal Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Portal_Navigation_Configuration">Portal Navigation Configuration</link></para>
           </listitem>
		    <listitem>
               <para><link linkend="sect-Reference_Guide-Internationalization_Configuration">Internationalization Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-RTL_Right_To_Left_Framework">RTL (Right To Left) Framework</link></para>
           </listitem>
       </itemizedlist>
  <section id="sect-Reference_Guide-Skin_Configuration-Types_of_Styles" role="NotInToc">
    <title>Skin Components</title>

    <para>
      The complete skinning of a page can be decomposed into three main
      parts:
    </para>

    <variablelist>
      <varlistentry>
        <term>Portal Skin</term>
        <listitem>

          <para>
            The portal skin contains the CSS styles for the portal and its various UI
            components. This should include all the UI components, except for the window
            decorators and portlet specific styles.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Window Styles</term>
        <listitem>
          <para>
            The CSS styles are associated with the porlet window decorators. The window
            decorators contain the control buttons and boarders surrounding each portlet.
            Individual portlets can have their own window decorator selected, or be 
            rendered without one.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Portlet Skins</term>
        <listitem>
          <para>
            The portlet skins affects how portlets are rendered on the page via one of the following ways:
          </para>
          <variablelist>
            <varlistentry>
              <term>Portlet Specification CSS Classes</term>
              <listitem>
                <para>The
                  portlet specification defines a set of CSS classes that should
                  be available to portlets. &PRODUCT; provides
                  these classes as part of the portal skin. This allows each portal skin to
                  define its own look and feel for these default values.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Portlet Skins</term>
              <listitem>
                <para>&PRODUCT;
                  provides a means for portlet CSS files to be loaded, basing on
                  the current portal skin. This allows a portlet to provide different 
                  CSS styles to better match the look and feel of the current portal. Portlet skins
                  provide a much more customizable CSS experience than just using the portlet
                  specification CSS classes.
                </para>
              </listitem>
            </varlistentry>

          </variablelist>

        </listitem>
      </varlistentry>
    </variablelist>

    <note>
      <para>
        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 part of the overall portal skin. The portal skin must include these component´s 
        CSS classes or they will not be displayed correctly.</para>
      <para>
        A portlet skin does not need to be included as part of the portal skin and can
        be included within the portlets web application.
    </para>
    </note>
  </section>

  <section id="sect-Reference_Guide-Skin_Configuration-Skin_Switching" role="NotInToc">
    <title>Skin Selection</title>

    <para xml:id="sect-Reference_Guide-Skin_Configuration-Skin_Switching-UI">
      <citetitle><emphasis role="bold">Select a skin throughout User Interface</emphasis></citetitle>
    </para>
      <para>
        There are a few means for you to select the display skin. The easiest way to change the skin is to select it through
        the user interface. Administrators can change the default skin for the portal, and users logged in can select their desired display skins.
	</para>
      <para>
        Please see the User Guide for information on how to change the skin using the user
        interface.
	</para>

    <para xml:id="sect-Reference_Guide-Skin_Configuration-Skin_Switching-config">
      <citetitle>
        <emphasis role="bold">Set the Default Skin within the configuration files</emphasis>
      </citetitle>
    </para>

      <para>
        The default skin can also be configured through the portal
        configuration files if you do not want to use the admin user interface.
        This will allow the portal to have the new default skin ready when &PRODUCT;
        is initially started.
      </para>
      <para>
        The default skin of the portal is called
        <emphasis>Default</emphasis>. To change this value, add a
        <emphasis>skin</emphasis> tag in the
        <filename>portal.war/WEB-INF/conf/portal/portal/classic/portal.xml</filename>
        configuration file.
      </para>
      <para>
        To change the skin to
        <emphasis>MySkin,</emphasis>
        you would make the following changes:
      </para>

<programlisting language="xml">&lt;portal-config&gt;
&lt;portal-name&gt;classic&lt;/portal-name&gt;
&lt;locale&gt;en&lt;/locale&gt;
&lt;access-permissions&gt;Everyone&lt;/access-permissions&gt;
&lt;edit-permission&gt;*:/platform/administrators&lt;/edit-permission&gt;
&lt;skin&gt;MySkin&lt;/skin&gt;
...</programlisting>
  </section>

  <section id="sect-Reference_Guide-Skin_Configuration-Skins_in_Page_Markups" role="NotInToc">
    <title>Skins in Page Markups</title>

    <para>The &PRODUCT;
      skin contains CSS styles for the portal's components but
      also shares components that may be reused in portlets. When &PRODUCT;
      generates a portal page markup, it inserts the stylesheet links in the page's
      <emphasis>head</emphasis> tag.
    </para>

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

    <variablelist>
      <varlistentry>
        <term>Portal Skin</term>
        <listitem>
          <para>
            The portal skin will appear as a single link to a CSS file. This
            link contains content from all the portal skin classes merged
            into one file. This allows the portal skin to be transferred more
            quickly as a single file instead of many multiple smaller files.
            All pages of the portal have the same skin defined in the CSS file.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Portlet Skin</term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>In the code fragment below, you can see two types of links:</para>

<programlisting language="html">&lt;head&gt;
...
&lt;!-- The portal skin --&gt;
&lt;link id="CoreSkin" rel="stylesheet" type="text/css" href="/eXoResources/skin/Stylesheet.css" /&gt;

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

  <note>
    <para>Both window styles and portlet specification CSS classes are included
      in the portal skin.</para>
  </note>
  </section>

  <section id="sect-Reference_Guid-Skin_Configuration-Skin_Service" role="NotInToc">
    <title>Skin Service</title>
    <para>
    The skin service of &PRODUCT; manages various types of
    skins. This service is responsible for discovering and deploying the skins into the
    portal.
    </para>
    <para>This section consists of the following topics:</para>
    <itemizedlist>
      <listitem>
        <para><link linkend="sect-Reference_Guid-Skin_Configuration-Skin_Service-Skin_configuration">Skin configuration</link> </para>
      </listitem>
      <listitem>
        <para><link linkend="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinConfigListener"> Resource Request Filter</link> </para>
      </listitem>
    </itemizedlist>

    <para xml:id="sect-Reference_Guid-Skin_Configuration-Skin_Service-Skin_configuration">
      <citetitle><emphasis role="bold"> Skin configuration</emphasis></citetitle>
    </para>

      <para>&PRODUCT; automatically discovers web archives that contain a
      file descriptor for skins (<filename>WEB-INF/gatein-resources.xml</filename>). This file is
      responsible for specifying the portal, portlet and window decorators to be deployed into the
      skin service.
      </para>
      
      <para>The full schema can be found in the lib directory:</para>
      <filename>exo.portal.component.portal.jar/gatein_resources_1_0.xsd</filename>
    
      <para>Here is an example where a skin (MySkin) with its CSS location is defined, and a few window decorator skins are specified: 
      </para>
      <programlisting language="xml">&lt;gatein-resources&gt;
  &lt;portal-skin&gt;
    &lt;skin-name&gt;MySkin&lt;/skin-name&gt;
    &lt;css-path&gt;/skin/myskin.css&lt;/css-path&gt;
    &lt;overwrite&gt;false&lt;/overwrite&gt;
  &lt;/portal-skin&gt;
&lt;/gatein-resources&gt;

  &lt;!-- window style --&gt;
  &lt;window-style&gt;
    &lt;style-name&gt;MyThemeCategory&lt;/style-name&gt;
    &lt;style-theme&gt;
      &lt;theme-name&gt;MyThemeBlue&lt;/theme-name&gt;
    &lt;/style-theme&gt;
    &lt;style-theme&gt;
      &lt;theme-name&gt;MyThemeRed&lt;/theme-name&gt;
    &lt;/style-theme&gt;
    ...</programlisting>


    <para xml:id="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinConfigListener">
      <citetitle><emphasis role="bold">Resource Request Filter</emphasis></citetitle>
    </para>

    <para>Because of the Right-To-Left support, all CSS files need to be
      retrieved through a Servlet filter and the web application needs to be
      configured to activate this filter. This is already done for the 
      <filename>eXoResources.war</filename> web application which contains the default skin.</para>
    <para>
      Any new web applications containing skinning CSS files will
      need to have the following added to their
      <emphasis>web.xml</emphasis>
     :
    </para>

    <programlisting language="xml">&lt;filter&gt;
      &lt;filter-name&gt;ResourceRequestFilter&lt;/filter-name&gt;
      &lt;filter-class&gt;org.exoplatform.portal.application.ResourceRequestFilter&lt;/filter-class&gt;
      &lt;/filter&gt;

      &lt;filter-mapping&gt;
      &lt;filter-name&gt;ResourceRequestFilter&lt;/filter-name&gt;
      &lt;url-pattern&gt;*.css&lt;/url-pattern&gt;
      &lt;/filter-mapping&gt;</programlisting>

    <note>
      <para>The <emphasis>display-name</emphasis> element also needs to
      be specified in the <filename>web.xml</filename> for the skinning service to work properly
      with the web application.</para>
    </note>
    
   </section>

  <section id="sect-Reference_Guide-Skin_Configuration-Default_Skin" role="NotInToc">
    <title>Default Skin</title>
    <para>
    The default skin for &PRODUCT; is located as part of the <filename>eXoResources.war</filename>.
    The main files associated with the skin are shown below:
    </para>
    
    <programlistingco>
      <areaspec>
        <area coords="1" id="area-Reference_Guide-Skin_Configuration-Default_Skin-gatein-resources" />
        <area coords="2" id="area-Reference_Guide-Skin_Configuration-Default_Skin-web" />
        <area coords="3" id="area-Reference_Guide-Skin_Configuration-Default_Skin-skin-Stylesheet" />
      </areaspec>
	<programlisting>WEB-INF/gatein-resources.xml
WEB-INF/web.xml
skin/Stylesheet.css</programlisting>
<calloutlist>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-gatein-resources">
          <para><filename>gatein-resources.xml</filename>: defines the skin setup to use.</para>
        </callout>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-web">
          <para><filename>web.xml</filename>: contains the resource filter and has the display-name set.</para>
        </callout>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-skin-Stylesheet">
          <para><filename>Stylesheet.css</filename>: contains the CSS class definitions for this skin.</para>
        </callout>
      </calloutlist>
    </programlistingco>
    <variablelist>
      <varlistentry>
        <term><filename>gatein-resources.xml</filename></term>
        <listitem>
          <para>
		    For the default portal skin, this file contains definitions for the portal skin, the window
		    decorations and defines some JavaScript resources which are not
		    related to the skin. The default portal skin does not directly define portlet skins which should be
		    provided by the portlets themeselves.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>web.xml</filename></term>
        <listitem>
          <para>
	        For the default portal skin, the <filename>web.xml</filename> of <filename>eXoResources.war</filename> contains a lot
	        of information which is mostly irrelevant to the portal skinning. The areas of interest
	        in this file is the ResourceRequestFilter and the fact that the display-name is set.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>Stylesheet.css</filename></term>
        <listitem>
          <para>
          This file contains the main stylesheet of the portal skin. The file is the main entry point to the CSS class definitions
          for the skin. The content of this file is shown below:
          </para>
          
    <programlistingco>
      <areaspec>
        <area coords="1" id="area-Reference_Guide-Skin_Configuration-Default_Skin-uiportletapplication" />
        <area coords="2" id="area-Reference_Guide-Skin_Configuration-Default_Skin-components" />
        <area coords="3" id="area-Reference_Guide-Skin_Configuration-Default_Skin-portletthemes" />
        <area coords="4" id="area-Reference_Guide-Skin_Configuration-Default_Skin-portlet" />
      </areaspec>
    <programlisting>@import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css);
@import url(DefaultSkin/webui/component/Stylesheet.css);
@import url(PortletThemes/Stylesheet.css);
@import url(Portlet/Stylesheet.css);</programlisting>
<calloutlist>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-uiportletapplication">
          <para>Skin for the main portal page.</para>
        </callout>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-components">
          <para>Skins for various portal components.</para>
        </callout>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-portletthemes">
          <para>Window decoration skins.</para>
        </callout>
        <callout arearefs="area-Reference_Guide-Skin_Configuration-Default_Skin-portlet">
          <para>The portlet specificiation CSS classes.</para>
        </callout>
      </calloutlist>
    </programlistingco>
		  <para>
		  Instead of defining all the CSS classes in this file, you can import other CSS stylesheet files,
		  some of which may also import other CSS stylesheets. The CSS classes are split up between multiple files to make
		  it easier for new skins to reuse parts of the default skin.
		  </para>
		  <para>To reuse the 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 this import: <filename>@import url(/eXoResources/skin/Portlet/Stylesheet.css);</filename></para>
		  
		  <note>
		  <para>When the portal skin is added to the page, it merges all the CSS stylesheets into a single file.</para>
		  </note>
        </listitem>
      </varlistentry>
    </variablelist>
    
  
  </section>

  <section id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin" role="NotInToc">
    <title>Create New Skins</title>

    <section id="sect-Reference_Guide-Skin_Configuration-How_to_create_new_portal_skin">
      <title>Create a new portal skin</title>
      
      <para>
        A new portal skin needs to be added to the portal through the skin service. The web application
        which contains the skin will need to be properly configured for the skin service to discover them. This 
        means that <filename>ResourceRequestFilter</filename> and <filename>gatein-resources.xml</filename> should be configured properly.
      </para>
      <para xml:id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin-Portal-skin-configuration">
        <citetitle>
          <emphasis role="bold">Portal Skin Configuration</emphasis>
        </citetitle>
      </para>
       <para>
        The <filename>gatein-resources.xml</filename> file needs to specify the new portal skin. This includes specifying the name
        of the new skin, where to locate its CSS stylesheet file and whether to overwrite an existing portal theme with
        the same name.
        </para>
        <programlisting language="xml">&lt;gatein-resources&gt;
  &lt;portal-skin&gt;
    &lt;skin-name&gt;MySkin&lt;/skin-name&gt;
    &lt;css-path&gt;/skin/myskin.css&lt;/css-path&gt;
    &lt;overwrite&gt;false&lt;/overwrite&gt;
  &lt;/portal-skin&gt;
&lt;/gatein-resources&gt;</programlisting>
      <para>The default portal skin and window styles are defined in
    <filename>eXoResources.war/WEB-INF/gatein-resources.xml</filename>.
    </para>
      <note>
      <para>
      The CSS for the portal skin needs to contain the CSS for all the window decorators and the portlet specification
      CSS classes.
      </para>
      </note>

      <para xml:id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin-Portal_skin_preview_icon">
        <citetitle>
          <emphasis role="bold">Portal Skin Preview Icon</emphasis>
        </citetitle>
      </para>
             <para>
         When selecting a skin, it is possible to preview it. 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.
         </para>

         <mediaobject>
		<imageobject role="html">
			<imagedata fileref="images/PortalDevelopment/Skinning/portal-change-skin.png"
				format="PNG" width="444" align="center" />
		</imageobject>
             <imageobject role="fo">
			<imagedata fileref="images/PortalDevelopment/Skinning/portal-change-skin.png"
				format="PNG" width="150mm" scalefit="1" align="center" />
		</imageobject>
	</mediaobject>

         <para>
         The portal skin preview icon is specified through the CSS of the portal skin. To display the preview for the current portal skin, you must specify a specific CSS class and set the icon as the background. 
         </para>
         <para>
         For the portal named <emphasis role="bold">MySkin</emphasis>, the CSS class must be defined as follows:
         </para>
         <programlisting role="css">.UIChangeSkinForm .UIItemSelector .TemplateContainer .<emphasis role="bold">MySkinImage</emphasis></programlisting>
         <para>
         In order for the default skin to know about the skin icon for a new portal skin, the preview screenshot
         needs to be placed in:</para>
         
         <filename>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background</filename>
         <para>
         The CSS stylesheet for the default portal needs to have the following updated with the preview icon CSS class. For a skin named 
         <emphasis
            role="bold">MySkin</emphasis>, you need to update the following:</para>
         <filename>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</filename>

         <programlisting role="css">.UIChangeSkinForm .UIItemSelector .TemplateContainer .<emphasis role="bold">MySkinImage</emphasis> {
  margin: auto;
  width: 329px; height:204px;
  background: url('background/MySkin.jpg') no-repeat top;
  cursor: pointer ;
}</programlisting>
    
    </section>

  <section id="sect-Reference_Guide-Skin_Configuration-How_to_create_new_themes">
    <title>Create a new window style</title>

    <para>Window styles are the CSS applied to the window decoration. When the
    administrator selects a new application to add to a page, he can decide
    which style of decoration would go around the window if any.</para>

    <para><mediaobject>
        <imageobject role="html">
          <imagedata fileref="images/PortalDevelopment/Skinning/windowStyles.png" format="PNG"
                     width="444" align="center" />
        </imageobject>
        <imageobject role="fo">
          <imagedata fileref="images/PortalDevelopment/Skinning/windowStyles.png" format="PNG"
                     width="150mm" align="center" scalefit="1" />
        </imageobject>
      </mediaobject></para>

	<para xml:id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin-Window_style_configuration">
    <citetitle>
       <emphasis role="bold">Window Style Configuration</emphasis>
    </citetitle>
	</para>

	<para>
	Window Styles are defined within the <filename>gatein-resources.xml</filename> file which is used by the skin service to
	deploy the window style into the portal. Window styles can belong in with a window style category, this
	category and the window styles need to be specified in the resources file.
	</para>
        
        <para>The following <filename>gatein-resource.xml</filename> fragment adds MyThemeBlue and MyThemeRed to
        the MyTheme category.</para>
        
        <programlisting language="xml">&lt;window-style&gt;
  &lt;style-name&gt;MyTheme&lt;/style-name&gt;
  &lt;style-theme&gt;
    &lt;theme-name&gt;MyThemeBlue&lt;/theme-name&gt;
  &lt;/style-theme&gt;
  &lt;style-theme&gt;
    &lt;theme-name&gt;MyThemeRed&lt;/theme-name&gt;
  &lt;/style-theme&gt;
&lt;/window-style&gt;</programlisting>

    <para>The windows style configuration for the default skin is configured in: <filename> 01eXoResources.war/WEB-INF/gatein-resources.xml</filename></para>

    <note><para>
    When a window style is defined in the <filename>gatein-resources.xml</filename> file, it will be available
    to all portlets whether the current portal skin supports the window decorator or 
    not. When a new window decorator is added, it is recommended that you add it
    to all portal skins or that portal skins share a common stylesheet for window decorators.
    </para></note>

    <para xml:id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin-Window_style_css">
      <citetitle>
        <emphasis role="bold">Window Style CSS</emphasis>
      </citetitle>
    </para>

	<para>
	To display the window decorators for the skin service, it must have the CSS classes with specific
	naming related to the window style name. The service will try and display the CSS based on this naming. 
	The CSS class must be included as part of the current portal skin for displaying the window decorators.
	</para>
	<para>The location of the window decorator CSS classes for the default portal theme is located at:</para>
	<filename>01eXoResources.war/skin/PortletThemes/Stylesheet.css</filename>
	

        <para>Create the CSS file:</para>

    <programlisting language="css">/*---- MyTheme ----*/
.MyTheme .WindowBarCenter .WindowPortletInfo {
  margin-right: 80px; /* orientation=lt */
  margin-left: 80px; /* orientation=rt */
}
.MyTheme .WindowBarCenter .ControlIcon {
  float: right;/* orientation=lt */
  float: left;/* orientation=rt */
  width: 24px; 
  height: 17px;
  cursor: pointer;
  background-image: url('background/MyTheme.png');
}
.MyTheme .ArrowDownIcon {
  background-position: center 20px;
}
.MyTheme .OverArrowDownIcon {
  background-position: center 116px;
}
.MyTheme .MinimizedIcon {
  background-position: center 44px;
}
.MyTheme .OverMinimizedIcon {
  background-position: center 140px;
}
.MyTheme .MaximizedIcon {
  background-position: center 68px;
}
.MyTheme .OverMaximizedIcon {
  background-position: center 164px;
}
.MyTheme .RestoreIcon {
  background-position: center 92px;
}
.MyTheme .OverRestoreIcon {
  background-position: center 188px;
}
.MyTheme .NormalIcon {
  background-position: center 92px;
}
.MyTheme .OverNormalIcon {
  background-position: center 188px;
}
.UIPageDesktop .MyTheme .ResizeArea {
  float: right;/* orientation=lt */
  float: left;/* orientation=rt */
  width: 18px; height: 18px;
  cursor: nw-resize;
  background: url('background/ResizeArea18x18.gif') no-repeat left top; /* orientation=lt */
  background: url('background/ResizeArea18x18-rt.gif') no-repeat right top; /* orientation=rt */
}
.MyTheme .Information {
  height: 18px; line-height: 18px;
  vertical-align: middle; font-size: 10px;
  padding-left: 5px;/* orientation=lt */
  padding-right: 5px;/* orientation=rt */
  margin-right: 18px;/* orientation=lt */
  margin-left: 18px;/* orientation=rt */
}
.MyTheme .WindowBarCenter .WindowPortletIcon {
  background-position: left top; /* orientation=lt */
  background-position: right top; /* orientation=rt */
  padding-left: 20px; /* orientation=lt */
  padding-right: 20px; /* orientation=rt */
  height: 16px;
  line-height: 16px;
}
.MyTheme .WindowBarCenter .PortletName {
  font-weight: bold;
  color: #333333;
  overflow: hidden;
  white-space: nowrap;
  width: 100%;
}
.MyTheme .WindowBarLeft {
  padding-left: 12px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: left -148px;
}
.MyTheme .WindowBarRight {
  padding-right: 11px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: right -119px;
}
.MyTheme .WindowBarCenter {
  background-image: url('background/MyTheme.png');
  background-repeat: repeat-x;
  background-position: left -90px;
}
.MyTheme .WindowBarCenter .FixHeight {
  height: 21px;
  padding-top: 8px;
}
.MyTheme .MiddleDecoratorLeft {
  padding-left: 12px;
  background: url('background/MyTheme.png') repeat-y left;
}
.MyTheme .MiddleDecoratorRight {
  padding-right: 11px;
  background: url('background/MyTheme.png') repeat-y right;
}
.MyTheme .MiddleDecoratorCenter {
  background: #ffffff;
}
.MyTheme .BottomDecoratorLeft {
  MyTheme: 12px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: left -60px;
}
.MyTheme .BottomDecoratorRight {
  padding-right: 11px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: right -30px;
}
.MyTheme .BottomDecoratorCenter {
  background-image: url('background/MyTheme.png');
  background-repeat: repeat-x;
  background-position: left top;
}
.MyTheme .BottomDecoratorCenter .FixHeight {
  height: 30px;
}
</programlisting>

    <para xml:id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin-Set_default_window_style">
      <citetitle>
        <emphasis role="bold">Set Default Window Style</emphasis>
      </citetitle>
    </para>

	<para>To set the default window style to be used for a portal, you need to specify the CSS classes
	for a theme called <emphasis>DefaultTheme</emphasis>.</para>
	<note>
		<para>You do not need to specify the DefaultTheme in <filename>gatein-resources.xml</filename>.</para>
	</note>
	</section>
  
    <section id="sect-Reference_Guide-Skin_Configuration-Portlet_Styles">
    <title>Create a new portlet skin</title>

    <para>Portlets often require additional styles that may not be defined by
    the portal skin. &PRODUCT; allows you to define additional
    stylesheets for each portlet and will append the corresponding
    <emphasis>link</emphasis> tags to the <emphasis>head</emphasis>.</para>

    <para>The link ID will be of the form
    <parameter>{portletAppName}{PortletName}</parameter>. For example:
    <emphasis>ContentPortlet</emphasis> in <filename>01eXoResources.war/WEB-INF/gatein-resources.xml</filename> and <filename>content.war</filename> in <filename>01eXoResources.war/WEB-INF/gatein-resources.xml</filename> will
    give
    <parameter>id="content<emphasis>ContentPortlet".</emphasis></parameter></para>

    <para>To define a new CSS file to include whenever a portlet is available on a portal page, the
    following fragment needs to be added to <filename>gatein-resources.xml</filename>.</para>
    
    <programlisting language="xml">&lt;portlet-skin&gt;
  &lt;application-name&gt;portletAppName&lt;/application-name&gt;
  &lt;portlet-name&gt;PortletName&lt;/portlet-name&gt;
  &lt;skin-name&gt;Default&lt;/skin-name&gt;
  &lt;css-path&gt;/skin/DefaultStylesheet.css&lt;/css-path&gt;
&lt;/portlet-skin&gt;

&lt;portlet-skin&gt;
  &lt;application-name&gt;portletAppName&lt;/application-name&gt;
  &lt;portlet-name&gt;PortletName&lt;/portlet-name&gt;
  &lt;skin-name&gt;OtherSkin&lt;/skin-name&gt;
  &lt;css-path&gt;/skin/OtherSkinStylesheet.css&lt;/css-path&gt;
&lt;/portlet-skin&gt;</programlisting>

    <para>This will load the <filename>DefaultStylesheet.css</filename> or <filename>OtherSkinStylesheet.css</filename> when the Default skin or OtherSkin is used respectively.</para>
    <note><para>If the current portal skin is not defined as part of the supported
    skins, the portlet CSS class will not be loaded. It is recommended that you update
    portlet skins whenever a new portal skin is created.</para></note>

      <para xml:id="sect-Reference_Guide-Tips_and_Tricks-Change_portlet_icons">
        <citetitle>
          <emphasis role="bold">Change portlet icons</emphasis>
        </citetitle>
      </para>

      <para>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 the portlet webapplication:</para>

      <itemizedlist>
        <listitem>
          <para><filename>skin/DefaultSkin/portletIcons/<replaceable>icon_name.png</replaceable></filename>.</para>
        </listitem>
      </itemizedlist>

         <para>To use the icon correctly, it must be named after the
          portlet.</para>
      <para>For example, the icon for an account portlet named AccountPortlet
      would be located at:</para>

      <itemizedlist>
        <listitem>
          <para><filename>skin/DefaultSkin/portletIcons/AccountPortlet.png</filename></para>
        </listitem>
      </itemizedlist>
      <note>
      <para>
      You must use <filename>skin/DefaultSkin/portletIcons/</filename> for the directory to store the
      portlet icon regardless of what skin is going to be used.
      </para>
      </note>
  </section>
      <section id="sect-Reference_Guide-Skin_Configuration-Portlet_Specification_CSS_Classes">
    <title>Create a new portlet specification CSS class</title>
    <para>The portlet specification defines a set of default CSS classes that should be available for portlets.
    These classes are included as part of the portal skin. Please see the portlet specification for a list of the 
    default classes that should be available.</para>
    <para>For the default portal skin, the portlet specification CSS classes are defined in:</para>
    <filename>eXoResources.war/skin/Portlet/Stylesheet.css</filename>
    </section>
   </section>
  
  
    <section id="sect-Reference_Guide-Skin_Configuration-Tips_and_Tricks" role="NotInToc">
    <title>Tips and Tricks</title>


    <para xml:id="sect-Reference_Guide-Tips_and_Tricks-Easier_css_debugging">
      <citetitle>
		<emphasis role="bold">Easier CSS debugging</emphasis>
	  </citetitle>
	</para>

      <para>By default, CSS files are cached and their imports are merged into
      a single CSS file at the server side. This reduces the number of HTTP
      requests from the browser to the server.</para>

      <para>The optimization code is quite simple as all the CSS files are
      parsed at the server startup time and all the @import and url(...)
      references are rewritten to support a single flat file. The result is
      stored in a cache directly used from the
      <emphasis>ResourceRequestFilter</emphasis>.</para>

      <para>Although the optimization is useful for production environments,
      it may be easier to deactivate this optimization while debugging
      stylesheets. To do so, set the java system property
      <emphasis>exo.product.developing</emphasis> to
      <emphasis>true</emphasis>.</para>

      <para>For example, the property can be passed as a JVM parameter with the
      <command>-D</command> option when running GateIn.</para>
      <command>sh $PLATFORM_JBOSS_HOME/bin/run.sh -Dexo.product.developing=true</command>

      <warning>
          <para>This option may cause display bugs with certain
          browsers, such as Internet Explorer.
		  </para>
      </warning>
	   
	  <para xml:id="sect-Reference_Guide-Tips_and_Tricks-Some_CSS_techniques">
		  <citetitle>
			<emphasis role="bold">Some CSS techniques</emphasis>
		  </citetitle>
	  </para>

      <para>It is recommended that you have some experiences with CSS before
      studying &PRODUCT; CSS.</para>

      <para>&PRODUCT; relies heavily on CSS to create the layout and effects
      for the UI. Some common techniques for customizing &PRODUCT; CSS are
      explained below.</para>

	  <itemizedlist>
		<listitem>
			<para xml:id="sect-Reference_Guide-Some_CSS_techniques-Decorator_pattern"><emphasis role="bold">Decorator pattern</emphasis></para>
			<para>The decorator is a pattern to create a contour or a curve around
        an area. To achieve this effect, you need to create 9 cells.
        The BODY is the central area for you to decorate. The other 8
        cells are distributed around the BODY cell. You can use the width,
        height and background image properties to achieve any desired decoration
        effects.</para>
 
        <mediaobject>
          <imageobject role="html">
            <imagedata fileref="images/PortalDevelopment/Skinning/decoratorPattern.png" format="PNG"
                     width="418" align="center" />
          </imageobject>
            <imageobject role="fo">
            <imagedata fileref="images/PortalDevelopment/Skinning/decoratorPattern.png" format="PNG"
                     width="70mm" scalefit="1" align="center" />
          </imageobject>
        </mediaobject>
		<para> </para>
        <programlisting language="html">&lt;div class="Parent"&gt;
  &lt;div class="TopLeft"&gt;
    &lt;div class="TopRight"&gt;
      &lt;div class="TopCenter"&gt;&lt;span&gt;&lt;/span&gt;&lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="CenterLeft"&gt;
    &lt;div class="CenterRight"&gt;
      &lt;div class="CenterCenter"&gt;BODY&lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="BottomLeft"&gt;
    &lt;div class="BottomRight"&gt;
      &lt;div class="BottomCenter"&gt;&lt;span&gt;&lt;/span&gt;&lt;/div&gt;
    &lt;/div&gt;
  &lt;div&gt;
&lt;/div&gt;</programlisting>
    </listitem>
	  <listitem>
		<para xml:id="sect-Reference_Guide-Some_CSS_techniques-Left_margin_left_pattern"><emphasis role="bold">Left margin left pattern</emphasis></para>
        <para>Left margin left pattern is a technique to create 2 blocks side
        by side. The left block has a fixed size and the right block
        will take the rest of the available space. When the user resizes the
        browser, the added or removed space will be taken from the right
        block.</para>

        <mediaobject>
          <imageobject role="html">
            <imagedata fileref="images/PortalDevelopment/Skinning/leftMarginPattern.png" format="PNG"
                     width="303" align="center" />
          </imageobject>
            <imageobject role="fo">
            <imagedata fileref="images/PortalDevelopment/Skinning/leftMarginPattern.png" format="PNG"
                     width="70mm" scalefit="1" align="center" />
          </imageobject>
        </mediaobject>
		<para></para>
        <programlisting language="html">&lt;div class="Parent"&gt;
  &lt;div style="float: left; width: 100px"&gt;
  &lt;/div&gt;
  &lt;div style="margin-left: 105px;"&gt;
  &lt;div&gt;
  &lt;div style="clear: left"&gt;&lt;span&gt;&lt;/span&gt;&lt;/div&gt;
&lt;/div&gt;</programlisting>
      </listitem>
	</itemizedlist>
  </section>
</section>