Author: thomas.heute(a)jboss.com
Date: 2010-02-15 04:12:44 -0500 (Mon, 15 Feb 2010)
New Revision: 1680
Added:
portal/trunk/docs/reference-guide/en/images/Calculator.png
portal/trunk/docs/reference-guide/en/images/Calendar.png
portal/trunk/docs/reference-guide/en/images/Todo.png
portal/trunk/docs/reference-guide/en/images/windowStyles.png
Modified:
portal/trunk/docs/reference-guide/en/modules/configuration/Skin_Configuration.xml
Log:
Adding missing images
Reworked the skin configuration chapter
Added: portal/trunk/docs/reference-guide/en/images/Calculator.png
===================================================================
(Binary files differ)
Property changes on: portal/trunk/docs/reference-guide/en/images/Calculator.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: portal/trunk/docs/reference-guide/en/images/Calendar.png
===================================================================
(Binary files differ)
Property changes on: portal/trunk/docs/reference-guide/en/images/Calendar.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: portal/trunk/docs/reference-guide/en/images/Todo.png
===================================================================
(Binary files differ)
Property changes on: portal/trunk/docs/reference-guide/en/images/Todo.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: portal/trunk/docs/reference-guide/en/images/windowStyles.png
===================================================================
(Binary files differ)
Property changes on: portal/trunk/docs/reference-guide/en/images/windowStyles.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified:
portal/trunk/docs/reference-guide/en/modules/configuration/Skin_Configuration.xml
===================================================================
---
portal/trunk/docs/reference-guide/en/modules/configuration/Skin_Configuration.xml 2010-02-15
07:57:06 UTC (rev 1679)
+++
portal/trunk/docs/reference-guide/en/modules/configuration/Skin_Configuration.xml 2010-02-15
09:12:44 UTC (rev 1680)
@@ -1,611 +1,600 @@
-<?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" [
+<?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-Skin_Configuration">
- <title>Skin Configuration</title>
- <section id="sect-Reference_Guide-Skin_Configuration-Overview">
- <title>Overview</title>
- <para>
- &PRODUCT; 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.
- </para>
- </section>
-
- <section id="sect-Reference_Guide-Skin_Configuration-Skin_Switching">
- <title>Skin Switching</title>
- <para>
- Skins can be switched dynamically at runtime.
- </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/portal-change-skin.png"
format="PNG" width="444" />
- </imageobject>
- </mediaobject>
- <para>
- When you switch, the whole portal will be repainted and the new styles will be applied
to the UI.
- </para>
- </section>
-
- <section
id="sect-Reference_Guide-Skin_Configuration-Skins_in_Page_Markups">
- <title>Skins in Page Markups</title>
- <para>
- A &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 stylesheet links in the page's
<literal>head</literal> tag.
- </para>
- <para>
- In the snipped code below you can see two types of links:
- </para>
- <programlistingco>
- <areaspec>
- <area coords="3"
id="area-Reference_Guide-Skin_Configuration-Coreskin" />
- <area coords="4"
id="area-Reference_Guide-Skin_Configuration-Stylesheets" />
- </areaspec>
-
-<programlisting><head>
+ <title>Skin Configuration</title>
+
+ <section id="sect-Reference_Guide-Skin_Configuration-Overview">
+ <title>Overview</title>
+
+ <para>&PRODUCT; 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.</para>
+ </section>
+
+ <section id="sect-Reference_Guide-Skin_Configuration-Skin_Switching">
+ <title>Skin Switching</title>
+
+ <para>Skins can be switched dynamically at runtime.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/portal-change-skin.png"
format="PNG"
+ width="444" />
+ </imageobject>
+ </mediaobject>
+
+ <para>When you switch, the whole portal will be repainted and the new
+ styles will be applied to the UI.</para>
+ </section>
+
+ <section id="sect-Reference_Guide-Skin_Configuration-Types_of_Styles">
+ <title>Types of skins</title>
+
+ <para>The complete skinning of a page can be decomposed into four
+ parts:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Portal skin</term>
+
+ <listitem>
+ <para>CSS styles for html tags (ex div,th,td...) and the portal UI
+ (including the toobar).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Portlets skins</term>
+
+ <listitem>
+ <para>CSS styles for each portlet. Used when a portlet want to
+ define it's own CSS.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Window styles</term>
+
+ <listitem>
+ <para>CSS styles for the surrounding of windows (Which embed either
+ gadgets or portlets).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Shared styles</term>
+
+ <listitem>
+ <para>&PRODUCT; WebUI components styles are reused among most of the
+ shipped-in portlets.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The main portal skin stylesheet
+ (<filename>/DefaultSkin/skin/Stylesheet.css</filename>)is shown below as
+ an example:</para>
+
+ <programlisting>@import url(/eXoResources/skin/PortletThemes/Stylesheet.css) ;
+@import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
+@import url(DefaultSkin/webui/component/Stylesheet.css) ;</programlisting>
+ </section>
+
+ <section
id="sect-Reference_Guide-Skin_Configuration-Skins_in_Page_Markups">
+ <title>Skins in Page Markups</title>
+
+ <para>A &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 stylesheet links in the page's
+ <literal>head</literal> tag.</para>
+
+ <para>In the snipped code below you can see two types of links:</para>
+
+ <programlistingco>
+ <areaspec>
+ <area coords="3"
id="area-Reference_Guide-Skin_Configuration-Coreskin" />
+
+ <area coords="4"
+ id="area-Reference_Guide-Skin_Configuration-Stylesheets" />
+ </areaspec>
+
+ <programlisting><head>
...
-<link id="CoreSkin" rel="stylesheet"
type="text/css" href="/eXoResources/skin/Stylesheet.css"
/>
-<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"
/>
+<link id="CoreSkin" rel="stylesheet" type="text/css"
href="/eXoResources/skin/Stylesheet.css" />
+<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>
+</head>
</programlisting>
- <calloutlist>
- <callout
arearefs="area-Reference_Guide-Skin_Configuration-Coreskin">
- <para>
- Portal skin stylesheet
(<literal>id="CoreSkin"</literal>).
- </para>
- </callout>
- <callout
arearefs="area-Reference_Guide-Skin_Configuration-Stylesheets">
- <para>
- Portlets skin stylesheets (<emphasis role="bold">all
others</emphasis>). Each portlet within the page may contribute its own style(s).
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </section>
-
- <section id="sect-Reference_Guide-Skin_Configuration-Types_of_Styles">
- <title>Types of Styles</title>
- <para>
- The portal skin is typically made of 3 types of styles:
- </para>
- <variablelist>
- <varlistentry>
- <term>Portlet themes</term>
- <listitem>
- <para>
- Decorations for portlet windows.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Portal styles</term>
- <listitem>
- <para>
- Default styles for html tags (ex div,th,td...) and the portal UI (including the
sidebar and portal admin screens).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Shared styles</term>
- <listitem>
- <para>
- &PRODUCT; WebUI components styles are reused among different portlets.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The main portal skin stylesheet
(<filename>/eXoVistaSkin/skin/Stylesheet.css</filename>)is shown below as an
example:
- </para>
-
-<programlisting>@import url(/eXoResources/skin/PortletThemes/Stylesheet.css) ;
-@import url(VistaSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
-@import url(VistaSkin/webui/component/Stylesheet.css) ;
-</programlisting>
- </section>
-
- <section id="sect-Reference_Guide-Skin_Configuration-Portlet_Styles">
- <title>Portlet Styles</title>
- <para>
- Portlets often require additionnal styles that may not be defined by the portal skin.
&PRODUCT; allows portlets to define additional stylesheets for each portlet and will
append the corresponding <literal>link</literal> tags to the
<literal>head</literal>.
- </para>
- <para>
- The link ID will be of the form
<parameter>{portletAppName}{}$$PortletName</parameter>. For example:
<literal>ContentPortlet</literal> in
<literal>content.war</literal>, will give
<parameter>id="content<literal>ContentPortlet"</literal></parameter>
- </para>
- <!-- #################### TODO: give some rules to follow in order to avoid
overriding portal styles ##################### -->
- </section>
-
- <section
id="sect-Reference_Guide-Skin_Configuration-How_to_Configure_a_Portal_Skin">
- <title>How to Configure a Portal Skin</title>
- <section
id="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinService">
- <title>SkinService</title>
- <para>
- The <ulink
url="http://fisheye.exoplatform.org/browse/projects/portal/trunk/web...
is an &PRODUCT; service that manages portal skin, portlet styles and portlet themes
(windows borders). The code snippet below is an excerpt of the API offered by this
service.
- </para>
-
-<programlisting role="JAVA">/**
- * Register the stylesheet for a portal Skin.
- * @param module skin module identifier
- * @param skinName skin name
- * @param cssPath path uri to the css file. This is relative to the root context, use
leading '/'
- * @param scontext the webapp's {@link ServletContext}
- */
- public void addPortalSkin(String module, String skinName, String cssPath,
ServletContext scontext) {
- [...]
- }
- /**
- * Register a portlet stylesheet for a Skin.
- * @param module skin module. Typically of the form
'portletAppName/portletName' .
- * @param skinName Name of the skin
- * @param cssPath path uri to the css file. This is relative to the root context, use
leading '/'
- * @param scontext the webapp's {@link ServletContext}
- */
- public void addSkin(String module, String skinName, String cssPath, ServletContext
scontext) {
- [...]
- }
- /**
- * Get a skin configuration for a given Skin
- * @param module skin module such as registered in {@link #addSkin(String, String,
String, ServletContext)}
- * @param skinName skin name
- * @return the skin configuration or, if not found try to find the default skin
- */
- public SkinConfig getSkin(String module, String skinName) {
- [...]
- }
- /**
- * Register multiple portlet themes
- * @param categoryName portlet theme category
- * @param themesName names of the themes
- */
- public void addTheme(String categoryName, List<String> themesName) {
- [...]
- }
-</programlisting>
- <para>
- Use the skin service to register your own portal skins, portlet styles and portlet
themes.
- </para>
- </section>
-
- <section
id="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinConfigListener">
- <title>SkinConfigListener</title>
- <para>
- &PRODUCT; provides a servlet listener that allows you to register your own skins
and styles when your webapp starts up. The first step is to add the listener to your
portlet app <literal>web.xml</literal>.
- </para>
-
-<programlisting role="XML"><web-app>
- [::]
- <listener>
-
<listener-class>org.exoplatform.portal.webui.skin.SkinConfigListener</listener-class>
- </listener>
- [::]
- </web-app>
-</programlisting>
- </section>
-
- <section
id="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinConfigScript.groovy">
- <title>SkinConfigScript.groovy</title>
- <para>
- The <literal>SkinListener</literal> looks for the groovy script file
located in the <filename>war</filename> under:
<filename>/WEB-INF/conf/script/groovy/SkinConfigScript.groovy</filename>
- </para>
- <para>
- This script allows full access to the <literal>SkinService</literal> and
<literal>ServletContext</literal> which are bound as scripting variables under
the same name. The following script is an example. It can be found in the
<literal>GateInResources.war</literal> and is used by &PRODUCT; to
register the <literal>Default</literal> portal skin and some portlet themes.
- </para>
-
-<programlisting>SkinService.addPortalSkin("CoreSkin","Default",
"/GateInResources/skin/Stylesheet.css", ServletContext);
-SkinService.addTheme("Simple",
["SimpleBlue","SimpleViolet","SimpleOrange","SimplePink","SimpleGreen"]);
-SkinService.addTheme("RoundConer",
["RoundConerBlue","RoundConerViolet","RoundConerOrange","RoundConerPink","RoundConerGreen"]);
-SkinService.addTheme("Shadow",
["ShadowBlue","ShadowViolet","ShadowOrange","ShadowPink","ShadowGreen"]);
-SkinService.addTheme("MacStyle",
["MacTheme","MacGray","MacGreenSteel","MacBlack"]);
-SkinService.addTheme("VistaStyle",
["VistaTheme","VistaBlue"]);
-</programlisting>
- <para>
- The syntax of addTheme() is:
-<programlisting>addTheme(String categoryName, List<String>
themesName)
-</programlisting>
- </para>
- <para>
- So, to provide your own skin you could use the following:
-<programlisting>SkinService.addSkin("mywebapp/MyPortlet",
"MyPortalSkin", "/mywebapp/skin/Stylesheet.css",
ServletContext);
-</programlisting>
- </para>
- <para>
- This simple line would register a styleesheet for a portlet named
<literal>MyPortlet</literal> in a portlet app named
<literal>mywebapp</literal>. The stylesheet would be used when a skin named
<literal>MyPortalSkin</literal> is selected in portal.
- </para>
- <para>
- The syntax of addSkin() is:
-<programlisting>addSkin(String module, String skinName, String cssPath,
ServletContext scontext, boolean overwrite)
-</programlisting>
- </para>
- <para>
- '<literal>overwrite</literal>' is optional, its default
value is "<parameter>false</parameter>". If its value is
<parameter>true</parameter>, the later call of
<parameter>addSkin()</parameter> for the same skin key (combination of module
+ skinName) replaces the skin of the previous call.
- </para>
- <para>
- Similarly, use the following to configure a particular portal:
- </para>
-
-<programlisting>SkinService.addSkin("myportalname",
"skin", "/path/to/skin/Stylesheet.css", ServletContext);
-</programlisting>
- <para>
- The syntax of addPortalSkin() is:
-<programlisting>addPortalSkin(String module, String skinName, String cssPath,
ServletContext scontext, boolean overwrite)
-</programlisting>
- </para>
- </section>
+ <calloutlist>
+ <callout
arearefs="area-Reference_Guide-Skin_Configuration-Coreskin">
+ <para>Portal skin stylesheet
+ (<literal>id="CoreSkin"</literal>).</para>
+ </callout>
- </section>
-
- <section id="sect-Reference_Guide-Skin_Configuration-Tips_and_Tricks">
- <title>Tips and Tricks</title>
- <section
id="sect-Reference_Guide-Tips_and_Tricks-Easier_css_debugging">
- <title>Easier css debugging</title>
- <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 <literal>ServletContext</literal> parameter allows direct access to
the CSS files from the <literal>SkinService</literal>. 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
<literal>ResourceRequestFilter</literal>.
- </para>
- <para>
- Although the optimization is useful for a production environments, it may be easier
to deactivate this optimization while debugging stylesheets. To do so, set the java system
property <literal>exo.product.developing</literal> to
<literal>true</literal>.
- </para>
- <para>
- For example, the property can passed as a JVM parameter with the
<literal>-D</literal> option in the <literal>GateIn.sh</literal>
startup script: {code} EXO{code}
- </para>
- <orderedlist numeration="arabic">
- <listitem>
- <para>
- warning("This is option may cause display bugs with certain browsers like
Internet Explorer")
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section
id="sect-Reference_Guide-Tips_and_Tricks-_Change_portlet_icons_">
- <title> Change portlet icons </title>
- <para>
- Each portlet is represented by an icon that you can see in the portlet registry, or
the webos dock. This icon can be changed by adding an image to the directory:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>$project/portlet/myportlets/src/main/webapp/skin/DefaultSkin/portletIcons<replaceable>icon_name.png</replaceable></filename>.
To be used correctly the icon must be named after the portlet.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- For example,the icon for an account portlet named AccountPortlet would be located
at:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>portal/tags/2.1.1/portlet/exoadmin/src/main/webapp/skin/DefaultSkin/portletIcons/AccountPortlet.png</filename>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Reference_Guide-Tips_and_Tricks-Set_the_default_skin">
- <title>Set the default skin</title>
- <para>
- The default skin of portal is called Default. To change this value (to a Mac-like
skin, a Windows Vista-like skin, or an original skin), add a skin tag in the
<literal>portal.xml</literal> that defines your portal:
- </para>
-
-<programlisting role="XML"><portal-config>
- <portal-name>classic</portal-name>
- <locale>en</locale>
- <access-permissions>Everyone</access-permissions>
-
<edit-permission>*:/platform/administrators</edit-permission>
- <skin>Mac</skin>
- <creator>root</creator>
+ <callout
arearefs="area-Reference_Guide-Skin_Configuration-Stylesheets">
+ <para>Portlets skins stylesheets (all
+ others). Each portlet within the page may contribute its
+ own style(s)</para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <note>
+ <para>Window styles are included with the portal skin</para>
+ </note>
+ </section>
+
+ <section
id="sect-Reference_Guide-Tips_and_Tricks-Set_the_default_skin">
+ <title>Set the default skin</title>
+
+ <para>The default skin of portal is called Default. To change this value
+ add a skin tag in the <literal>portal.xml</literal> that defines your
+ portal:</para>
+
+ <programlisting role="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>
+ <creator>root</creator>
...
</programlisting>
- </section>
-
- <section
id="sect-Reference_Guide-Tips_and_Tricks-Some_CSS_techniques">
- <title>Some CSS techniques</title>
- <para>
- It is recommended that users have some experience with CSS before studying
&PRODUCT; CSS. ALso, pleased read the CSS specification at <ulink
type="http"
url="http://www.w3.org/TR/REC-CSS2/selector.html" />
- </para>
- <para>
- &PRODUCT; relies heavily on CSS to create the layout and effects for the UI. Some
common techniques for customizing &PRODUCT;'s CSS are explained below.
- </para>
- <section
id="sect-Reference_Guide-Some_CSS_techniques-Decorator_pattern">
- <title>Decorator pattern</title>
- <para>
- The decorator is a pattern to create a contour or a curve around an area. In order
to achieve this effect you need to create 9 cells. The BODY is the central area that you
want 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 decoration effect that you
want.
- </para>
-
-<programlisting role="HTML">
------------------------------------------------------------------------
-| | | |
-| TopLeft | TopCenter | TopRight |
-| | | |
------------------------------------------------------------------------
-| | | |
-| CenterLeft | BODY | CenterRight |
-| | | |
------------------------------------------------------------------------
-| | | |
-| BottomLeft | BottomCenter | BottomRight |
-| | | |
------------------------------------------------------------------------
-<div class="Parent">
- <div class="TopLeft">
- <div class="TopRight">
- <div
class="TopCenter"><span></span></div>
- </div>
- </div>
- <div class="CenterLeft">
- <div class="CenterRight">
- <div
class="CenterCenter">BODY</div>
- </div>
- </div>
- <div class="BottomLeft">
- <div class="BottomRight">
- <div
class="BottomCenter"><span></span></div>
- </div>
- <div>
-</div>
-</programlisting>
- </section>
-
- <section
id="sect-Reference_Guide-Some_CSS_techniques-Left_margin_left_pattern">
- <title>Left margin left pattern</title>
- <para>
- Left margin left pattern is a technique to create 2 blocks side by side. The left
block will have a fixed size and the right block will take the rest of the available
space. When the user resizes the browser the added or removed space will be taken from the
right block.
- </para>
-
-<programlisting role="HTML">
-| | |
-| | |
-| |<--- fixed width --->| | will expand to right
----> |
-| | |
-| | |
-| | |
-----
-<div class="Parent">
- <div style="float: left; width: 100px">
- </div>
- <div style="margin-left: 105px;">
- <div>
- <div style="clear:
left"><span></span></div>
-</div>
-</programlisting>
- </section>
+ </section>
- </section>
- </section>
-
- <section
id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin">
- <title>How to create a new skin</title>
- <procedure>
- <step>
- <para>
- Define the new skin in the
<literal>WEB-INF/conf/script/groovy/SkinConfigScript.groovy</literal> file as
a <literal>Resource</literal> (for example, in the project
<replaceable>MyPortal</replaceable>, the resource would read;
<literal>GateInResourcesMyPortal</literal>).
- </para>
- <warning>
- <para>
- The
<literal>WEB-INF/conf/script/groovy/SkinConfigScript.groovy</literal> file
mentioned above does not exist in EPP-5.0.ER2. The closest match is
<literal>./jboss-as/server/default/tmp/<replaceable>instance</replaceable>/02portal.war/WEB-INF/conf/uiconf/portal/webui/portal/SkinConfigOption.groovy
</literal>
- </para>
- </warning>
-
-<programlisting>
-SkinService.addPortalSkin("MyPortalSkin","MyPortal","/GateInResourcesMyPortal/skin/Stylesheet.css",ServletContext);
-</programlisting>
- </step>
- <step>
- <para>
- Place the new skin files into the
<replaceable>skinyourSkin</replaceable> folder and create a new
<literal>Stylesheet.css</literal> file in the same directory. This file should
include lines to import all links to your CSS. For example in
<replaceable>MyPortal</replaceable> project:
- </para>
-
-<programlisting>
-@import url(MyPortalSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
-@import url(MyPortalSkin/webui/component/Stylesheet.css) ;
-</programlisting>
- </step>
- <step>
- <para>
- Finally, define the name of new skin and the image preview for the
<emphasis>Skin Settings</emphasis> action. The image preview can be set in the
file:<filename>ressource/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</filename>
-<programlisting>
-.UIChangeSkinForm .UIItemSelector .TemplateContainer .MyPortalImage {
- margin: auto;
- width: 329px; height:204px;
- background: url('background/MyPortal.jpg') no-repeat top;
- cursor: pointer ;
-}
-</programlisting>
- </para>
- <para>
- If no name is set for the new skin, it will be named
<literal>label></literal>. The skin name is defined in the
<literal>./jboss-as/server/default/tmp<replaceable>instance</replaceable>/<replaceable>resource</replaceable>/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</literal>.
- </para>
- <warning>
- <para>
- The program listing below is in French. This should be translated into en-US before
publication.
- </para>
- </warning>
-
-<programlisting>
-#############################################################################
-# Change Skin #
-#############################################################################
-
-UIChangeSkin.action.save=Appliquer
-UIChangeSkin.action.close=Fermer
-UIChangeSkin.title.SkinSetting=Configuration des styles
-UIChangeSkin.MyPortal.label=Style MyPortal
-UIChangeSkin.Default.label=Style par d?faut
-UIChangeSkin.Mac.label=Style Mac
-UIChangeSkin.Vista.label=Style Vista
-Skin.title=Liste des styles
-Skin.left.title=Voir et s?lectionner un style
-</programlisting>
- </step>
- <step>
- <para>
- Copy the image defined above (<literal>MyPortal.jpg</literal>) to the
folder
<literal>ressource/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background</literal>
and test your new skin.
- </para>
- </step>
- </procedure>
+ <section
id="sect-Reference_Guide-Skin_Configuration-How_to_create_a_new_skin">
+ <title>How to create a new skin</title>
- </section>
-
- <section
id="sect-Reference_Guide-Skin_Configuration-How_to_create_new_themes">
- <title>How to create new themes</title>
- <procedure>
- <step>
- <para>
- Define the new theme in
<literal>WEB-INF/conf/script/groovy/SkinConfigScript.groovy</literal> in your
<literal>Resource</literal> (for example, in the project MyPortal:
<literal>GateInResourcesCp060508</literal>).
- </para>
-
-<programlisting>SkinService.addTheme("MyPortal-MacTheme",
["MacGray","MacBlue","MacBlack"]);
-</programlisting>
- </step>
- <step>
- <para>
- Place new theme files into <literal>folder skinyourSkin</literal> and
create a new <literal>Stylesheet.css</literal> file in the same directory.
This file should include lines to import all links to all CSS resources. For example, in
the <replaceable>MyPortal</replaceable> project:
- </para>
-
-<programlisting>@import url(MyPortalSkin/PortletThemes/Stylesheet.css) ;
-</programlisting>
- </step>
- </procedure>
-
- <para>
- The code below illustrates the inclusion of all CSS resoucres for a new theme from the
example file
<literal>GateInResourcesCp060508/skin/MyPortalSkin/PortletThemes/Stylesheet.css</literal>.
- </para>
-
-<programlisting>
-/*---- MyPortalTheme ----*/
-.MyPortalTheme .WindowBarCenter .WindowPortletInfo {
- margin-right: 80px; /* orientation=lt */
- margin-left: 80px; /* orientation=rt */
+ <section
id="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinService">
+ <title>SkinService</title>
+
+ <para>The SkinService is an &PRODUCT; service that manages portal skin,
+ portlet styles and portlet themes (windows borders).</para>
+ </section>
+
+ <section
id="sect-Reference_Guide-How_to_Configure_a_Portal_Skin-SkinConfigListener">
+ <title>ResourceRequestFilter</title>
+
+ <para>&PRODUCT; automatically discovers web archives that contains a
+ file descriptor for skins (WEB-INF/gatein-resources.xml).</para>
+
+ <para>Because of the Right-To-Left support all CSS files need to be
+ retrieved through a Servlet filter and the web application need to be
+ configured to activate this filter. This is already done for the
+ 01eXoResources.war web application.</para>
+
+ <programlisting role="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></programlisting>
+ </section>
+
+ <section>
+ <title>Skin configuration</title>
+
+ <para>&PRODUCT; automatically discovers web archives that contains a
+ file descriptor for skins (WEB-INF/gatein-resources.xml).The
+ full schema can be found in
+ 02portal.war:/WEB-INF/gatein_resources_1-0.xsd</para>
+
+ <para>Here is an
example:<programlisting><gatein-resources>
+ <portal-skin>
+ <skin-name>MySkin</skin-name>
+ <css-path>/skin/myskin.css</css-path>
+ <overwrite>false</overwrite>
+ </portal-skin>
+</gatein-resources></programlisting></para>
+
+ <para>Here we defined a skin (MySkin) and the CSS location within the
+ same web archive.</para>
+
+ <para>Default portal skin and window styles are defined in
+ 01eXoResources.war:/WEB-INF/gatein-resources.xml and the part dedicated to
+ skinning is defined like:<programlisting><gatein-resources
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_resources_1_...
xmlns="http://www.ga
+tein.org/xml/ns/gatein_resources_1_0.xsd">
+ <portal-skin>
+ <skin-name>Default</skin-name>
+ <css-path>/skin/Stylesheet.css</css-path>
+ </portal-skin>
+
+ <!-- Simple window style -->
+ <window-style>
+ <style-name>Simple</style-name>
+ <style-theme>
+ <theme-name>SimpleBlue</theme-name>
+ </style-theme>
+ <style-theme>
+ <theme-name>SimpleViolet</theme-name>
+ </style-theme>
+ <style-theme>
+ <theme-name>SimpleOrange</theme-name>
+ </style-theme>
+ <style-theme>
+ <theme-name>SimplePink</theme-name>
+ </style-theme>
+ <style-theme>
+ <theme-name>SimpleGreen</theme-name>
+ </style-theme>
+ </window-style></programlisting></para>
+ </section>
+
+ <section>
+ <title>Skin icon</title>
+
+ <para>When selecting a skin, an overview of the skin is possible. It has
+ to be defined in the current skin used to display the form to change
+ skins.</para>
+
+ <para>Put the screeshot of the skin in:
+
<literal>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background</literal>
+ and add the following in
+
01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css:<programlisting>.UIChangeSkinForm
.UIItemSelector .TemplateContainer .<emphasis
+ role="bold">MySkin</emphasis>Image {
+ margin: auto;
+ width: 329px; height:204px;
+ background: url('background/<emphasis
role="bold">MySkin</emphasis>.jpg') no-repeat top;
+ cursor: pointer ;
+}</programlisting></para>
+ </section>
+ </section>
+
+ <section
id="sect-Reference_Guide-Skin_Configuration-How_to_create_new_themes">
+ <title>How to create a new window style</title>
+
+ <para>Window styles are the CSS applied to window decoration. When an
+ administrator choose a new application to add on a page he can decide
+ which style of decoration would go around the window if any.</para>
+
+ <para><mediaobject>
+ <imageobject>
+ <imagedata fileref="images/windowStyles.png"
format="PNG"
+ width="444" />
+ </imageobject>
+ </mediaobject></para>
+
+ <para>The code below illustrates the inclusion of all CSS resoucres for a
+ new theme from the example file
+
<literal>GateInResourcesCp060508/skin/MyPortalSkin/PortletThemes/Stylesheet.css</literal>.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>In 01eXoResources:/WEB-INF/gatein-resources.xml add the
+ following snippet:<programlisting><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></programlisting></para>
+
+ <para>Here we created a group of themes called 'MyTheme' and two
+ themes that reference CSS classnames.</para>
+ </listitem>
+
+ <listitem>
+ <para>Create the CSS file:</para>
+ </listitem>
+ </orderedlist>
+
+ <programlisting>
+/*---- MyTheme ----*/
+.MyTheme .WindowBarCenter .WindowPortletInfo {
+ margin-right: 80px; /* orientation=lt */
+ margin-left: 80px; /* orientation=rt */
}
-.MyPortalTheme .WindowBarCenter .ControlIcon {
- float: right;/* orientation=lt */
- float: left;/* orientation=rt */
- width: 24px;
- height: 17px;
- cursor: pointer;
- background-image: url('background/MyPortalTheme.png');
+.MyTheme .WindowBarCenter .ControlIcon {
+ float: right;/* orientation=lt */
+ float: left;/* orientation=rt */
+ width: 24px;
+ height: 17px;
+ cursor: pointer;
+ background-image: url('background/MyTheme.png');
}
-.MyPortalTheme .ArrowDownIcon {
- background-position: center 20px;
+.MyTheme .ArrowDownIcon {
+ background-position: center 20px;
}
-.MyPortalTheme .OverArrowDownIcon {
- background-position: center 116px;
+.MyTheme .OverArrowDownIcon {
+ background-position: center 116px;
}
-.MyPortalTheme .MinimizedIcon {
- background-position: center 44px;
+.MyTheme .MinimizedIcon {
+ background-position: center 44px;
}
-.MyPortalTheme .OverMinimizedIcon {
- background-position: center 140px;
+.MyTheme .OverMinimizedIcon {
+ background-position: center 140px;
}
-.MyPortalTheme .MaximizedIcon {
- background-position: center 68px;
+.MyTheme .MaximizedIcon {
+ background-position: center 68px;
}
-.MyPortalTheme .OverMaximizedIcon {
- background-position: center 164px;
+.MyTheme .OverMaximizedIcon {
+ background-position: center 164px;
}
-.MyPortalTheme .RestoreIcon {
- background-position: center 92px;
+.MyTheme .RestoreIcon {
+ background-position: center 92px;
}
-.MyPortalTheme .OverRestoreIcon {
- background-position: center 188px;
+.MyTheme .OverRestoreIcon {
+ background-position: center 188px;
}
-.MyPortalTheme .NormalIcon {
- background-position: center 92px;
+.MyTheme .NormalIcon {
+ background-position: center 92px;
}
-.MyPortalTheme .OverNormalIcon {
- background-position: center 188px;
+.MyTheme .OverNormalIcon {
+ background-position: center 188px;
}
-.UIPageDesktop .MyPortalTheme .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 */
+.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 */
}
-.MyPortalTheme .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 .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 */
}
-.MyPortalTheme .WindowBarCenter .WindowPortletIcon {
+.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;
+ padding-left: 20px; /* orientation=lt */
+ padding-right: 20px; /* orientation=rt */
+ height: 16px;
+ line-height: 16px;
}
-.MyPortalTheme .WindowBarCenter .PortletName {
- font-weight: bold;
- color: #333333;
- overflow: hidden;
- white-space: nowrap;
- width: 100%;
+.MyTheme .WindowBarCenter .PortletName {
+ font-weight: bold;
+ color: #333333;
+ overflow: hidden;
+ white-space: nowrap;
+ width: 100%;
}
-.MyPortalTheme .WindowBarLeft {
- padding-left: 12px;
- background-image: url('background/MyPortalTheme.png');
- background-repeat: no-repeat;
- background-position: left -148px;
+.MyTheme .WindowBarLeft {
+ padding-left: 12px;
+ background-image: url('background/MyTheme.png');
+ background-repeat: no-repeat;
+ background-position: left -148px;
}
-.MyPortalTheme .WindowBarRight {
- padding-right: 11px;
- background-image: url('background/MyPortalTheme.png');
- background-repeat: no-repeat;
- background-position: right -119px;
+.MyTheme .WindowBarRight {
+ padding-right: 11px;
+ background-image: url('background/MyTheme.png');
+ background-repeat: no-repeat;
+ background-position: right -119px;
}
-.MyPortalTheme .WindowBarCenter {
- background-image: url('background/MyPortalTheme.png');
- background-repeat: repeat-x;
- background-position: left -90px;
+.MyTheme .WindowBarCenter {
+ background-image: url('background/MyTheme.png');
+ background-repeat: repeat-x;
+ background-position: left -90px;
}
-.MyPortalTheme .WindowBarCenter .FixHeight {
- height: 21px;
- padding-top: 8px;
+.MyTheme .WindowBarCenter .FixHeight {
+ height: 21px;
+ padding-top: 8px;
}
-.MyPortalTheme .MiddleDecoratorLeft {
- padding-left: 12px;
- background: url('background/MMyPortalTheme.png') repeat-y left;
+.MyTheme .MiddleDecoratorLeft {
+ padding-left: 12px;
+ background: url('background/MyTheme.png') repeat-y left;
}
-.MyPortalTheme .MiddleDecoratorRight {
- padding-right: 11px;
- background: url('background/MMyPortalTheme.png') repeat-y right;
+.MyTheme .MiddleDecoratorRight {
+ padding-right: 11px;
+ background: url('background/MyTheme.png') repeat-y right;
}
-.MyPortalTheme .MiddleDecoratorCenter {
- background: #ffffff;
+.MyTheme .MiddleDecoratorCenter {
+ background: #ffffff;
}
-.MyPortalTheme .BottomDecoratorLeft {
- padding-left: 12px;
- background-image: url('background/MyPortalTheme.png');
- background-repeat: no-repeat;
- background-position: left -60px;
+.MyTheme .BottomDecoratorLeft {
+ MyTheme: 12px;
+ background-image: url('background/MyTheme.png');
+ background-repeat: no-repeat;
+ background-position: left -60px;
}
-.MyPortalTheme .BottomDecoratorRight {
- padding-right: 11px;
- background-image: url('background/MyPortalTheme.png');
- background-repeat: no-repeat;
- background-position: right -30px;
+.MyTheme .BottomDecoratorRight {
+ padding-right: 11px;
+ background-image: url('background/MyTheme.png');
+ background-repeat: no-repeat;
+ background-position: right -30px;
}
-.MyPortalTheme .BottomDecoratorCenter {
- background-image: url('background/MyPortalTheme.png');
- background-repeat: repeat-x;
- background-position: left top;
+.MyTheme .BottomDecoratorCenter {
+ background-image: url('background/MyTheme.png');
+ background-repeat: repeat-x;
+ background-position: left top;
}
-.MyPortalTheme .BottomDecoratorCenter .FixHeight {
- height: 30px;
+.MyTheme .BottomDecoratorCenter .FixHeight {
+ height: 30px;
}
</programlisting>
- </section>
+ </section>
+
+ <section
id="sect-Reference_Guide-Skin_Configuration-Portlet_Styles">
+ <title>How to create new Portlet skins</title>
-</section>
+ <para>Portlets often require additionnal styles that may not be defined by
+ the portal skin. &PRODUCT; allows portlets to define additional
+ stylesheets for each portlet and will append the corresponding
+ <literal>link</literal> tags to the
<literal>head</literal>.</para>
+ <para>The link ID will be of the form
+ <parameter>{portletAppName}{PortletName}</parameter>. For example:
+ <literal>ContentPortlet</literal> in
<literal>content.war</literal>, will
+ give
+
<parameter>id="content<literal>ContentPortlet"</literal></parameter></para>
+ <para>To define a new CSS file to include whenever a portlet is added, the
+ following snippet need to be added in
gatein-resources.xml<programlisting><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></programlisting></para>
+
+ <para>The portal framework will include the CSS file corresponding to the
+ skin in used.</para>
+
+
+ <section
id="sect-Reference_Guide-Tips_and_Tricks-Change_portlet_icons">
+ <title>Change portlet icons</title>
+
+ <para>Each portlet is represented by an icon that you can see in the
+ portlet registry. This icon can be changed by adding an image to the
+ directory:</para>
+
+ <itemizedlist>
+ <listitem>
+
<para><filename>skin/DefaultSkin/portletIcons<replaceable>icon_name.png</replaceable></filename>.
+ To be used correctly the icon must be named after the
+ portlet.</para>
+ </listitem>
+ </itemizedlist>
+
+ <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>
+ </section>
+ </section>
+
+
+
+ <section
id="sect-Reference_Guide-Skin_Configuration-Tips_and_Tricks">
+ <title>Tips and Tricks</title>
+
+ <section
id="sect-Reference_Guide-Tips_and_Tricks-Easier_css_debuggin">
+ <title>Easier css debugging</title>
+
+ <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
+ <literal>ResourceRequestFilter</literal>.</para>
+
+ <para>Although the optimization is useful for a production environments,
+ it may be easier to deactivate this optimization while debugging
+ stylesheets. To do so, set the java system property
+ <literal>exo.product.developing</literal> to
+ <literal>true</literal>.</para>
+
+ <para>For example, the property can passed as a JVM parameter with the
+ <literal>-D</literal> option when running
GateIn.<programlisting>sh $JBOSS_HOME/bin/run.sh
-Dexo.product.developing=true</programlisting></para>
+
+ <orderedlist numeration="arabic">
+ <listitem>
+ <para>warning("This is option may cause display bugs with certain
+ browsers like Internet Explorer")</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section
id="sect-Reference_Guide-Tips_and_Tricks-Some_CSS_techniques">
+ <title>Some CSS techniques</title>
+
+ <para>It is recommended that users have some experience 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;'s CSS are
+ explained below.</para>
+
+ <section
id="sect-Reference_Guide-Some_CSS_techniques-Decorator_pattern">
+ <title>Decorator pattern</title>
+
+ <para>The decorator is a pattern to create a contour or a curve around
+ an area. In order to achieve this effect you need to create 9 cells.
+ The BODY is the central area that you want 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 decoration
+ effect that you want.</para>
+
+ <programlisting role="HTML">
+-----------------------------------------------------------------------
+| | | |
+| TopLeft | TopCenter | TopRight |
+| | | |
+-----------------------------------------------------------------------
+| | | |
+| CenterLeft | BODY | CenterRight |
+| | | |
+-----------------------------------------------------------------------
+| | | |
+| BottomLeft | BottomCenter | BottomRight |
+| | | |
+-----------------------------------------------------------------------
+<div class="Parent">
+ <div class="TopLeft">
+ <div class="TopRight">
+ <div
class="TopCenter"><span></span></div>
+ </div>
+ </div>
+ <div class="CenterLeft">
+ <div class="CenterRight">
+ <div class="CenterCenter">BODY</div>
+ </div>
+ </div>
+ <div class="BottomLeft">
+ <div class="BottomRight">
+ <div
class="BottomCenter"><span></span></div>
+ </div>
+ <div>
+</div>
+</programlisting>
+ </section>
+
+ <section
id="sect-Reference_Guide-Some_CSS_techniques-Left_margin_left_pattern">
+ <title>Left margin left pattern</title>
+
+ <para>Left margin left pattern is a technique to create 2 blocks side
+ by side. The left block will have a fixed size and the right block
+ will take the rest of the available space. When the user resizes the
+ browser the added or removed space will be taken from the right
+ block.</para>
+
+ <programlisting role="HTML">
+| | |
+| | |
+| |<--- fixed width --->| | will expand to right
----> |
+| | |
+| | |
+| | |
+----
+<div class="Parent">
+ <div style="float: left; width: 100px">
+ </div>
+ <div style="margin-left: 105px;">
+ <div>
+ <div style="clear:
left"><span></span></div>
+</div>
+</programlisting>
+ </section>
+ </section>
+ </section>
+</section>