[gatein-commits] gatein SVN: r1680 - in portal/trunk/docs/reference-guide/en: modules/configuration and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Mon Feb 15 04:12:44 EST 2010
Author: thomas.heute at 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) ;
+ at import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
+ at 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) ;
- at import url(VistaSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
- at 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/webui/portal/src/main/java/org/exoplatform/portal/webui/skin/SkinService.java">SkinService</ulink> 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>
- at import url(MyPortalSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
- at 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_0.xsd" 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>
More information about the gatein-commits
mailing list