<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book id="DeveloperGuide">
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="bookinfo.xml"/>
  <chapter id="DEV.GetStarted">
    <title>Get Started </title>
    <abstract>
<para>Before jumping directly into the development tasks, you need to learn about the basic knowledge of eXo Platform 3.5 via the following sections:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.Glossary">Glossary</link>
            </emphasis>
	</para>
	<para>
	Technical terms which are used throughout the documentation.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.SetupMavenSettings">Set up Maven settings</link>
            </emphasis>
	</para>
	 <para>
	  Requirements and how to install a Maven project.
	 </para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.eXoArchitecturePremer">eXo Architecture Primer</link>
            </emphasis>
	</para>
	<para>
	Introduction to the eXo architecture, including:
	</para>
  <itemizedlist>
  <listitem>
   <para>
                <emphasis role="bold">
                  <link linkend="DEV.eXoArchitecturePremer.Kernel">Kernel</link>
                </emphasis>
   </para>
   <para>Concepts of containers, services, plugins and configuration loading sequence.</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
                  <link linkend="DEV.eXoArchitecturePremer.GateInExtensions">GateIn extensions</link>
                </emphasis>
	</para>
	<para>
	The special <emphasis>.war</emphasis> files that are recognized by eXo Platform and contribute to custom configurations to the PortalContainer. 
	</para>
  </listitem>
    <listitem>
	<para>
	  <emphasis role="bold">
                  <link linkend="DEV.eXoArchitecturePremer.JavaContentRepository">Java Content Repository</link>
                </emphasis>
	</para>
	<para>
	A Java Content Repository (JCR) where all data of eXo Platform are stored.
	</para>
  </listitem>
 </itemizedlist>
  </listitem>
</itemizedlist>
</abstract>
    <section id="DEV.Glossary">
      <title>Glossary </title>
      <para>This section gives you explanations of some technical terms which are used throughout the documentation.</para>
      <para>
<citetitle>
<emphasis role="bold">Container templates</emphasis>
</citetitle>
</para>
      <para>Templates which are used to contain the UI components in a specific layout and display them on the portal page.</para>
      <para>
<citetitle>
<emphasis role="bold">ConversationState</emphasis>
</citetitle>
</para>
      <para>An object which stores all information about the state of the current user. This object also stores acquired attributes of an Identity which is a set of principals to identify a user.</para>
      <para>
<citetitle>
<emphasis role="bold">Data container</emphasis>
</citetitle>
</para>
      <para>An object which implements the physical data storage. It enables different types of backend (such as RDB, FS files) to be used as a storage for the JCR data. With the main Data Container, other storages for persisted Property Values can be configured and used. The eXo JCR persistent data container can work in two configuration modes.</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">Multi-database</emphasis>: A database for each workspace (used in the standalone eXo JCR service mode).</para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">Single-database</emphasis>: All workspaces persisted in one database (used in the embedded eXo JCR service mode; for example in eXo portal). The data container uses the JDBC driver to communicate with the actual database software. For example, any JDBC-enabled data storage can be used with the eXo JCR implementation.</para>
        </listitem>
      </itemizedlist>
      <para>
<citetitle>
<emphasis role="bold">Database Creator (DBCreator)</emphasis>
</citetitle>
</para>
      <para>A service that is responsible for executing the DDL (Data Definition Language) script in runtime. A DDL script may contain templates for database name, username, and password which will be replaced by real values at execution time.</para>
      <para>
<citetitle>
<emphasis role="bold">Drives</emphasis>
</citetitle>
</para>
      <para>Customized workspaces which include:</para>
      <itemizedlist>
        <listitem>
          <para>a configured path where the user will start when browsing the drive.</para>
        </listitem>
        <listitem>
          <para>a set of views with limitations to available actions, such as editing or creating contents while being in the drive.</para>
        </listitem>
        <listitem>
          <para>a set of permissions to limit the access (and view) of the drive to a restricted number of people.</para>
        </listitem>
        <listitem>
          <para>a set of options to describe the behavior of the drive when users browse it.</para>
        </listitem>
      </itemizedlist>
      <para>
<citetitle>
<emphasis role="bold">eXo Cache</emphasis>
</citetitle>
</para>
      <para>One which all applications on the top of eXo JCR need. This can rely on an <emphasis role="italic">org.exoplatform.services.cache.ExoCache</emphasis> instance managed by <emphasis role="italic">org.exoplatform.services.cache.CacheService</emphasis>.</para>
      <para>
<citetitle>
<emphasis role="bold">eXoContainer</emphasis>
</citetitle>
</para>
      <para>An object which behaves like a class loader that is responsible for loading services/components. The eXoContainer class is inherited by all the containers, including RootContainer, PortalContainer, and StandaloneContainer. It itself inherits from a PicoContainer framework which allows eXo to apply the IoC Inversion of Control principles. </para>
      <para>
<citetitle>
<emphasis role="bold">External Plugin</emphasis>
</citetitle>
</para>
      <para>One which allows adding configuration for services and components easily.</para>
      <para>
<citetitle>
<emphasis role="bold">Folksonomy</emphasis>
</citetitle>
</para>
      <para>A system of classification which is derived from the practice and a method of collaboratively creating and managing tags to annotate and categorize content. This practice is also known as collaborative tagging social classification social indexing and social tagging. For more details, see: http://en.wikipedia.org.</para>
      <para>
<citetitle>
<emphasis role="bold">Gadgets</emphasis>
</citetitle>
</para>
      <para>Web-based software components which are based on HTML, CSS, and JavaScript. They allow developers to easily write useful web applications that work anywhere on the web without modification. For more details, see: opensocial.org.</para>
      <para>
<citetitle>
<emphasis role="bold">Groovy template</emphasis>
</citetitle>
</para>
      <para>A template which is widely used in eXo UI framework. It leverages the usage of Groovy language, a scripting language for Java. The template file consists of HTML code and Groovy code blocks.</para>
      <para>
<citetitle>
<emphasis role="bold">JCR WebDav</emphasis>
</citetitle>
</para>
      <para>A service that allows accessing a JCR repository via WebDav.</para>
      <para>
<citetitle>
<emphasis role="bold">JobSchedulerService</emphasis>
</citetitle>
</para>
      <para>One which defines a job to execute a given number of times during a given period. It is a service that is in charge of unattended background executions commonly known for historical reasons as batch processing. </para>
      <para>
<citetitle>
<emphasis role="bold">JodConverter (Java OpenDocument Converter)</emphasis>
</citetitle>
</para>
      <para>A tool which converts documents into different office formats and vice versa.</para>
      <para>
<citetitle>
<emphasis role="bold">JCR Item</emphasis>
</citetitle>
</para>
      <para>One which may be a node or a property.</para>
      <para>
<citetitle>
<emphasis role="bold">ListenerService</emphasis>
</citetitle>
</para>
      <para>An event mechanism which allows triggering and listening to events under specific conditions inside eXo Platform. This mechanism is used in several places in eXo Platform, such as login/logout time, creating/updating users, and groups.</para>
      <para>
<citetitle>
<emphasis role="bold">LockManager</emphasis>
</citetitle>
</para>
      <para>One which stores lock objects, so it can give a lock object or can release it. Also, LockManager is responsible for removing Locks that live too long.</para>
      <para>
<citetitle>
<emphasis role="bold">Namespace</emphasis>
</citetitle>
</para>
      <para>The name of a node or property which may have a prefix delimited by a single ':' colon character. This name indicates the namespace of the item (Source: <ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>) and is used to avoid the naming conflict. </para>
      <para>
<citetitle>
<emphasis role="bold">Navigation node</emphasis>
</citetitle>
</para>
      <para>A node which looks like a label of the link to page on the Navigation bar. By clicking a node, the page content is displayed. A node maps a URI and a portal page for the portal's navigation system. </para>
      <para>
<citetitle>
<emphasis role="bold">Navigation</emphasis>
</citetitle>
</para>
      <para>One which looks like a menu which is to help users visualize the site structure and to provide hyperlinks to other parts on a Portal. Thus, a bar which contains navigations is called the Navigation bar. </para>
      <para>
<citetitle>
<emphasis role="bold">Node type</emphasis>
</citetitle>
</para>
      <para>One which defines child nodes and properties which a node may (or must) have. Every node type has attributes, such as name, supertypes, mixin status, orderable child nodes status, property definitions, child node definitions and primary item name (Source: <ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>). </para>
      <para>
<citetitle>
<emphasis role="bold">Node</emphasis>
</citetitle>
</para>
      <para>An element in the tree structure that makes up a repository. Each node may have zero or more child nodes and zero or more child properties. There is a single root node per workspace which has no parent. All other nodes have only one parent. </para>
      <para>
<citetitle>
<emphasis role="bold">Organization listener</emphasis>
</citetitle>
</para>
      <para>One which provides a mechanism to receive notifications via an organization listener, including UserEventListener, GroupEventListener and MembershipEventListener. </para>
      <itemizedlist>
        <listitem>
          <para>UserEventListener is called when a user is created, deleted or modified.</para>
        </listitem>
        <listitem>
          <para>GroupEventListener is called when a group is created, deleted or modified.</para>
        </listitem>
        <listitem>
          <para>MembershipEventListener is called when a membership is created or removed.</para>
        </listitem>
      </itemizedlist>
      <para>
<citetitle>
<emphasis role="bold">Organization management</emphasis>
</citetitle>
</para>
      <para>A portlet that manages users groups and memberships. This portlet is often managed by administrators to set up permission for users and groups. </para>
      <para>
<citetitle>
<emphasis role="bold">OrganizationService</emphasis>
</citetitle>
</para>
      <para>A service that allows accessing the Organization model. This model is composed of users, groups, and memberships. It is the basis of eXo's personalization and authorizations and is used for all over the platform. </para>
      <para>
<citetitle>
<emphasis role="bold">Path constraint</emphasis>
</citetitle>
</para>
      <para>One which restricts the result node to a scope specified by a path expression. The following path constraints must be supported exact child nodes descendants and descendants or self (Source: <ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>). </para>
      <para>
<citetitle>
<emphasis role="bold">Permission</emphasis>
</citetitle>
</para>
      <para>A permission settings control which actions users can or cannot perform within the portal and are set by the portal administrators. Permission types specify what a user can do within the portal. </para>
      <para>
<citetitle>
<emphasis role="bold">Portal Page</emphasis>
</citetitle>
</para>
      <para>A page which consists of one or more various portlets. Their layouts are defined by container templates. To display a portal page, this page must be mapped to a navigation node. </para>
      <para>
<citetitle>
<emphasis role="bold">Portal skins</emphasis>
</citetitle>
</para>
      <para>Graphic styles which display an attractive user interface. Each skin has its own characteristics with different backgrounds, icons, color, and more. </para>
      <para>
<citetitle>
<emphasis role="bold">PortalContainer</emphasis>
</citetitle>
</para>
      <para>A type of container which is created at the startup of the portal web application in the init method of the PortalController servlet. </para>
      <para>
<citetitle>
<emphasis role="bold">Portlet</emphasis>
</citetitle>
</para>
      <para>A web-based application that provides a specific piece of content to be included as part of a portal page. In other words, portlets are pluggable user interface components that provide a presentation layer to information systems. There are two following types of portlet:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">Functional Portlets</emphasis> support all functions within the portal. They are integrated into the portal that can be accessed through toolbar links.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">Interface Portlets</emphasis> constitute the interface of a portal. eXo Portal consists of some Interface Portlets, such as Banner Portlet, Footer Portlet, Homepage Portlet, Console Portlet, Breadcrumb Portlet and more. </para>
        </listitem>
      </itemizedlist>
      <para>
<citetitle>
<emphasis role="bold">Property constraint</emphasis>
</citetitle>
</para>
      <para>One which may be specified by a query on the result nodes by way of property constraints (Source: <ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>). </para>
      <para>
<citetitle>
<emphasis role="bold">Property</emphasis>
</citetitle>
</para>
      <para>An element in the tree structure that makes up a repository. Each property has only one parent node and has no child node. </para>
      <para>
<citetitle>
<emphasis role="bold">Repository</emphasis>
</citetitle>
</para>
      <para>One which holds references to one or more workspaces. </para>
      <para>
<citetitle>
<emphasis role="bold">eXo REST framework</emphasis>
</citetitle>
</para>
      <para>One which is used to make eXo services (for example, the components deployed inside eXo Container) simply and transparently accessible via HTTP in a RESTful manner. In other words, those services should be viewed as a set of REST Resources-endpoints of the HTTP request-response chain. Those services are called <emphasis role="bold">ResourceContainers</emphasis>. </para>
      <para>
<citetitle>
<emphasis role="bold">RootContainer</emphasis>
</citetitle>
</para>
      <para>A base container which plays an important role during the startup. However, it is recommended that it should not be used directly.</para>
      <para>
<citetitle>
<emphasis role="bold">RTL Framework (Right To Left Framework)</emphasis>
</citetitle>
</para>
      <para>A framework which handles the text orientation depending on the current locale settings. It consists of four components, including Groovy template, Stylesheet, Images, and Client java.</para>
      <para>
<citetitle>
<emphasis role="bold">StandaloneContainer</emphasis>
</citetitle>
</para>
      <para>One which is a context independent eXo Container. It is also used for unit tests.</para>
      <para>
<citetitle>
<emphasis role="bold">Taxonomy</emphasis>
</citetitle>
</para>
      <para>One which is used to sort documents to ease searches when browsing documents online.</para>
      <para>
<citetitle>
<emphasis role="bold">Tree structure</emphasis>
</citetitle>
</para>
      <para>One structure which is defined as a hierarchical structure with a set of linked nodes and properties.</para>
      <para>
<citetitle>
<emphasis role="bold">Type constraint</emphasis>
</citetitle>
</para>
      <para>One which specifies the common primary node type of the returned nodes plus possibly additional mixin types that they also must have. Type constraints are inheritance-sensitive in which specifying a constraint of node type x will include all nodes explicitly declared to be type x and all nodes of subtypes of x (Source: <ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>).</para>
      <para>
<citetitle>
<emphasis role="bold">Web Content</emphasis>
</citetitle>
</para>
      <para>A textual, visual or aural content that is encountered as part of the user experiences on a website. It may include other things, such as texts images, sounds, videos, and animations. </para>
      <para>
<citetitle>
<emphasis role="bold">Workspace</emphasis>
</citetitle>
</para>
      <para>A container of single rooted tree which includes items.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.SetupMavenSettings">Set up Maven settings</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.eXoArchitecturePremer">eXo Architecture Primer</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.SetupMavenSettings">
      <title>Set up Maven settings </title>
      <para>Before setting up a complete project/extension, you need to have knowledge of how to install a Maven project.</para>
      <citetitle>
<para>
<emphasis role="bold">
Requirements
</emphasis>
</para>
</citetitle>
      <itemizedlist>
        <listitem>
          <para>JDK (Java Development Kit) 6.0 </para>
        </listitem>
        <listitem>
          <para>SVN 1.6+</para>
        </listitem>
        <listitem>
          <para>Maven 2.2.1+</para>
        </listitem>
        <listitem>
          <para>Tomcat 6.0.32 or JBoss EAP 5.1.1</para>
        </listitem>
      </itemizedlist>
      <citetitle>
<para>
<emphasis role="bold">
Install and configure Maven
</emphasis>
</para>
</citetitle>
      <para>You need to add a system environment variable <emphasis role="italic">MAVEN_OPTS</emphasis> (it could be in a <emphasis role="italic">.profile</emphasis> startup script on Linux/MacOS operating systems or in the global environment variables panel on Windows).</para>
      <itemizedlist>
        <listitem>
          <para>Windows:</para>
        </listitem>
      </itemizedlist>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[set MAVEN_OPTS=-Xshare:auto -Xms128M -Xmx1G -XX:MaxPermSize=256M]]></programlisting>
      </programlistingco>
      <itemizedlist>
        <listitem>
          <para>Linux/MacOS:</para>
        </listitem>
      </itemizedlist>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[export MAVEN_OPTS="-Xshare:auto -Xms128M -Xmx1G -XX:MaxPermSize=256M"]]></programlisting>
      </programlistingco>
      <citetitle>
<para>
<emphasis role="bold">
Maven settings
</emphasis>
</para>
</citetitle>
      <para>
        <emphasis role="bold">1.</emphasis> Save the <emphasis role="italic">settings.xml</emphasis> file to the <emphasis role="italic">HOME/.m2/settings.xml</emphasis> path.</para>
      <para>
        <emphasis role="bold">2.</emphasis> Edit and change the <emphasis role="italic">local-properties</emphasis> profile, including:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="italic">exo.projects.directory.dependencies</emphasis> contains the application servers, and Openfire.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>each <emphasis role="italic">exo.projects.app.AS-NAME.version</emphasis> contains the name and version of the application servers.</para>
        </listitem>
      </itemizedlist>
      <para>If the <emphasis role="italic">settings.xml</emphasis> file has been existing, you can merge them. You will need the followings:</para>
      <itemizedlist>
        <listitem>
          <para>The <emphasis role="italic">local-properties</emphasis> profile, which defines properties, is used to build application server distributions of our products.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>The <ulink url="http://repository.exoplatform.org/public">repository</ulink> to download our dependencies.</para>
        </listitem>
      </itemizedlist>
      <note>
        <para>In Linux environments, the ulimit limits the system-wide resource used. When running eXo Platform, you may get the error message about "Too many open files" because the ulimit had limited the opened files. By default, the number of open files is limited to "1024". You should execute the command "ulimit -n 8196" as root before starting the server to avoid this issue.</para>
      </note>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.Glossary">Glossary</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.eXoArchitecturePremer">eXo Architecture Primer</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.eXoArchitecturePremer">
      <title>eXo Architecture Primer </title>
      <highlights>
	<itemizedlist>
		<listitem>
		  <para>
			<link linkend="DEV.eXoArchitecturePremer.Kernel">Kernel</link>
		  </para>
		  <para>
			All eXo Platform services are built around the eXo Kernel, or the service management layer, which manages the configuration and the execution of all components. The main Kernel object is the eXo Container, a micro-container that glues services together through the dependency injection. The container is responsible for loading services/components.
		  </para>
		</listitem>
		<listitem>
		  <para>
			<link linkend="DEV.eXoArchitecturePremer.GateInExtensions">GateIn extensions</link>
		  </para>
		  <para>
		  Special <emphasis>.war</emphasis> files that are recognized by eXo Platform and contribute to custom configurations to the PortalContainer. To create your own portal, you will have to create a GateIn extension.
          </para>
		</listitem>
		<listitem>
		  <para>
			<link linkend="DEV.eXoArchitecturePremer.JavaContentRepository">Java Content Repository</link>
		  </para>
	      <para>
		  A repository which is tailored to the storage, searching, and retrieval of hierarchical data. All data of eXo Platform are stored in a Java Content Repository (JCR).
		  </para>
		</listitem>
	</itemizedlist>
</highlights>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.Glossary">Glossary</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SetupMavenSettings">Set up Maven settings</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.eXoArchitecturePremer.Kernel" role="NotInToc">
        <title>Kernel </title>
        <para>All eXo Platform services are built around the eXo Kernel, or the service management layer, which manages the configuration and the execution of all components. The main kernel object is the eXo Container, a micro-container that glues services together through the dependency injection. The container is responsible for loading services/components.</para>
        <section id="DEV.eXoArchitecturePremer.Containers">
          <title>Containers </title>
          <para>A container is always required to access a service, because the eXo Kernel relies on the dependency injection. This means that the lifecycle of a service (for example, instantiating, opening and closing streams, disposing) is handled by a dependency provider, such as the eXo Container, rather than the consumer. The consumer only needs a reference to an implementation of the requested service. The implementation is configured in an <emphasis role="italic">.xml</emphasis> configuration file that comes with every service. To learn more about the dependency injection, visit <ulink url="http://en.wikipedia.org/wiki/Dependency_injection">here</ulink>.</para>
          <para>eXo Platform provides two types of containers: RootContainer and PortalContainer.</para>
          <para>The <emphasis role="italic">RootContainer</emphasis> holds the low level components. It is automatically started before the <emphasis role="italic">PortalContainer</emphasis>. You will rarely interact directly with the <emphasis role="italic">RootContainer</emphasis> except when you activate your own extension. The <emphasis role="italic">PortalContainer</emphasis> is created for each portal (one or several portals). All services started by this container will run as embedded in the portal. It also gives access to components of its parent <emphasis role="italic">RootContainer</emphasis>.</para>
          <para>In your code, if you need to invoke a service of a container, you can use the <emphasis role="italic">ExoContainerContext</emphasis> helper from any location. The code below shows you a utility method that you can use to invoke any eXo Platform services.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[public class ExoUtils {
  /**
  * Get a service from the portal container
  * @param type : component type
  * @return the concrete instance retrieved in the container using the type as key
  */
  public <T>T getService(Class<T> type) {
    return (T)ExoContainerContext.getCurrentContainer().getComponentInstanceOfType(type);
  }
}]]></programlisting>
          </programlistingco>
          <para>Then, invoking becomes as easy as:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[OrganizationService orgService = ExoUtils.getService(OrganizationService.class)]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.eXoArchitecturePremer.Services">
          <title>Services </title>
          <para>Containers are used to gain access to services. The followings are important characteristics of services:</para>
          <itemizedlist>
            <listitem>
              <para>Because of the Dependency Injection concept, the interface and implementation for a service are usually separate.</para>
            </listitem>
            <listitem>
              <para>Each service has to be implemented as a singleton, which means it is created only once per portal container in a single instance.</para>
            </listitem>
            <listitem>
              <para>A component equals a service. A service must not be a large application. A service can be a little component that reads or transforms a document where the term "component" is often used instead of service.</para>
            </listitem>
          </itemizedlist>
          <para>For example, in the <emphasis role="italic">/lib</emphasis> folder, you can find services for the following databases, caching, and LDAP:</para>
          <itemizedlist>
            <listitem>
              <para>exo.core.component.database-x.y.z.jar</para>
            </listitem>
            <listitem>
              <para>exo.kernel.component.cache-x.y.z.jar</para>
            </listitem>
            <listitem>
              <para>exo.core.component.organization.ldap-x.y.z.jar</para>
            </listitem>
          </itemizedlist>
          <para>
            <anchor id="DEV.eXoArchitecturePremer.ServiceConfiguration"/>
          </para>
          <para>To declare a service, you must add the <emphasis role="bold">.xml</emphasis> configuration file to a specific place. This file can be in the jar file, in a webapp or in the external configuration directory. If you write a new component for the eXo Container, you should always provide a default configuration in your jar file. This default configuration must be in the <emphasis role="italic">/conf/portal/configuration.xml</emphasis> file in your jar.</para>
          <para>A configuration file can specify several services, so there can be several services in one jar file.</para>
          <para>The service configuration is performed in:</para>
          <itemizedlist>
            <listitem>
              <para>
                <link linkend="DEV.eXoArchitecturePremer.KernalXMLSchema">Kernel XML Schema</link>
              </para>
            </listitem>
            <listitem>
              <para>
                <link linkend="DEV.eXoArchitecturePremer.Components">Components</link>
              </para>
            </listitem>
            <listitem>
              <para>
                <link linkend="DEV.eXoArchitecturePremer.Parameters">Parameters</link>
              </para>
            </listitem>
          </itemizedlist>
          <para xml:id="DEV.eXoArchitecturePremer.KernalXMLSchema">
<citetitle>
<emphasis role="bold">Kernel XML Schema</emphasis>
</citetitle>
</para>
          <para>The containers configuration files must comply with the kernel configuration grammar. Thus, all configurations will contain an XSD declaration like this:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<configuration xmlns="http://www.exoplatform.org/xml/ns/kernel_1_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_1.xsd http://www.exoplatform.org/xml/ns/kernel_1_1.xsd">
</configuration>]]></programlisting>
          </programlistingco>
          <para>The <emphasis role="italic">kernel_1_1.xsd</emphasis> file mentioned in the example above can be found inside <code>exo.kernel.container-x.y.z.jar!org/exoplatform/container/configuration/</code> along with other versions.</para>
          <para xml:id="DEV.eXoArchitecturePremer.Components">
<citetitle>
<emphasis role="bold">Components</emphasis>
</citetitle>
</para>
          <para>The service registration within the container is done with the <emphasis role="italic">&lt;component&gt;</emphasis> element.</para>
          <para>For example, open the <emphasis role="italic">/webapps/exo-wcm-core/WEB-INF/conf/wcm-core/core-services-configuration.xml</emphasis> file. You will see the following code:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<component>
   <key>org.exoplatform.services.cms.CmsService</key>
   <type>org.exoplatform.services.cms.impl.CmsServiceImpl</type>
</component>]]></programlisting>
          </programlistingco>
          <para>Each component has a <emphasis role="italic">key</emphasis> which matches with the qualified Java interface name (<emphasis role="italic">org.exoplatform.services.cms.CmsService</emphasis>).</para>
          <para>The specific implementation class of the component (CmsServiceImpl) is defined in the &lt;type&gt; tag.</para>
          <para>If a service does not have a separate interface, the &lt;type&gt; will be used as the key in the container. This is the case of <emphasis role="italic">ContentInitializerService</emphasis>.</para>
          <para xml:id="DEV.eXoArchitecturePremer.Parameters">
<citetitle>
<emphasis role="bold">Parameters</emphasis>
</citetitle>
</para>
          <para>You can provide initial parameters for your service by defining them in the configuration file.</para>
          <para>
            <anchor id="DEV.eXoArchitecturePremer.Value-param"/>
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Value-param:</emphasis> You can use the value-param to pass a single value to the service.</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.services.resources.LocaleConfigService</key>
  <type>org.exoplatform.services.resources.impl.LocaleConfigServiceImpl</type>
  <init-params>
    <value-param>
      <name>locale.config.file</name>
      <value>war:/conf/common/locales-config.xml</value>
    </value-param>
  </init-params>
</component>]]></programlisting>
          </programlistingco>
          <para>The <emphasis role="italic">LocaleConfigService</emphasis> service accesses the value of value-param in its constructor.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[package org.exoplatform.services.resources.impl;
public class LocaleConfigServiceImpl implements LocaleConfigService {
  public LocaleConfigServiceImpl(InitParams params, ConfigurationManager cmanager) throws Exception {
    configs_ = new HashMap<String, LocaleConfig>(10);
    String confResource = params.getValueParam("locale.config.file").getValue();
    InputStream is = cmanager.getInputStream(confResource);
    parseConfiguration(is);
  }
}]]></programlisting>
          </programlistingco>
          <para>
            <anchor id="DEV.eXoArchitecturePremer.Object-param"/>
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Object-param:</emphasis> For the object-param component, you can look at the LDAP service:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.services.ldap.LDAPService</key>
  <type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
  <init-params>
    <object-param>
      <name>ldap.config</name>
      <description>Default ldap config</description>
      <object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
        <field name="providerURL"><string>ldaps://10.0.0.3:636</string></field>
        <field name="rootdn"><string>CN=Administrator,CN=Users,DC=exoplatform,DC=org</string></field>
        <field name="password"><string>exo</string></field>
        <field name="version"><string>3</string></field>
        <field name="minConnection"><int>5</int></field>
        <field name="maxConnection"><int>10</int></field>
        <field name="referralMode"><string>ignore</string></field>
        <field name="serverName"><string>active.directory</string></field>
      </object>
    </object-param>
  </init-params>
</component>]]></programlisting>
          </programlistingco>
          <para>The object-param is used to create an object (which is actually a Java Bean) passed as a parameter to the service. This object-param is defined by a name, a description and exactly one object. The object tag defines the type of the object, while the field tags define parameters for that object.</para>
          <para>You can see how the service accesses the object in the code below:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[package org.exoplatform.services.ldap.impl;

public class LDAPServiceImpl implements LDAPService {
  // ...
  public LDAPServiceImpl(InitParams params) {
    LDAPConnectionConfig config = (LDAPConnectionConfig) params.getObjectParam("ldap.config").getObject();
    ...
  }
  // ...
}]]></programlisting>
          </programlistingco>
          <para>The passed object is <emphasis role="italic">LDAPConnectionConfig</emphasis>, which is a classic Java Bean. It contains all fields defined in the configuration files and also the appropriate getters and setters (not listed here). You also can provide default values. The container creates a new instance of your Java Bean and calls all setters whose values are configured in the configuration file.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[package org.exoplatform.services.ldap.impl;

public class LDAPConnectionConfig {
  private String providerURL = "ldap://127.0.0.1:389";
  private String rootdn;
  private String password;
  private String version;
  private String authenticationType = "simple";
  private String serverName = "default";
  private int minConnection;
  private int maxConnection;
  private String referralMode = "follow";
  // ...
}]]></programlisting>
          </programlistingco>
          <para>
            <anchor id="DEV.eXoArchitecturePremer.RestOfParameterTypes"/>
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Rest of parameter types:</emphasis> Other possible parameter types are Collection, Map and Native Array. See the exhaustive reference in the Kernel reference guide.</para>
            </listitem>
          </itemizedlist>
        </section>
        <section id="DEV.eXoArchitecturePremer.Plugins">
          <title>Plugins </title>
          <para>Some components may want to offer some extensibilities. For this, they use a plugin mechanism based on the injection method. To offer an extension point for plugins, a component needs to provide a public method that takes an instance of <emphasis role="italic">org.exoplatform.container.xml. ComponentPlugin</emphasis> as a parameter.</para>
          <para>Plugins enable you to provide the structured configuration outside the original declaration of the component. This is the main way to customize eXo Platform to your needs.</para>
          <para>You can have a look at the configuration of the TaxonomyPlugin of the TaxonomyService as below:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<external-component-plugins>
  <target-component>org.exoplatform.services.cms.taxonomy.TaxonomyService</target-component>
  <component-plugin>
    <name>predefinedTaxonomyPlugin</name>
    <set-method>addTaxonomyPlugin</set-method>
    <type>org.exoplatform.services.cms.taxonomy.impl.TaxonomyPlugin</type>
    <init-params><!-- ... --></init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
          </programlistingco>
          <para>The &lt;target-component&gt; defines components that host the extension point. The configuration is injected by the container using the method defined in &lt;set-method&gt; (addTaxonomyPlugin(). The method accepts exactly one argument of the <emphasis role="italic">org.exoplatform.services. cms.categories.impl.TaxonomyPlugin</emphasis> type.</para>
          <para>The content of &lt;init-params&gt; is interpreted by the TaxonomyPlugin object.</para>
        </section>
        <section id="DEV.eXoArchitecturePremer.ConfigureLoadingSequence">
          <title>Configuration loading sequence </title>
          <para>The Kernel startup follows a well-defined sequence to load configuration files. The objects are initialized in the container only after the whole loading sequence is done. Hence, by placing your configuration in the upper location of the sequence, you can override a component declaration by yourself. You will typically do this when you want to provide your own implementation of a component, or declare custom init-params.</para>
          <note>
            <para>The <emphasis role="italic">external-component-plugins</emphasis> declarations are additive, so it is NOT possible to override them.</para>
          </note>
          <para>Configurations for the <emphasis role="italic">RootContainer</emphasis> are loaded first, and then for the <emphasis role="italic">PortalContainers</emphasis>.</para>
          <itemizedlist>
            <listitem>
              <para>Services default RootContainer configurations from JAR files: <emphasis role="italic">/conf/configuration.xml</emphasis>.</para>
            </listitem>
            <listitem>
              <para>External RootContainer configuration will be found at <emphasis role="italic">$exo.conf.dir/configuration.xml</emphasis>.</para>
            </listitem>
            <listitem>
              <para>Services default PortalContainer configurations from JAR files: <emphasis role="italic">/conf/$PORTAL/configuration.xml</emphasis>.</para>
            </listitem>
            <listitem>
              <para>Web applications configurations from WAR files <emphasis role="italic">/WEB-INF/conf/configuration.xml</emphasis>.</para>
            </listitem>
            <listitem>
              <para>External configuration for services of the portal will be found at <emphasis role="italic">$exo.conf.dir/portal/$PORTAL/configuration.xml</emphasis>.</para>
            </listitem>
          </itemizedlist>
          <note>
            <itemizedlist>
              <listitem>
                <para>
                  <emphasis role="italic">$exo.conf.dir</emphasis> is a system property which points to the folder containing external configuration files on the file system. It is passed to the JVM in the startup script like <emphasis role="italic">-Dexo.conf.dir=gatein</emphasis>.</para>
              </listitem>
              <listitem>
                <para>
                  <emphasis role="italic">$PORTAL</emphasis> is the name of the portal container. By default, the name "portal" is unique.</para>
              </listitem>
            </itemizedlist>
          </note>
        </section>
      </section>
      <section id="DEV.eXoArchitecturePremer.GateInExtensions" role="NotInToc">
        <title>GateIn extensions </title>
        <para>GateIn extensions are special <emphasis role="italic">.war</emphasis> files that are recognized by eXo Platform and contribute to custom configurations to the PortalContainer. To create your own portal, you will have to create a GateIn extension.</para>
        <para>The extension mechanism makes possible to extend or even override portal resources in almost plug-and-play way. You simply add a <emphasis role="italic">.war</emphasis> archive with your custom resources to the war folder and edit the configuration of the PortalContainerConfig service. Customizing a portal does not involve unpacking and repacking the original portal <emphasis role="italic">.war</emphasis> archives. Instead, you need to create your own <emphasis role="italic">.war</emphasis> archive with your own configurations, and modify resources. The content of your custom <emphasis role="italic">.war</emphasis> archive overrides the resources in the original archives.</para>
        <para>The most elegant way to reuse configuration for different coexisting portals is by way of extension mechanism. That is, you can inherit resources and configurations from existing web archives, then simply add extra resources and configurations to your extension, and override ones which need to be changed by including modified copies.</para>
        <note>
          <para>Starter is a web application which has been added to create and start all the portal containers once all the other web applications have already been started. Generally, each web application of a portal container defines several things, such as skins, JavaScripts, Google gadgets and configuration files, at its startup, so the loading order is important. For example, at startup of the web application 1, skins or configuration files or JavaScripts are defined that could depend on another JavaScript from the web application 2. Thus, if the web application 2 is loaded after the web application 1, you will get errors in the merged JavaScript file.</para>
        </note>
        <para>If you ship servlets or servlet filters as part of your portal extension, and these servlets/servlet filters need to access specific resources of a portal during the process of the servlets or filters request, make sure that these servlets/filters are associated with the current portal container. The proper way to do that is making your servlet extend the <emphasis role="italic">org.exoplatform.container.web.AbstractHttpServlet</emphasis> class. This will not only properly initialize the current <emphasis role="italic">PortalContainer</emphasis> for you, but also set the current thread's context ClassLoader to servlets or servlet filters which looks for resources in associated web applications in the order specified by dependencies configuration.</para>
        <para>As similar to filters, make  sure that your filter class extends <emphasis role="italic">org.exoplatform.container.web.AbstractFilter</emphasis>. Both <emphasis role="italic">AbstractHttpServlet</emphasis> and <emphasis role="italic">AbstractFilter</emphasis> have the method named <emphasis role="italic">getContainer()</emphasis>, which returns the current <emphasis role="italic">PortalContainer</emphasis>.</para>
        <para xml:id="DEV.eXoArchitecturePremer.defaultPortalContainer">
<citetitle>
<emphasis role="bold">Default Portal Container</emphasis>
</citetitle>
</para>
        <para>eXo Platform comes with a pre-configured PortalContainer named "portal". The configuration of this portal container ties the core and the extended services stack. The default Portal Container is started from <emphasis role="italic">portal.war</emphasis> and naturally maps to the <emphasis role="italic">/portal</emphasis> URL.</para>
        <para>The GateIn extension mechanism lets you extend the portal context easily. With this feature, you only need to make your desired modifications on your extension, but NOT on the <emphasis role="italic">portal.war</emphasis>. As a result, your upgrades will become simple as your <emphasis role="italic">extension.war</emphasis> is totally independent of the <emphasis role="italic">portal.war</emphasis>.</para>
        <para>This extensibility is achieved via 2 advanced features of the <emphasis role="italic">PortalContainer</emphasis>:</para>
        <itemizedlist>
          <listitem>
            <para>A unified ClassLoader: any classpath resource, such as property files, will be accessible as if it was inside the <emphasis role="italic">portal.war</emphasis>.</para>
          </listitem>
        </itemizedlist>
        <note>
          <para>This is valid only for resources but not for Java classes.</para>
        </note>
        <itemizedlist>
          <listitem>
            <para>A unified ServletContext: any web resources contained in your <emphasis role="italic">extension.war</emphasis> will be accessible from /portal/ uri.</para>
          </listitem>
        </itemizedlist>
        <tip>
          <para>For more details on how to make a simple extension for a "portal" container, see the <link linkend="DEV.eXoArchitecturePremer.RegisterExtension">Register Extension</link> section.</para>
        </tip>
        <para xml:id="DEV.eXoArchitecturePremer.RegisterExtension">
<citetitle>
<emphasis role="bold">Register Extension</emphasis>
</citetitle>
</para>
        <para>The webapps are loaded in the order defined in the list of dependencies of the <emphasis role="italic">PortalContainerDefinition</emphasis>. You then need to deploy the <emphasis role="italic">starter.war</emphasis>; otherwise, the webapps will be loaded in the default application server's order, such as the loading order of the Application Server.</para>
        <para>If you need to customize your portal by adding a new extension and/or a new portal, you need to define the related <emphasis role="italic">PortalContainerDefinitions</emphasis> and to deploy the starter. Otherwise, you do not need to define any <emphasis role="italic">PortalContainerDefinition</emphasis>.</para>
        <para>First, you need to tell eXo Platform to load <emphasis role="italic">WEB-INF/conf/configuration.xml</emphasis> of your extension, you need to declare it as a <emphasis role="italic">PortalContainerConfigOwner</emphasis>. Next, open the file <emphasis role="italic">WEB-INF/web.xml</emphasis> of your extension and add a listener:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<web-app>
  <display-name>my-portal</display-name>
    <listener>
      <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
    </listener>
  <!-- ... -->
</web-app>]]></programlisting>
        </programlistingco>
        <para>You need to register your extension in the portal container. This is done by the <emphasis role="bold">.xml</emphasis> configuration file like this: </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<external-component-plugins>
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <name>Change PortalContainer Definitions</name>
    <set-method>registerChangePlugin</set-method>
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
        <field name="dependencies">
          <collection type="java.util.ArrayList">
            <value>
              <string>my-portal</string>
            </value>
            <value>
              <string>my-portal-resources</string>
            </value>              
          </collection>
        </field>
        </object>
      </object-param> 
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>       
    </init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
        </programlistingco>
        <para>A <emphasis role="italic">PortalContainerDefinitionChangePlugin</emphasis> plugin is defined to the <emphasis role="italic">PortalContainerConfig</emphasis>. The plugin declares a list of dependencies that are webapps. The <emphasis role="italic">apply.default=true</emphasis> indicates that your extension is actually extending <emphasis role="italic">portal.war</emphasis>. You  need to package your extension into a <emphasis role="bold">.war</emphasis> file and put it to the tomcat webapps folder, then restart the server.</para>
        <para>In your portal, if you want to add your own property file to support localization for your keys, you can do as follows:</para>
        <itemizedlist>
          <listitem>
            <para>Put your property file into the <emphasis role="italic">/WEB-INF/classes/locale/portal</emphasis> folder of your extension project.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>Add an external plugin declaration to the <emphasis role="italic">.xml</emphasis> configuration file.   </para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<external-component-plugins>
  <!-- The full qualified name of the ResourceBundleService -->
  <target-component>org.exoplatform.services.resources.ResourceBundleService</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Sample ResourceBundle Plugin</name>
    <!-- The name of the method to call on the ResourceBundleService in order to register the ResourceBundles -->
    <set-method>addResourceBundle</set-method>
    <!-- The full qualified name of the BaseResourceBundlePlugin -->
    <type>org.exoplatform.services.resources.impl.BaseResourceBundlePlugin</type>
    <init-params>
      <!--values-param>
        <name>classpath.resources</name>
        <description>The resources that start with the following package name should be load from file system</description>
        <value>locale.portlet</value>
      </values-param-->
      <values-param>
        <name>init.resources</name>
        <description>Store the following resources into the db for the first launch </description>
        <value>locale.portal.sample</value>
      </values-param>
      <values-param>
        <name>portal.resource.names</name>
        <description>The properties files of the portal , those file will be merged
        into one ResoruceBundle properties </description>
        <value>locale.portal.sample</value>
      </values-param>
    </init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
        </programlistingco>
      </section>
      <section id="DEV.eXoArchitecturePremer.JavaContentRepository" role="NotInToc">
        <title>Java Content Repository </title>
        <para>All data of eXo Platform are stored in a Java Content Repository (JCR). JCR is the Java specification (<ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>) for a type of Object Database tailored to the storage, searching, and retrieval of hierarchical data. It is useful for the content management systems, which require storage of objects associated with metadata. The JCR also provides versioning, transactions, observations of changes in data, and import or export of data in XML. The data in JCR are stored hierarchically in a tree of nodes with associated properties.</para>
        <para>Also, the JCR is primarily used as an internal storage engine. Accordingly, <emphasis role="bold">Content</emphasis> lets you manipulate JCR data directly in several places. </para>
        <para>In Java Content Repository, there are 2 main parts:</para>
        <para>
          <anchor id="DEV.eXoArchitecturePremer.RepositoriesAndWorkspaces"/>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Repositories and workspaces:</emphasis> A content repository consists of one or more workspaces. Each workspace contains a tree of items.</para>
          </listitem>
        </itemizedlist>
        <para>
          <anchor id="DEV.eXoArchitecturePremer.WorkingWithNodesAndProperties"/>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Tree structure - nodes and properties:</emphasis> Every node can only have one primary node type. The primary node type defines names, types and other characteristics of the properties, and the number of its allowed child nodes. Every node has a special property called <emphasis role="italic">jcr:primaryType</emphasis> that records the name of its primary node type. A node may also have one or more mixin types. These are node type definitions that can mandate extra characteristics (for example, more child nodes, properties and their respective names and types).</para>
            <itemizedlist>
              <listitem>
                <para>Data are stored in properties, which may hold simple values, such as numbers, strings or binary data of arbitrary length.</para>
              </listitem>
              <listitem>
                <para>The JCR API provides methods to define node types and node properties, create or delete nodes, and add or delete properties from an existing node. You can refer to the "6.2.3 Node Read Methods" in the JCR Specification document.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <para>
<citetitle>
<emphasis role="bold">
Access the repository's content from a service
</emphasis>
</citetitle>
</para>
        <para>
          <emphasis role="bold">1.</emphasis> Get the session object.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[import javax.jcr.Session;

import org.exoplatform.services.jcr.RepositoryService;
import org.exoplatform.services.jcr.core.ManageableRepository;
import org.exoplatform.services.jcr.ext.common.SessionProvider;
import org.exoplatform.services.wcm.utils.WCMCoreUtils;

// For example
RepositoryService repositoryService = WCMCoreUtils.getService(RepositoryService.class);
ManageableRepository manageableRepository = repositoryService.getRepository(repository);
SessionProvider sessionProvider = WCMCoreUtils.getSessionProvider();
Session session = sessionProvider.getSession(workspace, manageableRepository);]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">i.</emphasis> Obtain the <emphasis role="italic">javax.jcr.Repository</emphasis> object via one of the following ways:</para>
        <para>
          <emphasis role="bold">The first way</emphasis>
        </para>
        <para>Call the <emphasis role="italic">getRepository()</emphasis> method of <emphasis role="italic">RepositoryService</emphasis>.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class);
Repository repository = repositoryService.getRepository("repositoryName");]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">The second way</emphasis>
        </para>
        <para>Call the <emphasis role="italic">getCurrentRepository()</emphasis> method, especially when you plan to use a single repository which covers more than 90% of usecases.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[// set current repository at initial time
RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class);
repositoryService.setCurrentRepositoryName("repositoryName");
....
// retrieve and use this  repository
Repository repository = repositoryService.getCurrentRepository();]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">The third way</emphasis>
        </para>
        <para>Using JNDI as specified in <ulink url="http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html">JSR-170</ulink>.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[Context ctx = new InitialContext();
Repository repository =(Repository) ctx.lookup("repositoryName");]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">ii.</emphasis> Log in the server to get a Session object by either of two ways:</para>
        <para>
          <emphasis role="bold">The first way</emphasis>
        </para>
        <para>Create a Credential object, for example:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[Credentials credentials = new SimpleCredentials("exo", "exo".toCharArray());

Session jcrSession = repository.login(credentials, "production");]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">The second way</emphasis>
        </para>
        <para>Log in the server without using a Credential object.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[Session jcrSession = repository.login("production");]]></programlisting>
        </programlistingco>
        <para>This way is only applied when you run an implementation of eXo Platform. The eXo Platform implementation will directly leverage the organization and security services that rely on LDAP or DB storage and JAAS login modules. Single-Sign-On products can now also be used as eXo Platform v.2 which supports them.</para>
        <note>
          <para>There are some JCR Session common considerations as follows:</para>
          <para>Because <emphasis role="italic">javax.jcr.Session</emphasis> is not a safe object of thread, it is recommended that you should not share it between threads.</para>
          <para>Do not use the System session from the user-related code because a system session has unlimited rights. Call <emphasis role="italic">ManageableRepository.getSystemSession()</emphasis> from the process-related code only.</para>
          <para>Call <emphasis role="italic">Session.logout()</emphasis> explicitly to release resources assigned to the session.</para>
          <para>When designing your application, you should take care of the Session policy inside your application. Two strategies are possible: Stateless (Session per business request) and Stateful (Session per User) or some mixings.</para>
        </note>
        <para>
          <emphasis role="bold">2.</emphasis> Retrieve your node content of the session object.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String path = "/"; // put your node path here

Node node = (Node) session.getItem(path);]]></programlisting>
        </programlistingco>
      </section>
    </section>
  </chapter>
  <chapter id="DEV.CreatingYourOwnPortal">
    <title>Create Your Own Portal </title>
    <abstract>
<para>When working with eXo Platform, it is important not to modify the source code. This will ensure compatibility with future upgrades, and support will be simplified. To customize your portal, you need to create an extension project by providing your own artifacts as a set of wars/jars/ears.</para>
<para>This chapter will show you how to create a portal via the following topics:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
            </emphasis>
	</para>
	<para>
	 Steps to deploy an extension project.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
            </emphasis>
	</para>
	<para>
	Required steps on how to configure a default portal.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
            </emphasis>
	</para>
	<para>
	Steps on how to define the structure throughout the portal navigation and visibility of pages.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
            </emphasis>
	</para>
	<para>
 	Ways to use parameters which allow developers to specify if a drive is automatically created or not.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
            </emphasis>
	</para>
	<para>
	Steps on how to define or remove a specific language through the locale configuration file.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
            </emphasis>
	</para>
	<para>
	Elements and various topics on how to create/customize a skin.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
            </emphasis>
	</para>
	<para>
	Instructions on how to add a JavaScript library.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
            </emphasis>
	</para>
	<para>
	How to create a custom page template for <emphasis role="bold">Page Creation Wizard</emphasis>.
	</para>
  </listitem>
</itemizedlist>
</abstract>
    <section id="DEV.CreateYourOwnPortal.CreateExtensionProject">
      <title>Create your extension project </title>
      <para>A custom extension contains two mandatory items:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">extension webapp</emphasis> contains resources and kernel configurations.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">extension activator jar</emphasis> identifies your webapp as a dependency of the portal container.</para>
        </listitem>
      </itemizedlist>
      <para>To see the sample extension package, visit <ulink url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/examples/extension/">here</ulink>.</para>
      <para>Once you have modified the sample extension to build your own portal, use the <emphasis role="italic">maven clean install</emphasis> command to create the archive files.</para>
      <para>
<citetitle>
<emphasis role="bold">
Deploy your extension in Tomcat
</emphasis>
</citetitle>
</para>
      <para>
        <emphasis role="bold">1.</emphasis> Add the <emphasis role="italic">sample-ext.war</emphasis> file from the <emphasis role="italic">sample/extension/war/target</emphasis>/ to the <emphasis role="italic">tomcat/webapps</emphasis> directory.</para>
      <para>
        <emphasis role="bold">2.</emphasis> Add the <emphasis role="italic">starter</emphasis> folder from <emphasis role="italic">starter/war/target</emphasis>/ to the <emphasis role="italic">tomcat/webapps</emphasis> directory.</para>
      <para>
        <emphasis role="bold">3.</emphasis> Rename the <emphasis role="italic">starter</emphasis> directory (unzipped folder) to <emphasis role="italic">starter.war</emphasis>.</para>
      <note>
        <para>This will only work if the starter.war is the last .war file to be loaded, so you may need to rename it if your war files are loaded in the alphabetical order.</para>
      </note>
      <para>
        <emphasis role="bold">4.</emphasis> Add the .jar file named <emphasis role="italic">exo.portal.sample.extension.config-X.Y.Z.jar</emphasis> from <emphasis role="italic">sample/extension/config/target</emphasis>/ to the <emphasis role="italic">tomcat/lib</emphasis> directory.</para>
      <para>
        <emphasis role="bold">5.</emphasis> Add the .jar file named <emphasis role="italic">exo.portal.sample.extension.jar-X.Y.Z.jar</emphasis> from <emphasis role="italic">sample/extension/jar/target</emphasis>/ to the <emphasis role="italic">tomcat/lib</emphasis> directory.</para>
      <para>
        <emphasis role="bold">6.</emphasis> Create a sample-ext.xml file (this file is <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html#A_word_on_Contexts">a Context Descriptor</ulink> to configure a context within Tomcat server and to ensure that the extension gets loaded before the starter.war). Then add this file to the <emphasis role="italic">tomcat/conf/Catalina/localhost</emphasis> directory with the following content.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<Context crossContext="true" debug="0" docBase="sample-ext" path="/sample-ext" reloadable="true"/>]]></programlisting>
      </programlistingco>
      <para>For the JBoss deployment with more details, refer to the <ulink url="../../../reference/html/GateInReferenceGuide.html">GateIn Reference Guide</ulink>.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.CreateYourOwnPortal.Create_default_portal">
      <title>Define a default portal </title>
      <para>When entering the link of the portal in the address bar of the browser without defining a specific portal (e.g. <emphasis role="italic">localhost:8080/portal</emphasis>/), you will be directed to a default portal.</para>
      <para>To configure the default portal, the portal must already exist first. Then, you just use the <emphasis role="italic">NewPortalConfigListener</emphasis> plugin as the sample code below.</para>
      <para>To use this plugin in the component configuration, you must use the following target-component:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<target-component>org.exoplatform.portal.config.UserPortalConfigService</target-component>]]></programlisting>
      </programlistingco>
      <para>The sample code below is the configuration of the portal named "<emphasis role="italic">default</emphasis>".</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<external-component-plugins>
		<target-component>org.exoplatform.portal.config.UserPortalConfigService</target-component>
		<component-plugin>
			<name>default.portal.config.user.listener</name>
			<set-method>initListener</set-method>
			<type>org.exoplatform.portal.config.NewPortalConfigListener</type>
			<description>this listener init the portal configuration</description>
			<init-params>
				<value-param>
					<name>default.portal</name>
					<description>The default portal for checking db is empty or not</description>
					<value>default</value>
				</value-param>
				<object-param>
					....
				</object-param>
			</init-params>
		</component-plugin>
</external-component-plugins>]]></programlisting>
      </programlistingco>
      <para>
        <emphasis role="bold">Init-param</emphasis>
      </para>
      <informaltable>
        <thead>
          <tr>
            <th>Name</th>
            <th>Type</th>
            <th>Value</th>
            <th> Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>default.portal</td>
            <td>String</td>
            <td>default</td>
            <td> The name of the default portal to which you are redirected when accessing the portal.</td>
          </tr>
        </tbody>
      </informaltable>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation during the portal creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">
      <title>Structure of portal, pages and menus </title>
      <para>You can create multiple pages within a single portal. Permissions can be defined to make them visible only to specific groups and/or users.</para>
      <para xml:id="DEV.CreateYourOwnPortal.PageLayout">
<citetitle>
<emphasis role="bold">Portal navigation</emphasis>
</citetitle>
</para>
      <para>The portal navigation incorporates the pages that can be accessed even when the user is not logged in assuming the applicable permissions allow the public access). For example, several portal navigations are used when a company owns multiple trademarks, and sets up a website for each of them.</para>
      <para>The configuration of the "classic" portal can be found in the <emphasis role="italic">/src/main/WEB-INF/conf/portal/portal/classic</emphasis> directory of your extension webapp.</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">portal.xml</emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <para>The <emphasis role="italic">portal.xml</emphasis> file describes the layout and portlets that will be shown on all pages. The layout usually contains the banner, footer, menu and breadcrumbs portlets. eXo Platform 3.5 is extremely configurable as every view element (even the banner and footer) is a portlet.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<portal-config xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0">
   <portal-name>classic</portal-name>
   <locale>en</locale>
   <access-permissions>Everyone</access-permissions>
   <edit-permission>*:/platform/administrators</edit-permission>
   <properties>
      <entry key="sessionAlive">onDemand</entry>
      <entry key="showPortletInfo">1</entry>
   </properties>

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

      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>NavigationPortlet</portlet-ref>
         </portlet>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>

      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>BreadcumbsPortlet</portlet-ref>
         </portlet>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>

      <page-body> </page-body>

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

   </portal-layout>

</portal-config>]]></programlisting>
      </programlistingco>
      <para>Each portlet can be configured with a set of preferences, which will be further detailed in the <link linkend="DEV.WorkingwithApplications">Work With Applications</link> chapter.</para>
      <para>It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible for the layout of their child portlets.</para>
      <para>The &lt;page-body&gt; &lt;/page-body&gt; tag is a placeholder for the different pages of your portal, it defines where Platform should render the current page. When the user opens a new portal page, all portlets of the portal layout (<emphasis role="italic">portal.xml</emphasis>) are remained, whereas the content of &lt;page-body&gt; switches to the page opened by the user.</para>
      <para>The defined "classic" portal is accessible to "Everyone" (at <emphasis role="italic">/portal/classic</emphasis>) but only members of the group <emphasis role="italic">/platform/administrators</emphasis> can edit it.</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">pages.xml</emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <para>The structure of the <emphasis role="italic">pages.xml</emphasis> configuration file is very similar to that in the <emphasis role="italic">portal.xml</emphasis> of the "classic" portal and it can also contain container tags. Each application can decide whether to render the portlet border, the window state, the icons or portlet's mode.</para>
      <para>This is the example of the <emphasis role="italic">pages.xml</emphasis> file of the "classic" portal.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<page-set xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0">

   <page>
      <name>homepage</name>
      <title>Home Page</title>
      <access-permissions>Everyone</access-permissions>
      <edit-permission>*:/platform/administrators</edit-permission>
      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>HomePagePortlet</portlet-ref>
            <preferences>
               <preference>
                  <name>template</name>
                  <value>system:/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</value>
                  <read-only>false</read-only>
               </preference>
            </preferences>
         </portlet>
         <title>Home Page portlet</title>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
         <show-application-state>false</show-application-state>
         <show-application-mode>false</show-application-mode>
      </portlet-application>
   </page>

   <page>
      <name>sitemap</name>
      <title>Site Map</title>
      <access-permissions>Everyone</access-permissions>
      <edit-permission>*:/platform/administrators</edit-permission>
      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>SiteMapPortlet</portlet-ref>
         </portlet>
         <title>SiteMap</title>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>
   </page>
   .......
</page-set>]]></programlisting>
      </programlistingco>
      <note>
        <para>See the <link linkend="DEV.WorkingwithApplications">Work With Applications</link> chapter to learn more about the portlet configuration within the <emphasis role="italic">pages.xml</emphasis> file.</para>
      </note>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">navigation.xml</emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <para>The <emphasis role="italic">navigation.xml</emphasis> file defines all the navigation nodes of the portal. The syntax is simply using the nested node tags. Each node refers to a page defined in the <emphasis role="italic">pages.xml</emphasis> file that will be explained later.</para>
      <para>If the administrator wants to create node labels for each language, he will have to use <emphasis role="italic">xml:lang</emphasis> attribute in the label tag with the value of <emphasis role="italic">xml:lang</emphasis> is set to the relevant locale.</para>
      <para>Otherwise, if the administrator wants the node label is localized by resource bundle files, the <emphasis role="italic">#{...}</emphasis> syntax will be used. The enclosed property name serves as a key that is automatically passed to the internationalization mechanism. Thus, the emphasis property name is replaced with a localized value taken from the associated properties file matching the current locale.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<node-navigation>
  <owner-type>portal</owner-type>
  <owner-id>classic</owner-id>
  <priority>1</priority>
  <page-nodes>
    <node>
      <uri>home</uri>
      <name>home</name>
      <label>#{portal.classic.home}</label>
      <page-reference>portal::classic::homepage</page-reference>
    </node>
    <node>
      <uri>webexplorer</uri>
      <name>webexplorer</name>
      <label>#{portal.classic.webexplorer}</label>
      <page-reference>portal::classic::webexplorer</page-reference>
    </node>
  </page-nodes>
</node-navigation>]]></programlisting>
      </programlistingco>
      <para>This navigation tree is shown and reused in different portlets, such as sitemap, navigation or breadcrumbs. The breadcrumbs portlet renders the position of the current navigation node.</para>
      <note>
        <para>For the top nodes, the URI and the navigation node name must have the same value. For other nodes, the URI is composed like <emphasis role="italic">&lt;uri&gt;contentmanagement/fileexplorer&lt;/uri&gt;</emphasis> where 'contentmanagement' is the name of the parent node, and 'fileexplorer' is the name of node (<emphasis role="italic">&lt;name&gt;fileexplorer&lt;/name&gt;</emphasis>).</para>
      </note>
      <para xml:id="DEV.CreateYourOwnPortal.VisibilityPages">
<citetitle>
<emphasis role="bold">Visibility of pages</emphasis>
</citetitle>
</para>
      <para>When you configure the <emphasis role="italic">navigation.xml</emphasis> file, sometimes you need to set the visibility of page (node).</para>
      <para>To configure the page visibility, simply put <emphasis role="italic">&lt;visibility&gt;type_of_visibility&lt;/visibility&gt;</emphasis> as a child of the <emphasis role="italic">&lt;node&gt;</emphasis> tag.</para>
      <para>eXo Platform supports 4 types of page visibility, including:</para>
      <itemizedlist>
        <listitem>
          <para>DISPLAYED: The page will be displayed.</para>
        </listitem>
        <listitem>
          <para>HIDDEN: The page is not visible in the navigation but can be accessed directly with its URL.</para>
        </listitem>
        <listitem>
          <para>SYSTEM: It is a system page which is visible to superusers. In particular, only superusers can change or delete this system page. </para>
        </listitem>
        <listitem>
          <para>TEMPORAL: The page is displayed in related time range. When the visibility of TEMPORAL page is configured, the start and end date can be specified by using <emphasis role="italic">&lt;startpublicationdate&gt;</emphasis> and <emphasis role="italic">&lt;endpublicationdate&gt;</emphasis>. For example:</para>
        </listitem>
      </itemizedlist>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<node>
  ...
  <visibility>TEMPORAL</visibility>
  <startpublicationdate>01/13/2011 12:46:38</startpublicationdate>
  <endpublicationdate>01/20/2011 18:46:42</endpublicationdate>
</node>]]></programlisting>
      </programlistingco>
      <itemizedlist>
        <listitem>
          <para>To hide a page from menu and navigation, use <emphasis role="italic">&lt;visibility&gt;HIDDEN&lt;/visibility&gt;</emphasis>:</para>
        </listitem>
      </itemizedlist>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<node-navigation xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0">
  <page-nodes>
    <node>
      <uri>sitemap</uri>
      <name>sitemap</name>
      <label>#{portal.classic.sitemap}</label>
      <visibility>HIDDEN</visibility>
      <page-reference>portal::classic::sitemap</page-reference>
    </node>
    ...
  </page-nodes>
</node-navigation>]]></programlisting>
      </programlistingco>
      <para xml:id="DEV.CreateYourOwnPortal.PagesAccessPermission">
<citetitle>
<emphasis role="bold">Page access permission</emphasis>
</citetitle>
</para>
      <para>You can easily restrict the access of selected pages and navigation nodes to certain groups and users. You just need to create <emphasis role="italic">pages.xml</emphasis> and <emphasis role="italic">navigation.xml</emphasis> files in folders named after groups and users to which you want to give permission:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="italic">sample-ext/portal/group/group-name/your files</emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="italic">sample-ext/portal/user/username/your files</emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <para>As you know, the permission on a page has two types: access (view the page) and edit. </para>
      <para>To configure them, edit the <emphasis role="italic">pages.xml</emphasis> file and put tags: <emphasis role="italic">&lt;access-permissions&gt;</emphasis> and <emphasis role="italic">&lt;edit-permission&gt;</emphasis>.</para>
      <para>Currently, eXo Platform supports several access permissions but only one edit permission. It means that you can configure to make many groups to have the access permission but you can only set one group for edit permission.</para>
      <para>For example:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<page>
  <name>newStaff</name>
  <title>New Staff</title>
  <access-permissions>manager:/organization/management/executive-board;member:/organization/management/executive-board</access-permissions>
  <edit-permission>manager:/organization/management/executive-board</edit-permission>
  ...
</page>]]></programlisting>
      </programlistingco>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">
      <title>Enable/Disable a drive creation </title>
      <para>During the portal creation, a drive with the same name as the portal is also automatically created. However, you can decide if such a drive is automatically created or not by using two parameters named <emphasis role="italic">autoCreatedDrive</emphasis>, and <emphasis role="italic">targetDrives</emphasis> in the <emphasis role="italic">CreateLivePortalEventListener</emphasis> external component plugin.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<external-component-plugins>
    <target-component>org.exoplatform.services.listener.ListenerService</target-component>
    <component-plugin>
        <name>org.exoplatform.portal.config.DataStorage.portalConfigCreated</name>
        <set-method>addListener</set-method>
        <type>org.exoplatform.services.wcm.portal.listener.CreateLivePortalEventListener</type>
        <description>this listener creates a new live portal content storage.</description>
        <init-params>
            <value-param>
                <name>autoCreatedDrive</name>
                <description>A drive will be automatically created during the portal creation.</description>
                <value>false</value>
            </value-param>
            <values-param>
                <name>targetDrives</name>
                <description>The list of drives which are automatically created during the portal creation with
                    "autoCreatedDrive=false".
                </description>
                <value>acme</value>
            </values-param>
        </init-params>
    </component-plugin>
</external-component-plugins>]]></programlisting>
      </programlistingco>
      <itemizedlist>
        <listitem>
          <para>If <emphasis role="italic">autoCreatedDrive=true</emphasis>, a drive will be automatically created during the portal creation regardless of <emphasis role="italic">targetDrives</emphasis>. In case <emphasis role="italic">autoCreatedDrive</emphasis> is not specified, then its default value is <emphasis role="italic">true</emphasis>.</para>
        </listitem>
        <listitem>
          <para>If <emphasis role="italic">autoCreatedDrive=false</emphasis>, only drives listed in <emphasis role="italic">targetDrives</emphasis> are created. In case <emphasis role="italic">targetDrives</emphasis> is not specified, no drives are created.</para>
        </listitem>
      </itemizedlist>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">
      <title>Add/Remove a language </title>
      <para>Developer can define new or remove a defined language through the locale configuration file. The resource is managed by <emphasis role="italic">org.exoplatform.services.resources.LocaleConfigService</emphasis> as following:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<component>
    <key>org.exoplatform.services.resources.LocaleConfigService</key>
    <type>org.exoplatform.services.resources.impl.LocaleConfigServiceImpl</type>
      <init-params>
        <value-param>
          <name>locale.config.file</name>
          <value>war:/conf/common/locales-config.xml</value>
        </value-param>
      </init-params>
</component>]]></programlisting>
      </programlistingco>
      <para>All languages defined in the <emphasis role="italic">locale-config.xml</emphasis> file are listed in the <link linkend="DEV.Interface_Language_Setting_window">
          <emphasis role="bold">Interface Language Settings</emphasis>
        </link> window.</para>
      <para xml:id="DEV.CreateYourOwnPortal.AddNewLanguages">
<citetitle>
<emphasis role="bold">Add a new language</emphasis>
</citetitle>
</para>
      <para>To add a new language, you need to add the corresponding language node in the <emphasis role="italic">locale-config.xml</emphasis> file. Next, you must create a new <emphasis role="italic">resource bundle</emphasis> file containing the suffix name as the key of the added node.</para>
      <para>For example, to add Italian, do as follows:</para>
      <para>
        <emphasis role="bold">1.</emphasis> Add the following node to the <emphasis role="italic">locale-config.xml</emphasis> file.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<locale-config>
  <locale>it</locale>
  <output-encoding>UTF-8</output-encoding>
  <input-encoding>UTF-8</input-encoding>
  <description>Default configuration for Italian locale</description>
</locale-config>]]></programlisting>
      </programlistingco>
      <para>
        <emphasis role="bold">2.</emphasis> Create a new <emphasis role="italic">resource bundle</emphasis> as <emphasis role="bold">
          <emphasis role="italic">webui_it.properties</emphasis>
        </emphasis> in the <emphasis role="italic">myextension.war/WEB-INF/classes/locale/portal</emphasis> folder.</para>
      <note>
        <para>This step is necessary because the Resource Bundle Service of the portal will find keys and values in the <emphasis role="italic">resource bundle</emphasis> of each corresponding language. </para>
      </note>
      <para>
        <emphasis role="bold">3.</emphasis> Restart the server.</para>
      <para>To check if the added language takes effect, hover the mouse over your username on the <emphasis role="bold">Administration</emphasis> bar and click <emphasis role="bold">Change Language</emphasis>. In the <emphasis role="bold">Interface Language Settings</emphasis> window that appears, you will see the Italian is listed as below:</para>
      <para>
        <anchor id="DEV.Interface_Language_Setting_window"/>
      </para>
      <para>
        <mediaobject>
          <imageobject role="fo">
            <imagedata align="center" fileref="images/example_addItalian.png" format="PNG" scalefit="1" width="100mm"/>
          </imageobject>
          <imageobject role="html">
            <imagedata align="center" fileref="images/example_addItalian.png" format="PNG" scalefit="0" width="100mm"/>
          </imageobject>
        </mediaobject>
      </para>
      <para xml:id="DEV.CreateYourOwnPortal.RemoveLanguages">
<citetitle>
<emphasis role="bold">Remove a language</emphasis>
</citetitle>
</para>
      <para>To remove an existing language, you need to delete the relevant language node in the <emphasis role="italic">locale-config.xml</emphasis> file and all files containing the suffix name as the key of language.</para>
      <para>For example, to remove French, do as follows:</para>
      <para>
        <emphasis role="bold">1.</emphasis> Find and remove the following node from the <emphasis role="italic">locale-config.xml</emphasis> file.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<locale-config>
  <locale>fr</locale>
  <output-encoding>UTF-8</output-encoding>
  <input-encoding>UTF-8</input-encoding>
  <description>Default configuration for france locale</description>
</locale-config>]]></programlisting>
      </programlistingco>
      <para>
        <emphasis role="bold">2.</emphasis> Continue removing all <emphasis role="italic">resource bundle</emphasis> files containing the suffix name as <emphasis role="bold">fr</emphasis> in all folders.</para>
      <note>
        <para>It is recommended this step be done to delete unnecessary data in the application.</para>
      </note>
      <para>  <emphasis role="bold">3.</emphasis> Restart the server.</para>
      <para>To check if French is removed, hover the mouse over your username on the <emphasis role="bold">Administration bar</emphasis> and click the <emphasis role="bold">Change Language</emphasis>.</para>
      <para>In the <emphasis role="bold">Interface Language Settings</emphasis> window that appears, French is no longer listed.</para>
      <para>
        <mediaobject>
          <imageobject role="fo">
            <imagedata align="center" fileref="images/example_removeFrench.png" format="PNG" scalefit="1" width="100mm"/>
          </imageobject>
          <imageobject role="html">
            <imagedata align="center" fileref="images/example_removeFrench.png" format="PNG" scalefit="0" width="100mm"/>
          </imageobject>
        </mediaobject>
      </para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">
      <title>Create a custom look and feel </title>
      <highlights>
<itemizedlist>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.PageSkinElemnets">Platform skin elements</link>
              </emphasis>
	</para>
	<para>
	The complete skinning of eXo Platform that can be decomposed into 3 main parts: Portal skin, Window style, Portlet skin, and further details of SkinService, ResourceRequestFilter and default skin. 
	</para>
	</listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.Skin_the_portlet">Skin the portlet</link>
              </emphasis>
	</para>
	<para>
	How to define additional stylesheets for each portlet, and to change its icon.
	</para>
	</listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.OverrideSkinsWithExtension">Override skins with extension</link>
              </emphasis>
	</para>
	<para>
	The way to replace a skin definition with the skin resource configured in the extension-deployed web application, and steps to override skins with extension.
	</para>
	</listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.CreateNewSkins">Create a new skin</link>
              </emphasis>
	</para>
	<para>
	Steps to create a new skin web archive and preview icon, to skin the window style as well as to configure the right-to-left skin.
	</para>
	</listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.Configure_portlet_skin">Configure Platform skin</link>
              </emphasis>
	</para>
	<para>
	The detailed topics which allow you to configure the eXo Platform skin effectively, such as how to select skins or to customize layouts, styles, templates or shared layouts.
	</para>
	</listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.CustomizeDocumentSkin">Customize Document's skin</link>
              </emphasis>
	</para>
	<para>
	Instructions on how to create a new document definition and configure it, to create templates, to create and export content into XML files, and finally to set up a deployment for importing the XML files into database.
	</para>
	</listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
                <link linkend="DEV.CreateYourOwnPortal.BestPracticeToCustomizeSkin">Best practices to customize a skin</link>
              </emphasis>
	</para>
	<para>
	Conventions and best ways to ease the integration of the design in eXo Platform.
	</para>
	</listitem>
</itemizedlist>
<para>
By following the information detailed in this section, you are able to customize a look and feel of your project effectively.
</para>
</highlights>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.CreateYourOwnPortal.PageSkinElemnets" role="NotInToc">
        <title>Platform skin elements  </title>
        <para>Platform provides support for skinning the entire portal User Interface (UI) including your own portlets. Skins are designed to help you pack and reuse common graphic resources.</para>
        <para>The complete skinning of eXo Platform can be decomposed into three main parts: Portal skin, Window style, Portlet skin.</para>
        <citetitle>
<para>
<emphasis role="bold">Portal skin</emphasis>
</para>
</citetitle>
        <para>The portal skin contains styles for the HTML tags (for example, div, th, td) and the portal UI (including the toolbar). This should include all UI components, except for window decorators and portlet specific styles.</para>
        <citetitle>
<para>
<emphasis role="bold">Window style</emphasis>
</para>
</citetitle>
        <para>The CSS styles are associated with the portlet window decorators. The window decorators contain control buttons and borders surrounding each portlet. Individual portlets can have their own window decorators selected, or be rendered without one.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/window_decoration.jpg" format="JPG" scalefit="1" width="80mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/window_decoration.jpg" format="JPG" scalefit="0" width="80mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <citetitle>
<para>
<emphasis role="bold">Portlet skin</emphasis>
</para>
</citetitle>
        <para>The portlet skins affect how portlets are rendered on the page. The portlet skins can affect in two main ways described in the following sections.</para>
        <para>
          <emphasis role="bold">Portlet Specification CSS Classes</emphasis> <anchor id="DEV.CreateYourOwnPortal.PortletSpecificationCSSClasses"/>
        </para>
        <para>The <ulink url="http://jcp.org/en/jsr/detail?id=286">portlet specification</ulink> defines a set of CSS classes that should be available to portlets. eXo Platform provides these classes as a part of the portal skin. This enables each portal skin to define its own look and feel for these default values.</para>
        <para>
          <emphasis role="bold">Portlet skins</emphasis> <anchor id="DEV.CreateYourOwnPortal.PortletSkins"/>
        </para>
        <para>eXo Platform provides a means for portlet CSS files to be loaded that is based on the current portal skin. This enables a portlet to provide different CSS styles to better match the current portal's look and feel.</para>
        <note>
          <para>The window decorators and the default portlet specification CSS classes should be considered as separate types of skinning components, but they need to be included as a part of the overall portal skin. The portal skin must include CSS classes of these components or they will not be displayed correctly. A portlet skin does not need  to be  included as a part of the portal skin and can be included within the portlets web application.</para>
        </note>
        <highlights>
 <para>More details of the eXo Platform skin elements are described in:</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.SkinService">SkinService</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.ResourceRequestFilter">ResourceRequestFilter</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.DefaultSkin">Default skin</link>
            </para>
          </listitem>
        </itemizedlist>
</highlights>
        <section id="DEV.CreateYourOwnPortal.SkinService">
          <title>SkinService </title>
          <para>Platform skin is processed by the SkinService. It is used to discover and deploy skins into the portal.</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Configure skins</emphasis> <anchor id="DEV.CreateYourOwnPortal.ConfigureSkins"/>
              </para>
            </listitem>
          </itemizedlist>
          <para>eXo Platform 3.5 has a file descriptor for skins (WEB-INF/gatein-resources.xml) which is to specify which portal, portlet and window decorators will be deployed into the skin service. Platform can automatically discover web archives containing this file gatein-resource.xml. The full schema can be found in the lib directory: <emphasis role="italic">exo.portal.component.portal.jar/gatein_resources_1_0.xsd</emphasis>.</para>
          <para>Here is the <emphasis role="italic">gatein-resources.xml</emphasis> file of a sample skin (called "MySkin") which defines the portal skin with its CSS location, window style and its portlet skins:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<gatein-resources>
<!-- define the portal skin -->
<portal-skin>
    <skin-name>MySkin</skin-name>
    <css-path>/skin/myskin.css</css-path>
    <overwrite>false</overwrite>
</portal-skin>

<!-- define the portlet skin -->

<portlet-skin>
  <application-name>web</application-name>
  <portlet-name>HomePagePortlet</portlet-name>
  <skin-name>Default</skin-name>
  <css-path>/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css</css-path>
    <overwrite>false</overwrite>
</portlet-skin>

  <!-- define the window style -->
<window-style>
    <style-name>MyThemeCategory</style-name>
    <style-theme>
      <theme-name>MyThemeBlue</theme-name>
    </style-theme>
    <style-theme>
      <theme-name>MyThemeRed</theme-name>
    </style-theme>
</window-style>
</gatein-resources>]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.CreateYourOwnPortal.ResourceRequestFilter">
          <title>ResourceRequestFilter </title>
          <para>The ResourceRequestFilter is used to map process skin request mapping from portal, portlet to the exact skin that was defined in portal. ResourceRequestFilter is configured in the <emphasis role="italic">web.xml</emphasis> file in the skin web archive.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<webapp>
<display-name>eXoResources</display-name>
<filter>
  <filter-name>ResourceRequestFilter</filter-name>
  <filter-class>org.exoplatform.portal.application.ResourceRequestFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>ResourceRequestFilter</filter-name>
  <url-pattern>*.css</url-pattern>
</filter-mapping>
</webapp>]]></programlisting>
          </programlistingco>
          <note>
            <para>The configuration of Portlet Skin takes an optional parameter application-name, which is the web application wrapping skinned portlet. Hence, the display-name element in <emphasis role="italic">web.xml</emphasis> needs to be coherent with the application-name in the <emphasis role="italic">gatein-resources.xml</emphasis> file.</para>
          </note>
        </section>
        <section id="DEV.CreateYourOwnPortal.DefaultSkin">
          <title>Default skin </title>
          <para>The default skin of eXo Platform 3.5 is in the <emphasis role="italic">eXoResource.war</emphasis> file. The main files associated with the skin are:</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="italic">WEB-INF/gatein-resources.xml</emphasis> defines the skin settings to use.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">WEB-INF/web.xml</emphasis> contains the resource filter with the display-name set.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">skin/Stylesheet.css</emphasis> contains the CSS class definitions for this skin.</para>
            </listitem>
          </itemizedlist>
          <note>
            <para>To get a new portal skin declared in <emphasis role="italic">gatein-resources.xml</emphasis> loaded successfully, <emphasis role="italic">display-name</emphasis> of the extension webapp (in <emphasis role="italic">web.xml</emphasis>) should be identical to the context path of the extension webapp.</para>
          </note>
          <para>The following block of CSS illustrates content of the <emphasis role="italic">skin/Stylesheet.css</emphasis> file:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[@import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css); (1)
@import url(DefaultSkin/webui/component/Stylesheet.css); (2)
@import url(PortletThemes/Stylesheet.css); (3)
@import url(Portlet/Stylesheet.css); (4)]]></programlisting>
          </programlistingco>
          <para>In which:</para>
          <itemizedlist>
            <listitem>
              <para>(1) Skin of the portal page. The <emphasis role="italic">UIPortalApplicationSkin.css</emphasis> defines CSS classes shared by all the portal pages.</para>
            </listitem>
            <listitem>
              <para>(2) Skins of various portal-owned components, such as WorkingWorkspace, MaskWorkspace, PortalForm, and more.</para>
            </listitem>
            <listitem>
              <para>(3) Window decorator skins.</para>
            </listitem>
            <listitem>
              <para>(4) The portlet specification CSS classes. (The CSS styles defined in Portlet Specification JSR286)</para>
            </listitem>
          </itemizedlist>
          <para>To make a default skin flexible and highly reusable, instead of defining all CSS classes in this file, CSS classes are arranged in nested stylesheet files, based on the @import statement. This makes easier for new skins to reuse parts of the default skin. To reuse a CSS stylesheet from the default portal skin, you need to refer to the default skin from eXoResources. For example, to include the window decorators from the default skin within a new portal skin, you need to use the following import:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[@import url(/eXoResources/skin/Portlet/Stylesheet.css);]]></programlisting>
          </programlistingco>
          <note>
            <para>When the portal skin is added to the page, it merges all CSS stylesheets into a single file.</para>
          </note>
        </section>
      </section>
      <section id="DEV.CreateYourOwnPortal.Skin_the_portlet" role="NotInToc">
        <title>Skin the portlet </title>
        <para>Portlets often require additional styles that may not be defined by the portal skin. eXo Platform 3.5 defines additional stylesheets for each portlet and will append the corresponding link tags to the head. The ID attribute of &lt;link&gt; element will be in the <emphasis role="italic">portletAppName/PortletName</emphasis> form. For example, the ContentPortlet in content.war takes "content/ContentPortlet" as ID. To define a new CSS file to be included whenever a portlet is available on a portal page, the following fragment needs to be added in the <emphasis role="italic">gatein-resources.xml</emphasis> file.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<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>
        </programlistingco>
        <para>This action will load DefaultStylesheet.css or OtherSkinStylesheet.css when the DefaultSkin or OtherSkin is used respectively.</para>
        <note>
          <para>If the current portal skin is not defined as part of the supported skins, the portlet CSS class will not be loaded. The portlet skins should be updated whenever a new portal skin is created.</para>
        </note>
        <para xml:id="DEV.CreateYourOwnPortal.ChangePortletIcons">
<citetitle>
<emphasis role="bold">Change portlet icons</emphasis>
</citetitle>
</para>
        <para>Each portlet can be represented by a unique icon that you can see in the portlet registry or page editor. This icon can be changed by adding an image to the directory of portlet web application: <emphasis role="italic">skin/DefaultSkin/portletIcons/icon_name.png</emphasis>. The icon must be named after the portlet. For example, the icon of account portlet must be named AccountPortlet and located at: <emphasis role="italic">skin/DefaultSkin/portletIcons/AccountPortlet.png</emphasis>.</para>
        <note>
          <para>You must use <emphasis role="italic">skin/DefaultSkin/portletIcons/</emphasis> for the directory to store the portlet icon regardless of using any skins.</para>
        </note>
      </section>
      <section id="DEV.CreateYourOwnPortal.OverrideSkinsWithExtension" role="NotInToc">
        <title>Override skins with extension </title>
        <para>The extension mechanism of eXo Platform 3.5 enables the skin definition to be replaced with the skin resource configured in the extension-deployed web application. This is the example where the CSS path of default portal skin needs to be modified without touching the Platform's files.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<gatein-resources>
  <portal-skin>
    <skin-name>Default</skin-name>
    <css-path>/skin/Defaultskin/Stylesheet.css</css-path>
    <overwrite>false</overwrite>
    <css-priority>0</css-priority>
  </portal-skin>
</gatein-resources>]]></programlisting>
        </programlistingco>
        <para>(The css-path specifies the stylesheet of the new skin.)</para>
        <para>
<citetitle>
<para>
              <emphasis role="bold">Override skins with extension</emphasis>
            </para>
</citetitle>
</para>
        <para>
          <emphasis role="bold">1.</emphasis> Create a web application whose <emphasis role="italic">gatein-resources.xml</emphasis> contains the same content as the above xml block, except the element &lt;css-path&gt; is modified.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Ensure that once the server has deployed the artifact, it does not load any web application with <emphasis role="italic">gatein-resources.xml</emphasis> configuring the same portal skin.</para>
      </section>
      <section id="DEV.CreateYourOwnPortal.CreateNewSkins" role="NotInToc">
        <title>Create a new skin </title>
        <para>Creating a new skin is not a simple topic because this task requires many steps to have a wished skin for your product. There are many options for you to create a new skin that depends on your various demands. A typical procedure of creating a new skin includes certain main steps, for example:</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.CreateNewSkins.WebArchive">Create a new skin web archive</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.PortalSkinPreviewIcon">Create the skin preview icon</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.Skin_the_window_style">Skin the window style</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.Configure_RTL_skin">Configure the right-to-left skin</link>
            </para>
          </listitem>
        </itemizedlist>
        <para xml:id="DEV.CreateYourOwnPortal.CreateNewSkins.WebArchive">
<citetitle>
<emphasis role="bold">Create a new skin web archive</emphasis>
</citetitle>
</para>
        <para>To create a new skin (called "MySkin"), you should create a new skin web archive with the following structure:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/FolderStructure.png" format="PNG" scalefit="1" width="80mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/FolderStructure.png" format="PNG" scalefit="0" width="80mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>The <emphasis role="italic">web.xml</emphasis> is the file that you will define the ResourceRequestFilter.</para>
          </listitem>
          <listitem>
            <para>The <emphasis role="italic">gatein-resource.xml</emphasis> will define your new skin (for portal, portlet or window style).</para>
          </listitem>
          <listitem>
            <para>The <emphasis role="bold">skin</emphasis> folder will contain images and stylesheets of your skin.</para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="bold">Configure portal skins</emphasis> <anchor id="DEV.CreateYourOwnPortal.ConfigurePortalSkins"/>
        </para>
        <para>You need to specify the new portal skin in the <emphasis role="italic">gatein-resources.xml</emphasis> file. You also need to specify the name of new skin, where to locate its CSS stylesheet file and whether to overwrite the existing portal theme with the same name.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<gatein-resources>
  <portal-skin>
    <skin-name>MySkin</skin-name>
    <css-path>/skin/myskin.css</css-path>
    <overwrite>false</overwrite>
    <css-priority>0</css-priority>
  </portal-skin>
</gatein-resources>]]></programlisting>
        </programlistingco>
        <para>The default portal skin and window styles are defined in the <emphasis role="italic">eXoResources.war/WEB-INF/gatein-resources.xml</emphasis> file.</para>
        <note>
          <para>The CSS for the portal skin needs to contain CSS for all window decorators and portlet specification CSS classes.</para>
          <para>eXo Platform provides the "CSS priority" concept  which controls the loading order of skins. The skin with lower "css-priority" value will be loaded first.</para>
        </note>
        <para xml:id="DEV.CreateYourOwnPortal.PortalSkinPreviewIcon">
<citetitle>
<emphasis role="bold">Create the skin preview icon</emphasis>
</citetitle>
</para>
        <para>When selecting a skin it is possible to see a preview of what the skin will look like. The current skin needs to know about the skin icons for all the available skins, otherwise it will not be able to show the previews. When creating a new portal it is recommended to include the preview icons of the other skins and to update the other skins with your new portal skin preview.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/Skin_preview.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/Skin_preview.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>For any portal skin, the paths to the preview images are specified in CSS class UIChangeSkinForm:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">eXoResources/src/main/webapp/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>For the portal named MySkin, it is required to define the following CSS classes:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[.UIChangeSkinForm .UIItemSelector .TemplateContainer .MySkinImage]]></programlisting>
        </programlistingco>
        <para>The default skin would be aware of skin icons if the preview screenshot is placed in:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background</emphasis>.</para>
          </listitem>
        </itemizedlist>
        <para>The CSS stylesheet for the default portal needs to have the following updated with the preview icon CSS class. For the skin named MySkin, it is required to update the following:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</emphasis>.</para>
          </listitem>
        </itemizedlist>
        <para>Now, amending the deployed package eXoResources is inevitable (modifying the default war/jar breaches development convention of Platform-based products). The problem would be resolved in future eXo Platform versions in which different skin modules are fully independent, for example, there will be no preview image duplication.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[.UIChangeSkinForm .UIItemSelector .TemplateContainer .MySkinImage {
margin: auto;
width: 329px; height:204px;
background: url('background/MySkin.jpg') no-repeat top;
cursor: pointer ;
}]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.CreateYourOwnPortal.Skin_the_window_style">
<citetitle>
<emphasis role="bold">Skin the window style</emphasis>
</citetitle>
</para>
        <para>Window style is the CSS applied to the window decorator. When the administrator selects a new application to add to a page, he can decide which style of decorator surrounding the window if any.</para>
        <para>
          <emphasis role="bold">Configure window styles</emphasis> <anchor id="DEV.CreateYourOwnPortal.ConfigureWindowStyles"/>
        </para>
        <para>Window style is defined within the <emphasis role="italic">gatein-resources.xml</emphasis> file used by the SkinService to deploy the window style. Window styles can belong to a window style category. This category and window styles need to be specified in the resources file. For example, the following <emphasis role="italic">gatein-resource.xml</emphasis> fragment will add MyThemeBlue and MyThemeRed to the MyTheme category.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<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>
        </programlistingco>
        <para>The windows style of the default skin is configured in the <emphasis role="italic">eXoResources.war/WEB-INF/gatein-resources.xml</emphasis> file.</para>
        <note>
          <para>When a window style is defined in the <emphasis role="italic">gatein-resources.xml</emphasis> file, it will be available to all portlets regardless of whether the current portal skin supports the window decorator or not. When a new window decorator is added, it should be added to all portal skins or the portal skins should share a common stylesheet for window decorators.</para>
        </note>
        <para>
          <emphasis role="bold">Window style CSS</emphasis> <anchor id="DEV.CreateYourOwnPortal.WindowStyleCSS"/>
        </para>
        <para>In order for the SkinService to display the window decorators, it must have CSS classes with the specific naming related to the window style name. The service will try and display CSS based on this naming. The CSS class must be included as part of the current portal skin for the window decorators to be displayed. The window decorator CSS classes for the default portal theme are located at <emphasis role="italic">eXoResources.war/skin/PortletThemes/Stylesheet.css</emphasis>.</para>
        <para>
          <emphasis role="bold">Set the default window style</emphasis> <anchor id="DEV.CreateYourOwnPortal.SetDefaultWindowStyle"/>
        </para>
        <para>To set the default window style for a portal, you need to specify the CSS classes for a theme called DefaultTheme.</para>
        <note>
          <para>You do not need to specify the DefaultTheme in the <emphasis role="italic">gatein-resources.xml</emphasis> file.</para>
        </note>
        <para xml:id="DEV.CreateYourOwnPortal.Configure_RTL_skin">
<citetitle>
<emphasis role="bold">Configure the right-to-left skin</emphasis>
</citetitle>
</para>
        <para>The SkinService handles stylesheet rewriting to accommodate the orientation. It works by appending <emphasis role="italic">-lt</emphasis> or <emphasis role="italic">-rt</emphasis> to the stylesheet name. For example, <emphasis role="italic">/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css</emphasis> will return the same stylesheet as <emphasis role="italic">/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css</emphasis> but processed for the RT orientation. The <emphasis role="italic">-lt</emphasis> suffix is optional. Stylesheet authors can annotate their stylesheet to create content that depends on the orientation.</para>
        <para>Example 1. This example uses the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[float: left; /* orientation=lt */
float: right; /* orientation=rt */
font-weight: bold;
text-align: center;
white-space: nowrap;]]></programlisting>
        </programlistingco>
        <para>The LT produced output will be:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[float: left; /* orientation=lt */
font-weight: bold;
text-align: center;
white-space: nowrap;]]></programlisting>
        </programlistingco>
        <para>The RT produced output will be:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[float: right; /* orientation=rt */
font-weight: bold;
text-align: center;
white-space: nowrap;]]></programlisting>
        </programlistingco>
        <para>Example 2. In this example, you need to modify the padding based on the orientation:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[color: white;
line-height: 24px;
padding: 0px 5px 0px 0px; /* orientation=lt */
padding: 0px 0px 0px 5px; /* orientation=rt */]]></programlisting>
        </programlistingco>
        <para>The LT produced output will be:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[color: white;
line-height: 24px;
padding: 0px 5px 0px 0px; /* orientation=lt */]]></programlisting>
        </programlistingco>
        <para>The RT produced output will be:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[color: white;
line-height: 24px;
padding: 0px 0px 0px 5px; /* orientation=rt */]]></programlisting>
        </programlistingco>
      </section>
      <section id="DEV.CreateYourOwnPortal.Configure_portlet_skin" role="NotInToc">
        <title>Configure Platform skin </title>
        <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.PageSkinElemnets">Platform skin elements</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.Skin_the_portlet">Skin the portlet</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.OverrideSkinsWithExtension">Override skins with extension</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.CreateNewSkins">Create a new skin</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.CustomizeDocumentSkin">Customize Document's skin</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.CreateYourOwnPortal.BestPracticeToCustomizeSkin">Best practices to customize a skin</link>
            </para>
          </listitem>
        </itemizedlist>
        <section id="DEV.CreateYourOwnPortal.SelectSkinWithinConfigurationFiles">
          <title>Select skins within the configuration files </title>
          <para>The default skin can be set in the portal configuration files. The skin configured as default is used by Platform as the administrator starts/restarts the server.</para>
          <para>Simply add a skin tag to the <emphasis role="italic">portal.war/WEB-INF/conf/portal/portal/classic/portal.xml</emphasis> configuration file.</para>
          <para>To change skin to YourSkin, use the following code:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<portal-config>
  <portal-name>classic</portal-name>
  <locale>en</locale>
  <access-permissions>Everyone</access-permissions>
  <edit-permission>*:/platform/administrators</edit-permission>
  <skin>MySkin</skin>
  ...
</portal-config>]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.CreateYourOwnPortal.SkinsInThePageMarkup">
          <title>Skins in the page markup </title>
          <para>The eXo Platform 3.5 skin not only contains CSS styles for the portal's components, but also shares components that may be reused in portlets. When eXo Platform 3.5 generates the page markup of portal, stylesheet links will be inserted in the page's head tag. There are two main types of CSS links which appear in the head tag: one to the portal skin CSS file and the other to the portlet skin CSS file.</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Portal Skin</emphasis> appears as a single link to a CSS file. This link contains contents from all portal skin classes merged into one file. The portal skin will be transferred more quickly as a single file instead of multiple smaller files.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">Portlet Skin</emphasis> only appears as the link on the page if that portlet is loaded on the current page. A page may contain many CSS links of portlet skins or none. In the code fragment below, you can see two types of links:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<head>
  ...
  <!-- The portal skin -->
  <link id="CoreSkin" rel="stylesheet" type="text/css" href="/eXoResources/skin/Stylesheet.css" />
  <!-- The portlet skins -->
  <link id="web_FooterPortlet" rel="stylesheet" type="text/css"
    href="/web/skin/portal/webui/
component/UIFooterPortlet/DefaultStylesheet.css" />
  <link id="web_NavigationPortlet" rel="stylesheet" type="text/css"
    href="/web/skin/portal/webui/
component/UINavigationPortlet/DefaultStylesheet.css" />
  <link id="web_HomePagePortlet" rel="stylesheet" type="text/css"
    href="/portal/templates/skin/
webui/component/UIHomePagePortlet/DefaultStylesheet.css" />
  <link id="web_BannerPortlet" rel="stylesheet" type="text/css"
    href="/web/skin/portal/webui/
component/UIBannerPortlet/DefaultStylesheet.css" />
  ...
</head>]]></programlisting>
          </programlistingco>
          <note>
            <para>Window styles and portlet specification CSS classes are included within the portal skin.</para>
          </note>
        </section>
        <section id="DEV.CreateYourOwnPortal.CustomizePortalLayout">
          <title>Customize portal's layout </title>
          <note>
            <para>This section is related to the configuration. You can see a sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/ecmdemo/webapp/src/main/webapp/WEB-INF/conf/sample-portal/portal/portal/acme/portal.xml">here.</ulink> You can leave all the portlet's preferences as blank, that means the default value will be taken and you do not need to care about it at this time.</para>
          </note>
          <para>For example, you will have a layout like this:</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/samplelayout.jpg" format="JPG" scalefit="1" width="80mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/samplelayout.jpg" format="JPG" scalefit="0" width="80mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>In which:</para>
          <itemizedlist>
            <listitem>
              <para>Branding: A branding application</para>
            </listitem>
            <listitem>
              <para>Top navigation: A top navigation application</para>
            </listitem>
          </itemizedlist>
          <para>A table column container with three nested containers:</para>
          <itemizedlist>
            <listitem>
              <para>Left Column and Right Column: Contain one application for each.</para>
            </listitem>
            <listitem>
              <para>Main content: Contain the page body.</para>
            </listitem>
          </itemizedlist>
          <para>And here is the fragment of <emphasis role="italic">portal.xml</emphasis> located in this path: <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/portal/portal/mysite/portal.xml</emphasis>.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<!-- ... -->

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

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

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

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

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

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

<!-- ... -->]]></programlisting>
          </programlistingco>
          <para>As you see in the <emphasis role="italic">portal.xml</emphasis> file above, every <emphasis role="bold">container</emphasis> tag has an <emphasis role="bold">id</emphasis> attribute, for example "&lt;container id = '<emphasis role="bold">RightColumn</emphasis>'&gt;". When you create a CSS file, the property applied for this container should have the following name manner:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[${container_id}TDContainer]]></programlisting>
          </programlistingco>
          <para>and the details of this container:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[RightColumnTDContainer]]></programlisting>
          </programlistingco>
          <para>The reason is, when you have a look in the file system: <emphasis role="italic">/groovy/portal/webui/container/UITableColumnContainer.gtmpl</emphasis> shown above, you will see this code fragment:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<table class="UITableColumnContainer"
  style="table-layout: fixed; margin: 0px auto;">
  <tr class="TRContainer">
    <% for(uiChild in uicomponent.getChildren()) {%>
    <td class="${uiChild.id}TDContainer TDContainer"><%
      uicomponent.renderUIComponent(uiChild) %></td> <% } %>
  </tr>
</table>]]></programlisting>
          </programlistingco>
          <para>So, in the <emphasis role="bold">table</emphasis> element (which represents the outer container), there are many <emphasis role="bold">td</emphasis> elements, each of which has the <emphasis role="bold">class</emphasis> attribute that equals to the <emphasis role="bold">id</emphasis> of the corresponding child component plus the "TDContainer" string literal.</para>
        </section>
        <section id="DEV.CreateYourOwnPortal.CustomizePageLayout">
          <title>Customize page's layouts </title>
          <note>
            <para>This section is related to the configuration. You can see a sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/ecmdemo/webapp/src/main/webapp/WEB-INF/conf/sample-portal/portal/portal/acme/pages.xml">here.</ulink> You can leave all the portlet's preferences as blank, that means the default value will be taken and you do not need to care about it at this time.</para>
          </note>
          <itemizedlist>
            <listitem>
              <para>Like <emphasis role="italic">portal.xml</emphasis>, you can define the layout for each page in your site as shown in the following example:</para>
            </listitem>
          </itemizedlist>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/sample_page.jpg" format="JPG" scalefit="1" width="60mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/sample_page.jpg" format="JPG" scalefit="0" width="60mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<!-- ... -->

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

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

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

<!-- ... -->]]></programlisting>
          </programlistingco>
        </section>
        <section id="customize-portal-and-page-style">
          <title>Customize portal and page's style </title>
          <para>
<citetitle>
<emphasis role="bold">
Apply your skin into all pages
</emphasis>
</citetitle>
</para>
          <para>
            <emphasis role="bold">1.</emphasis> Go to <emphasis role="bold">Sites Explorer --&gt;</emphasis> <emphasis role="bold">Shared</emphasis> drive <emphasis role="bold">--&gt; CSS</emphasis> folder.</para>
          <para>
            <emphasis role="bold">2.</emphasis> Create a new CSS document which contains your stylesheet. You can use any name for this document and put a priority number.</para>
          <para>
<citetitle>
<emphasis role="bold">
Apply your skin into your MySite page only
</emphasis>
</citetitle>
</para>
          <para>
            <emphasis role="bold">1.</emphasis> Click <inlinemediaobject>
              <imageobject role="fo">
                <imagedata fileref="images/gear_icon.png" format="PNG" scalefit="1" width="5mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata fileref="images/gear_icon.png" format="PNG" scalefit="0" width="5mm"/>
              </imageobject>
            </inlinemediaobject> <emphasis role="bold">--&gt; Sites Explorer--&gt; Sites Management drive --&gt; MySite/css</emphasis> folder.</para>
          <para>
            <emphasis role="bold">2.</emphasis> Create a new CSS document which contains your stylesheet for the portal and the page layout. You can use any name for this document and put a priority number.</para>
          <note>
            <para>This document should contain ONLY one stylesheet for the page and portal level.</para>
          </note>
          <para>The following is the sample stylesheet:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[/* ... */
.LeftColumnTDContainer { 
/* ... */
  
}

.RightColumnTDContainer { 
/* ... */
  
}

/* ... */]]></programlisting>
          </programlistingco>
          <note>
            <para>The order of applying CSS files (of site and web content) depends on their own <emphasis role="bold">priority</emphasis> property value. It means that we can apply the site CSS first and then web content CSS, or vice versa.</para>
          </note>
        </section>
        <section id="DEV.CreateYourOwnPortal.CustomizeCLVPortletTemplate">
          <title>Customize CLV portlet's template </title>
          <note>
            <para>This section is related to the configuration. You can see a sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/wcm-artifacts/application-templates/content-list-viewer/list-by-folder/TwoColumnsCLVTemplate.gtmpl">here.</ulink>
            </para>
          </note>
          <itemizedlist>
            <listitem>
              <para>Apply your HTML/Groovy template code for this template.</para>
            </listitem>
          </itemizedlist>
          <para>For example:</para>
          <para>
            <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/template/list/ACustomizedCLVTemplate.gtmpl</emphasis>
          </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<div id="$uicomponent.id" class="ACustomizedCLVTemplate">
  <div class="ListContents">
    <!-- something here -->
  </div>
</div>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>Now, you need to import this template to the database.</para>
            </listitem>
          </itemizedlist>
          <para>
            <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/template/configuration.xml</emphasis>
          </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<external-component-plugins>
  <target-component>org.exoplatform.services.cms.views.ApplicationTemplateManagerService</target-component>
  <component-plugin>
    <name>ACustomizedCLVTemplate</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.cms.views.PortletTemplatePlugin</type>
    <description>This is a sample customized CLV template</description>
    <init-params>
      <value-param>
        <name>portletName</name>
        <value>Content List Viewer</value>
      </value-param>
      <value-param>
        <name>portlet.template.path</name>
        <value>war:/conf/myportal/customized/template</value>
      </value-param>
      <object-param>
        <name>default.folder.list.viewer</name>
        <description>Default folder list viewer groovy template</description>
        <object type="org.exoplatform.services.cms.views.PortletTemplatePlugin$PortletTemplateConfig">
          <field name="templateName">
            <string>ACustomizedCLVTemplate.gtmpl</string>
          </field>
          <field name="category">
            <string>list</string>
          </field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.CreateYourOwnPortal.CustomizeCLVTemplateStyle">
          <title>Customize CLV template's style </title>
          <para>
            <emphasis role="bold">1.</emphasis> Go to <emphasis role="bold">Sites explorer</emphasis> portlet <emphasis role="bold">--&gt; Sites management</emphasis> drive <emphasis role="bold">--&gt; MySite/css</emphasis> folder.</para>
          <para>
            <emphasis role="bold">2.</emphasis> Create a new CSS document which contains your stylesheet for the portal and the page layout. You can use any name for this document and put a priority number.</para>
          <note>
            <para>This document should contain ONLY one stylesheet for THIS template. If you have another template, you should create a new CSS document.</para>
          </note>
          <itemizedlist>
            <listitem>
              <para>The following is the sample stylesheet:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[/* ... */
.ACustomizedCLVTemplate {
/* ... */

}

.ListContents {
/* ... */

}

/* ... */]]></programlisting>
          </programlistingco>
          <para>
            <emphasis role="bold">3.</emphasis> Export the document and now you have an XML file.</para>
          <para>Please check out <ulink url="http://wiki.exoplatform.com/xwiki/bin/view/WCM/How+to+create+and+deploy+pre-defined+contents+in+WCM">this tutorial</ulink> to know how to import this XML into the database.</para>
        </section>
        <section id="DEV.CreateYourOwnPortal.Sharedlayout">
          <title>Configure a shared layout </title>
          <para xml:id="DEV.CreateYourOwnPortal.ExistingConfigurationsOfSharedlayout">
<citetitle>
<emphasis role="bold">Existing configurations of sharedlayout.xml</emphasis>
</citetitle>
</para>
          <para>There are currently 4 configurations of <emphasis role="italic">sharedLayout.xml</emphasis> in eXo Platform:</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="italic">portal/WEB-INF/conf/portal/portal/sharedlayout.xml</emphasis>
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">webos-ext/WEB-INF/conf/portal/portal/sharedlayout.xml</emphasis>
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">ecm-wcm-extension/WEB-INF/conf/portal/portal/sharedlayout.xml</emphasis>
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">platform-extension/WEB-INF/conf/portal/portal/sharedlayout.xml</emphasis>
              </para>
            </listitem>
          </itemizedlist>
          <para>The order of <emphasis role="italic">sharedlayout.xml</emphasis> loading is important. The last loaded extension defines the <emphasis role="italic">sharedlayout.xml</emphasis> file which the system uses to define portlets displayed in the <emphasis role="bold">Admin</emphasis> bar.</para>
          <para>To make sure your extension is last loaded, look at the configuration file: <emphasis role="italic">jar:/conf/configuration.xml</emphasis>. The <emphasis role="bold">PortalContainerConfig</emphasis> component can be used to define the order of war loading.</para>
          <para xml:id="DEV.CreateYourOwnPortal.HowItWorks">
<citetitle>
<emphasis role="bold">How it works?</emphasis>
</citetitle>
</para>
          <para>The code which is responsible for <emphasis role="italic">sharedlayout.xml</emphasis> loading is located in the <emphasis role="italic">POMDataStorage.java</emphasis> class from portal.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[public Container getSharedLayout() throws Exception
   {
      String path = "war:/conf/portal/portal/sharedlayout.xml";
      String out = IOUtil.getStreamContentAsString(confManager_.getInputStream(path));
      ByteArrayInputStream is = new ByteArrayInputStream(out.getBytes("UTF-8"));
      IBindingFactory bfact = BindingDirectory.getFactory(Container.class);
      UnmarshallingContext uctx = (UnmarshallingContext)bfact.createUnmarshallingContext();
      uctx.setDocument(is, null, "UTF-8", false);
      Container container = (Container)uctx.unmarshalElement();
      generateStorageName(container);
      return container;
   }]]></programlisting>
          </programlistingco>
          <para>You can see the path is hard-coded. Once the good configuration file is chosen by the portal container, this one will use it to add portlets to the <emphasis role="bold">Admin</emphasis> bar. You can see that all sharedlayout portlets are configured with the <emphasis role="italic">show-info-bar</emphasis> parameter set to "true".</para>
          <para xml:id="DEV.CreateYourOwnPortal.Overriding">
<citetitle>
<emphasis role="bold">Override Sharedlayout.xml</emphasis>
</citetitle>
</para>
          <para>To override the <emphasis role="italic">sharedlayout.xml</emphasis> file, you need to add your configuration file into the <emphasis role="italic">custom-extension.war/WEB-INF/conf/portal/portal/Sharedlayout.xml</emphasis> file.</para>
          <note>
            <para>Remember to configure your extension loaded to override the other <emphasis role="italic">sharedlayout.xml</emphasis> configuration.</para>
          </note>
          <para xml:id="DEV.CreateYourOwnPortal.CustomizeAdminbar">
<citetitle>
<emphasis role="bold">Example of the Sharedlayout.xml configuration: Customize the Admin bar</emphasis>
</citetitle>
</para>
          <para>The <emphasis role="bold">Admin</emphasis> bar is a special container which is composed of portlets and defined in <emphasis role="italic">WEB-INF/conf/portal/portal/sharedlayout.xml</emphasis>.</para>
          <para>If you want to redefine these portlets, you need to override this file by creating your own <emphasis role="italic">sharedlayout.xml</emphasis> located into your extension: <emphasis role="italic">custom-extension.war!WEB-INF/conf/portal/portal/sharedlayout.xml</emphasis>.</para>
          <para>Followings are 3 typical examples of the Admin bar configuration: removing a portlet, adding a new portlet and changing the color scheme.</para>
          <para>
            <emphasis role="bold">Remove a portlet from the Admin bar</emphasis> <anchor id="DEV.CreateYourOwnPortal.RemoveAdminbarContent"/>
          </para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/admin_bar_portlets.png" format="PNG" scalefit="1" width="120mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/admin_bar_portlets.png" format="PNG" scalefit="0" width="120mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>In the illustration above, each circle represents a portlet defined in the <emphasis role="bold">Admin</emphasis> bar and configured in <emphasis role="italic">sharedlayout.xml</emphasis>.</para>
          <para>The <emphasis role="italic">sharedlayout.xml</emphasis> file configures the current displayed portlets on the <emphasis role="bold">Admin</emphasis> bar. For example, to remove the <emphasis role="bold">Dashboard</emphasis> menu, you will need to remove the following block:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[...
<container id="UserToolBarDashboardPortlet" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
  <portlet-application>
    <portlet>
      <application-ref>exoadmin</application-ref>
      <portlet-ref>UserToolbarDashboardPortlet</portlet-ref>
    </portlet>
    <access-permissions>Everyone</access-permissions>
    <show-info-bar>false</show-info-bar>
  </portlet-application>
</container>
 ...]]></programlisting>
          </programlistingco>
          <para>
            <emphasis role="bold">Add a portlet to the Admin bar</emphasis> <anchor id="DEV.CreateYourOwnPortal.AddAdminbarContent"/>
          </para>
          <para>In the same way you removed a portlet from the Admin bar, you can add your own portlet by editing your <emphasis role="italic">sharedlayout.xml</emphasis>.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[...
<container id="UILogoutPortlet" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
  <access-permissions>*:/platform/users</access-permissions>
  <portlet-application>
    <portlet>
      <application-ref>platformNavigation</application-ref>
      <portlet-ref>UILogoutPortlet</portlet-ref>
    </portlet>
    <access-permissions>*:/platform/users</access-permissions>
    <show-info-bar>false</show-info-bar>
  </portlet-application>
</container>
...]]></programlisting>
          </programlistingco>
          <para>The style of portlet container can be changed by editing the CSS file: <emphasis role="italic">eXoResources/skin/DefaultSkin/portal/webui/component/view/UIToolbarContainer/Stylesheet.css</emphasis>.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[.UIToolbarContainer .UILogoutPortletTDContainer {
	float: right; /* orientation=lt */
	float: left; /* orientation=rt */
}]]></programlisting>
          </programlistingco>
          <para>
            <emphasis role="bold">Change the color scheme</emphasis> <anchor id="DEV.CreateYourOwnPortal.ChangeColorScheme"/>
          </para>
          <para>The current color of the <emphasis role="bold">Admin</emphasis> bar is gray gradient. However, you can change the color to match your brand colors.</para>
          <para>The default style of the <emphasis role="bold">Admin</emphasis> bar.</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/admin_bar.png" format="PNG" scalefit="1" width="120mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/admin_bar.png" format="PNG" scalefit="0" width="120mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>The style of the <emphasis role="bold">Admin</emphasis> bar is defined in the <emphasis role="bold">stylesheet.css</emphasis> located in <emphasis role="italic">extension/resources/src/main/webapp/skin/platformSkin/UIToolbarContainer</emphasis>.</para>
          <para>Edit this CSS file to customize the <emphasis role="bold">Admin</emphasis> bar to your preferred color scheme.</para>
          <para>The CSS code below shows how to modify the <emphasis role="bold">Admin</emphasis> bar to look like this:</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/modified_admin_bar.png" format="PNG" scalefit="1" width="120mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/modified_admin_bar.png" format="PNG" scalefit="0" width="120mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[.UIWorkingWorkspace #UIToolbarContainer .HomeLinkTDContainer {
	line-height: 31px;
    margin: 0px 5px;
    vertical-align: middle;
}

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

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

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

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

.UIWorkingWorkspace .UIToolbarContainer .ToolbarContainer a.SetupMenuItem  {
	padding: 0 8px;
	line-height:25px;
 }]]></programlisting>
          </programlistingco>
        </section>
      </section>
      <section id="DEV.CreateYourOwnPortal.CustomizeDocumentSkin" role="NotInToc">
        <title>Customize Document's skin </title>
        <note>
          <para>This section is related to the configuration. You can see a sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/wcm-extension/wcm/nodetypes-configuration.xml">here.</ulink>
          </para>
        </note>
        <para>First, you need to create a new document definition.</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/document/ACustomizedDocument.xml</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[code type name :exo:customizedDocument
properties: exo:name(type : String), exo:title(type : String), exo:content(type : String)]]></programlisting>
        </programlistingco>
        <para>You also need to configure it to make sure it is imported to the database.</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/document/definition-configuration.xml</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<external-component-plugins>
  <target-component>org.exoplatform.services.jcr.RepositoryService</target-component>
  <component-plugin>
    <name>ACustomizedDocument</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.jcr.impl.AddNodeTypePlugin</type>
    <priority>200</priority>
    <init-params>
      <values-param>
        <name>autoCreatedInNewRepository</name>
        <description>ACustomizedDocument document definition</description>
        <value>war:/conf/myportal/customized/document/ACustomizedDocument.xml</value>
      </values-param>
    </init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
        </programlistingco>
        <para>Next, create the templates for this document, including:</para>
        <itemizedlist>
          <listitem>
            <para>Dialog: see the sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/dms-extension/dms/artifacts/templates/article/dialogs/dialog1.gtmpl">here.</ulink>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/document/dialog.gtmpl</emphasis>
        </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[<div class="UIForm ACustomizedDocument">
  <% uiform.begin() %>
  <!-- Document dialog content is here -->
  <% uiform.end() %>]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>View: see the sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/dms-extension/dms/artifacts/templates/article/views/view1.gtmpl">here.</ulink>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/document/view.gtmpl</emphasis>
        </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[<style>
  <% _ctx.include(uicomponent.getTemplateSkin("exo:customizedDocument", "Stylesheet")); %>
</style>
<!-- Document view template content is here -->]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>Stylesheet: see the sample <ulink url="http://svn.exoplatform.org/projects/ecms/tags/2.1.0-GA/packaging/wcm/webapp/src/main/webapp/WEB-INF/conf/dms-extension/dms/artifacts/templates/article/skins/Stylesheet-lt.css">here.</ulink>
            </para>
          </listitem>
        </itemizedlist>
        <note>
          <para>This document should contain ONLY the stylesheet for THIS template.</para>
        </note>
        <para>
          <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/document/stylesheet.css</emphasis>
        </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[/* ... */

.ACustomizedDocument {
  /* ... */
}

/* ... */]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>You also need to import them to the database.</para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="italic">&lt;myportal_path&gt;/src/main/webapp/WEB-INF/conf/myportal/customized/document/template-configuration.xml</emphasis>
        </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<external-component-plugins>
  <target-component>org.exoplatform.services.cms.templates.TemplateService</target-component>
  <component-plugin>
    <name>addTemplates</name>
    <set-method>addTemplates</set-method>
    <type>org.exoplatform.services.cms.templates.impl.TemplatePlugin</type>
    <init-params>
      <value-param>
        <name>autoCreateInNewRepository</name>
        <value>true</value>
      </value-param>
      <value-param>
        <name>storedLocation</name>
        <value>war:/conf/myportal/customized/document</value>
      </value-param>
      <value-param>
        <name>repository</name>
        <value>repository</value>
      </value-param>
      <object-param>
        <name>template.configuration</name>
        <description>configuration for the localtion of nodetypes templates to inject in jcr</description>
        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig">
          <field name="nodeTypes">
            <collection type="java.util.ArrayList">
              <value>
                <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$NodeType">
                  <field name="nodetypeName">
                    <string>exo:customizedDocument</string>
                  </field>
                  <field name="documentTemplate">
                    <boolean>true</boolean>
                  </field>
                  <field name="label">
                    <string>Customized Document</string>
                  </field>
                  <field name="referencedView">
                    <collection type="java.util.ArrayList">
                      <value>
                        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                          <field name="templateFile">
                            <string>view.gtmpl</string>
                          </field>
                          <field name="roles">
                            <string>*</string>
                          </field>
                        </object>
                      </value>
                    </collection>
                  </field>
                  <field name="referencedDialog">
                    <collection type="java.util.ArrayList">
                      <value>
                        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                          <field name="templateFile">
                            <string>dialog.gtmpl</string>
                          </field>
                          <field name="roles">
                            <string>webdesigner:/platform/web-contributors</string>
                          </field>
                        </object>
                      </value>
                    </collection>
                  </field>
                  <field name="referencedSkin">
                    <collection type="java.util.ArrayList">
                      <value>
                        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                          <field name="templateFile">
                            <string>stylesheet.css</string>
                          </field>
                          <field name="roles">
                            <string>*</string>
                          </field>
                        </object>
                      </value>
                    </collection>
                  </field>
                </object>
              </value>
            </collection>
          </field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
        </programlistingco>
        <para>Finally, you should create some initial contents and export them to XML files.</para>
        <para>To import this XML into database, you can set up the deployment like this:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<external-component-plugins>
  <target-component>org.exoplatform.services.wcm.deployment.WCMContentInitializerService</target-component>
  <component-plugin>
    <name>Content Initializer Service</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.wcm.deployment.plugins.XMLDeploymentPlugin</type>
    <description>XML Deployment Plugin</description>
    <init-params>
      <object-param>
        <name>ACME Logo data</name>
        <description>Deployment Descriptor</description>
        <object type="org.exoplatform.services.deployment.DeploymentDescriptor">
          <field name="target">
            <object type="org.exoplatform.services.deployment.DeploymentDescriptor$Target">
              <field name="repository">
                <string>repository</string>
              </field>
              <field name="workspace">
                <string>collaboration</string>
              </field>
              <field name="nodePath">
                <string>/sites content/live/acme/web contents/site artifacts</string>
              </field>
            </object>
          </field>
          <field name="sourcePath">
            <string>war:/conf/wcm/artifacts/site-resources/acme/Logo.xml</string>
          </field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
</external-component-plugins>]]></programlisting>
        </programlistingco>
      </section>
      <section id="DEV.CreateYourOwnPortal.BestPracticeToCustomizeSkin" role="NotInToc">
        <title>Best practices to customize a skin </title>
        <para>The skin folder structure must be prepared once you start the design. Follow these conventions and best practices to ease the integration of your design in eXo Platform.</para>
        <para>
          <emphasis role="bold">Name files and folders</emphasis> <anchor id="DEV.CreateYourOwnPortal.NameFiles&amp;Folder"/>
        </para>
        <para>The id and class names are defined after the WebUI components name and portlets name with the 'UI-' as prefix. The same rule is applied for folder that contains components and portlets. It will help you find and edit correct files easily. For example, the UI portlet will be named as UIFooterPortlet, or UIBannerPortlet and the UI component will be named as UIToolbarContainer, or UIVerticalTab.</para>
        <para>
          <emphasis role="bold">Folder structure</emphasis> <anchor id="DEV.CreateYourOwnPortal.FolderStructure"/>
        </para>
        <citetitle>
<para>
<emphasis role="bold">Portal skins</emphasis>
</para>
</citetitle>
        <para>The portal skin will appear as a single link to a CSS file. This link will contain content from all the portal skin classes merged into one file. This enables the portal skin to be transferred more quickly as a single file instead of many smaller files included with every page render.</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">The general folder structure for portal skin:</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <code>/webapp/skin/NameOfPortalSkin/portal</code>
        </para>
        <para>For example:</para>
        <para>
          <code>/webapp/skin/DefaultSkin/portal</code>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">The main entry CSS file:</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>The main entry CSS file should be placed right in the main portal skin folder. The file is the main entry point to the CSS class definitions for the skin:</para>
        <para>
          <code>/webapp/skin/NameOfPortalSkin/Stylesheet.css</code>
        </para>
        <para>For example:</para>
        <para>
          <code>/webapp/skin/SkinBlue/Stylesheet.css</code>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">The folder structure for WebUI components:</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <code>/webapp/skin/SkinBlue/webui/component/YourUIComponentName</code>
        </para>
        <para>For example:</para>
        <para>
          <code>/webapp/skin/SkinBlue/webui/component/UIToolbarContainer</code>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Window decorator CSS is put in:</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <code>webapp/skin/PortletThemes/Stylesheet.css</code>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Where to put images for portal skin?</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>The images for portal skin should be put in the background folder right in the Portal skin folder and for each UI component.</para>
        <para>For example:</para>
        <para> <code>/webapp/skin/SkinBlue/webui/component/UIProfileUser/SkinBlue/background</code>
        </para>
        <para>In summary, the folder structure for a new portal skin should be:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[webapp
|- skin
|--- NameOfPortalSkin
|----- stylesheet.css
|------- webui
|---------- component
|------------ UIComponentName
|--------------- NameOfPortalSkin.css
|--------------- NameOfPortalSkin
|------------------ background]]></programlisting>
        </programlistingco>
        <citetitle>
<para>
<emphasis role="bold">Portlet skin</emphasis>
</para>
</citetitle>
        <para>Each portlet on a page may contribute its own style. The link to the portlet skin will only appear on the page if that portlet is loaded on the current page. A page may contain many portlet skin CSS links or none. The link ID will be named like {portletAppName}{PortletName}. For example,  ContentPortlet in <emphasis role="italic">content.war</emphasis> will have the <emphasis role="italic">id="contentContentPortlet"</emphasis>.</para>
        <para>
          <emphasis role="bold">General folder structure for portlet skin:</emphasis> <emphasis role="italic">/webapp/skin/portlet/webui/component/YourUIPortletName</emphasis>
        </para>
        <para>and for the Groovy skin: <emphasis role="italic">/webapp/groovy/portlet/webui/component/YourUIPortletName</emphasis>/</para>
        <para>For example:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">/webapp/skin/portlet/webui/component/UIBannerPortlet</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">/webapp/groovy/portlet/webui/component/UIBannerPortlet</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="bold">Portlet images folder:</emphasis> <emphasis role="italic">/webapp/skin/portlet/YourUIPortletName/PortalSkinName/background</emphasis>
        </para>
        <para>For example:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">/webapp/skin/portlet/UIBannerPortlet/BlueSkin/background</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="bold">Portlet themes</emphasis>
        </para>
        <para>Main entry CSS:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">/webapp/skin/PortletThemes/Stylesheet.css</emphasis>           s</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">/webapp/skin/PortletThemes/background</emphasis>
            </para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">/webapp/skin/PortletThemes/icons</emphasis>
            </para>
          </listitem>
        </itemizedlist>
      </section>
    </section>
    <section id="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">
      <title>Add JavaScript to your portal </title>
      <para>This can be done entirely within your extension by customizing the <emphasis role="italic">gatein-resources.xml</emphasis> configuration.</para>
      <para>To add a JavaScript library, for example jQuery, create the <emphasis role="italic">war:/WEB-INF/gatein-resources.xml</emphasis> file.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<javascript>
  <param>
    <js-module>jQuery</js-module>
    <js-path>/javascript/jQuery.js</js-path>
    <js-priority>0</js-priority>
  </param>
</javascript>]]></programlisting>
      </programlistingco>
      <para>In which:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="italic">&lt;js-module&gt;</emphasis> is the namespace of your JavaScript.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="italic">&lt;js-path&gt;</emphasis> is the path to your JavaScript file.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="italic">&lt;js-priority&gt;</emphasis> is an optional tag. This tag is used to indicate the loading order of JavaScript files across all eXo Platform. Its value is of the integer type. If its value is not negative (&gt;=0), the loading priority is sorted by the descending order. If its value is negative (&lt;0), the loading priority of the JavaScript file depends on the loading order of the web app (.war file) containing the JavaScript file.</para>
        </listitem>
      </itemizedlist>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">Create custom templates for pages</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal.Create_custom_templates_for_pages">
      <title>Create custom templates for pages </title>
      <para>eXo Platform 3.5 provides you with some built-in templates when you create a new page via <emphasis role="bold">Page Creation Wizard</emphasis>. In this section, you will learn how to create a custom page template for <emphasis role="bold">Page Creation Wizard</emphasis>.</para>
      <para>You should use the extension to add the page layout configuration. In this guide, you are going to work with the <emphasis role="italic">/examples/extension</emphasis> project.</para>
      <para>
<citetitle>
<emphasis role="bold">
Create a custom page template
</emphasis>
</citetitle>
</para>
      <para>
        <emphasis role="bold">1.</emphasis> Add your sample template "FourRowsLayout" by overriding the <emphasis role="italic">PageConfigOptions.groovy</emphasis> file (portal.war).</para>
      <para>Add it to this path: <emphasis role="italic">/examples/extension/war/src/main/webapp/WEB-INF/conf/uiconf/portal/webui/page/PageConfigOptions.groovy</emphasis>
      </para>
      <para>
        <mediaobject>
          <imageobject role="fo">
            <imagedata align="center" fileref="images/PageConfigOptions.groovy.png" format="PNG" scalefit="1" width="60mm"/>
          </imageobject>
          <imageobject role="html">
            <imagedata align="center" fileref="images/PageConfigOptions.groovy.png" format="PNG" scalefit="0" width="60mm"/>
          </imageobject>
        </mediaobject>
      </para>
      <para>Sample code:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="java"><![CDATA[...
SelectItemCategory samplePageConfigs = new SelectItemCategory("samplePageConfigs"):
categories.add(samplePageConfigs):
samplePageConfigs.addSelectItemOption(new SelectItemOption("samplePage.FourRowsLayout","four-rows","FourRowsLayout:"));
...]]></programlisting>
      </programlistingco>
      <para>
        <emphasis role="bold">2.</emphasis> Add your template file into the <emphasis role="italic">/examples/extension/war/src/main/webapp/WEB-INF/conf/portal/template/pages/four-rows/page.xml</emphasis> file.</para>
      <para>
        <mediaobject>
          <imageobject role="fo">
            <imagedata align="center" fileref="images/page.xml.png" format="PNG" scalefit="1" width="60mm"/>
          </imageobject>
          <imageobject role="html">
            <imagedata align="center" fileref="images/page.xml.png" format="PNG" scalefit="0" width="60mm"/>
          </imageobject>
        </mediaobject>
      </para>
      <para>Sample code:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[<page
xmlns:xsi="http://www.w3.org.2001/XMLSchema-instance"
xsi:schemaLocation="httlp://www.gatein.org/xml/ns/gatein_object_1_2.xsd http://gatein.org/xml/ns/gatein_object_1_2.xsd"
xmlns:"http://gatein.org/xml/ns/gatein_object_1_2.xsd">
<name></name>
<container template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
<access-permission>Everyone<access-permission>
</container>

<container template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
<access-permission>Everyone<access-permission>
</container>

<container template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
<access-permission>Everyone<access-permission>
</container>

<container template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
<access-permission>Everyone<access-permission>
</container>
</page>]]></programlisting>
      </programlistingco>
      <para>You can refer to the default template of eXo Platform in this path: <emphasis role="italic">/web/portal/src/main/webapp/WEB-INF/conf/portal/template/pages</emphasis>
      </para>
      <para>
        <emphasis role="bold">3</emphasis>. Add the stylesheet to make the template preview image.</para>
      <para>Add your own stylesheet in your extension webapp:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[.UIItemSelector .<FourRowsLayout>{
 width: 270px; height: 170px;
 margin: auto;
 background: url('background/ItemSelector.gif') no-repeat left -1700px;
}]]></programlisting>
      </programlistingco>
      <para>You can refer to the eXo Platform 3.5's default stylesheet in this path: <emphasis role="italic">/web/eXoResources/src/main/webapp/skin/DefaultSkin/webui/component/UISelector/UIItemSelector/Stylesheet.css</emphasis>
      </para>
      <para>
        <emphasis role="bold">4</emphasis>. Deploy your extension project. You will see the template and its preview image in the <emphasis role="bold">Page Creation Wizard</emphasis>.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateExtensionProject">Create your extension project</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.Create_default_portal">Define a default portal</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.StructureOfPortalPages&amp;Menus">Structure of portal, pages and menus</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.EnableDisableDriveCreation">Enable/Disable a drive creation</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddOrRemoveLanguages">Add/Remove a language</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.CreateCustomLookAndFeel">Create a custom look and feel</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.CreateYourOwnPortal.AddJavaScriptToYourPortal">Add JavaScript to your portal</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
  </chapter>
  <chapter id="DEV.WorkingwithContent">
    <title>Work With Content </title>
    <abstract>
<para>This chapter represents issues related to creating a new content manually via the following topics:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.WorkWithContent.NodeType">Node type</link>
            </emphasis>
	</para>
	<para>
	Ways to define your node type and document type, as well as to select types of Content template.
	</para>
  </listitem>
  <listitem>
	<para>
	 <emphasis role="bold">
              <link linkend="DEV.WorkWithContent.DialogSyntax">Dialog Syntax</link>
            </emphasis>
	</para>
	<para>
	Groovy Templates that generate forms by mixing static HTML fragments and Groovy calls to the components responsible for building the UI at runtime.
	</para>
  </listitem>
  <listitem>
	<para>
	 <emphasis role="bold"> <link linkend="DEV.WorkWithContent.CKEditor">Customize CKEditor</link>
            </emphasis>
	</para>
	<para>
	A WYSIWYG editor (text editor) which allows you to see what the published results look like while editing your text.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.WorkWithContent.Taxonomy">Taxonomy</link>
            </emphasis>
	</para>
	<para>
	A particular classification arranged in a hierarchical structure that helps you organize your content into categories.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.WorkWithContent.ManageTemplateService">Template Service</link>
            </emphasis>
	</para>
	<para>
	A service which allows developers to create dialogs and view templates for each node type register.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.WorkWithContent.NavigationByContent">Navigation By Content</link>
            </emphasis>
	</para>
	<para>
	A feature which allows developers to browse content of each page easily. With this feature, users experiencing eXo Platform 3.5 can navigate from a page to another or browse site content inside one page directly from a contextual menu.
	</para>
  </listitem>
</itemizedlist>
</abstract>
    <note>
      <para>eXo Platform provides you with 2 options to create the content for your new extension:</para>
      <itemizedlist>
        <listitem>
          <para>Create new content manually.</para>
        </listitem>
        <listitem>
          <para>Import an existing content into your extension.</para>
        </listitem>
      </itemizedlist>
    </note>
    <section id="DEV.WorkWithContent.NodeType">
      <title>Node type </title>
      <para>To create a content for your extension, you first need to define a node type which represents the document type in the JCR. There are 2 ways to define your node type:</para>
      <itemizedlist>
        <listitem>
          <para>Via the <emphasis role="bold">Content Administration</emphasis> portlet. For more details on how to create a note type via the <emphasis role="bold">Content Administration</emphasis> portlet, see the <emphasis role="bold">
              <ulink url="../../../user-guide/html/sect-User_Guide-Content_Types-Manage_Node_Types.html">Manage node types</ulink>
            </emphasis> in the eXo Platform 3.5 user guide.</para>
        </listitem>
        <listitem>
          <para>Via the .xml configuration files by creating a <emphasis role="italic">nodetypes-configuration.xml</emphasis> file in your extension as below.</para>
        </listitem>
      </itemizedlist>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<nodeType hasOrderableChildNodes="false" isMixin="true" name="exo:newnodetype" primaryItemName="">
  <supertypes>
    <supertype>exo:article</supertype>
  </supertypes>
  <propertyDefinitions>
    <propertyDefinition autoCreated="true" mandatory="true" multiple="false" name="text" onParentVersion="COPY" protected="false" requiredType="String">
      <valueConstraints/>
    </propertyDefinition>
    <propertyDefinition autoCreated="false" mandatory="true" multiple="false" name="date" onParentVersion="COPY" protected="false" requiredType="Date">
      <valueConstraints/>
    </propertyDefinition>

  </propertyDefinitions>
</nodeType>]]></programlisting>
      </programlistingco>
      <para>By defining a supertype, you can reuse other node types and extend them with more properties (just like inheritance in Object Oriented Programming).</para>
      <para xml:id="DEV.WorkWithContent.DocumentType">
<citetitle>
<emphasis role="bold">
Document type
</emphasis>
</citetitle>
</para>
      <para>The <emphasis role="bold">Document Type</emphasis> checkbox is to define if the node type should be a <emphasis role="bold">Document Type</emphasis> or not. If this checkbox is selected, the <emphasis role="bold">Sites Explorer</emphasis> considers such nodes as user content and applies the following behavior:</para>
      <itemizedlist>
        <listitem>
          <para>The <emphasis role="bold">View</emphasis> template will be used to display the <emphasis role="bold">DocumentType</emphasis> nodes.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>The document types nodes can be created by the <emphasis role="bold">Add Content</emphasis> action. The forms shown in the <emphasis role="bold">Add Document</emphasis> action are the corresponding <emphasis role="bold">Dialog</emphasis> templates of each document type.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>Non-document types are hidden unless the <emphasis role="bold">Show Non-document Nodes</emphasis> option is checked.</para>
        </listitem>
      </itemizedlist>
      <para>Templates are written using Groovy Templates and will require experiences with JCR API and HTML notions.</para>
      <para xml:id="DEV.WorkWithContent.WCMTemplate">
<citetitle>
<emphasis role="bold">
Content template
</emphasis>
</citetitle>
</para>
      <para>After defining your node type, you need to select templates which are applied to a node type or a metadata mixin type. eXo Platform provides 2 types of Content templates, including:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">dialogs</emphasis> which are HTML forms for creating node instances.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">views</emphasis> which are HTML fragments for displaying nodes.</para>
        </listitem>
      </itemizedlist>
      <para>From the <emphasis role="bold">Content Administration</emphasis> portlet, the <emphasis role="bold">Manage Template</emphasis> module lists all existing node types that have been associated with <emphasis role="bold">Dialog</emphasis> and/or <emphasis role="bold">View</emphasis> templates. These templates can be attached to permissions (in the usual <emphasis role="italic">membership:group</emphasis> form), so which specific templates are displayed according to user rights (which can be useful in a content validation workflow activity).</para>
      <para>
<citetitle>
<emphasis role="bold">
Enable JavaScrip
</emphasis>
</citetitle>
</para>
      <para>In eXo Platform, you can specify whether JavaScript is allowed to run on a field of the content template or not by using the <emphasis role="italic">"option"</emphasis> parameter.</para>
      <para>
        <emphasis role="bold">1.</emphasis> Go to <emphasis role="bold">Content Administration --&gt; Content Presentation --&gt; Manage Templates</emphasis>.</para>
      <para>
        <emphasis role="bold">2.</emphasis> Edit your desired template.</para>
      <para>
        <emphasis role="bold">3.</emphasis> Select the <emphasis role="bold">Dialog</emphasis> tab, and then edit the content of <emphasis role="italic">Dialog1</emphasis> in the <emphasis role="bold">View &amp; Edit Template</emphasis> form.</para>
      <para>
        <emphasis role="bold">4.</emphasis> Add <emphasis role="italic">option = noSanitization</emphasis> to the code in the <emphasis role="bold">Main</emphasis> field as the example below.</para>
      <para>For example:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[String [] htmlArguments = ["jcrPath = / node / default.html / JCR: content / JCR: data", "options = toolbar: CompleteWCM, height: '410px ', noSanitization" htmlContent];]]></programlisting>
      </programlistingco>
      <note>
        <para>By default, JavaScript is disabled for any fields of some content templates to prevent the XSS attacks.</para>
      </note>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.DialogSyntax">Dialog Syntax</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.CKEditor">Customize CKEditor</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.Taxonomy">Taxonomy</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.ManageTemplateService">Template Service</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NavigationByContent">Navigation By Content</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.WorkWithContent.DialogSyntax">
      <title>Dialog Syntax </title>
      <highlights>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.Interceptors">Interceptors</link>
            </para>
			<para>
			By placing interceptors in your template, you will be able to execute a Groovy script just before and just after saving the node. 
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.HiddenFields">Hidden fields</link>
            </para>
			<para>
			Information about the hidden fields of Content.
			</para>
          </listitem>
        </itemizedlist>
<para>Dialogs are Groovy Templates that generate forms by mixing static HTML fragments and Groovy calls to the components responsible for building the UI at runtime. As a result, you will get a simple but powerful syntax.</para>
</highlights>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NodeType">Node type</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.CKEditor">Customize CKEditor</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.Taxonomy">Taxonomy</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.ManageTemplateService">Template Service</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NavigationByContent">Navigation By Content</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.WorkWithContent.Interceptors" role="NotInToc">
        <title>Interceptors </title>
        <para>By placing interceptors in your template, you will be able to execute a Groovy script just before and just after saving the node. Pre-save interceptors are mostly used to validate input values and their overall meaning while the post-save interceptor can be used to do some manipulations or references for the newly created node, such as binding it with a forum discussion or wiki space.</para>
        <para>To place interceptors, use the following fragment:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[<% uicomponent.addInterceptor("ecm-explorer/interceptor/PreNodeSaveInterceptor.groovy", "prev");%>]]></programlisting>
        </programlistingco>
        <para>Interceptor Groovy scripts are managed in the 'Manage Script' section in the ECM admin portlet. They must implement the CmsScript interface. Pre-save interceptors obtain input values within the context:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[public class PreNodeSaveInterceptor implements CmsScript {

  public PreNodeSaveInterceptor() {
  }

  public void execute(Object context) {
    Map inputValues = (Map) context;
    Set keys = inputValues.keySet();
    for(String key : keys) {
      JcrInputProperty prop = (JcrInputProperty) inputValues.get(key);
      println("   --> "+prop.getJcrPath());
    }
  }

  public void setParams(String[] params) {
  }

}]]></programlisting>
        </programlistingco>
        <para>Whereas the post-save interceptor is passed the path of the saved node in the context:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[<% uicomponent.addInterceptor("ecm-explorer/interceptor/PostNodeSaveInterceptor.groovy", "post");%>

public class PostNodeSaveInterceptor implements CmsScript {

  public PostNodeSaveInterceptor() {
  }

  public void execute(Object context) {
    String path = (String) context;

    println("Post node save interceptor, created node: "+path);
  }

  public void setParams(String[] params) {
  }
}]]></programlisting>
        </programlistingco>
      </section>
      <section id="DEV.WorkWithContent.HiddenFields" role="NotInToc">
        <title>Hidden fields </title>
        <para>In the next code sample, each argument is composed of a set of keys and values. The order of arguments are not important and only the key matters. That example defines a field with the id as "hiddenField2", which will generate a hidden field. The value of this field will be automatically set to UTF-8 and no visible field will be printed on the form.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] hiddenField2 = ["jcrPath=/node/jcr:content/jcr:encoding", "visible=false", "UTF-8"];
uicomponent.addHiddenField("hiddenInput2", hiddenField2);]]></programlisting>
        </programlistingco>
        <para>Once the form has been saved, the date value will be saved under the relative JCR path ./exo:image/jcr:lastModified.</para>
        <para xml:id="DEV.WorkWithContent.Non-ValueField">
<citetitle>
<emphasis role="bold">Non-value field</emphasis>
</citetitle>
</para>
        <para>You cannot either see the non-value field on the form or input value for them. Its value will be automatically created or defined when you are managing templates.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] hiddenField1 = ["jcrPath=/node/jcr:content", "nodetype=nt:resource", "mixintype=dc:elementSet", "visible=false"] ;
uicomponent.addHiddenField("hiddenInput1", hiddenField1) ;]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.Non-EditableFields">
<citetitle>
<emphasis role="bold">Non-editable fields</emphasis>
</citetitle>
</para>
        <para>It is possible to create widgets that are non-editable (and then only used to print some information).</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] fieldCategories = ["jcrPath=/node/exo:category", "multiValues=true", "reference=true", "editable=false"]; uicomponent.addTextField("categories", fieldCategories);]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.CreateNodeTypeOrMixinType">
<citetitle>
<emphasis role="bold">Create node type or mixin type</emphasis>
</citetitle>
</para>
        <para>In many cases, when creating an instance where the node is out of form, you must still specify the CMS service about the node structure. Particularly, you must define if which node type is child of the newly created node or if the current node has any mixin type attributed.</para>
        <para>By defining these arguments, the node and its children are created with the correct node type and mixin type.</para>
        <para>See the following example:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] hiddenField = ["jcrPath=/node/jcrcontent", "nodetype=nt:resource", "mixintype=exo:rss-enable", "visible=false"] ;
uicomponent.addHiddenField("hiddenInput", hiddenField) ;]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.HiddenFieldWithDefaultValue">
<citetitle>
<emphasis role="bold">Hidden field with default value</emphasis>
</citetitle>
</para>
        <para>In the previous sample, the value was automatically created and set according to the current date. However, it is also possible to set a default value for a field.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] hiddenField = ["jcrPath=/node/jcrcontent/jcr:mimeType", "image/jpeg"] ;
uicomponent.addHiddenField("hiddenInput", hiddenField) ;]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.VisibleWithoutNullFields">
<citetitle>
<emphasis role="bold">Visible without null fields</emphasis>
</citetitle>
</para>
        <para>It is possible to tell that a widget should be visible only if its value is not null or when the form is used to edit the node which has been existing.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String nameArgs[] = ["jcrPath=/node", "mixintype=mix:votable", "visible=if-not-null"];
uicomponent.addMixinField("name", nameArgs )]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.WYSIWYGWidget">
<citetitle>
<emphasis role="bold">WYSIWYG widget</emphasis>
</citetitle>
</para>
        <para>Widgets are natively part of the eXo Platform product to provide a simple and easy way for users to get information and notification on their application. They complete the portlet application that focuses on more transactional behaviors. </para>
        <para>WYSIWYG stands for What You See Is What You Get. This widget is one of the most powerful tools. It renders an advanced JavaScript text editor with many functionalities, including the ability to dynamically upload images or flash assets into a JCR workspace and then to refer to them from the created HTML text.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] fieldSummary = ["jcrPath=/node/exo:summary", "options=basic"] ;
uicomponent.addWYSIWYGField("summary", fieldSummary) ;]]></programlisting>
        </programlistingco>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] fieldContent = ["jcrPath=/node/exo:text", "options=toolbar:CompleteWCM,'height:410px'", ""] ;
uicomponent.addRichtextField("content", fieldContent)]]></programlisting>
        </programlistingco>
        <para>The "options" argument is used to tell the component which toolbar should be used.</para>
        <para>By default, there are five options for the toolbar: CompleteWCM, Default, BasicWCM, Basic, SuperBasicWCM.</para>
        <itemizedlist>
          <listitem>
            <para>CompleteWCM: a full set of tools is shown.</para>
          </listitem>
        </itemizedlist>
        <para>The following buttons are shown: Source, Templates, Show Blocks, Cut, Copy, Paste Text, Undo, Redo, SpellCheck, WCM Insert Gadget, Flash, Table,  Insert Special Character, WCM Insert Content Link, Bold, Italic, Underline, Strike Through, Justify Left, Justify Center, Justify Right, Justify Full, Ordered List, Unordered List, Text Color, Background Color, Remove Format, Link, WCM Insert Portal Link, Unlink, Anchor, Style, Font Format, Font Name, Font Size, Maximize.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/CompleteWCMToolbar.png" format="PNG" scalefit="1" width="100mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/CompleteWCMToolbar.png" format="PNG" scalefit="0" width="100mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>Default: a large set of tools is shown, no "options" argument is needed in that case.</para>
          </listitem>
        </itemizedlist>
        <para>The following buttons are shown: Source, Templates, Cut, Copy, PasteText, Undo, Redo, SpellCheck, RemoveFormat, Bold, Italic, Underline, Strike Through, Ordered List, Unordered List, Link, Unlink, Anchor, Image, Flash, Table, Special Character, Text Color, Background Color, Show Blocks, Style, Font Format, Font Name, Font Size, Maximize.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/DefaultToolbar.png" format="PNG" scalefit="1" width="100mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/DefaultToolbar.png" format="PNG" scalefit="0" width="100mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>BasicWCM: a minimal set of tools is shown. </para>
          </listitem>
        </itemizedlist>
        <para>The following buttons are shown: Source, Bold, Italic, Underline, Strike Through, OrderedList, UnorderedList, Outdent, Indent, Justify Left, Justify Center, Justify Right, JustifyFull, Blockquote, Link, Unlink, WCM Insert Portal Link, WCM Insert Content Link, Show Blocks, Style, Font Format, Font Name, FontSize, Maximize.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/BasicWCMToolbar.png" format="PNG" scalefit="1" width="100mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/BasicWCMToolbar.png" format="PNG" scalefit="0" width="100mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>Basic: </para>
          </listitem>
        </itemizedlist>
        <para>The following buttons are shown: Source, Bold, Italic, Underline, Strike Through, Ordered List, Unordered List, Outdent, Indent, Justify Left, Justify Center, Justify Right, Justify Full, Blockquote, Link, Unlink, Show Blocks, Style, Font Format, Font Name, Font Size, Maximize.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/BasicTools.png" format="PNG" scalefit="1" width="100mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/BasicTools.png" format="PNG" scalefit="0" width="100mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>SuperBasicWCM: </para>
          </listitem>
        </itemizedlist>
        <para>The following buttons are shown: Source, Bold, Italic, Underline, Justify Left, Justify Center, Justify Right, Justify Full, Link, Unlink, WCM Insert Portal Link, WCM Insert Gadget, WCM Insert Content Link.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/SuperBasicWCMToolbar.png" format="PNG" scalefit="1" width="100mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/SuperBasicWCMToolbar.png" format="PNG" scalefit="0" width="100mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>There is also a simple text area widget, which has text-input area only: </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String [] descriptionArgs = ["jcrPath=/node/exo:title", "validate=empty"];
uicomponent.addTextAreaField("description", descriptionArgs) ;]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.Create_a_custom_Richtext_editor_fields">
<citetitle>
<emphasis role="bold">Create a custom RichText editor fields</emphasis>
</citetitle>
</para>
        <para>In the <link linkend="DEV.WorkWithContent.WYSIWYGWidget">WYSIWYG widget</link> section, you already know about a set of default toolbars (CompleteWCM, Default, BasicWCM, Basic, SuperBasicWCM). In this section, you will learn how to create a <emphasis role="bold">RichText</emphasis> editor with custom buttons.</para>
        <para>Just edit the configuration file and modify or add new items to the configuration file of the <emphasis role="bold">RichText</emphasis> editor is located in: <emphasis role="italic">apps/resource-static/src/main/Webapp/eXoConfig.js</emphasis>
        </para>
        <para>Take a look at the eXoConfig.js file to see a definition of a custom toolbar named "MyCustomToolbar":</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[FCKConfig.ToolbarSets["MyCustomToolbar"] = [
  ['Source','Templates','-','FitWindow','ShowBlocks'],
 ['Cut','Copy','PasteText','-','SpellCheck','-','Undo','Redo'],
 ['WCMInsertGadget','Flash','Table','SpecialChar', 'WCMInsertContent'],
 '/',
 ['Bold','Italic','Underline','StrikeThrough','-','JustifyLeft','JustifyCenter','JustifyRight','JustifyFull','-','OrderedList','UnorderedList','-','TextColor','BGColor','-','RemoveFormat'],
 ['Link','WCMInsertPortalLink','Unlink','Anchor'],
 '/',
 ['Style','FontFormat','FontName','FontSize']
] ;]]></programlisting>
        </programlistingco>
        <para>Every toolbar set is composed of a series of "toolbar bands" that are grouped in the final toolbar layout. The bands items move together on new rows when resizing the editor.</para>
        <para>Every toolbar band is defined as a separated JavaScript array of strings. Each string corresponds to an available toolbar item defined in the editor code or in a plugin.</para>
        <itemizedlist>
          <listitem>
            <para>Put the desired button names in square bracket ("[" &amp; "]") and separate them by commas to create a toolbar band. You can look at the above code to know all the possible toolbar item. If the toolbar item does not exist, a message will be displayed when loading the editor.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>Include a separator in the toolbar band by putting the "-" string on it.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>Separate each toolbar brands with commas.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>Use slash ("/") to tell the editor that you want to force the next bands to be rendered in a new row and not following the previous one.</para>
          </listitem>
        </itemizedlist>
        <note>
          <para>The last toolbar band must have no comma after it.</para>
        </note>
        <para xml:id="DEV.WorkWithContent.SimpleSelectBoxWidget">
<citetitle>
<emphasis role="bold">Simple select box widget</emphasis>
</citetitle>
</para>
        <para>The select box widget enables you to render a select box with static values. These values are enumerated in a comma-separated list in the "options" argument. The argument with no key (here "text/html") is selected by default.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] mimetype = ["jcrPath=/node/jcrcontent/jcr:mimeType", "text/html", "options=text/html,text/plain"] ;
uicomponent.addSelectBoxField("mimetype", mimetype) ;]]></programlisting>
        </programlistingco>
        <para>As usual, the value will be stored at the relative path defined by the jcrPath directive argument.</para>
        <para>For more examples on how to create WCM templates, refer to the <ulink url="../../../reference/html/CONTref.InsideWCMTemplates.html">WCM Templates</ulink> section.</para>
        <para xml:id="DEV.WorkWithContent.AdvancedDynamicSelectBox">
<citetitle>
<emphasis role="bold">Advanced dynamic select box</emphasis>
</citetitle>
</para>
        <para>In many cases, the previous solution with static options is not good enough and one would like to have the select box checked dynamically.  That is what eXo Platform provide thanks to the introduction of a Groovy script as shown in the code fragment below.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] args = ["jcrPath=/node/exodestWorkspace", "script=ecm-explorer/widget/FillSelectBoxWithWorkspaces:groovy", "scriptParams=production"];
uicomponent.addSelectBoxField("destWorkspace", args) ;]]></programlisting>
        </programlistingco>
        <para>The script itself implements the CMS Script interface and the cast is done to get the select box object as shown in the script code which fills the select box with the existing JCR workspaces.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[import java.util.List ;
import java.util.ArrayList ;

import org.exoplatform.services.jcr.RepositoryService;
import org.exoplatform.services.jcr.core.ManageableRepository;

import org.exoplatform.webui.form.UIFormSelectBox;
import org.exoplatform.webui.core.model.SelectItemOption;
import org.exoplatform.services.cms.scripts.CmsScript;

public class FillSelectBoxWithWorkspaces implements CmsScript {

  private RepositoryService repositoryService_;

  public FillSelectBoxWithWorkspaces(RepositoryService repositoryService) {
    repositoryService_ = repositoryService;
  }

  public void execute(Object context) {
    UIFormSelectBox selectBox = (UIFormSelectBox) context;

    ManageableRepository jcrRepository = repositoryService_.getRepository();
    List options = new ArrayList();
    String[] workspaceNames = jcrRepository.getWorkspaceNames();
    for(name in workspaceNames) {
      options.add(new SelectItem(name, name));
    }
    selectBox.setOptions(options);
  }

  public void setParams(String[] params) {
  }
}]]></programlisting>
        </programlistingco>
        <note>
          <para>It is also possible to provide a parameter to the script by using the argument "scriptParams".</para>
        </note>
        <para xml:id="DEV.WorkWithContent.WidgetWithSelector">
<citetitle>
<emphasis role="bold">Widget with selector</emphasis>
</citetitle>
</para>
        <para>One of the most advanced functionalities of this syntax is the ability to plug your own component that shows an interface, enabling you to select the value of the field.</para>
        <para>In the generated form, you will see an icon which is configurable thanks to the selectorIcon argument. The syntax is a bit more complex but not much.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] groupArgs = ["jcrPath=/node/exogroup", "selectorClass=org:exoplatform:ecm:webui:selector:UIGroupMemberSelector"];
uicomponent.addActionField("group", groupArgs);]]></programlisting>
        </programlistingco>
        <para>You can plug your own component using the selectorClass argument. It must follow the eXo UIComponent mechanism and implements the interface ComponentSelector:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[package org.exoplatform.ecm.webui.selector;

import org.exoplatform.webui.core.UIComponent;
public interface ComponentSelector {
  public UIComponent getSourceComponent() ;
  public void setSourceComponent(UIComponent uicomponent, String[] initParams) ;    
}]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.Multi-valueWidget">
<citetitle>
<emphasis role="bold">Multi-valued widget</emphasis>
</citetitle>
</para>
        <para>A widget can have multiple values if you add the argument "multiValues=true" to the directive.</para>
      </section>
    </section>
    <section id="DEV.WorkWithContent.CKEditor">
      <title>Customize CKEditor  </title>
      <highlights>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.CKEditor.Installation">Installation</link>
            </para>
			<para> 
			Instructions on how to do a fresh installation of CKEditor and steps to upgrade an existing CKEditor installation.
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.CKEditor.FileAndFolderStructure">File and Folder Structure</link>
            </para>
			<para>
			Information about the file and folder structure inside CKEditor and introduction to CKEditor in eXo Platform.
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.CKEditor.ConfigurationInCKEditor">Configuration in CKEditor</link>
            </para>
			<para>
			Instructions on how to set configurations, to change the CKEditor skin, to add a new toolbar, and to create a basic plugin for CKEditor.
			</para>
          </listitem>
        </itemizedlist>
<para>CKEditor is a WYSIWYG editor (text editor) which allows you to see what the published results look like while editing your text. It brings to the common web-editing features found on desktop-editing applications like Microsoft Word, and OpenOffice.
To have more information about a WYSIWYG editor, see the <link linkend="DEV.WorkWithContent.WYSIWYGWidget">WYSIWYG widget</link> section.</para>
</highlights>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NodeType">Node type</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.DialogSyntax">Dialog Syntax</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.Taxonomy">Taxonomy</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.ManageTemplateService">Template Service</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NavigationByContent">Navigation By Content</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.WorkWithContent.CKEditor.Installation" role="NotInToc">
        <title>Installation </title>
        <para>You can install CKEditor easily by selecting an appropriate procedure (fresh installation or upgrade) by doing the following steps:</para>
        <para xml:id="DEV.WorkWithContent.CKEditor.RefreshInstallation">
<citetitle>
<emphasis role="bold">
Fresh Installation
</emphasis>
</citetitle>
</para>
        <note>
          <para>This way is used to install CKEditor for the first time.</para>
        </note>
        <para>
          <emphasis role="bold">1.</emphasis> Download the latest version of the editor <ulink url="http://ckeditor.com/download">here</ulink>.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Extract (decompress) the downloaded archive to a directory called <emphasis role="italic">ckeditor</emphasis> in the root of your website.</para>
        <note>
          <para> You can place the files in any path of your website. The <emphasis role="italic">ckeditor</emphasis> directory is the default one.</para>
        </note>
        <para xml:id="DEV.WorkWithContent.CKEditor.Upgrade">
<citetitle>
<emphasis role="bold">
Upgrade an existing CKEditor installation
</emphasis>
</citetitle>
</para>
        <para>
          <emphasis role="bold">1.</emphasis> Rename your old editor folder to a backup folder, for example, "ckeditor_old".</para>
        <para>
          <emphasis role="bold">2.</emphasis> Download the latest version of the editor <ulink url="http://ckeditor.com/download">here</ulink>.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Extract/Decompress the downloaded archive to the original editor directory, for example, "ckeditor".</para>
        <para>
          <emphasis role="bold">4.</emphasis> Copy all configuration files that you have changed from the backup folder to their corresponding positions in the new directory. These files could include (but not limited to) the following files:</para>
        <itemizedlist>
          <listitem>
            <para>config.js</para>
          </listitem>
          <listitem>
            <para>contents.css</para>
          </listitem>
          <listitem>
            <para>plugins/templates/templates/default.js</para>
          </listitem>
          <listitem>
            <para>plugins/styles/styles/default.js</para>
          </listitem>
          <listitem>
            <para>plugins/pastefromword/filter/default.js</para>
          </listitem>
        </itemizedlist>
      </section>
      <section id="DEV.WorkWithContent.CKEditor.FileAndFolderStructure" role="NotInToc">
        <title>File and Folder Structure </title>
        <para xml:id="DEV.WorkWithContent.CKEditor.InsideCKEditor">
<citetitle>
<emphasis role="bold">
Inside CKEditor
</emphasis>
</citetitle>
</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/ckeditor_folder.png" format="PNG" width="120m"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/ckeditor_folder.png" format="PNG" width="120m"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>There are the following folders:</para>
        <informaltable>
          <thead>
            <tr>
              <th>Folders</th>
              <th> Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>samples</td>
              <td> Contain CKEditor samples.</td>
            </tr>
            <tr>
              <td>source</td>
              <td>Contain CKEditor source code.</td>
            </tr>
            <tr>
              <td>adapters</td>
              <td>Contain CKEditor adapters. It may be removed if you do not use any adapters, like the jQuery one.</td>
            </tr>
            <tr>
              <td>images</td>
              <td>Contain CKEditor graphics files.</td>
            </tr>
            <tr>
              <td>lang</td>
              <td>Contain CKEditor language files.</td>
            </tr>
            <tr>
              <td>plugins</td>
              <td>Contain plugin files and is necessary for CKEditor to work.</td>
            </tr>
            <tr>
              <td>skins</td>
              <td>Contain CKEditor skin files along with toolbar buttons and stylesheet definitions.</td>
            </tr>
            <tr>
              <td>themes</td>
              <td>Contains CKEditor theme.</td>
            </tr>
          </tbody>
        </informaltable>
        <informaltable>
          <thead>
            <tr>
              <th>Files</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>ckeditor.js</td>
              <td> The heart of CKEditor application. It is the unique compressed file which contains all of codes to run CKEditor.</td>
            </tr>
            <tr>
              <td>ckeditorbasic.js</td>
              <td> The compressed file like <emphasis role="italic">ckeditor.js</emphasis>, but it is only a bootstrap which contains the core functionality only, so the rest of the code can be loaded at later time, avoiding delaying the initial load of the page.</td>
            </tr>
            <tr>
              <td>ckeditorsource.js</td>
              <td> An uncompressed version of <emphasis role="italic">ckeditor.js</emphasis>.</td>
            </tr>
            <tr>
              <td>ckeditorbasicsource.js</td>
              <td> An uncompressed version of <emphasis role="italic">ckeditorbasic.js</emphasis>.</td>
            </tr>
            <tr>
              <td>config.js</td>
              <td>Allow users to customize some configurations.</td>
            </tr>
            <tr>
              <td>contents.css</td>
              <td> Define the stylesheets of the CKEditor application.</td>
            </tr>
            <tr>
              <td>ckeditor.asp</td>
              <td>Used for ASP integration.</td>
            </tr>
            <tr>
              <td>ckeditor.php</td>
              <td>Used for PHP integration.</td>
            </tr>
            <tr>
              <td>ckeditorphp4.php</td>
              <td> Used for PHP4 integration.</td>
            </tr>
            <tr>
              <td>ckeditorphp5.php</td>
              <td> Used for PHP5 integration.</td>
            </tr>
            <tr>
              <td>ckeditor.pack</td>
              <td> Re-build the compression version of 2 files: <emphasis role="italic">ckeditor.js</emphasis>, and <emphasis role="italic">ckeditorbasic.js</emphasis>.</td>
            </tr>
          </tbody>
        </informaltable>
        <para xml:id="DEV.WorkWithContent.CKEditor.CKEditorIneXoPlatform">
<citetitle>
<emphasis role="bold">
CKEditor in Context of eXo Platform
</emphasis>
</citetitle>
</para>
        <para>There is a <emphasis role="italic">.war</emphasis> package named <emphasis role="italic">eXoStaticResources</emphasis> which integrates the CKEditor application into eXo Platform. The source code is placed inside the <emphasis role="italic">apps/resources-static/src/main/webapp</emphasis> folder.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/static_resources.png" format="PNG" width="50mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/static_resources.png" format="PNG" width="50mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>Its structure consists of the folders and files below:</para>
        <informaltable>
          <thead>
            <tr>
              <th>Folders &amp; Files</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>ckeditor</td>
              <td> Contain all source codes of CKEditor v3.3.2.</td>
            </tr>
            <tr>
              <td>eXoPlugins</td>
              <td> Contain the source code of 3 external plugins: {}Insert Content Link{}, {}Insert Portal Link{}, {}WCM Insert Gadget{}.</td>
            </tr>
            <tr>
              <td>eXoConfig.js</td>
              <td>Register 3 external plugins, and define some types of the toolbar.</td>
            </tr>
            <tr>
              <td>eXoPlugins.js</td>
              <td> Define some utility functions which can be used by 3 external plugins.</td>
            </tr>
          </tbody>
        </informaltable>
      </section>
      <section id="DEV.WorkWithContent.CKEditor.ConfigurationInCKEditor" role="NotInToc">
        <title>Configuration in CKEditor </title>
        <para xml:id="DEV.WorkWithContent.CKEditor.SettingConfiguration">
<citetitle>
<emphasis role="bold">
Set configurations
</emphasis>
</citetitle>
</para>
        <para>CKEditor comes with a rich set of configuration options that make it possible to customize its appearance, features, and behavior. The main configuration file is named <emphasis role="italic">config.js</emphasis>. This file can be found in the root of the CKEditor installation folder (<emphasis role="italic">/webapps/eXoStaticResources/ckeditor/config.js</emphasis>). By default, this file is mostly empty. To change the CKEditor configuration, add the settings that you want to modify to the <emphasis role="italic">config.js</emphasis> file.</para>
        <para>For example:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[CKEDITOR.editorConfig = function( config )
{
    config.language = 'en';
    config.uiColor = '#AADC6E';
};]]></programlisting>
        </programlistingco>
        <para>Instead of using the default <emphasis role="italic">config.js</emphasis> file, you can create a copy of that file in anywhere in your website and simply point the editor instances to load it. For example, in eXo Platform, the configuration file for CKEditor is placed at <emphasis role="italic">/webapps/eXoStaticResources/eXoConfig.js</emphasis>, so the content of the <emphasis role="italic">config.js</emphasis> file will be:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[CKEDITOR.editorConfig = function( config )
{
    config.customConfig = "../eXoConfig.js";
};]]></programlisting>
        </programlistingco>
        <para xml:id="DEV.WorkWithContent.CKEditor.Skin">
<citetitle>
<emphasis role="bold">
Change the CKEditor skin
</emphasis>
</citetitle>
</para>
        <para>You can change the CKEditor skin by adjusting a single configuration option. In eXo Platform, to change the CKEditor skin, do as follows:</para>
        <para>
          <emphasis role="bold">1.</emphasis> Open the <emphasis role="italic">/webapps/eXoStaticResources/eXoConfig.js</emphasis> configuration file of CKEditor.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Set up a skin for CKEditor. It may be the name of the skin folder inside the editor installation path, or the name and the path separated by a comma.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[config.skin = 'v2';
config.skin = 'myskin,/customstuff/myskin/';]]></programlisting>
        </programlistingco>
        <para>By default, CKEditor has 3 skins for users to select: <emphasis role="bold">v2</emphasis>, <emphasis role="bold">kama</emphasis>, and <emphasis role="bold">office2003</emphasis>. They are placed in the <emphasis role="italic">/webapps/eXoStaticResources/ckeditor/skins</emphasis> folder.</para>
        <para xml:id="DEV.WorkWithContent.CKEditor.Toolbar">
<citetitle>
<emphasis role="bold">
Add a new toolbar
</emphasis>
</citetitle>
</para>
        <para>CKEditor is a full-featured WYSIWYG editor, but not all of its options are needed in all cases. Therefore, the toolbar customization is one of the most common and required tasks when dealing with CKEditor.</para>
        <para>
          <anchor id="DEV.WorkWithContent.CKEditor.ToolbarDefinition"/>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Toolbar Definition</emphasis> is a JavaScript array which contains the elements to be displayed in all toolbar rows available in the editor. In eXo Platform, the toolbar definition is placed in the <emphasis role="italic">/webapps/eXoStaticResources/eXoConfig.js</emphasis> file. The following code snippet contains the default CKEditor toolbar set in eXo Platform.</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[config.toolbar_Default = [
     ['Source','Templates'],
     ['Cut','Copy','PasteText','-','SpellCheck'],
     ['Undo','Redo','-','RemoveFormat'],
    '/',
     ['Bold','Italic','Underline','Strike'],
     ['NumberedList','BulletedList'],
     ['Link','Unlink','Anchor'],
     ['Image','Flash','Table','SpecialChar'],
     ['TextColor','BGColor'],
     ['Maximize', 'ShowBlocks'],
     ['Style','Format','Font','FontSize']
] ;]]></programlisting>
        </programlistingco>
        <para>
          <anchor id="DEV.WorkWithContent.CKEditor.AddNewToolbar"/>
        </para>
        <itemizedlist>
          <listitem>
            <para>To add a new toolbar in eXo Platform, open the <emphasis role="italic">/webapps/eXoStaticResources/eXoConfig.js</emphasis> configuration file of CKEditor, then add the following code snippet to it.</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[config.toolbar_MyToolbar =
[
 ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink','-','About']
];]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>To show the newly added toolbar, you have to add it to a field of a WCM template. For example, to show  the new toolbar on the content field of HTML file, you need to modify the dialog template of HTML file as follows:</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[String[] fieldSummary = ["jcrPath=/node/jcr:content/jcr:data", "", "options=toolbar:MyToolbar, noSanitization"] ;
uicomponent.addRichtextField("contentHtml", fieldSummary) ;]]></programlisting>
        </programlistingco>
        <para>By adding a new HTML file, you will see the new toolbar (MyToolbar) on the content field:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/MyToolbar.png" format="PNG" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/MyToolbar.png" format="PNG" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para xml:id="DEV.WorkWithContent.CKEditor.CreatePluginForCKEditor">
<citetitle>
<emphasis role="bold">
Create a basic plugin for CKEditor
</emphasis>
</citetitle>
</para>
        <para>Assuming that you will develop a <emphasis role="italic">timestamp</emphasis> plugin that inserts the current date and time into the editing area of CKEditor. The <emphasis role="italic">timestamp</emphasis> will be added after a user clicks a dedicated toolbar button. The implementation makes use of the <emphasis role="italic">insertHtml</emphasis> function which can be also easily adjusted to insert any other HTML elements into CKEditor.</para>
        <para>
          <emphasis role="bold">1.</emphasis> Create a directory inside the <emphasis role="italic">eXoPlugins</emphasis> directory for CKEditor with the <emphasis role="italic">timestamp</emphasis> plugin.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Place the <emphasis role="italic">plugin.js</emphasis> file that contains the plugin logic inside the newly created <emphasis role="italic">timestamp</emphasis> folder. Also, you will need a toolbar icon for the plugin by adding an <emphasis role="italic">images</emphasis> folder and subsequently placing the <emphasis role="italic">timestamp.png</emphasis> file inside it.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Modify the <emphasis role="italic">plugin.js</emphasis> file in which you will write the behavior.</para>
        <para>The following is the code used to create a simple plugin named <emphasis role="italic">timestamp</emphasis>:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[CKEDITOR.plugins.add( 'timestamp',
{
 init: function( editor )
 {
  editor.addCommand( 'insertTimestamp',
   {
    exec : function( editor )
    {
     var timestamp = new Date();
     editor.insertHtml( 'The current date and time is: <em>' + timestamp.toString() + '</em>' );
    }
   });
  editor.ui.addButton( 'Timestamp',
  {
   label: 'Insert Timestamp',
   command: 'insertTimestamp',
   icon: this.path + 'images/timestamp.png'
  } );
 }
} );]]></programlisting>
        </programlistingco>
        <para>To use the created plugin, plug it to CKEditor by using the following code:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[ (function() {CKEDITOR.plugins.addExternal('timestamp',CKEDITOR.eXoPath+'eXoPlugins/timestamp/','plugin.js');})();
    ....
    config.extraPlugins = 'content,insertGadget,insertPortalLink,timestamp';
    ....
    config.toolbar_MyToolbar =
    [
                   ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink','-','About','Timestamp']
    ];]]></programlisting>
        </programlistingco>
        <para>The following is the illustration about the Timestamp plugin added to the CKEditor.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/Timestamp.png" format="PNG" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/Timestamp.png" format="PNG" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
      </section>
    </section>
    <section id="DEV.WorkWithContent.Taxonomy">
      <title>Taxonomy </title>
      <para>Taxonomy is a particular classification arranged in a hierarchical structure. The Taxonomy trees in eXo Platform will help you organize your content into categories.</para>
      <para>When you create a new taxonomy tree, you will add a pre-configured <emphasis role="italic">exo:action</emphasis> (<emphasis role="italic">exo:scriptAction</emphasis> or <emphasis role="italic">exo:businessProcessAction</emphasis>) to the root node of the taxonomy tree. This action is triggered when a new document is added anywhere in the taxonomy tree. The default action moves the document to the physical storage location and replaces the document in the taxonomy tree with a symlink of the <emphasis role="italic">exo:taxonomyLink</emphasis> type pointing to it. The physical storage location is defined by a workspace name, a path and the current date and time.</para>
      <itemizedlist>
        <listitem>
          <para>Like adding document types, taxonomy trees can be managed through the <emphasis role="bold">Content Administration</emphasis> portlet, or by adding .xml configuration files.</para>
        </listitem>
      </itemizedlist>
      <para>
<citetitle>
<emphasis role="bold">
Configure a taxonomy tree by adding the configuration files in the <emphasis>/webapp/WEB-INF/conf/acme-portal/wcm/taxonomy/</emphasis> directory
</emphasis>
</citetitle>
</para>
      <para>Create a new file called <emphasis role="italic">$taxonomyName-taxonomies-configuration.xml</emphasis>. For example, if the name of your taxonomy tree is "acme", the file should be named <emphasis role="italic">acme-taxonomies-configuration.xml</emphasis>.</para>
      <itemizedlist>
        <listitem>
          <para>You can view the file in <emphasis role="italic">$PLF-HOME_/samples/acme-website/webapp/src/main/webapp/WEB-INF/conf/acme-portal/wcm/taxonomy/acme-taxonomies-configuration.xml</emphasis>.</para>
          <itemizedlist>
            <listitem>
              <para>The value-params enable you to define the repository, workspace, name of the tree and its JCR path. </para>
            </listitem>
            <listitem>
              <para>You can then configure permissions for each group of users in the portal, and the triggered action when a new document is added to the taxonomy tree. </para>
            </listitem>
            <listitem>
              <para>Finally, you can describe the structure and names of the categories inside your taxonomy tree.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NodeType">Node type</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.DialogSyntax">Dialog Syntax</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.CKEditor">Customize CKEditor</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.ManageTemplateService">Template Service</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NavigationByContent">Navigation By Content</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.WorkWithContent.ManageTemplateService">
      <title>Template Service </title>
      <para>
        <emphasis role="bold">Template Service</emphasis> enables you to create dialogs and view templates for each registered node type. Each node type may have many dialogs and view templates. The template will be used when creating or viewing nodes.</para>
      <para>You can find the template service configuration in <emphasis role="italic">/webapps/ecm-wcm-core/WEB-INF/conf/wcm-core/core-services-configuration.xml</emphasis>.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.services.cms.templates.TemplateService</key>
  <type>org.exoplatform.services.cms.templates.impl.TemplateServiceImpl</type>
</component>]]></programlisting>
      </programlistingco>
      <para>As usual, one can register a plugin inside the service. This plugin initializes default dialogs and views template of any node type as nt:file, exo:article, exo:workflowAction, exo:sendMailAction, and more.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<component-plugins>
  <component-plugin>
    <name>addTemplates</name>
    <set-method>addTemplates</set-method>
    <type>org.exoplatform.services.cms.templates.impl.TemplatePlugin</type>
    .........
  </component-plugin>
</component-plugins>]]></programlisting>
      </programlistingco>
      <para>With init-parameters as:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<init-params>
  <value-param>
    <name>autoCreateInNewRepository</name>
    <value>true</value>
  </value-param>
  <value-param>
    <name>storedLocation</name>
    <value>war:/conf/ecm/artifacts/templates</value>
  </value-param>
  <value-param>
    <name>repository</name>
    <value>repository</value>
  </value-param>
  <object-param>
    <name>template.configuration</name>
    <description>configuration for the location of templates to inject in jcr</description>
    <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig">
      <field name="nodeTypes">
        <collection type="java.util.ArrayList">
          <value>
            <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$NodeType">
              <field name="nodetypeName">
                <string>exo:article</string>
              </field>
              <field name="documentTemplate">
                <boolean>true</boolean>
              </field>
              <field name="label">
                <string>Article</string>
              </field>
              <field name="referencedView">
                <collection type="java.util.ArrayList">
                  <value>
                    <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                      <field name="templateFile">
                        <string>/article/views/view1.gtmpl</string>
                      </field>
                      <field name="roles">
                        <string>*</string>
                      </field>
                    </object>
                  </value>
                </collection>
              </field>
              <field name="referencedDialog">
                <collection type="java.util.ArrayList">
                  <value>
                    <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                      <field name="templateFile">
                        <string>/article/dialogs/dialog1.gtmpl</string>
                      </field>
                      <field name="roles">
                        <string>*</string>
                      </field>
                    </object>
                  </value>
                </collection>
              </field>
            </object>
          </value>
        </collection>
      </field>
    </object>
  </object-param>
</init-params>]]></programlisting>
      </programlistingco>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NodeType">Node type</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.DialogSyntax">Dialog Syntax</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.CKEditor">Customize CKEditor</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.Taxonomy">Taxonomy</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NavigationByContent">Navigation By Content</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.WorkWithContent.NavigationByContent">
      <title>Navigation By Content </title>
      <highlights>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.NavigationByContent.ContentNavigation">Actual content navigation</link>
            </para>
			<para>Steps to add "actual content navigation" to a page, including the way to configure the right and left portlets.</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.NavigationByContent.Add_content_to_the_navigation">Add content to the navigation</link>
            </para>
			<para>The detailed procedure to attach your root folder/node to some page nodes.</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.NavigationByContent.ActionsNavigationByContent">Actions on Navigation By Content</link>
            </para>
			<para>Instructions on how to restrict the visibility of some content, to sort elements of the contextual menu, to restore a node to the contextual menu and attach it to another page, and to add your newly created content to the contextual menu.</para>
          </listitem>
		  <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.NavigationByContent.CreateDataForNavigationByContentExamples">Create data for Navigation By Content</link>
            </para>
			<para>TWO typical examples of creating data for <emphasis role="bold">Navigation By Content</emphasis>, including how to create a Product page, and to develop your own Product content.</para>
          </listitem>
		  <listitem>
			<para>
			  <link linkend="DEV.WorkWithContent.CreateNewContentListTemplate">Create a new Content List template</link>
			</para>
			<para>
			Knowledge and typical steps to create a new template that is used in the <emphasis role="bold">Content List</emphasis> portlet.
			</para>
		  </listitem>
        </itemizedlist>
<para>
          <emphasis role="bold">Navigation By Content</emphasis> is a feature which allows users to browse content of each page easily. With this feature, users experiencing eXo Platform 3.5 can navigate from a page to another or browse site content inside one page directly from a contextual menu.</para>
</highlights>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.NodeType">Node type</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.DialogSyntax">Dialog Syntax</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.CKEditor">Customize CKEditor</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.Taxonomy">Taxonomy</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithContent.ManageTemplateService">Template Service</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.WorkWithContent.NavigationByContent.ContentNavigation" role="NotInToc">
        <title>Actual content navigation </title>
        <para>One of the powerful features of Enterprise Content Management System (ECMS) that comes out with eXo Platform 3.5 is the ability to navigate in site content using taxonomies. This functionality can easily be added in a page with the help of two <emphasis role="bold">Content List Viewer</emphasis> (CLV) portlets. The pre-configured example can be found in the <emphasis role="bold">News</emphasis> page of the sample ACME website. In this example, all content in the <emphasis role="italic">/Sites Management/acme/events/All</emphasis> node will be used.</para>
        <citetitle>
<para>
<emphasis role="bold">Add "Actual content navigation" to a page</emphasis>
</para>
</citetitle>
        <para>
          <emphasis role="bold">1.</emphasis> Log into the sample ACME website.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Add a new page, for example "Events".</para>
        <para>
          <emphasis role="bold">3.</emphasis> Parameterize this page with the <emphasis role="bold">Autofit Two Columns</emphasis> container.</para>
        <para>
          <emphasis role="bold">4.</emphasis> Add two <emphasis role="bold">Content List</emphasis> portlets to each column.</para>
        <para>
          <emphasis role="bold">5.</emphasis> Add content.</para>
        <para>
          <emphasis role="bold">i. Configure the left portlet as follows</emphasis>:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/browseByCLV.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/browseByCLV.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>In which:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Folder path</emphasis> = <emphasis role="italic">/Sites Management/acme/events/All</emphasis>: The path to the folder that contains the content.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Header</emphasis> = <emphasis role="italic">Browse by</emphasis>: The title of all content that is listed in the content list viewer.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Template</emphasis> = <emphasis role="italic">CategoryTree.gtmpl</emphasis>: The template used for displaying the content list.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Contextual Folder</emphasis> = <emphasis role="italic">Disabled</emphasis>: The Contextual Content property is set to "Disable", the Advanced pane is closed by default and a single content will be opened by an URL containing the content path. </para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Show in page</emphasis> =<emphasis role="italic">Events</emphasis>: A single content in CLV will be shown in the <emphasis role="bold">Events</emphasis> page.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">With</emphasis> = <emphasis role="italic">folder-id</emphasis>: The parameter containing the content path. </para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="bold">ii. Configure the right portlet as follows</emphasis>:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/showListCLV.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/showListCLV.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>In which:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Folder path</emphasis> = <emphasis role="italic">/Sites Management/acme/events/All</emphasis>: The path to the folder that contains the content.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Template</emphasis> = <emphasis role="italic">OneColumnCLVTemplate.gtmpl</emphasis>: The template used for displaying the content list.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Contextual Folder</emphasis> = <emphasis role="italic">Enabled</emphasis>: The Contextual Content property is set to "Enable". This portlet is configured with the provided parameter (content-id by default).</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Show in page</emphasis> = <emphasis role="italic">Details</emphasis>: A single content in CLV will be shown in the "Details" page.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">With</emphasis> = <emphasis role="italic">content-id</emphasis>: The parameter containing the content path.</para>
          </listitem>
        </itemizedlist>
        <para>As a result, the created <emphasis role="bold">Events</emphasis> page will look like:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/eventsPage.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/eventsPage.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>You can now navigate from the left portlet to see content displayed in the right portlet.</para>
        <para>The new <emphasis role="bold">Navigation By Content</emphasis> feature will traduce this example in a contextual menu.</para>
      </section>
      <section id="DEV.WorkWithContent.NavigationByContent.Add_content_to_the_navigation" role="NotInToc">
        <title>Add content to the navigation </title>
        <citetitle>
<para>
<emphasis role="bold">Attach your root folder/node to some page nodes from the homepage (the drop-down menu holds your new contextual menu)
</emphasis>
</para>
</citetitle>
        <para>
          <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Explorer</emphasis> page and navigate to <emphasis role="italic">/Sites Management/acme/events/All</emphasis>.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Click the <emphasis role="bold">Content Navigation</emphasis> button, the <emphasis role="bold">Navigation</emphasis> form will appear. If you do not see this button on the <emphasis role="bold">Action</emphasis> bar, add this button via the <emphasis role="bold">Content Administration</emphasis> page.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Fill values into the <emphasis role="bold">Content Navigation</emphasis> form:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Navigation_form.png" format="PNG" scalefit="1" width="100mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Navigation_form.png" format="PNG" scalefit="0" width="100mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>In which:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Visible</emphasis> = true. This node will be navigable.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Target parent navigation</emphasis> = Events. The contextual menu will be attached to the <emphasis role="bold">Events</emphasis> drop-down menu.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Clickable</emphasis> = false. This node will not be clickable.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Page for list</emphasis> = catalog. This page is a system page that contains a <emphasis role="bold">Content List Viewer</emphasis> portlet and will be used to display the list of child nodes.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Page for detail</emphasis> = detail. This page is a system page that contains a <emphasis role="bold">Single Content Viewer</emphasis> portlet and will be used to display details of child nodes.</para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="bold">4.</emphasis> Save changes, then go back to the ACME homepage. You will see changes from the <emphasis role="bold">Events</emphasis> drop-down menu.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/contextualMenu.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/contextualMenu.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>In which:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Visible</emphasis>: The <emphasis role="italic">/Sites Management/acme/events/All</emphasis> node is navigable and its child nodes are rendered in the contextual menu.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Target parent navigation</emphasis>: The <emphasis role="italic">/Sites Management/acme/events/All</emphasis> node is attached to the site menu item called <emphasis role="bold">Events</emphasis>.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Clickable</emphasis>: The <emphasis role="italic">/Sites Management/acme/events/All</emphasis> node is not clickable but all of its child nodes are clickable.</para>
          </listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Page for list</emphasis>: The list of child nodes (if a child node is <emphasis role="bold">directory/folder</emphasis>) will be rendered in the following page.</para>
          </listitem>
        </itemizedlist>
        <para>Click the <emphasis role="bold">Earth</emphasis> menu item from the contextual menu, you will see that content of the <emphasis role="bold">Earth</emphasis> directory are rendered in a separate page (catalog):</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/listEarth.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/listEarth.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Page for detail</emphasis>: The details of child nodes (if a child node is a sample content) will be rendered in this page.</para>
          </listitem>
        </itemizedlist>
        <para>Select the <emphasis role="bold">Power 1 - Fire</emphasis> menu item from the contextual menu to see the <emphasis role="bold">Fire</emphasis> content displayed in a separate page (details):</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Power1_fire_item.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Power1_fire_item.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
      </section>
      <section id="DEV.WorkWithContent.NavigationByContent.ActionsNavigationByContent" role="NotInToc">
        <title>Actions on Navigation By Content </title>
        <citetitle>
<para>
<emphasis role="bold">Restrict the visibility of some content</emphasis>
</para>
</citetitle>
        <para>
          <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Explorer</emphasis> page and navigate to the <emphasis role="italic">/Sites Management/acme/events/All/Fire</emphasis> node.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Click the <emphasis role="bold">Content Navigation</emphasis> button to open the <emphasis role="bold">Navigation</emphasis> form.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Uncheck the <emphasis role="bold">Visible</emphasis> field and save.</para>
        <para>
          <emphasis role="bold">4.</emphasis> Go back to the ACME homepage. You will see that the <emphasis role="bold">Fire</emphasis> sub-menu is not displayed in the contextual menu anymore.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Restrict_content_visibility.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Restrict_content_visibility.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <citetitle>
<para>
<emphasis role="bold">Sort elements of the contextual menu</emphasis>
</para>
</citetitle>
        <para>
          <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Explorer</emphasis> page and navigate to the <emphasis role="italic">/Sites Management/acme/events/All</emphasis> node.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Select the <emphasis role="italic">/Sites Management/acme/events/All/Earth</emphasis> node.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Click the <emphasis role="bold">Content Navigation</emphasis> button to open the <emphasis role="bold">Navigation</emphasis> form.</para>
        <para>
          <emphasis role="bold">4.</emphasis> Set the <emphasis role="bold">Display order</emphasis> field to "1" and save.</para>
        <para>
          <emphasis role="bold">5.</emphasis> Select the <emphasis role="italic">/Sites Management/acme/events/All/Water</emphasis> node.</para>
        <para>
          <emphasis role="bold">6.</emphasis> Click the <emphasis role="bold">Content Navigation</emphasis> button.</para>
        <para>
          <emphasis role="bold">7.</emphasis> Set the <emphasis role="bold">Display order</emphasis> field to "2" and save.</para>
        <para>
          <emphasis role="bold">8.</emphasis> Select the <emphasis role="italic">/Sites Management/acme/events/All/Air</emphasis> node.</para>
        <para>
          <emphasis role="bold">9.</emphasis> Click the <emphasis role="bold">Content Navigation</emphasis> button.</para>
        <para>
          <emphasis role="bold">10.</emphasis> Set the <emphasis role="bold">Display order</emphasis> field to "3" and save.</para>
        <para>
          <emphasis role="bold">11.</emphasis> Go back to the ACME homepage. You will see that the display order from the contextual menu is <emphasis role="bold">Earth</emphasis>, <emphasis role="bold">Water</emphasis>, <emphasis role="bold">Air</emphasis>. Note that the <emphasis role="bold">Fire</emphasis> sub-menu is not displayed because it is set to "Invisible" in the previous example.</para>
        <citetitle>
<para>
<emphasis role="bold">Restore a node to the contextual menu and attach it to another page</emphasis>
</para>
</citetitle>
        <para>
          <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Explorer</emphasis> page and navigate to the <emphasis role="italic">/Sites Management/acme/events/All/Fire</emphasis> node.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Click the <emphasis role="bold">Content Navigation</emphasis> button to open the <emphasis role="bold">Navigation</emphasis> form.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Fill values into the <emphasis role="bold">Navigation</emphasis> form fields, including:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Visible</emphasis> = true</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Target parent navigation</emphasis> = News</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Clickable</emphasis> = false</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Page for list</emphasis> = catalog</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Page for detail</emphasis> = detail</para>
          </listitem>
        </itemizedlist>
        <para>
          <emphasis role="bold">4.</emphasis> Save changes and go back to the <emphasis role="bold">Acme/Overview</emphasis> homepage. You will see that the <emphasis role="bold">Fire</emphasis> node is attached to the <emphasis role="bold">News</emphasis> drop-down menu from the site menu:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Attach_node_ to_another_page.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Attach_node_ to_another_page.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>However, if you want to add your newly created content directly to the contextual menu, you need to add the <emphasis role="bold">populateToMenu</emphasis> action first.</para>
        <citetitle>
<para>
<emphasis role="bold">Add your newly created content to the contextual menu</emphasis>
</para>
</citetitle>
        <para>
          <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Explorer</emphasis> page and navigate to the <emphasis role="italic">/Sites Management/acme/events/All/Fire</emphasis> node.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Click the <emphasis role="bold">Actions</emphasis> button and add the <emphasis role="bold">exo:populateToMenu</emphasis> action.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/populateToMenuAction.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/populateToMenuAction.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>
          <emphasis role="bold">3.</emphasis> Create a document under the <emphasis role="italic">/Sites Management/acme/events/All/Fire</emphasis> node and publish it.</para>
        <para>
          <emphasis role="bold">4.</emphasis> Go back to the homepage. You will see that your newly created document is added to the contextual menu.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/docPDF.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/docPDF.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>The sample ACME website comes with a configured navigation by content menu:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/productsMenu.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/productsMenu.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>You can click the <emphasis role="bold">Vision</emphasis> sub-menu and see content of <emphasis role="bold">Vision</emphasis> directory rendered in the <emphasis role="bold">catalog</emphasis> page:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/visionSubMenuList.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/visionSubMenuList.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>Select the <emphasis role="bold">X-Ray</emphasis> content and see the newly implemented content using new visual effects and presentation.</para>
        <itemizedlist>
          <listitem>
            <para>"Benefits" and "Features" tabs:</para>
          </listitem>
        </itemizedlist>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Benefits_tab.png" format="PNG" scalefit="1" width="150mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/Benefits_tab.png" format="PNG" scalefit="0" width="150mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>Coverflow section:</para>
          </listitem>
        </itemizedlist>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/coverflow.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/coverflow.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <itemizedlist>
          <listitem>
            <para>Related documents:</para>
          </listitem>
        </itemizedlist>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/navigation_by_content_feature/relatedDocuments.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/navigation_by_content_feature/relatedDocuments.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
      </section>
      <section id="DEV.WorkWithContent.NavigationByContent.CreateDataForNavigationByContentExamples" role="NotInToc">
        <title>Create data for Navigation By Content </title>
        <para>
<itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.NavigationByContent.CreateDataForNavigationByContentExamples.CreateNewProductPage">Create a Product page</link>
            </para>
			<para>Steps to create content and to add media files to enrich the Product page.</para>
          </listitem>
		   <listitem>
            <para>
              <link linkend="DEV.WorkWithContent.NavigationByContent.CreateDataForNavigationByContentExamples.DevelopProductContent">Develop your own Product content</link>
            </para>
			<para>Steps to create fields in the Product content type, and to develop the Product's view form.</para>
          </listitem>
</itemizedlist>
</para>
        <note>
          <para>By following 2 typical examples above, you can create data for Navigation By Content easily.</para>
        </note>
        <section id="DEV.WorkWithContent.NavigationByContent.CreateDataForNavigationByContentExamples.CreateNewProductPage" role="NotInToc">
          <title>Create a Product page </title>
          <citetitle>
<para>
<emphasis role="bold">Create content about the product</emphasis>
</para>
</citetitle>
          <para>
            <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Explorer</emphasis> page and navigate to <emphasis role="italic">somePath/someDirectory</emphasis>.</para>
          <para>
            <emphasis role="bold">2.</emphasis> Click the <emphasis role="bold">New Content</emphasis> button on the <emphasis role="bold">Action</emphasis> bar. There will be a several content type appears.</para>
          <para>
            <emphasis role="bold">3.</emphasis> Select the <emphasis role="bold">Product</emphasis> content type. </para>
          <para>
            <emphasis role="bold">4.</emphasis> Fill the <emphasis role="bold">Product</emphasis> dialog form.</para>
          <para>
            <emphasis role="bold">5.</emphasis> Save changes.</para>
          <citetitle>
<para>
<emphasis role="bold">Add media files to enrich the Product page</emphasis>
</para>
</citetitle>
          <para>
            <emphasis role="bold">1.</emphasis> Go to <emphasis role="italic">somePath/someDirectory/sampleProduct/medias/images</emphasis>.</para>
          <para>
            <emphasis role="bold">2.</emphasis> Click <emphasis role="bold">Upload</emphasis> on the <emphasis role="bold">Action</emphasis> bar to upload some images from your local device and publish them.</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductImages.png" format="PNG" scalefit="1" width="150mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductImages.png" format="PNG" scalefit="0" width="150mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>
            <emphasis role="bold">3.</emphasis> Go to <emphasis role="italic">somePath/someDirectory/sampleProduct/medias/videos</emphasis>.</para>
          <para>
            <emphasis role="bold">4.</emphasis> Click <emphasis role="bold">Upload</emphasis> on the <emphasis role="bold">Action</emphasis> bar to upload some videos from your local device and publish it.</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductVideos.png" format="PNG" scalefit="1" width="150mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductVideos.png" format="PNG" scalefit="0" width="150mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>
            <emphasis role="bold">5.</emphasis> Go to <emphasis role="italic">somePath/someDirectory/sampleProduct/documents</emphasis>.</para>
          <para>
            <emphasis role="bold">6.</emphasis> Create two directories, including <emphasis role="bold">Sale Materials</emphasis> and <emphasis role="bold">Technical Documentations</emphasis>.</para>
          <para>
            <emphasis role="bold">7.</emphasis> Upload a PDF document and publish it under each sub-folder.</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductDocuments.png" format="PNG" scalefit="1" width="150mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductDocuments.png" format="PNG" scalefit="0" width="150mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>
            <emphasis role="bold">8.</emphasis> Add your <emphasis role="bold">sampleProduct</emphasis> to some categories or add it to the <emphasis role="bold">Content List</emphasis> portlet.</para>
          <para>Your newly created product is now ready to be displayed in some pages.</para>
          <para>
            <emphasis role="bold">9.</emphasis> Publish your newly created product. Note that you can select this content from a CLV:</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductCLV.png" format="PNG" scalefit="1" width="100mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductCLV.png" format="PNG" scalefit="0" width="100mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <para>As a result, the content will be displayed in a detailed page as follows:</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductDetail.png" format="PNG" scalefit="1" width="100mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/navigation_by_content_feature/sampleProductDetail.png" format="PNG" scalefit="0" width="100mm"/>
              </imageobject>
            </mediaobject>
          </para>
        </section>
        <section id="DEV.WorkWithContent.NavigationByContent.CreateDataForNavigationByContentExamples.DevelopProductContent" role="NotInToc">
          <title>Develop your own Product content </title>
          <para>The sample <emphasis role="bold">Product</emphasis> page is composed of the following fields and folders:</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Product</emphasis> content type fields: Name, Title, Illustration Image, Summary, Benefits, and Features.</para>
            </listitem>
          </itemizedlist>
          <para>(The <emphasis role="bold">Product</emphasis> content type is the template specified for the <emphasis role="bold">Product</emphasis> page.)</para>
          <itemizedlist>
            <listitem>
              <para>Other content folders: documents, medias/images, medias/videos.</para>
            </listitem>
          </itemizedlist>
          <para>(These folders contain documents and media files to enrich the <emphasis role="bold">Product</emphasis> page.)</para>
          <citetitle>
<para>
<emphasis role="bold">Create fields in the Product content type</emphasis>
</para>
</citetitle>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Name</emphasis> Other content folders are created within the product content when the <emphasis role="bold">Name</emphasis> field is created. This can be achieved (from the .gtmpl product dialog) as follows:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<tr>
	<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.name")%></td>
	<td class="FieldComponent">
	<%
	String[] productFieldName = ["jcrPath=/node", "mixintype=mix:votable,mix:commentable","editable=if-null","validate=name,empty"] ;
	uicomponent.addTextField("name", productFieldName) ;
	String[] documentsFolder = ["jcrPath=/node/documents", "nodetype=nt:folder","mixintype=exo:documentFolder", "defaultValues=documents"] ;
	String[] mediasFolder = ["jcrPath=/node/medias", "nodetype=exo:multimediaFolder", "defaultValues=medias"] ;
	String[] imagesFolder = ["jcrPath=/node/medias/images", "nodetype=nt:folder", "defaultValues=images"] ;
	String[] videoFolder = ["jcrPath=/node/medias/videos", "nodetype=nt:folder", "defaultValues=videos"] ;
	uicomponent.addHiddenField("documentsFolder", documentsFolder);
	uicomponent.addHiddenField("mediasFolder", mediasFolder);
	uicomponent.addHiddenField("imagesFolder", imagesFolder);
	uicomponent.addHiddenField("videoFolder", videoFolder);
	%>
	</td>
</tr>]]></programlisting>
          </programlistingco>
          <para>
            <emphasis role="bold">Other fields are created almost in the same way:</emphasis>
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Title:</emphasis>
              </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<tr>
	<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.title")%></td>
	<td class="FieldComponent">
	<%
		String[] productFieldTitle = ["jcrPath=/node/exo:title", "validate=empty", "editable=if-null"];
		uicomponent.addTextField("title", productFieldTitle) ;
	%>
	</td>
</tr>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Illustration image</emphasis>:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<%
private void setUploadFields(name) {
	String[] illustrationHiddenField1 = ["jcrPath=/node/medias/images/illustration", "nodetype=nt:file", "mixintype=mix:referenceable", "defaultValues=illustration"];
	String[] illustrationHiddenField2 = ["jcrPath=/node/medias/images/illustration/jcr:content", "nodetype=nt:resource", "mixintype=dc:elementSet", "visible=false"];
	String[] illustrationHiddenField3 = ["jcrPath=/node/medias/images/illustration/jcr:content/jcr:encoding", "visible=false", "UTF-8"];
	String[] illustrationHiddenField4 = ["jcrPath=/node/medias/images/illustration/jcr:content/jcr:lastModified", "visible=false"];
	String[] illustrationHiddenField5 = ["jcrPath=/node/medias/images/illustration/jcr:content/dc:date", "visible=false"];
	uicomponent.addHiddenField("illustrationHiddenField1", illustrationHiddenField1);
	uicomponent.addHiddenField("illustrationHiddenField2", illustrationHiddenField2);
	uicomponent.addHiddenField("illustrationHiddenField3", illustrationHiddenField3);
	uicomponent.addCalendarField("illustrationHiddenField4", illustrationHiddenField4);
	uicomponent.addCalendarField("illustrationHiddenField5", illustrationHiddenField5);
	String[] fieldImage = ["jcrPath=/node/medias/images/illustration/jcr:content/jcr:data"] ;
	uicomponent.addUploadField(name, fieldImage) ;
}
%>
<tr>
	<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.illustrationImage")%></td>
	<td class="FieldComponent">
		<%
			String illustration = "illustration";
			if(ProductNode != null && ProductNode.hasNode("medias/images/illustration") && (uicomponent.findComponentById(illustration) == null)) {
				def imageNode = ProductNode.getNode("medias/images/illustration") ;
				def resourceNode = imageNode.getNode("jcr:content");
				if(resourceNode.getProperty("jcr:data").getStream().available() > 0) {
					def imgSrc = uicomponent.getImage(imageNode, "jcr:content");
					def actionLink = uicomponent.event("RemoveData", "/medias/images/illustration/jcr:content");
					%>
						<div>
							<image src="$imgSrc" width="100px" height="80px"/>
							<a onclick="$actionLink">
								<img src="/eXoResources/skin/DefaultSkin/background/Blank.gif" class="ActionIcon Remove16x16Icon"/>
							</a>
						</div>
					<%
				} else {
					setUploadFields(illustration);
				}
			} else {
				setUploadFields(illustration);
			}
		%>
	</td>
</tr>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Summary:</emphasis>
              </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<tr>
	<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.summary")%></td>
	<td class="FieldComponent">
	<%
		String[] fieldSummary = ["jcrPath=/node/exo:summary", "options=Basic", ""] ;
		uicomponent.addRichtextField("summary", fieldSummary) ;
	%>
	</td>
</tr>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Benefits:</emphasis>
              </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<tr>
	<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.benefits")%></td>
	<td class="FieldComponent">
	<div class="UIFCKEditor">
	<%
		String[] productFieldBenefits = ["jcrPath=/node/exo:productBenefits", "options=toolbar:CompleteWCM", ""] ;
		uicomponent.addRichtextField("productBenefits", productFieldBenefits) ;
	%>
	</div>
	</td>
</tr>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">Features:</emphasis>
              </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<tr>
	<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.features")%></td>
	<td class="FieldComponent">
	<div class="UIFCKEditor">
	<%
		String[] productFieldFeatures = ["jcrPath=/node/exo:productFeatures", "options=toolbar:CompleteWCM", ""] ;
		uicomponent.addRichtextField("productFeatures", productFieldFeatures) ;
	%>
	</div>
	</td>
</tr>]]></programlisting>
          </programlistingco>
          <citetitle>
<para>
<emphasis role="bold">Develop the Product's view form</emphasis>
</para>
</citetitle>
          <para>
            <emphasis role="bold">The illustration image, title and summary are grouped together:</emphasis>
          </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<!-- Hot news -->
<div class="BigNews ClearFix">
	<!-- Begin illustrative image -->
		<%
		RESTImagesRendererService imagesRenderer = uicomponent.getApplicationComponent(RESTImagesRendererService.class);
		def imageURI = imagesRenderer.generateImageURI(currentNode.getNode("medias/images/illustration"),null);
		if (imageURI != null){
		%>
	<a class="Image"><img width="93" src="$imageURI" alt=""></a>
		<%
		}
		%>
	<div class="Content">
	<!-- Begin title -->
	<%
	  if(currentNode.hasProperty("exo:title")) {
		def title = currentNode.getProperty("exo:title").getString();
		%>
		<a href="#" class="Title">$title</a>
		<div class="Index1">$title</div>
		<%
	  }
	%>
	<!-- End title -->
	<!-- Begin summary -->
		<%
		if(currentNode.hasProperty("exo:summary")) {
		def summary = currentNode.getProperty("exo:summary").getString();
		%>
		<div class="Summary">$summary</div>
		<%
		}
		%>
	<!-- End summary -->
	</div>
</div>]]></programlisting>
          </programlistingco>
          <para>In which:</para>
          <itemizedlist>
            <listitem>
              <para>Name: The name of the product.</para>
            </listitem>
            <listitem>
              <para>Title: The title of the product.</para>
            </listitem>
            <listitem>
              <para>Illustration Image: The image that is used as an illustration for the product.</para>
            </listitem>
            <listitem>
              <para>Summary: The summary about the product that goes with the illustration.</para>
            </listitem>
            <listitem>
              <para>Benefits: The benefits of the product.</para>
            </listitem>
            <listitem>
              <para>Features: The features of the product.</para>
            </listitem>
          </itemizedlist>
          <para>
            <emphasis role="bold">Benefits and Features fields are rendered in two tabs using the jQuery library (already integrated into eXo Platform 3.5).</emphasis>
          </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<div id="sectionsTabs" class="ui-tabs">
	<ul class="ui-tabs-nav ClearFix">
		<li class="ui-state-default">
			<!-- Begin Benefits head section -->
			<a class="ArrowCtrl" href="#tab-benefits"><%=_ctx.appRes("Product.view.label.benefits")%></a>
			<!-- End Benefits head section -->
		</li>
		<li class="ui-tabs-selected">
			<!-- Begin Features head section -->
			<a class="ArrowCtrl" href="#tab-features"><%=_ctx.appRes("Product.view.label.features")%></a>
			<!-- End Features head section -->
		</li>
	</ul>
	<div id="tab-benefits">
	  <%
		  if(currentNode.hasProperty("exo:productBenefits")) {
			def benefits = currentNode.getProperty("exo:productBenefits").getString();
			print benefits;
		  }
	  %>
	</div>
	<div id="tab-features">
	  <%
		  if(currentNode.hasProperty("exo:productFeatures")) {
			def features = currentNode.getProperty("exo:productFeatures").getString();
			print features;
		  }
	  %>
	</div>
</div>

<script type="text/javascript">
	jQuery.noConflict();
	jQuery(document).ready(function() {
		jQuery("#sectionsTabs").tabs();
	});
</script>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>The jQuery-based feature is used to display the product's images (in the coverflow view) from the images folder.</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<div class="jQProBoxC">
<!-- Begin jCarouselLite part -->
<button class="jQprev">&nbsp;</button>
<div class="jCarouselLite">
	<ul>
	   <%
             FOR IMAGE IN PRODUCT'S IMAGE FOLDER
		String imgSrc = "";
		/*
		GET THE IMAGE PATH
		imgSrc = GET THE IMAGE PATH;
		*/
		%>
		<li><img src="$imgSrc" width="204" height="200"/></li>
		<%
	    %>
	</ul>
</div>
<button class="jQnext">&nbsp;</button>
<!-- End jCarouselLite part -->
</div>
<script type="text/javascript">
jQuery.noConflict();
   jQuery(document).ready(function(){
  //jQuery.noConflict();
	jQuery(".jCarouselLite").jCarouselLite({
	btnNext: ".jQprev",
	btnPrev: ".jQnext",
	//auto: 500,
	//speed: 500
});
});
</script>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>Documents and videos are simply displayed within the view form as follows:</para>
            </listitem>
          </itemizedlist>
          <para>
            <emphasis role="bold">1.</emphasis> Get the node path to a document or video.</para>
          <para>
            <emphasis role="bold">2.</emphasis> Use some customized CSS classes to display a link for this node.</para>
          <para>Labels and/or messages are displayed in the dialog and the view form are localized.</para>
          <para>The use of this instruction is described as below:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[<td class="FieldLabel"><%=_ctx.appRes("Product.dialog.label.summary")%></td>
(...)
<h1><%=_ctx.appRes("Product.view.label.seeItInAction")%></h1>]]></programlisting>
          </programlistingco>
          <para>This can be achieved by adding locale files. For example:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<Product>
  <view>
    <label>
      <benefits>Benefits</benefits>
      <features>Features</features>
      <seeItInAction>See it in action</seeItInAction>
      <resources>Resources</resources>
      <videos>Videos</videos>
    </label>
  </view>
</Product>]]></programlisting>
          </programlistingco>
          <para>Make sure that locale files are added to the resource bundle configuration. If locale files (dialogs and views) are under the <emphasis role="italic">classes/locale/wcm</emphasis> directory, use the following code:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<value>locale.wcm.dialogs</value>
<value>locale.wcm.views</value>]]></programlisting>
          </programlistingco>
        </section>
      </section>
      <section id="DEV.WorkWithContent.CreateNewContentListTemplate" role="NotInToc">
        <title>Create a new Content List template  </title>
        <para>eXo Platform provides many powerful features to manipulate and expose any types of content on a page. This is due to the fact that eXo Platform stores all the content in its Java Content Repository (JCR) and renders the content on a page using Groovy Templates.</para>
        <para>In this section, you will learn how to create a new template that is used in the <emphasis role="bold">Content List</emphasis> portlet. For example, in the sample ACME site, you can show the content in One-column or Two-column display just by selecting different templates:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/ExampleTypesOfColumns.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/ExampleTypesOfColumns.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>Before writing a new template, it is important to learn where templates are stored.</para>
        <para>
<citetitle>
<emphasis role="bold">eXo Content Service: Template Storage</emphasis>
</citetitle>
</para>
        <para>Like many things inside eXo Platform, eXo JCR is used to store templates. Templates are just a special type of content. This allows developers to easily write and test code without following a complex deployment process, but also it makes it easy to export a running configuration to another one. To do this, you just need to use the standard JCR export/import features.</para>
        <para>All templates and eXo Content Service configurations are stored inside a specific JCR workspace named "dms-system".</para>
        <para>Each template type (for example, Document Type, or Content List) is stored in a specific location. In this case, you are going to work on the <emphasis role="bold">Content List</emphasis> portlet so templates are stored inside the <code>/exo:ecm/views/templates/content-list-viewer/list/</code> folder.</para>
        <para>The following steps allow you to inspect this folder using the eXo CRaSH utility. If you are not interested in it, you can jump to the <link linkend="DEV.WorkWithContent.CreateNewContentListTemplateUsingIDE">next section</link>. CRaSH is a shell for Java Content Repositories, the source of CRaSH is available on Google Code. So in the terminal window:</para>
        <para>
          <emphasis role="bold">1.</emphasis> Connect to CRaSH using the telnet client: <command>telnet 127.0.0.1 5000</command>.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Connect to the JCR workspace using the following command: <command>connect -u root -p gtn -c portal dms-system</command>.</para>
        <para>Where: <code>-u</code> is the user, <code>-p</code> is the password, <code>-c</code> is the Portal Container, and <code>dms-system</code> is the workspace to use.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Move the folder that contains all templates for the <emphasis role="bold">Content List</emphasis> portlet: <command>cd /exo:ecm/views/templates/content-list-viewer/list/</command>.</para>
        <para>
<emphasis role="bold">4.</emphasis> List all templates using the <command>ls</command> command.
</para>
        <para>You can see the list of all templates available for the <emphasis role="bold">Content List</emphasis> portlet.</para>
        <para xml:id="DEV.WorkWithContent.CreateNewContentListTemplateUsingIDE">
<citetitle>
<emphasis role="bold">Create a new Content List template using IDE</emphasis>
</citetitle>
</para>
        <para>Before doing the following steps, be sure that you are connected to a user who belongs to the <emphasis role="italic">/Developer</emphasis> group. The <emphasis role="italic">root</emphasis> user can be used for the simplicity reason.</para>
        <para>
          <emphasis role="bold">1.</emphasis> Access IDE by clicking <inlinemediaobject>
            <imageobject role="fo">
              <imagedata fileref="images/gear_icon.png" format="PNG" width="3mm fo:scalefit"/>
            </imageobject>
            <imageobject role="html">
              <imagedata fileref="images/gear_icon.png" format="PNG" scalefit="0" width="3mm fo:scalefit"/>
            </imageobject>
          </inlinemediaobject> <emphasis role="bold">--&gt; IDE</emphasis>.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Switch to the <emphasis role="italic">dms-system</emphasis> workspace by clicking <emphasis role="bold">My Spaces --&gt; on Window --&gt; Select Workspace</emphasis> from the IDE menu. Next, select the <emphasis role="italic">dms-system</emphasis> location in the dialog box and click <emphasis role="bold">OK</emphasis>.</para>
        <para>
          <emphasis role="bold">3.</emphasis> Navigate to the template location from the file structure on the left: <code>/exo:ecm/views/templates/content-list-viewer/list/</code>
        </para>
        <para>
          <emphasis role="bold">4.</emphasis> Create a new template by clicking <emphasis role="bold">File --&gt; New --&gt; Groovy Template</emphasis> from the IDE menu.</para>
        <para>
          <emphasis role="bold">5.</emphasis> Save the file as "MyNewTemplate.gtmpl".</para>
        <para>
          <emphasis role="bold">6.</emphasis> Enter some basic codes:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[<h1>This is my template</h1>
The date is <= new Date()>]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">7.</emphasis> Save the template, then go back to the homepage of the ACME site.</para>
        <para>
          <emphasis role="bold">8.</emphasis> Switch to the <emphasis role="bold">Edit</emphasis> mode by clicking <emphasis role="bold">Edit</emphasis> on the <emphasis role="bold">Administration</emphasis> bar.</para>
        <para>
          <emphasis role="bold">9.</emphasis> Hover your cursor over the top of the list of news and click <inlinemediaobject>
            <imageobject role="fo">
              <imagedata fileref="images/PreferencesIcon.png" format="PNG" scalefit="1" width="3mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata fileref="images/PreferencesIcon.png" format="PNG" scalefit="0" width="3mm"/>
            </imageobject>
          </inlinemediaobject>.</para>
        <para>
          <emphasis role="bold">10.</emphasis> Select "MyNewTemplate" from the list of templates, then click <emphasis role="bold">Save</emphasis>.</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/SelectTemplate.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/SelectTemplate.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>You have created your new template, and use it on a page. Now, you should add some more interesting codes to the template to really loop over the content based on the portlet configuration. But before this, you need to understand caching and code modification.</para>
        <para>
<citetitle>
<emphasis role="bold">eXo Template and Cache</emphasis>
</citetitle>
</para>
        <para>To improve performance and a running system, the compiled version of the template is cached by default. This is the reason why you do not see any change when you are modifying a template. There are 2 ways to work around this:</para>
        <itemizedlist>
          <listitem>
            <para>Run eXo Platform in the Debug mode. In this case, nothing is cached.</para>
          </listitem>
          <listitem>
            <para>Invalidate the cache manually using JMX.</para>
          </listitem>
        </itemizedlist>
        <para>Since working with no cache at all is not an option, here is the MBean you have to use for invalidating the Template Service cache:</para>
        <itemizedlist>
          <listitem>
            <para>
              <code>exo:portal="portal",service=cache,name="TemplateService"</code>
            </para>
          </listitem>
        </itemizedlist>
        <para>Then, call the <code>clearCache</code> operation on it.</para>
        <para>You can use any methods to call your MBeans operation. Here, JConsole will be used:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/TemplateServiceCacheMbean.png" format="PNG" scalefit="1" width="50mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/TemplateServiceCacheMbean.png" format="PNG" scalefit="0" width="50mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>Do not forget to call this operation each time you modify your template to ensure that eXo recompiles the template.</para>
        <para>
<citetitle>
<emphasis role="bold">Access content in the template</emphasis>
</citetitle>
</para>
        <para>The current code of the template is really simple. Now, you need to add code to print the content in the page. To do this, you are going to use some <emphasis role="bold">Content</emphasis> programmings once again in IDE.</para>
        <para>The template used by the <emphasis role="bold">Content List</emphasis> portlet is based on the following Java class: <code>org.exoplatform.wcm.webui.clv.UICLVPresentation</code>. This class is responsible for setting the complete context that you can use in the template, such as:</para>
        <itemizedlist>
          <listitem>
            <para>The folder or category that contains the content to show. The <emphasis role="bold">Folder Path</emphasis> field is in the preference screen.</para>
          </listitem>
          <listitem>
            <para>The display settings: title, number of documents, elements to show and more.</para>
          </listitem>
        </itemizedlist>
        <para>Here is the code to access these preferences:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[// import all the classes need in the template
import javax.jcr.Node;
import org.exoplatform.wcm.webui.paginator.UICustomizeablePaginator;
import org.exoplatform.wcm.webui.clv.UICLVPortlet;
import org.exoplatform.wcm.webui.Utils;
import org.exoplatform.services.wcm.core.NodeLocation;

// get the portlet preferences

def header = uicomponent.getHeader();
def isShowRssLink = uicomponent.isShowRssLink();
def isShowHeader = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_HEADER);
def isShowRefresh = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_REFRESH_BUTTON);

def isShowTitle = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_TITLE);
def isShowDate = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_DATE_CREATED);
def isShowLink = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_LINK);
def isShowReadmore = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_READMORE);
def isShowImage = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_ILLUSTRATION) ;
def isShowSummary = uicomponent.isShowField(UICLVPortlet.PREFERENCE_SHOW_SUMMARY);]]></programlisting>
        </programlistingco>
        <para>The <code>uicomponent</code> object is defined by the container class of the portlet that calls the template. This class contains many utility methods. The code above retrieves all the preferences of the portlet. Because the name is self-explanatory, it is not necessary to detail them, especially when you look at the preferences screen below:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/ContentListPreference.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/ContentListPreference.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>Now, the template has all the preferences, it is time to loop on the content on printing the information.</para>
        <para>The <emphasis role="bold">Content Service</emphasis> provides API to manipulate the content, including pagination of content. The idea behind this is to let the Content Service manage the JCR query, sorting, caching and pagination of data. So in your template, you will mainly manage 2 classes to loop through the content to show:</para>
        <itemizedlist>
          <listitem>
            <para>
              <code>uicomponent.getUIPageIterator()</code> - a paginator object that is configured based on the portlet preferences.</para>
          </listitem>
          <listitem>
            <para>
              <code>uicomponent.getCurrentPageData()</code> - a list of the content (JCR Nodes) that should be printed on the current page.</para>
          </listitem>
        </itemizedlist>
        <para>So, you can print all the content of the page as a simple HTML list:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[<ul style="margin: 20px">
<%
      for (viewNode in uicomponent.getCurrentPageData()) {
        def title = viewNode.getProperty("exo:title").getString()
        print("<li>$title</li>");
      }
%>
</ul>]]></programlisting>
        </programlistingco>
        <para>Just copy this code to your template, save it, then refresh the cache and go to your page. You should see the list of the content in a simple HTML list.</para>
        <para>On each content (Node), the <emphasis role="bold">Content API</emphasis> provides some helper methods to easily manipulate the content and avoid using the JCR API directly. In the following code, you can see the most important methods accessing the content properties:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[def itemName = viewNode.getName();
def itemLink = uicomponent.getURL(viewNode);
def webdDavLink = uicomponent.getWebdavURL(viewNode);
def itemDateCreated = uicomponent.getCreatedDate(viewNode);
def itemModifiedDate = uicomponent.getModifiedDate(viewNode);
def itemAuthor = uicomponent.getAuthor(viewNode);
def imgSrc = uicomponent.getIllustrativeImage(viewNode);
def itemTitle = uicomponent.getTitle(viewNode);
def itemSummary = uicomponent.getSummary(viewNode);]]></programlisting>
        </programlistingco>
        <para>One important point is the fact that these methods are responsible for many things, for example: formatting dates, returning complete URLs that depends on the context of the portlet.</para>
        <para>Based on these methods, you can now work on the presentation of the information on the page. For example, you can  click the image and the title to go in the detailed view of the article. This is done simply by using the following code:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[<%
  for (viewNode in uicomponent.getCurrentPageData()) {
    def itemName = viewNode.getName();
    def itemLink = uicomponent.getURL(viewNode);
    def webdDavLink = uicomponent.getWebdavURL(viewNode);
    def itemDateCreated = uicomponent.getCreatedDate(viewNode);
    def itemModifiedDate = uicomponent.getModifiedDate(viewNode);
    def itemAuthor = uicomponent.getAuthor(viewNode);
    def imgSrc = uicomponent.getIllustrativeImage(viewNode);
    def itemTitle = uicomponent.getTitle(viewNode);
    def itemSummary = uicomponent.getSummary(viewNode);

    %>
<div style="overflow: auto;">
  <img src="$imgSrc" align="left">
  <h3><a href="$itemLink">$itemTitle</a></h3>
  $itemSummary
</div>

<%
  }
%>]]></programlisting>
        </programlistingco>
        <para>For the simplicity reason, this code does not manage any null value. Also, the template does not deal with the portlet preferences, such as the "Header", "RSS" links. The Website should look like:</para>
        <para>
          <mediaobject>
            <imageobject role="fo">
              <imagedata align="center" fileref="images/NewSite.png" format="PNG" scalefit="1" width="120mm"/>
            </imageobject>
            <imageobject role="html">
              <imagedata align="center" fileref="images/NewSite.png" format="PNG" scalefit="0" width="120mm"/>
            </imageobject>
          </mediaobject>
        </para>
        <para>The last important point is to add the support for the in-context editing that allows users to edit the content directly from the template. Once again, this is done with a method of the <code>uicomponent</code> object that creates a DIV around the content:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[<%
  for (viewNode in uicomponent.getCurrentPageData()) {
    def itemName = viewNode.getName();
    def itemLink = uicomponent.getURL(viewNode);
    def webdDavLink = uicomponent.getWebdavURL(viewNode);
    def itemDateCreated = uicomponent.getCreatedDate(viewNode);
    def itemModifiedDate = uicomponent.getModifiedDate(viewNode);
    def itemAuthor = uicomponent.getAuthor(viewNode);
    def imgSrc = uicomponent.getIllustrativeImage(viewNode);
    def itemTitle = uicomponent.getTitle(viewNode);
    def itemSummary = uicomponent.getSummary(viewNode);

    %>
<div style="overflow: auto;">
  <%=uicomponent.addQuickEditDiv("MyTemplateContentEditor", viewNode)%>
  <img src="$imgSrc" align="left">
  <h3><a href="$itemLink">$itemTitle</a></h3>
  $itemSummary
  < /div>
</div>

<%
  }
%>]]></programlisting>
        </programlistingco>
        <para>The 15 and 19 lines are new in this template and provide support for the <emphasis role="bold">Quick Edit</emphasis> feature.</para>
        <para>After creating your own template for <emphasis role="bold">Content Service</emphasis> using the embedded IDE, you are free to use your imagination for adding cool features to your site.</para>
      </section>
    </section>
  </chapter>
  <chapter id="DEV.WorkingwithApplications">
    <title>Work With Applications </title>
    <abstract>
<para>Applications play an important role in each eXo service, so it is necessary for you to further understand about them.</para>
<para>This chapter includes the following main topics:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.WorkWithApplications.ApplicationIntegration">Integrate an application</link> </emphasis>
	</para>
	<para>
	Instructions on how to add an application (especially a portlet) to your portal's paces.
		</para>
	  </listitem>
	  <listitem>
		<para>
	  <emphasis role="bold">
              <link linkend="DEV.WorkWithApplications.DevelopYourOwnApplications">Develop your own application</link> </emphasis>
		</para>
		<para>
	Instructions on how to develop a gadget for eXo Platform, and information about Portlet Bridges.
		</para>
	  </listitem>
	<listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.ExtendeXoApplications">Extend eXo applications</link>
            </emphasis>
	</para>
	<para>
	Concept and mechanism of UI Extension framework which allows the customization and extensibility of eXo applications through simple plugins.
	</para>
  </listitem>
	
	</itemizedlist>
</abstract>
    <section id="DEV.WorkWithApplications.ApplicationIntegration">
      <title>Integrate an application </title>
      <para>To add a portlet to one of your portal's pages, you should configure the <emphasis role="italic">pages.xml</emphasis> file located at <emphasis role="italic">/war/src/main/webapp/WEB-INF/conf/sample-ext/portal/portal/classic</emphasis>/.</para>
      <para>Here is an example of the portlet configuration in the <emphasis role="italic">pages.xml</emphasis> file:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<portlet-application>
  <portlet>
    <application-ref>presentation</application-ref>
    <portlet-ref>SingleContentViewer</portlet-ref>
    <preferences>
      <preference>
        <name>repository</name>
        <value>repository</value>
        <read-only>false</read-only>
      </preference>
      <preference>
        <name>workspace</name>
        <value>collaboration</value>
        <read-only>false</read-only>
      </preference>
      <preference>
        <name>nodeIdentifier</name>
        <value>/sites content/live/acme/web contents/site artifacts/Introduce</value>
        <read-only>false</read-only>
      </preference>
      <!-- ... -->
    </preferences>
  </portlet>
  <title>Homepage</title>
  <access-permissions>Everyone</access-permissions>
  <show-info-bar>false</show-info-bar>
  <show-application-state>false</show-application-state>
  <show-application-mode>false</show-application-mode>
</portlet-application>]]></programlisting>
      </programlistingco>
      <para>
        <emphasis role="bold">Details:</emphasis>
      </para>
      <informaltable>
        <thead>
          <tr>
            <th> XML tag name </th>
            <th> Description </th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td> <code>application-ref</code> </td>
            <td> The name of the webapp that contains the portlet. </td>
          </tr>
          <tr>
            <td> <code>portlet-ref</code> </td>
            <td> The name of the portlet. </td>
          </tr>
          <tr>
            <td> <code>title</code> </td>
            <td> The title of the page. </td>
          </tr>
          <tr>
            <td> <code>access-permission</code> </td>
            <td> Define who can access the portlet. </td>
          </tr>
          <tr>
            <td> <code>show-info-bar</code> </td>
            <td> Show the top bar with the portlet title. </td>
          </tr>
          <tr>
            <td> <code>show-application-state</code> </td>
            <td> Show the collapse/expand icons. </td>
          </tr>
          <tr>
            <td> <code>show-application-mode</code> </td>
            <td> Show the change portlet mode icon. </td>
          </tr>
          <tr>
            <td> <code>preferences</code> </td>
            <td> Contain a list of <emphasis role="italic">preferences</emphasis> specific to each portlet. Each <emphasis role="italic">preference</emphasis> has a <emphasis role="italic">name</emphasis> and a <emphasis role="italic">value</emphasis>. You can also lock it by setting the <emphasis role="italic">read-only</emphasis> element to "true". To learn more, refer to <ulink url="../../../reference/html/JCRReferenceGuide.html">eXo JCR and Extension Services Reference</ulink>. </td>
          </tr>
        </tbody>
      </informaltable>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithApplications.DevelopYourOwnApplications">Develop your own application</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.ExtendeXoApplications">Extend eXo applications</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.WorkWithApplications.DevelopYourOwnApplications">
      <title>Develop your own application </title>
      <highlights>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithApplications.DevelopAGadgetForPlatform">Develop a gadget for eXo Platform</link>
            </para>
			<para>
			Introduction to the resources which can be shared for all gadgets and their categories, instructions on how to apply for a gadget and to customize the gadget thumbnail. 
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithApplications.PortletBridges">Portlet Bridges</link>
            </para>
			<para>
			Adapter for a web framework to the portlet container runtime. It works ideally with framework that does not expose the servlet container with the limited support for the full portlet API.
			</para>
          </listitem>
        </itemizedlist>
</highlights>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.WorkWithApplications.ApplicationIntegration">Integrate an application</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.ExtendeXoApplications">Extend eXo applications</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.WorkWithApplications.DevelopAGadgetForPlatform" role="NotInToc">
        <title>Develop a gadget for eXo Platform </title>
        <note>
          <para>It is important to understand distinctions between gadgets and portlets. Portlets are user interface components that provide fragments of markup code from the server side, while gadgets generate dynamic web content on the client side. With Gadgets, small applications can be built quickly, and mashed up on the client side using the lightweight Web-Oriented Architecture (WOA) technologies, like REST or RSS. For more information on how to develop gadgets and portlets, see the <ulink url="../../../reference/html/chap-Reference_Guide-Portlet_development.html">Portlet development</ulink> and <ulink url="../../../reference/html/chap-Reference_Guide-Gadget_development.html">Gadget development</ulink> sections.</para>
        </note>
        <para>Because a gadget is basically an independent HTML content, the gadget UI, such as layout, font, color may be different. Thus, making consistent in the look and feel of all eXo Platform gadgets is very important. In this part, it is assumed that developers have already known how to write a gadget in eXo Platform. The information here helps developers make a consistent look and feel with eXo Platform skin, even when this skin may be changed in the future.</para>
        <note>
          <para>To get more information on how to develop gadgets, see the <ulink url="../../../reference/html/chap-Reference_Guide-Gadget_development.html">Gadget development</ulink> and <ulink url="../ide-user-guide/IDEdev.GoogleGadgetOperation.CreateGoogleGadget.html">Develop gadgets via a powerful web-based IDE of eXo Platform</ulink> sections.</para>
        </note>
        <section id="DEV.WorkWithApplications.DevelopAGadgetForPlatform.Resource">
          <title>Resources </title>
          <para>To achieve the consistent look and feel, you have to collect the common features of all gadgets as much as possible and put in a place where it can be shared for all gadgets. You will use exo-gadget-resources for this purpose.  It is a <emphasis role="italic">.war</emphasis> file that contains commonly used static resources (stylesheets, images, JavaScript libraries, and more) available for all gadgets in eXo Platform at runtime: </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[/exo-gadget-resources
 |__skin 
 |   |__exo-gadget 
 |   |   |__images 
 |   |   |__gadget-common.css 
 |   |__...(3rd-party components' CSS)
 |__script 
    |__jquery 
    |  |__1.6.2 
    |  |__...(other jQuery versions) 
    |  |__plugins 
    |__utils]]></programlisting>
          </programlistingco>
          <para>The resources are divided into 2 categories: skin and script.</para>
          <para>
            <emphasis role="bold">Skin</emphasis>: is the place for the shared stylesheets of the gadgets (<emphasis role="italic">exo-gadget/gadget-common.css</emphasis>) and other third-party components styles adapted to the eXo Platform skin (jqPlot, Flexigrid, and more). This is a copy of the component's original CSS with some modifications to match the eXo Platform's skin. You can find this original file at the component's folder under <emphasis role="italic">exo-gadget-resources/script</emphasis>  , then link to it or make your own copy (put it in your gadget's folder and refer to it in gadget's .xml file) to suit your need.</para>
          <para>The <emphasis role="italic">gadget-common.css</emphasis> file is the main place for the global stylesheets. When the eXo Platform skin is changed, updating stylesheets in this file will affect all gadgets skins accordingly. In this file, you will define stylesheets applied for all gadgets, such as gadget title, gadget body, fonts, colors, tables, and some commonly used icons, such as drop-down arrow, list bullet, setting button, and more.</para>
          <para>For example:</para>
          <itemizedlist>
            <listitem>
              <para>UIGadgetThemes: the gadget container.</para>
            </listitem>
            <listitem>
              <para>TitGad: the gadget title.</para>
            </listitem>
            <listitem>
              <para>ContTit: the gadget title content.</para>
            </listitem>
            <listitem>
              <para>GadCont: the gadget content.</para>
            </listitem>
            <listitem>
              <para>SettingButton: the setting button for gadget's User Preferences.</para>
            </listitem>
          </itemizedlist>
          <para>
            <emphasis role="bold">Script</emphasis>: is the place for commonly used third-party JavaScript libraries (e.g: jQuery and its plugins) and a library of useful utility scripts (the utils folder). </para>
          <para>jQuery and plugins:</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="italic">jquery/&lt;version&gt;</emphasis>: <ulink url="http://jquery.com/">jQuery JavaScript library</ulink>.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">jquery/plugins/jqplot</emphasis>: <ulink url="http://www.jqplot.com/">Charts and Graphs for jQuery</ulink>.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">jquery/plugins/flexigrid</emphasis>: <ulink url="http://flexigrid.info/">Lightweight but rich data grid</ulink>.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">jquery/plugins/date.js</emphasis>: <ulink url="http://www.datejs.com/">JavaScript date library</ulink>.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="italic">jquery/plugins/jquery.timers</emphasis>: <ulink url="http://plugins.jquery.com/project/timers">JavaScript timer</ulink>.</para>
            </listitem>
          </itemizedlist>
          <para>(Here you should keep the latest and several versions of jQuery because some plugins may not work with the latest version. Several versions of a plugin are also kept).</para>
          <para>The utilities scripts:</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="italic">utils/pretty.date.js</emphasis>: Calculate the difference from a point of time in the past to the present and display "4 months 3 weeks ago", for example.</para>
            </listitem>
          </itemizedlist>
        </section>
        <section id="DEV.WorkWithApplications.DevelopAGadgetForPlatform.ApplyForGadget">
          <title>Apply for a gadget </title>
          <para>A gadget should use static resources available in <emphasis role="italic">exo-gadget-resources</emphasis> instead of including them in their own package. This helps reduce packaging size, avoid duplication (considering that every gadget includes a version of jQuery is in its own package) and take advantages of automatic skin changing/updating when the resources of <emphasis role="italic">exo-gadget-resources</emphasis> are updated to the new eXo Platform skin. To make it work, the applied gadget must use the CSS classes defined in <emphasis role="italic">gadget-common.css</emphasis> (at least for the gadget title) like the sample gadget below:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<Module>
<ModulePrefs title="Sample gadget"/> 
<Content type="html"> 
  <head> 
    <link href="/exo-gadget-resources/skin/exo-gadget/gadget-common.css" rel="stylesheet" type="text/css"/> 
    <script language="javascript" src="/exo-gadget-resources/script/jquery/1.6.2/jquery.min.js" type="text/javascript"/> 
    <script language="javascript" type="text/javascript"> 
      $(function(){ 
        alert("Hello from jQuery");  (3)
      }); 
    </script>  
  </head> 
  <body> 
    <div class="UIGadgetThemes"> 
      <div class="TitGad ClearFix"> 
        <div class="ContTit">Gadget title</div>  (1)
      </div> 
      <div class="GadCont">  (2)
        Gadget content 
      </div> 
    </div> 
  </body> 
</Content> 
</Module>]]></programlisting>
          </programlistingco>
          <para>The sample gadget:</para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/sample_gadget.png" format="PNG" scalefit="1" width="80mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/sample_gadget.png" format="PNG" scalefit="0" width="80mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <citetitle>
<para>
<emphasis role="bold">The sample user settings of a gadget</emphasis>
</para>
</citetitle>
          <para>The following gadget gives the demo of a user settings screen which uses eXo Platform standard icons (setting button, list item bullet, and more) that are defined in the <emphasis role="italic">gadget-common.css</emphasis>.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<Module>
<ModulePrefs title="Setting demo"> 
  <Require feature="dynamic-height"/> 
  <Require feature="setprefs"/> 
</ModulePrefs>  
<Content type="html"> 
  <head> 
    <link href="/exo-gadget-resources/skin/exo-gadget/gadget-common.css" rel="stylesheet" type="text/css"/> 
    <style type="text/css"> 
      .SettingButton:hover {cursor:pointer;} 
    </style>  
    <script language="javascript" src="/exo-gadget-resources/script/jquery/1.6.2/jquery.min.js" type="text/javascript"/> 
    <script language="javascript" type="text/javascript"> 
 
      $(function(){ 
        var prefs = new gadgets.Prefs(); 
        var defaultNumItems = 3; 

        function displayItems(){ 
          var numItems = prefs.getInt("numItems") || defaultNumItems; 
          $("#content").html(""); 
          for(i=0; i&lt;=numItems; i++) { 
            $("#content").append("&lt;div class='IconLink'&gt;Item " + (i+1) + "&lt;/div&gt;");    (3)
          } 
          gadgets.window.adjustHeight($(".GadCont").get(0).offsetHeight); 
        }      
		
        $(".SettingButton").live("click", function(){ 
          $("#txtNumItems").val(prefs.getInt("numItems") || defaultNumItems); 
          $("#setting").toggle(); 
          gadgets.window.adjustHeight($(".GadCont").get(0).offsetHeight); 
        }); 

        $("#btnOk").live("click", function(){ 
          var sNumItems = $("#txtNumItems").val(); 
          prefs.set("numItems", parseInt(sNumItems) || defaultNumItems); 
          $("#setting").hide(); 
          displayItems(); 
        }); 

        $("#btnCancel").live("click", function(){ 
          $("#setting").hide(); 
          gadgets.window.adjustHeight($(".GadCont").get(0).offsetHeight); 
        }); 

        displayItems(); 
      }); 
 
    </script>  
  </head> 
  <body> 
    <div class="UIGadgetThemes"> 
      <div class="TitGad ClearFix"> 
        <div class="ContTit"> 
          Setting demo 
          <div class="SettingButton" style="display:block; width:20px; height:20px"/>   (1)
        </div> 
      </div> 
      <div class="GadCont"> 
        <div id="setting" style="display:none;">   (2)
          <label for="txtNumItems">Num of items</label> 
          <input id="txtNumItems" type="text"/>                                       
          <input id="btnOk" type="button" value="OK"/> 
          <input id="btnCancel" type="button" value="Cancel"/> 
          <hr/> 
        </div> 
        <div id="content"/> 
      </div> 
    </div> 
  </body> 
</Content> 
</Module>]]></programlisting>
          </programlistingco>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/setting_demo_form.png" format="PNG" scalefit="1" width="80mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/setting_demo_form.png" format="PNG" scalefit="0" width="80mm"/>
              </imageobject>
            </mediaobject>
          </para>
        </section>
        <section id="DEV.WorkWithApplications.DevelopAGadgetForPlatform.CustomizeGadgetThumnail">
          <title>Customize the gadget thumbnail </title>
          <para>The gadget thumbnails are displayed in the <emphasis role="bold">Page Editor</emphasis> window when you edit a page. The thumbnail image size needs to be consistent for all gadgets in the list.  The current size (in eXo Platform 3.5) is 80 x 80px, so you should select an image of this size in PNG (preferred), JPG or GIF format for your gadget thumbnail. </para>
          <para>
            <mediaobject>
              <imageobject role="fo">
                <imagedata align="center" fileref="images/gadget_thumbnail.png" format="PNG" scalefit="1" width="150mm"/>
              </imageobject>
              <imageobject role="html">
                <imagedata align="center" fileref="images/gadget_thumbnail.png" format="PNG" scalefit="0" width="150mm"/>
              </imageobject>
            </mediaobject>
          </para>
          <itemizedlist>
            <listitem>
              <para>The image can also be one from a public website (absolute URL), for example: &lt;ModulePrefs title="Sample gadget" thumbnail="http://www.example.com/images/sample-icon.jpg"/&gt;; or from an internal image (relative URL): &lt;ModulePrefs title="Sample gadget" thumbnail="image/sample-icon<emphasis role="italic">80x80.png"/&gt;.</emphasis>
              </para>
            </listitem>
          </itemizedlist>
        </section>
      </section>
      <section id="DEV.WorkWithApplications.PortletBridges" role="NotInToc">
        <title>Portlet Bridges </title>
        <para>The Portlet Bridge is an adapter for a web framework to the portlet container runtime. It works ideally with framework that does not expose the servlet container with the limited support for the full portlet API.</para>
        <para>The JavaTM Specification Request 168 Portlet Specification (JSR 168) standardizes how components for portal servers are developed. This standard has industry backing from major portal server vendors. A Portlet Bridge allows you to create a JSR-168 compliant portlet with very little change on your existing web application.</para>
        <para>For example, the JSF Bridge allows you to transparently deploy your existing JSF Applications as a Portlet Application or Web Application. For more details, see http://wiki.apache.org/myfaces/PortletBridge.</para>
        <para>The JBoss implementation of the Portlet Bridge has enhancements to support other web frameworks, such as RichFaces and Seam. For more details, see http://jboss.org/portletbridge/docs.html.</para>
      </section>
    </section>
    <section id="DEV.ExtendeXoApplications">
      <title>Extend eXo applications </title>
      <highlights>
<itemizedlist>
	<listitem>
		<para>
              <emphasis role="bold">
                <link linkend="DEV.UI_Extension_Framework.UI_Extension_components">UI Extension components</link>
              </emphasis>
            </para>
		<para>Necessary information about UIExtensionManager, UIExtensionPlugin, introduction to UI Extension definition and its class, parent UI components, and details about filters of each UI Extension.</para>
	</listitem>
	<listitem>
		<para>
              <emphasis role="bold">
                <link linkend="DEV.UI_Extension_Framework.Mechanism">Mechanism</link>
              </emphasis>
            </para>
		<para>Details about the working process of each UI Extension, including: setting up, loading and activating.</para>
	</listitem>
</itemizedlist>
</highlights>
      <citetitle>
		<para>
			<emphasis role="bold">
				What is UI Extension framework?
			</emphasis>
		</para>	
	</citetitle>
      <para>UI Extension is an extension of UI Component. As you know, extension is an object that contains programming for extending the capabilities of data available to a more basic program. Here, UI Extension helps expanding the dynamic children of UI Component. With UI Extension, you can add, change or remove a lot of children in UI Component more easily than in traditional ways.</para>
      <citetitle>
		<para>
			<emphasis role="bold">
				Why use UI Extension framework?
			</emphasis>
		</para>	
	</citetitle>
      <para>It is simple for you and your team to control applications containing few components that are all constant. But when you start an application which contains a lot of components, transactions, filters and permissions on each component, it is really a disaster. As each developer may handle problems in their own way, it also likely raises the convention problem. Thus, UI Extension framework was created to solve the management dynamic components on the applications and free developers from controlling too many of them. </para>
      <para>The main goals of this framework are:</para>
      <itemizedlist>
        <listitem>
          <para>Create simple child UI Components.</para>
        </listitem>
        <listitem>
          <para>Apply a filter on each component for a variety of purposes more easily.</para>
        </listitem>
        <listitem>
          <para>Add or remove extensions simply by configuration.</para>
        </listitem>
      </itemizedlist>
      <prompt>
	<para>
		<emphasis role="bold">See also</emphasis>
	</para>
</prompt>
      <itemizedlist>
        <listitem>
          <para>
            <ulink url="../../../reference/html/SOCref.DevelopersReferences.UIExtensions.html">How to create an activity plugin for Social?</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="../../../reference/html/CONTref.Extensions.ExtendUIExtension.html">How to make your own ECMS UI Extensions?</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="../../../reference/html/KSref.DeveloperReference.Extend_actions_over_a_wiki_page_from_external_jars.html">How to add action extensions to Wiki?</ulink>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.UI_Extension_Framework.UI_Extension_components" role="NotInToc">
        <title>UI Extension components </title>
        <citetitle>
		<para>
			<emphasis role="bold">
				UIExtensionManager
			</emphasis>
		</para>	
	</citetitle>
        <para> This class is used to manage all extensions available in the system. The target is to create the ability to add a new extension dynamically without changing anything in the source code.   UIExtensionManager is implemented by <emphasis role="italic">UIExtensionManagerImpl</emphasis>.  </para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.webui.ext.UIExtensionManager</key>
  <type>org.exoplatform.webui.ext.impl.UIExtensionManagerImpl</type>
</component>]]></programlisting>
        </programlistingco>
        <citetitle>
		<para>
			<emphasis role="bold">
				UIExtensionPlugin
			</emphasis>
		</para>	
	</citetitle>
        <para>This class allows you to define new extensions in the configuration file dynamically (for example: <emphasis role="italic">configuration.xml</emphasis>). As you want <emphasis role="italic">UIExtensionManager</emphasis> to manage every extension, you have to plug <emphasis role="italic">UIExtensionPlugin</emphasis> into it:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<external-component-plugins>
    <target-component>org.exoplatform.webui.ext.UIExtensionManager</target-component>
    <component-plugin>
      <name>add.action</name>
      <set-method>registerUIExtensionPlugin</set-method>
      <type>org.exoplatform.webui.ext.UIExtensionPlugin</type>
		...
	</component-plugin>
</external-component-plugins>]]></programlisting>
        </programlistingco>
        <citetitle>
		<para>
			<emphasis role="bold">
				Definition of UI Extensions
			</emphasis>
		</para>	
	</citetitle>
        <para>Each UI Extension is defined as an object param:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[...
<object-param>
          <name>EditPage</name>
          <object type="org.exoplatform.webui.ext.UIExtension">
            <field name="type"><string>org.exoplatform.wiki.UIPageToolBar</string></field>
            <field name="rank"><int>300</int></field>
            <field name="name"><string>EditPage</string></field>
            <field name="component"><string>org.exoplatform.wiki.webui.control.action.EditPageActionComponent</string></field>
          </object>
 </object-param>
...]]></programlisting>
        </programlistingco>
        <para>In which:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Name</emphasis>: the extension's name.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Object Type</emphasis>: point to the UI Extension lib class.</para>
            <itemizedlist>
              <listitem>
                <para>
                  <emphasis role="bold">Type</emphasis>: the "parent" UI component which is extended by your UI Extension.</para>
              </listitem>
              <listitem>
                <para>
                  <emphasis role="bold">Rank</emphasis>: used to sort by Collection of UI Extension.</para>
              </listitem>
              <listitem>
                <para>
                  <emphasis role="bold">Component</emphasis>: point to the UI Extension definition class.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <citetitle>
		<para>
			<emphasis role="bold">
			UI Extension Definition class			
			</emphasis>
		</para>	
	</citetitle>
        <para>This class is used to define filters, actions and templates of UI Extension:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[@ComponentConfig( 
  events =
{(listeners = EditPageActionComponent.EditPageActionListener.class);}) 
  public class EditPageActionComponent extends UIComponent { 
  private static final List<UIExtensionFilter> FILTERS = Arrays.asList(new UIExtensionFilter[] { new IsViewModeFilter() }); 
  @UIExtensionFilters 
   public List<UIExtensionFilter> getFilters() {
    return FILTERS;
}
  public static class EditPageActionListener extends UIPageToolBarActionListener<EditPageActionComponent> {
    @Override
    protected void processEvent(Event<EditPageActionComponent> event) throws Exception {
     ...
      super.processEvent(event);
    }
  } 
...]]></programlisting>
        </programlistingco>
        <citetitle>
		<para>
			<emphasis role="bold">
			Parent UI Component
			</emphasis>
		</para>	
	</citetitle>
        <para>This is what your UI Extension will be added to (in this example, the parent UI Componet is <emphasis role="italic">UIPageToolBar</emphasis>). All extensions of this component are got by UIExtensionManager.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[UIExtensionManager manager = getApplicationComponent(UIExtensionManager.class);
 
List<UIExtension> extensions = manager.getUIExtensions(EXTENSION_TYPE);
 public List<ActionComponent> getActions() throws Exception {
    ....
    List<UIExtension> extensions = manager.getUIExtensions(EXTENSION_TYPE);
    if (extensions != null) {
      for (UIExtension extension : extensions) {
        UIComponent component = manager.addUIExtension(extension, context, this);
// Child UI Component has been made by UI Extension
// It's available to use now
        ...
      }
    }
    return activeActions;
  }]]></programlisting>
        </programlistingco>
        <citetitle>
		<para>
			<emphasis role="bold">
			Internal filter
			</emphasis>
		</para>	
	</citetitle>
        <para>Each UI Extension has a list of filters depending on variety of purposes. It indicates which UI Extension is accepted and which is denied. You are free to create your own filter extended from <emphasis role="italic">UIExtensionAbstractFilter</emphasis>. Internal filters are a part of the business logic of your component. For example, if your component is only dedicated to articles, you will add an internal filter to your component that will check the type of the current document.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[public class IsViewModeFilter extends UIExtensionAbstractFilter { 
   public IsViewModeFilter(String messageKey) {
    super(messageKey, UIExtensionFilterType.MANDATORY);
  } 
  @Override
  public boolean accept(Map<String, Object> context) throws Exception {
    UIWikiPortlet wikiPortlet = (UIWikiPortlet) context.get(UIWikiPortlet.class.getName());
    return(wikiPortlet.getWikiMode() == WikiMode.VIEW||wikiPortlet.getWikiMode() == WikiMode.VIEWREVISION);
  } 
  @Override
  public void onDeny(Map<String, Object> context) throws Exception {
    // TODO Auto-generated method stub 
  }]]></programlisting>
        </programlistingco>
        <para>Your filter will define which type of filter it belongs to (in <emphasis role="italic">UIExtensionFilterType</emphasis>). There are 4 types:</para>
        <informaltable>
          <thead>
            <tr>
              <th>Types</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>
                <emphasis role="bold">MANDATORY</emphasis>
              </td>
              <td>Check if the action related to the extension can be launched and if the component related to the extension can be added to the WebUI tree. This filter is required to launch the action and add the component related to the extension to the WebUI tree. If it succeeds, you need to check the other filters. If it fails, you need to stop.</td>
            </tr>
            <tr>
              <td>
                <emphasis role="bold">REQUISITE</emphasis>
              </td>
              <td>Check if the action related to the extension can be launched. This filter is required to launch the action to the WebUI tree. If it succeeds, you need to check the other filters. If it fails, you need to stop.</td>
            </tr>
            <tr>
              <td>
                <emphasis role="bold">REQUIRED</emphasis>
              </td>
              <td>Check if the action related to the extension can be launched and can be used for adding warnings. This filter is required to launch the action. If it succeeds or fails, you need to check the other filters.</td>
            </tr>
            <tr>
              <td>
                <emphasis role="bold">OPTIONAL</emphasis>
              </td>
              <td>Check if the action related to the extension can be launched and can be used for the auditing purpose. This filter is not required to launch the action. If it succeeds or fails, you need to check the other filters.</td>
            </tr>
          </tbody>
        </informaltable>
        <para>There are 2 conditions for filtering: Accept and onDeny. </para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Accept</emphasis>: Describe the "Accept" condition, and how an UI Extension can accept by a context.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">onDeny</emphasis>: What you will do after the filter denies an UI Extension by a specific context (generating a message for pop-up form, for example).</para>
          </listitem>
        </itemizedlist>
        <para>You have known how and where the filter is put in an UI Component, but when it is gonna fire?</para>
        <para>It falls into 2 situations: when you get it and when it is action fire. Thus, you should ensure that your UI Extension is always trapped by its filter.</para>
        <citetitle>
		<para>
			<emphasis role="bold">
			External filter
			</emphasis>
		</para>	
	</citetitle>
        <para>External filters are mainly used to add new filters that are not related to the business logic to your component. A good example is the <emphasis role="italic">UserACLFilter</emphasis> which allows you to filter by access permissions.</para>
        <para>For example, to make the EditPage action only be used by <emphasis role="italic">manager:/platform/administrators</emphasis>, do as follows:</para>
        <itemizedlist>
          <listitem>
            <para>Create an external filter:</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="java"><![CDATA[public class UserACLFilter implements UIExtensionFilter { 
  /**
   * The list of all access permissions allowed
   */
  protected List<String> permissions; 
  /**
   * {@inheritDoc}
   */
  public boolean accept(Map<String, Object> context) throws Exception {
    if (permissions == null || permissions.isEmpty()) {
      return true;
    }
    ExoContainer container = ExoContainerContext.getCurrentContainer();
    UserACL userACL = (UserACL) container.getComponentInstance(UserACL.class);
    for (int i = 0, length = permissions.size(); i < length; i++) {
      String permission = permissions.get(i);
      if (userACL.hasPermission(permission)) {
        return true;
      }
    }
    return false;
  }
 
  /**
   * {@inheritDoc}
   */
  public UIExtensionFilterType getType() {
    return UIExtensionFilterType.MANDATORY;
  }
 
  /**
   * {@inheritDoc}
   */
  public void onDeny(Map<String, Object> context) throws Exception {}
}]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>Add the external filter to an UI Extension in the <emphasis role="italic">configuration.xml</emphasis> file:</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<object-param>
  <name>EditPage</name>
  <object type="org.exoplatform.webui.ext.UIExtension">
    <field name="type"> <string>org.exoplatform.wiki.UIPageToolBar</string> </field>
 <field name="rank"><int>300</int></field>
    <field name="name"> <string>EditPage</string> </field>
    <field name="component"><string>org.exoplatform.wiki.webui.control.action.EditPageActionComponent</string> </field>
	<!-- The external filters -->
    <field name="extendedFilters">
      <collection type="java.util.ArrayList">
        <value>
          <object type="org.exoplatform.webui.ext.filter.impl.UserACLFilter">
            <field name="permissions">
              <collection type="java.util.ArrayList">
                <value>
                  <string>manager:/platform/administrators</string>
                </value>
              </collection>
            </field>
          </object>
        </value>
      </collection>
    </field>
  </object>
</object-param>]]></programlisting>
        </programlistingco>
      </section>
      <section id="DEV.UI_Extension_Framework.Mechanism" role="NotInToc">
        <title>Mechanism </title>
        <para>The UI Extension's working process is divided into 3 phases:</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.UI_Extension_Framework.Mechanism.Setup">Setting up</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.UI_Extension_Framework.Mechanism.Load">Loading</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.UI_Extension_Framework.Mechanism.Active">Activating</link>
            </para>
          </listitem>
        </itemizedlist>
        <citetitle>
		<para xml:id="DEV.UI_Extension_Framework.Mechanism.Setup">
			<emphasis role="bold">
			Setting up
			</emphasis>
		</para>	
	</citetitle>
        <para>At first, you must add Dependencies to <emphasis role="italic">pom.xml</emphasis>. In this phase, you are going to install all elements of UI Extension framework in the <emphasis role="italic">configuration.xml</emphasis> file:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="italic">UIExtensionManager</emphasis> is implemented by <emphasis role="italic">UIExtensionManagerImpl</emphasis>.</para>
          </listitem>
          <listitem>
            <para>Plug <emphasis role="italic">UIExtensionPlugin</emphasis> in <emphasis role="italic">UIExtensionManager</emphasis> by using the <code>registerUIExtensionPlugin()</code> method.</para>
          </listitem>
          <listitem>
            <para>List all the UI Extension's definitions. You can also define your own external filter (optional).</para>
          </listitem>
          <listitem>
            <para>Create the parent UI Component class.</para>
          </listitem>
          <listitem>
            <para>Create the UI Extension class.</para>
          </listitem>
          <listitem>
            <para>Create the internal filters.</para>
          </listitem>
        </itemizedlist>
        <citetitle>
		<para xml:id="DEV.UI_Extension_Framework.Mechanism.Load">
			<emphasis role="bold">
			Loading
			</emphasis>
		</para>	
	</citetitle>
        <para>
          <emphasis role="italic">UIExtensionPlugin</emphasis> is responsible for looking up all UI Extension definitions, thus you can use it to obtain all UI Extensions, then plug it into <emphasis role="italic">UIExtensionManager</emphasis>. At present, all UI Extensions in your project will be managed by <emphasis role="italic">UIExtensionManager</emphasis>.  Now you can get UI Extensions everywhere by invoking the <code>getUIExtensions(String objectType)</code> method.</para>
        <para>In the UI Component class, implement a function which:</para>
        <itemizedlist>
          <listitem>
            <para>Retrieve a collection of UI Extensions which belongs to it by <emphasis role="italic">UIExtensionManager</emphasis>:</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[List<UIExtension> extensions = manager.getUIExtensions("org.exoplatform.wiki.UIPageToolBar");]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>Transform them into <emphasis role="italic">UIComponent</emphasis> and add them to the parent UI Component:</para>
          </listitem>
        </itemizedlist>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[// You are free to create a context
Map<String, Object> context = new HashMap<String, Object>();
context.put(key,Obj);
// UIExtensionManager will depend on this context and extension to add or does not add extension to UI Component(this)
UIComponent component = manager.addUIExtension(extension, context, this);]]></programlisting>
        </programlistingco>
        <para>The <code>addUIExtension()</code> method is responsible for adding extensions to an UI Component. It depends on:</para>
        <itemizedlist>
          <listitem>
            <para>UIExtension, in particular, the UIExtension's filter. Either internal filter or external filter has the <code>accept</code> method, thus the adding process will be successful if <code>accept</code> returns 'true' and vice versa.</para>
          </listitem>
          <listitem>
            <para>Context will be the parameter of the <code>accept</code> method.</para>
          </listitem>
        </itemizedlist>
        <citetitle>
		<para xml:id="DEV.UI_Extension_Framework.Mechanism.Active">
			<emphasis role="bold">
			Activating
			</emphasis>
		</para>	
	</citetitle>
        <para>The final step is to present UI Extension in a template.</para>
        <para>As all UI Extensions are presently becoming children of UI Component, you can implement UI Component's action thanks to UI Extension's action. For example:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting><![CDATA[<%for(entry in uicomponent.getActions()) {
  String action = entry.Id();
  def uiComponent = entry;
  String link = uiComponent.event(action);
%>
  <a href="$link" class="$action" title="$action" %>"><%= action %></a>
<%}%>]]></programlisting>
        </programlistingco>
        <note>
          <para>You are free to customize your action's Stylesheet.</para>
        </note>
      </section>
    </section>
  </chapter>
  <chapter id="DEV.SystemIntegration">
    <title>System Integration </title>
    <abstract>
<para>This chapter will show you how to integrate eXo Platform 3.5 into your system throughout the specific topics below:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.SystemIntegration.Authentication">Authentication</link> </emphasis>
	</para>
	<para>
	The information which is related to the authentication, including:
	</para>
	<itemizedlist>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.SingleSignON">Single-Sign-On (SSO)</link>  </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.CenterAuthenticationService">Central Authentication Service (CAS)</link>  </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.KerberosSSOOnActiveDirectory">Kerberos SSO on Active Directory</link> </emphasis>
		</para>
	  </listitem>
	</itemizedlist>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.SystemIntegration.UserIntegration">Users integration</link>  </emphasis>
	</para>
	<para>The information which is related to the users integration, including:</para>
	<itemizedlist>
	  <listitem>
		<para>
		<emphasis role="bold">  <link linkend="DEV.SystemIntegration.OrganizationService">Organization Service</link> </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.MembershipsGroupsAndUsers">Memberships, Groups and Users</link> </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.OrganizationAPI">Organization API</link> </emphasis>
		</para>
	  </listitem>
	</itemizedlist>
  </listitem>
  <listitem>
	<para>
	 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.LDAPIntegration">LDAP Integration</link>
            </emphasis>
	</para>
	<para>
	Explanations of numerous parameters of the eXo LDAP organization service, including:
	</para>
	<itemizedlist>
	  <listitem>
		<para>
		<emphasis role="bold">  <link linkend="DEV.SystemIntegration.ConnectionSettings">Connection Settings</link> </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.OrganizationServiceConfiguration">Organization Service Configuration</link> </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.ActiveDirectorySampleConfiguration">Active Directory sample configuration</link>
                </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.SystemIntegration.PicketlinkIDM">Picketlink IDM</link> </emphasis>
		</para>
	  </listitem>
	</itemizedlist>
  </listitem>
  <listitem>
	<para>
	<emphasis role="bold">  <link linkend="DEV.SystemIntegration.Email">Email</link> </emphasis>
	</para>
	<para>
	Ways to configure the email service.
	</para>
  </listitem>
</itemizedlist>
</abstract>
    <section id="DEV.SystemIntegration.Authentication">
      <title>Authentication </title>
      <para xml:id="DEV.SystemIntegration.SingleSignON">
<citetitle>
<emphasis role="bold">
Single-Sign-On (SSO)
</emphasis>
</citetitle>
</para>
      <para>When logging into the portal, you can gain access to many systems through portlets using a single identity. However, in many cases, the portal infrastructure must be integrated with other SSO-enabled systems. There are many different Identity Management solutions available. The GateIn documentation gives detailed configuration for different SSO implementation. For more details, see <ulink url="../../../reference/html/chap-Reference_Guide-SSO_Single_Sign_On.html">SSO - Single Sign On</ulink>.</para>
      <para xml:id="DEV.SystemIntegration.CenterAuthenticationService">
<citetitle>
<emphasis role="bold">
Central Authentication Service (CAS)
</emphasis>
</citetitle>
</para>
      <para>Central Authentication Service (CAS) is a Web Single-Sign-On (WebSSO), developed by JA-SIG as an open source project. CAS enables you to work on different applications to log in only once and to be recognized and authenticated by all applications. Details about CAS can be found <ulink url="http://www.jasig.org/cas">here</ulink>.</para>
      <para>The CAS integration consists of two steps:</para>
      <itemizedlist>
        <listitem>
          <para>Installing or configuring the CAS server.</para>
        </listitem>
        <listitem>
          <para>Setting up the portal to use the CAS server.</para>
        </listitem>
      </itemizedlist>
      <para>For more information on CAS configuration, see <ulink url="../../../reference/html/sect-Reference_Guide-Single_Sign_On-CAS_Central_Authentication_Service.html">here</ulink>.</para>
      <para xml:id="DEV.SystemIntegration.KerberosSSOOnActiveDirectory">
<citetitle>
<emphasis role="bold">
Kerberos SSO on Active Directory
</emphasis>
</citetitle>
</para>
      <para>eXo Portal 3.5 supports the Kerberos authentication on a Microsoft Active Directory. You will need to configure both your Active Directory server and the application server.</para>
      <para>The implementation makes possible to use SPNEGO or NTLM. The client will get two authentication headers, including <emphasis role="bold">Negotiate</emphasis> and <emphasis role="bold">NTLM</emphasis> and will use whichever supported by the browser. In Firefox, it is possible to manage authentication types, but it is not in Internet Explorer; therefore, SPNEGO will be used.</para>
      <para>To learn more about how to configure Kerberos SSO, see <ulink url="http://wiki.exoplatform.com/xwiki/bin/view/WS/Kerberos%20SSO%20on%20Active%20Directory">here</ulink>.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.UserIntegration">Users integration</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.LDAPIntegration">LDAP Integration</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.Email">Email</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.SystemIntegration.UserIntegration">
      <title>Users integration </title>
      <para xml:id="DEV.SystemIntegration.OrganizationService">
<citetitle>
<emphasis role="bold">
Organization Service
</emphasis>
</citetitle>
</para>
      <para>To specify the initial Organization configuration, the content of your extension.war in <emphasis role="italic">/WEB-INF/conf/organization/organization-configuration.xml</emphasis> should be edited. This file uses the portal XML configuration schema. It lists several configuration plugins.</para>
      <para>The plugin of <emphasis role="italic">org.exoplatform.services.organization.OrganizationDatabaseInitializer</emphasis> type is used to specify a list of membership types, groups and users to be created.</para>
      <para xml:id="DEV.SystemIntegration.MembershipsGroupsAndUsers">
<citetitle>
<emphasis role="bold">
Memberships, Groups and Users
</emphasis>
</citetitle>
</para>
      <para>The predefined membership types are specified in the <emphasis role="bold">membershipType</emphasis> field of the OrganizationConfig plugin parameter.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<field name="membershipType">
  <collection type="java.util.ArrayList">
    <value>
      <object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">
        <field name="type">
          <string>member</string>
        </field>
        <field name="description">
          <string>member membership type</string>
        </field>
      </object>
    </value>
    <value>
      <object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">
        <field name="type">
          <string>owner</string>
        </field>
        <field name="description">
          <string>owner membership type</string>
        </field>
      </object>
    </value>
  </collection>
</field>]]></programlisting>
      </programlistingco>
      <para>The predefined groups are specified in the <emphasis role="bold">group</emphasis> field of the OrganizationConfig plugin parameter.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<field name="group">
  <collection type="java.util.ArrayList">
    <value>
      <object type="org.exoplatform.services.organization.OrganizationConfig$Group">
        <field name="name">
          <string>portal</string>
        </field>
        <field name="parentId">
          <string/>
        </field>
        <field name="type">
          <string>hierachy</string>
        </field>
        <field name="description">
          <string>the /portal group</string>
        </field>
      </object>
    </value>
    <value>
      <object type="org.exoplatform.services.organization.OrganizationConfig$Group">
        <field name="name">
          <string>community</string>
        </field>
        <field name="parentId">
          <string>/portal</string>
        </field>
        <field name="type">
          <string>hierachy</string>
        </field>
        <field name="description">
          <string>the /portal/community group</string>
        </field>
      </object>
    </value>
    ...
  </collection>
</field>]]></programlisting>
      </programlistingco>
      <para>The predefined users are specified in the <emphasis role="bold">membershipType</emphasis> field of the OrganizationConfig plugin parameter.</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<field name="user">
  <collection type="java.util.ArrayList">
    <value>
      <object type="org.exoplatform.services.organization.OrganizationConfig$User">
        <field name="userName">
          <string>root</string>
        </field>
        <field name="password">
          <string>exo</string>
        </field>
        <field name="firstName">
          <string>root</string>
        </field>
        <field name="lastName">
          <string>root</string>
        </field>
        <field name="email">
          <string>exoadmin@localhost</string>
        </field>
        <field name="groups">
          <string>member:/admin,member:/user,owner:/portal/admin</string>
        </field>
      </object>
    </value>
    <value>
      <object type="org.exoplatform.services.organization.OrganizationConfig$User">
        <field name="userName">
          <string>exo</string>
        </field>
        <field name="password">
          <string>exo</string>
        </field>
        <field name="firstName">
          <string>site</string>
        </field>
        <field name="lastName">
          <string>site</string>
        </field>
        <field name="email">
          <string>exo@localhost</string>
        </field>
        <field name="groups">
          <string>member:/user</string>
        </field>
      </object>
    </value>
    ...
  </collection>
</field>]]></programlisting>
      </programlistingco>
      <para xml:id="DEV.SystemIntegration.OrganizationAPI">
<citetitle>
<emphasis role="bold">
Organization API
</emphasis>
</citetitle>
</para>
      <para>The <emphasis role="italic">exo.platform.services.organization</emphasis> package has five main components: user, user profile, group, membership type and membership. There is an additional component that serves as an entry point into Organization API - <emphasis role="italic">OrganizationService</emphasis> component which provides handling functionality for five components. For more details, see the <ulink url="../../../reference/html/sect-Reference_Guide-APIs-Organization_API.html">Organization API</ulink> section.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.Authentication">Authentication</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.LDAPIntegration">LDAP Integration</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.Email">Email</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.SystemIntegration.LDAPIntegration">
      <title>LDAP Integration </title>
      <highlights>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.SystemIntegration.ConnectionSettings">Connection Settings</link>
            </para>
			<para>
			Description of parameters used in the connection settings.
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.SystemIntegration.OrganizationServiceConfiguration">Organization Service Configuration</link>
            </para>
			<para>
			Required information for configuring Organization Service that shows how the directory is structured and how to interact with it.
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.SystemIntegration.ActiveDirectorySampleConfiguration">Active Directory sample configuration</link>
            </para>
			<para>
			Introduction to an alternative configuration for active directory, and steps to use the LDAPs protocol with the Active Directory.
			</para>
          </listitem>
		  <listitem>
            <para>
              <link linkend="DEV.SystemIntegration.PicketlinkIDM">Picketlink IDM</link>
            </para>
			<para>
			Information about the PicketLink IDM component which eXo Platform currently uses for keeping the necessary identity information, such as users, groups, memberships.
			</para>
          </listitem>
        </itemizedlist>
</highlights>
      <note>
        <para>If you have an existing LDAP server, the eXo predefined settings will likely not match your directory structure. eXo LDAP organization service implementation was written with flexibility in mind and can certainly be configured to meet your requirements.</para>
        <para>The configuration is done in the <emphasis role="italic">ldap-configuration.xml</emphasis> file which contains numerous parameters.</para>
      </note>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.Authentication">Authentication</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.UserIntegration">Users integration</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.Email">Email</link>
          </para>
        </listitem>
      </itemizedlist>
      <section id="DEV.SystemIntegration.ConnectionSettings" role="NotInToc">
        <title>Connection Settings </title>
        <para>First, start by connection settings which will tell eXo how to connect to your directory server. These settings are very close to the <ulink url="http://java.sun.com/products/jndi">JNDI API</ulink> context parameters. This configuration is activated by the init-param <emphasis role="italic">ldap.config</emphasis> of service <emphasis role="italic">LDAPServiceImpl</emphasis>.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.services.ldap.LDAPService</key>
  <type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
  <init-params>
    <object-param>
      <name>ldap.config</name>
      <description>Default ldap config</description>
      <object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
        <field name="providerURL">
          <string>ldap://127.0.0.1:389,10.0.0.1:389</string>
        </field>
        <field name="rootdn">
          <string>CN=Manager,DC=exoplatform,DC=org</string>
        </field>
        <field name="password">
          <string>secret</string>
        </field>
        <!-- field name="authenticationType"><string>simple</string></field -->
        <field name="version">
          <string>3</string>
        </field>
        <field name="referralMode">
          <string>follow</string>
        </field>
        <!-- field name="serverName"><string>active.directory</string></field -->
      </object>
    </object-param>
  </init-params>
</component>]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">providerURL</emphasis>: LDAP server URL (see <ulink url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Context.html#PROVIDER_URL">PROVIDER URL</ulink>). For multiple LDAP servers, use comma separated list of host:port (For example, ldap://127.0.0.1:389,10.0.0.1:389).</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">rootdn</emphasis>: distinguished name of user that will be used by the service to authenticate on the server (see <ulink url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Context.html#SECURITY_PRINCIPAL">SECURITY PRINCIPAL</ulink>).</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">password</emphasis>: password for user <emphasis role="italic">rootdn</emphasis> (see <ulink url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Context.html#SECURITY_CREDENTIALS">SECURITY CREDENTIALS</ulink>).</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">authenticationType</emphasis>: type of authentication to be used (see <ulink url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Context.html#SECURITY_AUTHENTICATION">SECURITY AUTHENTICATION</ulink>). Use one of <emphasis role="italic">none</emphasis>, <emphasis role="italic">simple</emphasis>, <emphasis role="italic">strong</emphasis>. Default is <emphasis role="italic">simple</emphasis>.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">version</emphasis>: LDAP protocol version (see <ulink url="http://java.sun.com/products/jndi/tutorial/ldap/misc/version.html">java.naming.ldap.version</ulink>). Set to 3 if your server supports LDAP V3.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">referralMode</emphasis>: one of <emphasis role="italic">follow</emphasis>, <emphasis role="italic">ignore</emphasis>, <emphasis role="italic">throw</emphasis> (see <ulink url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Context.html#REFERRAL">REFERRAL</ulink>).</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">serverName</emphasis>: you will need to set this to <emphasis role="italic">active.directory</emphasis> to work with Active Directory servers. Any other value will be ignored and the service will act as on a standard LDAP.</para>
          </listitem>
        </itemizedlist>
      </section>
      <section id="DEV.SystemIntegration.OrganizationServiceConfiguration" role="NotInToc">
        <title>Organization Service Configuration </title>
        <para>Next, you need to configure the eXo <emphasis role="bold">OrganizationService</emphasis> to show how the directory is structured and how to interact with it. This is managed by a couple of init-params: <emphasis role="bold">ldap.userDN.key</emphasis> and <emphasis role="bold">ldap.attribute.mapping</emphasis> in the <emphasis role="italic">ldap-configuration.xml</emphasis> file (by default located at <emphasis role="italic">portal.war/WEB-INF/conf/organization</emphasis>)</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.services.organization.OrganizationService</key>
  <type>org.exoplatform.services.organization.ldap.OrganizationServiceImpl</type>
  [...]
  <init-params>
    <value-param>
      <name>ldap.userDN.key</name>
      <description>The key used to compose user DN</description>
      <value>cn</value>
    </value-param>
    <object-param>
      <name>ldap.attribute.mapping</name>
      <description>ldap attribute mapping</description>
      <object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping"/>
        [...]
    </object-param>
  </init-params>
  [...]
</component>]]></programlisting>
        </programlistingco>
        <para>
          <emphasis role="bold">ldap.attribute.mapping</emphasis> maps your LDAP to eXo. At first, there are two main parameters to configure in it:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<field name="baseURL">
  <string>dc=exoplatform,dc=org</string>
</field>
<field name="ldapDescriptionAttr">
  <string>description</string>
</field>]]></programlisting>
        </programlistingco>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">baseURL</emphasis>: root dn for eXo organizational entities. This entry cannot be created by eXo and must have existed in the directory already.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">ldapDescriptionAttr</emphasis>: Name of a common attribute that will be used as description for groups and membership types.</para>
          </listitem>
        </itemizedlist>
        <warning>
          <para>In Core, the ldapDescriptionAttr key is present but not consistently used everywhere in code. When using <emphasis role="bold">Core</emphasis>, consider that the description is always mapped to the 'description' attribute.</para>
        </warning>
        <section id="DEV.SystemIntegration.Users">
          <title>Users </title>
          <para xml:id="DEV.SystemIntegration.MainParameters">
<citetitle>
<emphasis role="bold">
Main parameters
</emphasis>
</citetitle>
</para>
          <para>Here are the main parameters to map eXo users to your directory:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<field name="userURL">
  <string>ou=users,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="userObjectClassFilter">
  <string>objectClass=person</string>
</field>
<field name="userLDAPClasses">
  <string>top,person,organizationalPerson,inetOrgPerson</string>
</field>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">userURL</emphasis>: base dn for users. Users are created in a flat structure under this base with a <emphasis role="bold">dn</emphasis> of the form: <emphasis role="bold">ldap.userDN.key=username,userURL</emphasis>.</para>
            </listitem>
          </itemizedlist>
          <para>For example: <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting><![CDATA[uid=john,cn=People,o=MyCompany,c=com]]></programlisting>
            </programlistingco>
          </para>
          <para>However, if users exist deeply under <emphasis role="italic">userURL</emphasis>, eXo will be able to retrieve them.</para>
          <para>Example: <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting><![CDATA[uid=tom,ou=France,ou=EMEA,cn=People,o=MyCompany,c=com]]></programlisting>
            </programlistingco>
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">userObjectClassFilter</emphasis>: Filter used under <emphasis role="italic">userURL</emphasis> branch to distinguish eXo user entries from others.</para>
            </listitem>
          </itemizedlist>
          <para>Example: <emphasis role="italic">john</emphasis> and <emphasis role="italic">tom</emphasis> will be recognized as valid eXo users but <emphasis role="italic">EMEA</emphasis> and <emphasis role="italic">France</emphasis> entries will be ignored in the following subtree:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[uid=john,cn=People,o=MyCompany,c=com
  objectClass: person
  ...
ou=EMEA,cn=People,o=MyCompany,c=com
  objectClass: organizationalUnit
  ...
    ou=France,ou=EMEA,cn=People,o=MyCompany,c=com
      objectClass: organizationalUnit
      ...
        uid=tom,ou=EMEA,cn=People,o=MyCompany,c=com
          objectClass: person
          ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">userLDAPClasses</emphasis>: commas are used to separate list of classes used for creating users.  When a new user is created, an entry will be created with the given <emphasis role="italic">objectClass</emphasis> attributes.  The classes must at least define <emphasis role="italic">cn</emphasis> and any attribute referenced in the user mapping.</para>
            </listitem>
          </itemizedlist>
          <para>For example, adding the user <emphasis role="italic">Marry Simons</emphasis> could produce:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[uid=marry,cn=users,ou=portal,dc=exoplatform,dc=org
  objectclass: top
  objectClass: person
  objectClass: organizationalPerson
  objectClass: inetOrgPerson
  ...]]></programlisting>
          </programlistingco>
          <para xml:id="DEV.SystemIntegration.UserMapping">
<citetitle>
<emphasis role="bold">
User mapping
</emphasis>
</citetitle>
</para>
          <para>The following parameters maps LDAP attributes to eXo User Java objects attributes.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<field name="userUsernameAttr">
  <string>uid</string>
</field>
<field name="userPassword">
  <string>userPassword</string>
</field>
<field name="userFirstNameAttr">
  <string>givenName</string>
</field>
<field name="userLastNameAttr">
  <string>sn</string>
</field>
<field name="userDisplayNameAttr">
  <string>displayName</string>
</field>
<field name="userMailAttr">
  <string>mail</string>
</field>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">userUsernameAttr</emphasis>: username (login)</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">userPassword</emphasis>: password (used when the portal authentication is done by eXo login module)</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">userFirstNameAttr</emphasis>: first name</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">userLastNameAttr</emphasis>: last name</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">userDisplayNameAttr</emphasis>: display name</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">userMailAttr</emphasis>: email address</para>
            </listitem>
          </itemizedlist>
          <para>In the example above, the user <emphasis role="italic">Marry Simons</emphasis> could produce:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[uid=marry,cn=users,ou=portal,dc=exoplatform,dc=org
  userPassword: XXXX
  givenName: Marry
  sn: Simons
  displayName: Marry Simons
  mail: marry.simons@example.org
  uid: marry
  ...]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.SystemIntegration.Groups">
          <title>Groups </title>
          <para>eXo Platform groups can be mapped to organizational or applicative groups defined in your directory.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<field name="groupsURL">
  <string>ou=groups,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="groupLDAPClasses">
  <string>top,organizationalUnit</string>
</field>
<field name="groupObjectClassFilter">
  <string>objectClass=organizationalUnit</string>
</field>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">groupsURL</emphasis>: base dn for eXo groups Groups can be structured hierarchically under <emphasis role="italic">groupsURL</emphasis>.              For example, groups, including <emphasis role="italic">communication</emphasis>, <emphasis role="italic">communication/marketing</emphasis> and <emphasis role="italic">communication/press</emphasis>, would map to:             </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org
...
  ou=marketing,ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org
  ...            
  ou=press,ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org                          
  ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">groupLDAPClasses</emphasis>: commas are used to separate list of classes used for group creation.  When a new group is created, an entry will be also created with the given objectClass attributes. The classes must define at least the required attributes: <emphasis role="bold">ou</emphasis>, <emphasis role="bold">description</emphasis> and <emphasis role="bold">l</emphasis>.</para>
            </listitem>
          </itemizedlist>
          <note>
            <para>The <emphasis role="bold">l</emphasis> attribute corresponds to the <emphasis role="bold">City</emphasis> property in OU property editor.</para>
          </note>
          <para>                         For example, adding the <emphasis role="italic">human-resources</emphasis> group could produce: </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
  objectclass: top
  objectClass: organizationalunit
  ou: human-resources
  description: The human resources department
  l: Human Resources
  ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">groupObjectClassFilter</emphasis>: This filter is used under the <emphasis role="italic">groupsURL</emphasis> branch to distinguish eXo groups from other entries. You can also use a complex filter if you need.              Example: groups <emphasis role="italic">WebDesign</emphasis>, <emphasis role="italic">WebDesign/Graphists</emphasis> and <emphasis role="italic">sales</emphasis> could be retrieved in:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[l=Paris,dc=sites,dc=mycompany,dc=com
  ...
  ou=WebDesign,l=Paris,dc=sites,dc=mycompany,dc=com
  ...
    ou=Graphists,WebDesign,l=Paris,dc=sites,dc=mycompany,dc=com
    ...
l=London,dc=sites,dc=mycompany,dc=com
  ...
  ou=Sales,l=London,dc=sites,dc=mycompany,dc=com
  ...]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.SystemIntegration.MembershipTypes">
          <title>Membership types </title>
          <para>Membership types are the possible roles that can be assigned to users in groups.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<field name="membershipTypeURL">
  <string>ou=memberships,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="membershipTypeLDAPClasses">
  <string>top,organizationalRole</string>
</field>
<field name="membershipTypeNameAttr">
  <string>cn</string>
</field>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipTypeURL</emphasis>: base dn for membership types storage. eXo stores membership types in a flat structure under <emphasis role="italic">membershipTypeURL</emphasis>. For example, roles, including <emphasis role="italic">manager</emphasis>, <emphasis role="italic">user</emphasis>, <emphasis role="italic">admin</emphasis> and <emphasis role="italic">editor</emphasis> could be defined by the subtree:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[ou=roles,ou=portal,dc=exoplatform,dc=org
...
  cn=manager,ou=roles,ou=portal,dc=exoplatform,dc=org
  ...
  cn=user,ou=roles,ou=portal,dc=exoplatform,dc=org
  ...
  cn=admin,ou=roles,ou=portal,dc=exoplatform,dc=org               
  ...
  cn=editor,ou=roles,ou=portal,dc=exoplatform,dc=org
  ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipTypeLDAPClasses</emphasis>: commas are used to separate list of classes for creating membership types. When a new membership type is created, an entry will be also created with the given <emphasis role="italic">objectClass</emphasis> attributes. The classes must define the required attributes: <emphasis role="bold">description</emphasis>, <emphasis role="bold">cn</emphasis>. </para>
            </listitem>
          </itemizedlist>
          <para>For example, adding the membership type <emphasis role="italic">validator</emphasis> would produce: </para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[cn=validator,ou=roles,ou=portal,dc=exoplatform,dc=org
  objectclass: top
  objectClass: organizationalRole
  ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipTypeNameAttr</emphasis>: Attribute will be used as the name of the role.            For example, if <emphasis role="italic">membershipTypeNameAttr</emphasis> is <emphasis role="italic">cn</emphasis>, the role name will be <emphasis role="italic">manager</emphasis> for the following membership type entry: </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[cn=manager,ou=roles,ou=portal,dc=exoplatform,dc=org ]]></programlisting>
          </programlistingco>
        </section>
        <section id="DEV.SystemIntegration.Membership">
          <title>Memberships </title>
          <para>Memberships are used to assign a role within a group. They are entries that are placed under the group entry of their scope group. Users in this role are defined as attributes of the membership entry.             </para>
          <itemizedlist>
            <listitem>
              <para>For example, to designate <emphasis role="italic">tom</emphasis> as the <emphasis role="italic">manager</emphasis> of the group <emphasis role="italic">human-resources</emphasis>: </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
  ...
  cn=manager,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
    member: uid=tom,ou=users,ou=portal,dc=exoplatform,dc=org
    ...]]></programlisting>
          </programlistingco>
          <para>The parameters to configure memberships are:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<field name="membershipLDAPClasses">
  <string>top,groupOfNames</string>
</field>
<field name="membershipTypeMemberValue">
  <string>member</string>
</field>
<field name="membershipTypeRoleNameAttr">
  <string>cn</string>
</field>
<field name="membershipTypeObjectClassFilter">
  <string>objectClass=organizationalRole</string>
</field>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipLDAPClasses</emphasis>: the commas are used to separate the list of classes for creating memberships. When a new membership is created, an entry will be also created with the given <emphasis role="italic">objectClass</emphasis> attributes. The classes must at least define the attribute designated by <emphasis role="italic">membershipTypeMemberValue</emphasis>.            Example: Adding membership <emphasis role="italic">validator</emphasis> would produce:</para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[cn=validator,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
  objectclass: top
  objectClass: groupOfNames
  ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipTypeMemberValue</emphasis>: Multi-valued attribute is used in memberships to reference users that have the role in the group.  Values should be a user dn.</para>
            </listitem>
          </itemizedlist>
          <para>Example: <emphasis role="italic">james</emphasis> and <emphasis role="italic">root</emphasis>, who have <emphasis role="italic">admin</emphasis> role within the group <emphasis role="italic">human-resources</emphasis>, would give:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[cn=admin,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
  member: cn=james,ou=users,ou=portal,dc=exoplatform,dc=org
  member: cn=root,ou=users,ou=portal,dc=exoplatform,dc=org
  ...]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipTypeRoleNameAttr</emphasis>: Attribute of the membership entry whose value refers to the membership type.              For example, in the following membership entry:             </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[cn=manager,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org]]></programlisting>
          </programlistingco>
          <para>           The <emphasis role="italic">cn</emphasis> attribute is used to designate the <emphasis role="italic">manager</emphasis> membership type. In other words, the name of role is given by the 'cn' attribute.</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">membershipTypeObjectClassFilter</emphasis>: Filter is used to distinguish membership entries under groups. You can use the more complex filters.              For example, the following is a filter used for a customer that needs to trigger a dynlist overlay on OpenLDAP.            </para>
            </listitem>
          </itemizedlist>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting><![CDATA[(&amp;amp;(objectClass=ExoMembership)(membershipURL=&#42;)) ]]></programlisting>
          </programlistingco>
          <para>          </para>
          <note>
            <para>Please pay attention to the xml escaping of the '&amp;' (and) operator.</para>
          </note>
        </section>
        <section id="DEV.SystemIntegration.UserProfiles">
          <title>User profiles </title>
          <para>eXo User profiles also have entries in the LDAP but the actual storage is still done with the hibernate service. You will need the following parameters:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[<field name="profileURL">
  <string>ou=profiles,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="profileLDAPClasses">
  <string>top,organizationalPerson</string>
</field>]]></programlisting>
          </programlistingco>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">profileURL</emphasis>: base dn to store user profiles.</para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">profileLDAPClasses</emphasis>: Classes used for creating user profiles.</para>
            </listitem>
          </itemizedlist>
        </section>
      </section>
      <section id="DEV.SystemIntegration.ActiveDirectorySampleConfiguration" role="NotInToc">
        <title>Active Directory sample configuration </title>
        <para>Here is an alternative configuration for active directory that you can find in <emphasis role="bold">activedirectory-configuration.xml</emphasis>.</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[[...]
<component>
  <key>org.exoplatform.services.ldap.LDAPService</key>
  [..]
  <object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">         
  <!-- for multiple ldap servers, use comma separated list of host:port (Ex. ldap://127.0.0.1:389,10.0.0.1:389) -->
  <!-- whether or not to enable ssl, if ssl is used ensure that the javax.net.ssl.keyStore & java.net.ssl.keyStorePassword properties are set -->
  <!-- exo portal default installed javax.net.ssl.trustStore with file is java.home/lib/security/cacerts-->
  <!-- ldap service will check protocol, if protocol is ldaps, ssl is enable (Ex. for enable ssl: ldaps://10.0.0.3:636 ;for disable ssl: ldap://10.0.0.3:389 ) -->
  <!-- when enable ssl, ensure server name is *.directory and port (Ex. active.directory) -->	  		 
    <field name="providerURL"><string>ldaps://10.0.0.3:636</string></field>
    <field name="rootdn"><string>CN=Administrator,CN=Users, DC=exoplatform,DC=org</string></field>
    <field name="password"><string>site</string></field> 		
    <field name="version"><string>3</string></field>	            
    <field name="referralMode"><string>ignore</string></field>     	       	       
    <field name="serverName"><string>active.directory</string></field>    	       	  
  </object>
  [..]
</component>
<component>
  <key>org.exoplatform.services.organization.OrganizationService</key>
  [...]
  <object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping">                
    [...]
    <field name="userAuthenticationAttr"><string>mail</string></field>
    <field name="userUsernameAttr"><string>sAMAccountName</string></field>
    <field name="userPassword"><string>unicodePwd</string></field> 
    <field name="userLastNameAttr"><string>sn</string></field>
    <field name="userDisplayNameAttr"><string>displayName</string></field>
    <field name="userMailAttr"><string>mail</string></field>
    [..]
    <field name="membershipTypeLDAPClasses"><string>top,group</string></field>
    <field name="membershipTypeObjectClassFilter"><string>objectClass=group</string></field>
    [..]
    <field name="membershipLDAPClasses"><string>top,group</string></field>
    <field name="membershipObjectClassFilter"><string>objectClass=group</string></field>
  </object>
  [...]  
</component>]]></programlisting>
        </programlistingco>
        <note>
          <para>There is a Microsoft limitation: the password cannot be set in AD via unsecured connection, you have to use the LDAPs protocol.</para>
        </note>
        <para>Here is how to use the LDAPs protocol with the Active Directory:</para>
        <para>
          <emphasis role="bold">1.</emphasis> Set up AD to use SSL:</para>
        <para>
          <emphasis role="bold">i.</emphasis> Add the Active Directory Certificate Services role.</para>
        <para>
          <emphasis role="bold">ii.</emphasis> Install the right certificate for the DC machine.</para>
        <para>
          <emphasis role="bold">2.</emphasis> Enable Java VM to use the certificate from AD:</para>
        <para>
          <emphasis role="bold">i.</emphasis> Import the root CA used in AD, to keystore, such as: keytool <emphasis role="strikethrough">importcert </emphasis>file 2008.cer <emphasis role="strikethrough">keypass changeit </emphasis>keystore /home/user/java/jdk1.6/jre/lib/security/cacerts.</para>
        <para>
          <emphasis role="bold">ii.</emphasis> Set the Java options as below:</para>
        <para>  <emphasis role="italic">JAVA_OPTS="${JAVA_OPTS} -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStore=/home/user/java/jdk1.6/jre/lib/security/ca"</emphasis>
        </para>
      </section>
      <section id="DEV.SystemIntegration.PicketlinkIDM" role="NotInToc">
        <title>Picketlink IDM </title>
        <para>eXo Platform uses the PicketLink IDM component to keep the necessary identity information, such as users, groups, memberships. While the legacy interfaces are still used (org.exoplatform.services.organization) for the identity management, there is a wrapper implementation that delegates to the PicketLink IDM framework.  For further information, visit <ulink url="http://jboss.org/picketlink/IDM.html">here</ulink>.</para>
        <para>The project exo.core defines the API for Organization Service and the eXo Platform implementation of API. For the Organization Service plugged in the eXo Platform product, you are flexible in switching between: eXo Organization Service, PicketLink and your own implementation. The configuration to switch between various Organization Service implementations can be found in <emphasis role="italic">portal.war/WEB-INF/conf/configuration.xml</emphasis>:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<!--PicketLink IDM integration -->
<import>war:/conf/organization/idm-configuration.xml</import>

<!--Former exo implementations -->
<!--<import>war:/conf/organization/exo/hibernate-configuration.xml</import> -->
<!-- <import>war:/conf/organization/exo/jdbc-configuration.xml</import> -->
<!--for organization service used active directory which is user lookup server -->
<!-- <import>war:/conf/organization/exoactivedirectory-configuration.xml</import> -->
<!--for organization service used ldap server which is user lookup server -->
<!-- <import>war:/conf/ldap-configuration.xml</import> -->]]></programlisting>
        </programlistingco>
        <para>If you want to switch between different implementations, you just need to uncomment the corresponding &lt;import&gt; and leave others commented:</para>
        <programlistingco>
          <areaspec units="linecolumn"/>
          <programlisting language="xml"><![CDATA[<!--PicketLink IDM integration -->
<import>war:/conf/ldap-configuration.xml</import>
<!-- <import>war:/conf/organization/idm-configuration.xml</import> -->
<!--Former exo implementations -->
<!--<import>war:/conf/organization/exo/hibernate-configuration.xml</import> -->
<!-- <import>war:/conf/organization/exo/jdbc-configuration.xml</import> -->
<!--for organization service used active directory which is user lookup server -->
<!-- <import>war:/conf/organization/exoactivedirectory-configuration.xml</import> -->
<!--for organization service used ldap server which is user lookup server -->]]></programlisting>
        </programlistingco>
      </section>
    </section>
    <section id="DEV.SystemIntegration.Email">
      <title>Email </title>
      <para>The email service can use any SMTP account configured in the <emphasis role="italic">configuration.properties</emphasis> file.</para>
      <para>
        <emphasis role="bold">File location</emphasis>
      </para>
      <informaltable>
        <thead>
          <tr>
            <th> File </th>
            <th> Tomcat </th>
            <th> JBoss </th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td> <emphasis role="italic">
                <emphasis role="bold">configuration.properties</emphasis>
              </emphasis> </td>
            <td> <emphasis role="italic">$PLATFOORM_TOMCAT_HOME/gatein/conf/configuration.properties</emphasis> </td>
            <td> <emphasis role="italic">$PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties</emphasis> </td>
          </tr>
        </tbody>
      </informaltable>
      <para>The relevant section looks like:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[# EMail
gatein.email.smtp.username=
gatein.email.smtp.password=
gatein.email.smtp.host=smtp.gmail.com
gatein.email.smtp.port=465
gatein.email.smtp.starttls.enable=true
gatein.email.smtp.auth=true
gatein.email.smtp.socketFactory.port=465
gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory]]></programlisting>
      </programlistingco>
      <para>It is pre-configured for Gmail, so any Gmail account can easily be used. You simply need to use the full Gmail address as username, and fill in the password.</para>
      <para>In corporate environments, you will want to use your corporate SMTP gateway. When using it over SSL, like in the default configuration, you may need to configure a certificate trust-store, containing your SMTP server's public certificate. Depending on the key sizes, you might also need to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your Java Runtime Environment.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.Authentication">Authentication</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.UserIntegration">Users integration</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.SystemIntegration.LDAPIntegration">LDAP Integration</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
  </chapter>
  <chapter id="DEV.eXoPlatformAPIs">
    <title>eXo Platform 3.5 APIs </title>
    <abstract>
<para>This chapter presents the information about APIs that help you build your own applications from eXo services via the following topics:</para>
<itemizedlist>
  <listitem>
	<para>
	 <emphasis role="bold"> <link linkend="DEV.eXoPlatformSupportedAPIs.DefinitionsOfAPILevels">Definitions of API Levels</link>
            </emphasis>
	</para>
	<para>
		Introduction to the different levels of APIs, Provisional or Experimental APIs.
	</para>
  </listitem>
  <listitem>
	<para>
	 <emphasis role="bold"> <link linkend="DEV.eXoPlatformSupportedAPIs.PlatformAPIs">Platform APIs</link>
            </emphasis>
	</para>
	<para>
		Definitions of levels of Platform APIs, including:
	</para>
	<itemizedlist>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.eXoPlatformSupportedAPIs.JavaAPIs">Java APIs</link>
                </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.eXoPlatformSupportedAPIs.JavaScriptAPIs">JavaScript APIs</link>
                </emphasis>
		</para>
	  </listitem>
	  <listitem>
		<para>
		 <emphasis role="bold"> <link linkend="DEV.eXoPlatformSupportedAPIs.WebServices">Web Services</link>
                </emphasis>
		</para>
	  </listitem>
	</itemizedlist>
  </listitem>
  <listitem>
	<para>
	 <emphasis role="bold">
              <link linkend="DEV.eXoPlatformSupportedAPIs.ProvisionalAPIs">Provisional APIs</link>
            </emphasis>
	</para>
	<para>
		A list of provisional APIs.
	</para>
  </listitem>
</itemizedlist>
</abstract>
    <section id="DEV.eXoPlatformSupportedAPIs.DefinitionsOfAPILevels">
      <title>Definitions of API Levels </title>
      <para>APIs vary according to the maturity level. It is important to understand the eXo Platform's general approach to the API change management. The different levels of APIs are described in the following table:</para>
      <informaltable>
        <thead>
          <tr>
            <th> API Level </th>
            <th> Test Suite </th>
            <th> Clients </th>
            <th> Documentation </th>
            <th> Support </th>
            <th> Compatibility X.Y.Z(1) </th>
            <th> Compatibility X.Y(1) </th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>
              <emphasis role="bold">Platform API</emphasis>
            </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
          </tr>
          <tr>
            <td>
              <emphasis role="bold">Provisional API</emphasis>
            </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
          </tr>
          <tr>
            <td>
              <emphasis role="bold">Experimental API</emphasis>
            </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/yes.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> Best effort </td>
            <td> Best effort </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
          </tr>
          <tr>
            <td>
              <emphasis role="bold">Unsupported API</emphasis>
            </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
            <td> <inlinemediaobject>
                <imageobject role="fo">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
                <imageobject role="html">
                  <imagedata fileref="images/no.gif" format="GIF"/>
                </imageobject>
              </inlinemediaobject> </td>
          </tr>
        </tbody>
      </informaltable>
      <para>
        <emphasis role="bold">Test Suite</emphasis>: A suite of tests that can be run against the API to detect changes.</para>
      <para>
        <emphasis role="bold">Clients</emphasis>: The API has been used successfully by at least 2 different teams, using the API Documentation only.</para>
      <para>
        <emphasis role="bold">Documentation</emphasis>: The API has a clean JavaDoc and reference documentation.</para>
      <para>
        <emphasis role="bold">Support</emphasis>: The eXo Support team provides help on the code that uses this API, and fixes any reported bugs.</para>
      <para>
        <emphasis role="bold">Compatibility X.Y.Z(1)</emphasis>: The compatibility between maintenance versions (X.Y.Z and X.Y.Z1) is guaranteed. If there is any change between X.Y and X.Y1, the eXo Support team will help by upgrading the code.</para>
      <para>
        <emphasis role="bold">Compatibility X.Y(1)</emphasis>: The compatibility between minor versions (X.Y and X.Y1) is guaranteed. If there is any change between X and X1, the eXo Support team will help by upgrading the code.</para>
      <para>
        <emphasis role="bold">Best Effort</emphasis>: You will receive assistance, but eXo Platform cannot guarantee any specific result.</para>
      <para xml:id="DEV.eXoPlatformSupportedAPIs.UseProvisionalOrExperimentalAPIs">
<citetitle>
<emphasis role="bold">
Use Provisional or Experimental APIs
</emphasis>
</citetitle>
</para>
      <para>These APIs are provided to give an "early look" at which will be available in upcoming versions of eXo Platform. These APIs are not final, but they can be used to start developing your application.</para>
      <para>
        <emphasis role="bold">Provisional APIs</emphasis> are APIs close to being frozen, but that need a last look from users. They can be used by third-party developers for their own apps, with the knowledge that only a limited compatibility guarantee is offered.</para>
      <para>
        <emphasis role="bold">Experimental APIs</emphasis> are APIs that are likely to change. They are published to get feedback from the community. These APIs have been tested successfully, but have not yet had enough feedback from developers.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.eXoPlatformSupportedAPIs.PlatformAPIs">Platform APIs</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.eXoPlatformSupportedAPIs.ProvisionalAPIs">Provisional APIs</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.eXoPlatformSupportedAPIs.PlatformAPIs">
      <title>Platform APIs </title>
      <highlights>
<para>This section summarizes a list of eXo Platform APIs which can be categoried into:</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.eXoPlatformSupportedAPIs.JavaAPIs">Java APIs</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.eXoPlatformSupportedAPIs.JavaScriptAPIs">JavaScript APIs</link>
            </para>
          </listitem>
		  <listitem>
            <para>
              <link linkend="DEV.eXoPlatformSupportedAPIs.WebServices">Web Services</link>
            </para>
          </listitem>
        </itemizedlist>
</highlights>
      <para xml:id="DEV.eXoPlatformSupportedAPIs.JavaAPIs">
<citetitle>
<emphasis role="bold">
Java APIs
</emphasis>
</citetitle>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/sect-Reference_Guide-Portlet_Primer.html">Portlet API:</ulink> (JSR 168 and JSR 286)</emphasis> A Java standard that defines how to write portlets. This is the way to develop Java applications that are integrated into eXo Platform.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/wsrp.html">WSRP 1.0 on JBoss:</ulink>
            </emphasis> A network protocol for integrating remote portlets into eXo Platform.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/WS.RestServicesList.html">JAX-RS:</ulink> (JSR 311)</emphasis> A standard API that provides support for creating REST-like services.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/JCR.WhyuseJCR.WhatJCR.html">JCR (JSR 170):</ulink>
            </emphasis> A standard API that provides access to a content repository.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/JCR.Extensions.html">JCR Service Extensions:</ulink>
            </emphasis> A set of APIs that provide extended functionalities for the JCR, such as observation, permissions, and access to a repository.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="http://www.oracle.com/technetwork/java/javaee/overview/index.html">Java EE 6:</ulink>
            </emphasis> eXo Platform supports the Java EE 5 APIs, so you can develop applications using this standard.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="http://docs.jboss.org/exojcr/1.14.7-GA/developer/en-US/html/ch-cache.html">Cache:</ulink>
            </emphasis> An API used for data caching.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Kernel.UnderstandingtheListenerService.html">Event and Listener:</ulink>
            </emphasis> An API for listening and sending events within eXo Platform.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Core.OrganizationService.html">Organization:</ulink>
            </emphasis> An API and SPI for accessing user, group and membership information.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/PortalContainer.html">Portal Container:</ulink>
            </emphasis> This API is used to configure your portal.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.TaxonomyService.html">TaxonomyService:</ulink>
            </emphasis> An API that allows you to organize your content.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.LinkManager.html">LinkManager:</ulink>
            </emphasis> An API that provides a way to manage links when developing WCM features.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.PublicationManager.html">PublicationManager:</ulink>
            </emphasis> An API that provides different ways to manage the publication of content when developing WCM features.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.WCMComposer.html">WCMComposer:</ulink>
            </emphasis> An API to get content shown in the website. The cache management is used in this service, and methods to update the content cache.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.NewFolksonomy.html">NewFolksonomy:</ulink>
            </emphasis> An API to manage all the tags and their styles. Currently, it just supports adding/editing/removing the <emphasis role="bold">Private &amp; Public</emphasis> tags.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.ApplicationTemplateManager.html">ApplicationTemplateManager:</ulink>
            </emphasis>   An API to manage dynamic groovy templates for WCM-based products.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.NodeFinder.html">NodeFinder:</ulink>
            </emphasis> An API to find a node with a given path.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.JodConverter.html">JodConverter:</ulink>
            </emphasis> An API to convert documents into different office formats.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.Configuration.Components.SiteSearchService.html">SiteSearchService:</ulink>
            </emphasis> An API that allows users to find all information matching with their given keyword.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.JavaServices.SEOService.html">SEOService:</ulink>
            </emphasis> An API that manages SEO data of a page or a content.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.Configuration.Components.TimelineService.html">TimelineService:</ulink>
            </emphasis> An API that allows documents to be displayed by days, months and years.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Kernel.ServicesWiring.IntroductionXMLSchemaOfConfigurationXML.html">XML Configuration:</ulink>
            </emphasis> A set of DTD for configuring eXo Platform.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Developer_document.Java_APIs.Activity_Manager.html">ActivityManager:</ulink>
            </emphasis> An API to manage activities (create/delete/like activity; delete/like/create comment; get activities of space/user/connection).</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Developer_document.Java_APIs.Identity_Manager.html">IdentityManager:</ulink>
            </emphasis> An API to manage identities (create identity, save profile, get connection of an identity).</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Developer_document.Java_APIs.Relationship_manager.html">RelationshipManager:</ulink>
            </emphasis> An API which is used to work with connections between 2 identities, interact between identities, get list access to get list of connections, incomings, outgoings.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Developer_document.JavaAPIs.Java_APIs.SpaceService.html">SpaceService:</ulink>
            </emphasis>  An API that provides methods for working with space (create new space, delete, get space by url, groupid, display name, pretty name).</para>
        </listitem>
      </itemizedlist>
      <para xml:id="DEV.eXoPlatformSupportedAPIs.JavaScriptAPIs">
<citetitle>
<emphasis role="bold">
JavaScript APIs
</emphasis>
</citetitle>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="http://opensocial-resources.googlecode.com/svn/spec/1.1/Social-Gadget.xml">OpenSocial 1.1 Gadget Specification:</ulink>
            </emphasis> A standard that defines how to write gadgets and provide APIs. Gadgets are particularly useful for integrating external applications into eXo Platform.</para>
        </listitem>
      </itemizedlist>
      <para xml:id="DEV.eXoPlatformSupportedAPIs.WebServices">
<citetitle>
<emphasis role="bold">
Web Services
</emphasis>
</citetitle>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.CMIS.html">CMIS:</ulink>
            </emphasis> A standard API that gives access to the content repository via REST and SOAP Web services.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/JCR.FTP.html">FTP:</ulink>
            </emphasis> A standard protocol for exchanging documents.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="http://opensocial-resources.googlecode.com/svn/spec/1.1/Social-API-Server.xml">OpenSocial 1.1 REST Protocol:</ulink>
            </emphasis> A standard API for accessing the social graph and activity streams.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/JCR.WebDAV.html">WebDAV:</ulink>
            </emphasis> A standard protocol for exchanging document over HTTP.</para>
        </listitem>
      </itemizedlist>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.eXoPlatformSupportedAPIs.DefinitionsOfAPILevels">Definitions of API Levels</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.eXoPlatformSupportedAPIs.ProvisionalAPIs">Provisional APIs</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.eXoPlatformSupportedAPIs.ProvisionalAPIs">
      <title>Provisional APIs </title>
      <para xml:id="DEV.eXoPlatformSupportedAPIs.ProvisionalAPIs.JavaAPIs">
<citetitle>
<emphasis role="bold">
Java APIs
</emphasis>
</citetitle>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.Extensions.UIExtensions.html">UI Extensions:</ulink>
            </emphasis> An API to plug new actions into the eXo Platform UI.</para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/CONTref.Extensions.UIExtensions.AddOwnTabInECMAdministration.AddOwnUIAction.html">ECM Admin and DocumentExplorer Toolbar</ulink>
            </emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="../../../reference/html/Developer_document.Activity_plug-in.html">Activity Sharing</ulink>
            </emphasis>
          </para>
        </listitem>
      </itemizedlist>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.eXoPlatformSupportedAPIs.DefinitionsOfAPILevels">Definitions of API Levels</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.eXoPlatformSupportedAPIs.PlatformAPIs">Platform APIs</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
  </chapter>
  <chapter id="DEV.Cookbook">
    <title>Cookbook </title>
    <abstract>
<para>This chapter currently focuses on how to copy a work done on the eXo Platform server, such as creating navigations, node types and templates, to another eXo Platform servers throughout these topics:</para>
    <itemizedlist>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.CopySitesContentFolderWithVersionHistory">Copy a site's content folder with its version history</link>
            </emphasis>
         </para>
      </listitem>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.CopyNavigationNodesOfSites">Copy navigation nodes of sites</link> </emphasis>
         </para>
      </listitem>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.CopyTemplateOfNodeType">Copy templates of node types templates</link> </emphasis>
         </para>
      </listitem>
      <listitem>
        <para>
        <emphasis role="bold">  <link linkend="DEV.Cookbook.CopyWCMTemplates">Copy the WCM template</link>
            </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.CopyTaxonomyTree">Copy a Taxonomy tree</link>
            </emphasis>
         </para>
      </listitem>
      <listitem>
        <para>
        <emphasis role="bold">  <link linkend="DEV.Cookbook.CopyMetadataTemplates">Copy metadata templates</link>
            </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
        <emphasis role="bold">  <link linkend="DEV.Cookbook.CopyQueries">Copy queries</link>
            </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
        <emphasis role="bold">  <link linkend="DEV.Cookbook.CopyScripts">Copy scripts</link>
            </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.CopyDriveConfigurations">Copy drive configurations</link>
            </emphasis>
         </para>
      </listitem>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.CopyGadgets">Copy gadgets</link> </emphasis>
         </para>
      </listitem>
      <listitem>
        <para>
         <emphasis role="bold"> <link linkend="DEV.Cookbook.RestartServer">Restart the server</link>
            </emphasis>
         </para>
      </listitem>
    </itemizedlist>
</abstract>
    <para>The procedure of each step will be detailed as follows:</para>
    <para xml:id="DEV.Cookbook.CopySitesContentFolderWithVersionHistory">
<citetitle>
 <emphasis role="bold">Step 1. Copy a site's content folder with its version history.</emphasis>
 </citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Sites Management</emphasis> drive.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Open the site node, for example "acme".</para>
    <para>
      <emphasis role="bold">3.</emphasis> Click <emphasis role="bold">Export Node</emphasis> to export the node with its version history as below:</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_site_nodes2.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_site_nodes2.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">4.</emphasis> Select <emphasis role="bold">Export</emphasis> and <emphasis role="bold">Export Version History</emphasis> to perform the exporting.</para>
    <para>
      <emphasis role="bold">5.</emphasis> Navigate to the node where you want to import the file, then click <emphasis role="bold">Import Node</emphasis> to open the <emphasis role="bold">Import Node</emphasis> form.</para>
    <para>
      <emphasis role="bold">6.</emphasis> Select the exported nodes and version history to be imported.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_site_nodes2.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_site_nodes2.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>One pop-up message will appear to inform that you have imported successfully.</para>
    <para xml:id="DEV.Cookbook.CopyNavigationNodesOfSites">
<citetitle>
<emphasis role="bold">Step 2. Copy navigation nodes of sites.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Go to the <emphasis role="bold">Content Administration</emphasis> page and add a new drive to both target and source servers.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/add_portal_system_drive.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/add_portal_system_drive.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">2.</emphasis> Export the navigation node.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_site_navigations.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_site_navigations.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">3.</emphasis> Import the nodes navigation.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_site_navigations.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_site_navigations.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para xml:id="DEV.Cookbook.CopyTemplateOfNodeType">
<citetitle>
<emphasis role="bold">Step 3. Copy templates of node types.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Add the <emphasis role="bold">System</emphasis> drive to both servers.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/add_system_drive.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/add_system_drive.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">2.</emphasis> Open <emphasis role="italic">system:/jcr:system/exo:namespaces/{namespace_name}</emphasis>, and export it.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_namespace.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_namespace.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">3.</emphasis> Open <emphasis role="italic">system:/jcr:system/exo:namespaces</emphasis>/, and import the exported file as described in <link linkend="DEV.Cookbook.CopyNavigationNodesOfSites">
        <emphasis role="bold">Step 2</emphasis>
      </link>.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_namespace.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_namespace.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">4.</emphasis> Open <emphasis role="italic">system:/jcr:system/jcr:nodetypes/{node_type}</emphasis>, and export it.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_node_type.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_node_type.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">5.</emphasis> Open <emphasis role="italic">system:/jcr:system/jcr:nodetypes</emphasis>/, and import the exported file as described in <link linkend="DEV.Cookbook.CopyWCMTemplates">
        <emphasis role="bold">Step 4</emphasis>
      </link>.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_nodetype.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_nodetype.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <note>
      <para>If you have some specific JCR namespaces and node types, you need to import them into the new server.</para>
    </note>
    <para xml:id="DEV.Cookbook.CopyWCMTemplates">
<citetitle>
<emphasis role="bold">Step 4. Copy the WCM template.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the <emphasis role="bold">DMS Administration</emphasis> drive.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Open <emphasis role="italic">dms-system:/exo:ecm/templates/{node_type}</emphasis>, and export it.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_node_type_templates.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/export_node_type_templates.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>
      <emphasis role="bold">3.</emphasis> Open <emphasis role="italic">dms-system:/exo:ecm/templates</emphasis>/, and import the exported file.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_node_type_templates.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/import_node_type_templates.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>Also, for the CLV/PCLV templates, you can find all template views defined in the <emphasis role="italic">dms-system:/exo:ecm/views</emphasis> path with:</para>
    <itemizedlist>
      <listitem>
        <para>userviews: this folder contains views of Sites Explorer with a set of actions.</para>
      </listitem>
      <listitem>
        <para>templates: where you can find all gtmpl templates of:</para>
        <itemizedlist>
          <listitem>
            <para>Category Navigation Portlet templates.</para>
          </listitem>
          <listitem>
            <para>Content List Viewer (CLV) templates and its paginator templates.</para>
          </listitem>
          <listitem>
            <para>content-browser templates (Deprecated Portlet).</para>
          </listitem>
          <listitem>
            <para>ecm-explorer templates define how to display nodes in the Sites Explorer portlet, such as CoverFlow template, IconView template.</para>
          </listitem>
          <listitem>
            <para>Parameterized Content List Viewer (PCLV) templates and its paginator templates.</para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">WCM Advanced Search</emphasis> is used in the <emphasis role="bold">WCM Search</emphasis> portlet to define the form, layout, result and result's paginator.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
    <para>If you want to reuse one of the non-predefined templates above, simply export and import it into the new server at the same place.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/WCM_templates.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/WCM_templates.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <note>
      <para>If you have some specific WCM (CLV/PCLV) views and/or templates of node types, you will need to import them into the new server.</para>
    </note>
    <para xml:id="DEV.Cookbook.CopyTaxonomyTree">
<citetitle>
<emphasis role="bold">Step 5. Copy a Taxonomy tree.</emphasis>
</citetitle>
</para>
    <para>By importing the whole site as described in the <link linkend="DEV.Cookbook.CopySitesContentFolderWithVersionHistory">
        <emphasis role="bold">Copy a site's content folder with its version history</emphasis>
      </link> section, you will also have the Taxonomy tree imported. The default location where the site's Taxonomy is placed in a sub-folder is named <emphasis role="bold">category</emphasis>. So, you do not need to export or import them because this step is automatically done. But the Taxonomy tree definition is still not fully imported in the new server. What you need to do is to add this Taxonomy tree definition by following these steps:</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the <emphasis role="bold">DMS Administration</emphasis> drive in the new server.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Go to <emphasis role="italic">dms-system:/exo:ecm/exo:taxonomyTrees/definition</emphasis>/.</para>
    <para>
      <emphasis role="bold">3.</emphasis> Add a symlink to the <emphasis role="bold">Taxonomy Tree Root Node</emphasis>, for example <emphasis role="italic">collaboration:/sites content/live/acme/categories/acme</emphasis>.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/select_TaxonomyTree_rootNode.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/select_TaxonomyTree_rootNode.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>The name of symlink is displayed as "acme".</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/select_TaxonomyTree_rootNode2.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/select_TaxonomyTree_rootNode2.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>The symlink will be generated as below:</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/select_TaxonomyTree_rootNode3.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/select_TaxonomyTree_rootNode3.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para>In some cases, to see changes, you need to clear the cache by disconnecting or restarting the server.</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/TaxonomyTree_added_successfully.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/TaxonomyTree_added_successfully.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
    <para xml:id="DEV.Cookbook.CopyMetadataTemplates">
<citetitle>
<emphasis role="bold">Step 6. Copy metadata templates.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the <emphasis role="bold">DMS Administration</emphasis> drive in the new server.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Go to <emphasis role="italic">/exo:ecm/metadata/{meta_data_name}</emphasis>.</para>
    <para>
      <emphasis role="bold">3.</emphasis> Export and import it in the same location in the new server again.</para>
    <para xml:id="DEV.Cookbook.CopyQueries">
<citetitle>
<emphasis role="bold">Step 7. Copy queries.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the <emphasis role="bold">DMS Administration</emphasis> drive in the new server.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Go to <emphasis role="italic">/exo:ecm/queries/{query_name}</emphasis>.</para>
    <para>
      <emphasis role="bold">3.</emphasis> Export and import it in the same location in the new server again.</para>
    <para xml:id="DEV.Cookbook.CopyScripts">
<citetitle>
<emphasis role="bold">Step 8. Copy scripts.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the <emphasis role="bold">DMS Administration</emphasis> drive in the new server.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Go to <emphasis role="italic">/exo:ecm/scripts/ecm-explorer</emphasis>.</para>
    <para>You will find three folders referring to the three types of groovy scripts in eXo Platform, including:</para>
    <itemizedlist>
      <listitem>
        <para>action: The action scripts are launched when an ECM action triggers them. For more information, refer to <emphasis role="bold">Actions Concept</emphasis>.</para>
      </listitem>
    </itemizedlist>
    <itemizedlist>
      <listitem>
        <para>interceptor: Interceptor scripts are triggered before and/or after the JCR node is saved, or when a node is created or edited. They are used to either validate the value entered in a form or to manipulate the newly created node, for example, to map the new node with a forum thread or any other type of discussion areas.</para>
      </listitem>
    </itemizedlist>
    <itemizedlist>
      <listitem>
        <para>widget: Widget scripts are used to fill widgets, such as a select box in a dynamic way.</para>
      </listitem>
    </itemizedlist>
    <para>
      <emphasis role="bold">3.</emphasis> Export your customized script in the same location in the new server.</para>
    <para xml:id="DEV.Cookbook.CopyDriveConfigurations">
<citetitle>
<emphasis role="bold">Step 9. Copy drive configurations.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the <emphasis role="bold">DMS Administration</emphasis> drive in the new server.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Go to <emphasis role="italic">/exo:ecm/exo:drives/{drive_name}</emphasis>.</para>
    <para>
      <emphasis role="bold">3.</emphasis> Export and import it in the same location in the new server again.</para>
    <para xml:id="DEV.Cookbook.CopyGadgets">
<citetitle>
<emphasis role="bold">Step 10. Copy gadgets.</emphasis>
</citetitle>
</para>
    <para>
      <emphasis role="bold">1.</emphasis> Open the drive that points into the <emphasis role="bold">Portal-System</emphasis> Workspace.</para>
    <para>
      <emphasis role="bold">2.</emphasis> Go to your gadget by following the <emphasis role="italic">portal-system:/production/app:gadgets/{gadget_name}</emphasis> path.</para>
    <para>
      <emphasis role="bold">3.</emphasis> Export and import it in the same location in the new server again.</para>
    <para xml:id="DEV.Cookbook.RestartServer">
<citetitle>
<emphasis role="bold">Step 11. Restart the server.</emphasis>
</citetitle>
</para>
    <para>After importing the site navigation nodes, the site may look quite broken, so you need to restart the server first. After the server is restarted, the site will look like:</para>
    <para>
      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" fileref="images/how_to_copy_a_site/acme_site_after_import_and_restart.png" format="PNG" scalefit="1" width="150mm"/>
        </imageobject>
        <imageobject role="html">
          <imagedata align="center" fileref="images/how_to_copy_a_site/acme_site_after_import_and_restart.png" format="PNG" scalefit="0" width="150mm"/>
        </imageobject>
      </mediaobject>
    </para>
  </chapter>
  <chapter id="DEV.Upgrade">
    <title>Upgrade eXo Platform </title>
    <abstract>
<para>Upgrading eXo Platform from 3.0 to 3.5 is generally a procedure which includes 2 steps:</para>
<para xml:id="Step1_UpgradeProjectExtensions">
        <emphasis role="bold">Step 1.</emphasis> Upgrade the project extensions.</para>
<para xml:id="Step2_UpgradeProject_ProductData">
        <emphasis role="bold">Step 2.</emphasis> Upgrade the project and the product data.</para>
<para>This chapter aims at instructing you how to archive <link linkend="Step1_UpgradeProjectExtensions">Step 1</link> via the following topics:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.Upgrade.Prerequisites">Prerequisites</link>  </emphasis>
	</para>
	<para>
	Questions that help developers to gather all requirements for their upgraded project, required preparations of an extension project, and steps which need to be adpated in eXo Platform.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.Upgrade.Update_MavenDependenciesConfigurationsComponents">Update Maven dependencies, configurations and components</link>
            </emphasis>
	</para>
	<para>
	How to update Maven dependencies, configurations and components.
	</para>
  </listitem>
  <listitem>
	<para>
	  <emphasis role="bold">
              <link linkend="DEV.Upgrade.Update_extension">Update extensions</link>
            </emphasis>
	</para>
	<para>
	How to update your custom eXo Platform extensions, including updating Kernel XML Schema, portal and APIs.
	</para>
  </listitem>
</itemizedlist>
</abstract>
    <note>
      <para>Upgrading data can be strongly dependent on both your deployments and environments, so it is recommended that you contact <ulink url="eXo Support">http://support.exoplatform.com</ulink> to bootstrap the <link linkend="Step2_UpgradeProject_ProductData">Step 2</link>.</para>
    </note>
    <section id="DEV.Upgrade.Prerequisites">
      <title>Prerequisites </title>
      <para>Before upgrading, you first need to understand how to create a project which is based on eXo Platform 3.5. For more details, refer to <link linkend="DEV.CreatingYourOwnPortal">Create Your Own Portal</link>.</para>
      <para>And now, you need to gather all requirements for your upgraded project by clarifying the following questions:</para>
      <itemizedlist>
        <listitem>
          <para>Do you actually need to migrate your project sources?</para>
        </listitem>
        <listitem>
          <para>Have you created any new portal containers in your system?</para>
        </listitem>
        <listitem>
          <para>Have you made any lifetime-related changes on eXo Platform? Would you like to keep these changes?</para>
        </listitem>
        <listitem>
          <para>Have you developed a custom application? Where have you stored your application data?</para>
        </listitem>
        <listitem>
          <para>Have you configured a dedicated JCR workspace?</para>
        </listitem>
        <listitem>
          <para>Which eXo APIs are you using in your code?</para>
        </listitem>
        <listitem>
          <para>Have you overridden any files of eXo Platform?</para>
        </listitem>
        <listitem>
          <para>Have you disabled any services of eXo Platform?</para>
        </listitem>
        <listitem>
          <para>Which Kernel configurations have you customized?</para>
        </listitem>
      </itemizedlist>
      <para xml:id="DEV.Upgrade.Prepare_extension_project">
<citetitle>
<emphasis role="bold">
Prepare for your extension project
</emphasis>
</citetitle>
</para>
      <para>You need to create a new branch for eXo Platform 3.5 extension project, then clone your source code of eXo Platform 3.0 with that of eXo Platform 3.5.</para>
      <para>The way to package your project customization called extensions has been introduced in eXo Platform 3.0. Therefore, by using the WAR extension configuration approach, you can overload eXo Platform's default files defined in WARs, such as <emphasis role="italic">gtmpl, favicon, xml, jsp</emphasis>.  For more details on how to create your extension project, refer to the <link linkend="DEV.CreatingYourOwnPortal">Create Your Own Portal</link> section.</para>
      <para>Because there are not any changes on the eXo Platform 3.5 extension mechanism, your extensions should be mostly compatible. However, if your extension was overriding either of the eXo Platform 3.0 built-in files, you should check that the file has not been changed in eXo Platform 3.5 and update it if any.</para>
      <para xml:id="DEV.Upgrade.What_need_to_be_adapted">
<citetitle>
<emphasis role="bold">
What needs to be adapted in eXo Platform extension
</emphasis>
</citetitle>
</para>
      <para>There are 4 main steps which need to be defined for updating eXo Platform extension from 3.0 to 3.5:</para>
      <itemizedlist>
        <listitem>
          <para>Update your project Maven dependencies in the <emphasis role="italic">POM</emphasis> files.</para>
        </listitem>
        <listitem>
          <para>Update your eXo Platform 3.5 configurations.</para>
        </listitem>
        <listitem>
          <para>Update components in your eXo Platform extension to use components of Platform 3.5</para>
        </listitem>
        <listitem>
          <para>Update your eXo Platform extension which are customised features/components (were added new/ modified/ delete in eXo Platform 3.0 extension), and make sure they can work well in eXo Platform 3.5 environment.</para>
        </listitem>
      </itemizedlist>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.Upgrade.Update_MavenDependenciesConfigurationsComponents">Update Maven dependencies, configurations and components</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.Upgrade.Update_extension">Update extensions</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.Upgrade.Update_MavenDependenciesConfigurationsComponents">
      <title>Update Maven dependencies, configurations and components </title>
      <highlights>
<para>After gathering all requirements, and preparing for your extension project and adaptions in eXo Platform extension, you then need to update:</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.Upgrade.Update_project_Maven_dependencies">Maven dependencies</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.Upgrade.Update_configuration">Configurations</link>
            </para>
          </listitem>
		  <listitem>
            <para>
              <link linkend="DEV.Upgrade.Update_components">Components</link>
            </para>
          </listitem>
        </itemizedlist>
</highlights>
      <para xml:id="DEV.Upgrade.Update_project_Maven_dependencies">
<citetitle>
<emphasis role="bold">
Maven dependencies
</emphasis>
</citetitle>
</para>
      <para>eXo Platform includes many components, so if you want to update your eXo Platform extension to use eXo Platform 3.5, you need to update the version of all dependencies in the <emphasis role="italic">POM</emphasis> files, and select the version of dependencies which are compatible with eXo Platform 3.5. For example, eXo Platform 3.5.1 needs to have the following main dependencies:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<!-- kernel -->
<dependency>
	<groupId>org.exoplatform.kernel</groupId>
	<artifactId>kernel-parent</artifactId>
	<version>2.3.5-GA</version>
</dependency>
<!-- core -->
<dependency>
   <groupId>org.exoplatform.core</groupId>
   <artifactId>core-parent</artifactId>
   <version>2.4.5-GA</version>
</dependency>
<!-- ws -->
<dependency>
   <groupId>org.exoplatform.ws</groupId>
   <artifactId>ws-parent</artifactId>
   <version>2.2.5-GA</version>
</dependency>

<!-- jcr -->
<dependency>
  <groupId>org.exoplatform.jcr</groupId>
  <artifactId>jcr-parent</artifactId>
  <version>1.14.5-GA</version>
</dependency>

<!-- jcr service -->
<dependency>
  <groupId>org.exoplatform</groupId>
  <artifactId>exo-jcr-services</artifactId>
  <version>1.14.5-GA</version>
</dependency>

<!-- commons -->
<dependency>
  <groupId>org.exoplatform.commons</groupId>
  <artifactId>exo.platform.commons</artifactId>
  <version>1.1.5</version>
</dependency>

<!-- exogtn -->
<dependency>
   <groupId>org.exoplatform.portal</groupId>
   <artifactId>exo.portal.parent</artifactId>
   <version>3.2.2-PLF</version>
</dependency>

<!-- webos -->
<dependency>
  <groupId>org.exoplatform.webos</groupId>
  <artifactId>webos-parent</artifactId>
  <version>2.0.2</version>
</dependency>

<!-- ecms -->
<dependency>
  <groupId>org.exoplatform.ecms</groupId>
  <artifactId>exo-ecms</artifactId>
  <version>2.3.5</version>
</dependency>

<!-- ide -->
<dependency>
   <groupId>org.exoplatform.ide</groupId>
   <artifactId>exo-ide-parent</artifactId>
   <version>1.1.4</version>
</dependency>

<!-- cs -->
<dependency>
  <groupId>org.exoplatform.cs</groupId>
  <artifactId>cs</artifactId>
  <version>2.2.7</version>
</dependency>

<!-- ks -->
<dependency>
  <groupId>org.exoplatform.ks</groupId>
  <artifactId>ks</artifactId>
  <version>2.2.7</version>
</dependency>

<!-- social -->
<dependency>
  <groupId>org.exoplatform.social</groupId>
  <artifactId>social-project</artifactId>
  <version>1.2.7</version>
</dependency>

<!-- integration -->
<dependency>
  <groupId>org.exoplatform.integration</groupId>
  <artifactId>integ</artifactId>
  <version>1.0.5</version>
</dependency>]]></programlisting>
      </programlistingco>
      <para xml:id="DEV.Upgrade.Update_configuration">
<citetitle>
<emphasis role="bold">
Configurations
</emphasis>
</citetitle>
</para>
      <para>After updating Maven dependencies, you need to update configurations via answering 2 questions:</para>
      <itemizedlist>
        <listitem>
          <para>In your eXo Platform extension, did you override anything in <emphasis role="italic">$PLATFORM_TOMCAT_HOME/gatein/conf</emphasis>?</para>
          <itemizedlist>
            <listitem>
              <para>If NO, you can skip this step, and simply keep all configurations in <emphasis role="italic">$PLATFORM_TOMCAT_HOME/gatein/conf</emphasis>.</para>
            </listitem>
            <listitem>
              <para>If YES, you first need to keep all configurations of eXo Platform 3.5, then define which configurations you want to add/remove/update. After that, you can put them into <emphasis role="italic">$PLATFORM_TOMCAT_HOME/gatein/conf</emphasis>.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
      <note>
        <para>There are some new configurations in <emphasis role="italic">$PLATFORM_TOMCAT_HOME/gatein/conf/</emphasis> which are related to <ulink url="../../../admin-guide/html/ADM.Clustering.html">how to deploy the eXo Platform clustering</ulink>, and <ulink url="../../../reference/html/JCR.JBossCacheConfigurationTemplates.html">JBoss Cache configuration.</ulink>
        </para>
      </note>
      <itemizedlist>
        <listitem>
          <para>In your eXo Platform extension, did you override anything in <emphasis role="italic">$PLATFORM_TOMCAT_HOME/bin</emphasis>?</para>
          <itemizedlist>
            <listitem>
              <para>If NO, you can skip this step, and simply keep all configurations in <emphasis role="italic">$PLATFORM_TOMCAT_HOME/bin</emphasis>.</para>
            </listitem>
            <listitem>
              <para>If YES, you first need to keep all eXo Platform 3.5's origin configurations, then add/remove/update your extension configuration into it.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
      <note>
        <para>
          <emphasis role="italic">$PLATFORM-TOMCAT-HOME/bin/gatein.sh</emphasis> and <emphasis role="italic">$PLATFORM_TOMCAT_HOME/bin/gatein.bat</emphasis> are no longer used. Therefore, you should add your customized configurations in a more official way to set environment variables via <emphasis role="italic">setenv.sh</emphasis> or <emphasis role="italic">setenv.bat</emphasis>.</para>
      </note>
      <para xml:id="DEV.Upgrade.Update_components">
<citetitle>
<emphasis role="bold">
Components
</emphasis>
</citetitle>
</para>
      <para>There are many components in eXo Platform, so if you update your eXo Platform extension to eXo Platform 3.5, you need to update the version of all eXo Platform 3.5's components.  To do so, simply configure the Maven POM file that allows you to use the artifacts (eXo Platform 3.5 and its components). For more details, see the <link linkend="DEV.Upgrade.Update_project_Maven_dependencies">Update project Maven dependencies</link> section. All eXo Platform 3.5's components will be automatically included in your eXo Platform extension.</para>
      <para>There are some new components in eXo Platform 3.5 that have not been existing in eXo Platform 3.0, including Webos, Wiki, and Gadget-pack. To use these components, simply activate their profiles. For more details, see the <ulink url="../../../admin-guide/html/ADM.Installation.eXo_profiles.html">Profiles of eXo Platform</ulink> section.</para>
      <para>In eXo Platform 3.5, the "intranet" portal is defined in the <emphasis role="italic">acme-intranet.war</emphasis> file (not in the <emphasis role="italic">office-portal.war</emphasis> file of eXo Platform 3.0). So if you have overridden anything in the "intranet" portal, you need to synchronize your extension with the <emphasis role="italic">acme-intranet.war</emphasis> file of eXo Platform-3.5.</para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.Upgrade.Prerequisites">Prerequisites</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.Upgrade.Update_extension">Update extensions</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
    <section id="DEV.Upgrade.Update_extension">
      <title>Update extensions </title>
      <highlights>
 <para>The next procedure of upgrading eXo Platform is to update your custom eXo Platform extensions, including:</para>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.Upgrade.Update_extension.Update_Kernel_XML_Schema">Kernel XML Schema</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.Upgrade.Update_extension.Update_portal">Portal</link>
            </para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.Upgrade.Update_extension.Update_APIs">APIs</link>
            </para>
          </listitem>
        </itemizedlist>
</highlights>
      <para xml:id="DEV.Upgrade.Update_extension.Update_Kernel_XML_Schema">
<citetitle>
<emphasis role="bold">
Kernel XML Schema
</emphasis>
</citetitle>
</para>
      <itemizedlist>
        <listitem>
          <para>Simply upgrade the version from <emphasis role="italic">kernel_1_0.xsd</emphasis> to <emphasis role="italic">kernel_1_2.xsd</emphasis> in all <emphasis role="italic">.xml</emphasis> configurations files.</para>
        </listitem>
      </itemizedlist>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<configuration xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">
	.....
</configuration>]]></programlisting>
      </programlistingco>
      <para xml:id="DEV.Upgrade.Update_extension.Update_portal">
<citetitle>
<emphasis role="bold">
Portal
</emphasis>
</citetitle>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">Portal data import</emphasis> <anchor id="DEV.Upgrade.Update_extension.Update_portal.Portal_data_import"/>
          </para>
        </listitem>
      </itemizedlist>
      <note>
        <para>It is recommended you have the knowledge of the import mechanism by referring to the <ulink url="../../../reference/html/sect-Reference_Guide-Import_Strategy.html">Data Import Strategy</ulink> section.</para>
      </note>
      <para>Processing the portal data import includes the following tasks:</para>
      <itemizedlist>
        <listitem>
          <para>Improve the current data import strategy so that it becomes more flexible in various scenarios.</para>
        </listitem>
        <listitem>
          <para>Deploy an extension after you have initialized the portal that allows the extension to contribute its entities to an existing site.</para>
        </listitem>
        <listitem>
          <para>Reimport data by overwriting an existing entire configuration at each startup.</para>
        </listitem>
      </itemizedlist>
      <para>
        <emphasis role="bold">
          <emphasis role="italic">What's new?</emphasis>
        </emphasis>
      </para>
      <informaltable>
<tgroup cols="2">
  <thead>
	<row>
	  <entry>Previous behavior</entry>
	  <entry>New behavior</entry>
	</row>
  </thead>
  <tbody>
	<row>
	  <entry>
		<para>The previous mode for navigations is defined using the overridden configuration. </para>
		<itemizedlist>
		  <listitem>
			<para>
                      <emphasis role="bold">Merge</emphasis>: Merge data from the XML descriptor to the existing data.</para>
		  </listitem>
		  <listitem>
		<para>
                      <emphasis role="bold">Override</emphasis>: Destroy any existing data, and create new ones.</para>
		  </listitem>
		</itemizedlist>
		<para>The previous mode has two main issues:</para>
		<itemizedlist>
		  <listitem>
			<para>The behavior for instance disables the "always merge data" usecase. It means that it is always impossible to merge new navigations nodes from XML to MOP.</para>
          </listitem>
          <listitem>
		    <para>The behavior is configured by the overridden parameter.</para>
		  </listitem>
		</itemizedlist>
	  </entry>
	  <entry>
	  <para>The new behavior which is configured at the import level with a field parameter would have the following values:</para>
      <itemizedlist>
		<listitem>
		  <para>
                      <emphasis role="bold">conserve</emphasis>: Import data. However, if the navigation has been existing, it will be kept.</para>
        </listitem>
        <listitem>
		  <para>
                      <emphasis role="bold">insert</emphasis>: Insert the missing descriptor data by adding new nodes without any modifications on the existing nodes.</para>
		</listitem>
		<listitem>
		   <para>
                      <emphasis role="bold">merge</emphasis>: Merge the descriptor data, add missing nodes and update the nodes of the same name.</para>
		</listitem>
		<listitem>
		  <para>
                      <emphasis role="bold">overwrite</emphasis>: Always destroy the previous data and create new ones.</para>
		</listitem>
	   </itemizedlist>
	 </entry>
	</row>
  </tbody>
</tgroup>
</informaltable>
      <para>For example, if you want to merge the new portal navigation from the configuration file and the existing portal navigation into the current eXo Platform, you can configure as below:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting language="xml"><![CDATA[<object-param>
  <name>portal.configuration</name>
  <object type="org.exoplatform.portal.config.NewPortalConfig">
    <field name="predefinedOwner">
     <collection type="java.util.HashSet">
       <value><string>classic</string></value>
     </collection>
    </field>
    <field name="ownerType">
      <string>portal</string>
    </field>
    <field name="templateLocation">
      <string>war:/conf/portal</string>
    </field>
    <field name="importMode">
      <string>merge</string>
    </field>
  </object>
</object-param>]]></programlisting>
      </programlistingco>
      <note>
        <para>When a mode is not specified, the default mode will be <emphasis role="bold">conserve</emphasis>.</para>
      </note>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">Authentication</emphasis>: eXo Platform 3.5 uses a new authentication mechanism so-called the WCI authentication mechanism. This change from GateIn into the WCI module is because: <anchor id="DEV.Upgrade.Update_extension.Update_portal.Authentication"/>
          </para>
          <itemizedlist>
            <listitem>
              <para>Authentication is commonly part of Java EE and happens at the Servlet Container layer, while WCI is the layer of integration between our stack and the Servlet Container. </para>
            </listitem>
            <listitem>
              <para>WCI provides an easier integration of SSO providers that allows the SSO module to depend on the WCI module instead of integrating directly with the GateIn module. Its main benefit is to improve the quality of SSO and to decouple SSO from GateIn.</para>
            </listitem>
            <listitem>
              <para>The GateIn stack wants to support and leverage specifications of both Servlet 3.0 and Servlet 2.5 that are not supported by the GateIn module. Meanwhile, WCI can serve both.</para>
            </listitem>
            <listitem>
              <para>The Servlet 3.0 provides a programmatic login feature which can be used to implement WCI.</para>
            </listitem>
            <listitem>
              <para>WCI provides the stronger guaranty of the authentication quality, meanwhile the authentication of GateIn was not unit tested. By moving the GateIn to WCI module, the test can be made against several implementations.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
      <para>If there are other new portal containers in your eXo Platform extension, you need to update the authentication mechanism in the <emphasis role="italic">$PLATFORM-TOMCAT-HOME/conf/jaas.conf</emphasis> file.  For example, in case you have added a new portal container named "company" to eXo Platform, you need to configure the new authentication module for the new portal container as follows:</para>
      <programlistingco>
        <areaspec units="linecolumn"/>
        <programlisting><![CDATA[<!--this configuration for defaul portal container with name "portal"-->
gatein-domain {
  org.gatein.wci.security.WCILoginModule optional;
  org.exoplatform.services.security.jaas.SharedStateLoginModule required;
  org.exoplatform.services.security.j2ee.TomcatLoginModule required;
};

<!--this configuration for new portal container with name "company"-->
gatein-domain-company {
  org.gatein.wci.security.WCILoginModule optional
    portalContainerName="company"
  	realmName="gatein-domain-company";
  org.exoplatform.services.security.jaas.SharedStateLoginModule required
    portalContainerName="company"
  	realmName="gatein-domain-company";
  org.exoplatform.services.security.j2ee.TomcatLoginModule required
    portalContainerName="company"
  	realmName="gatein-domain-company";
};]]></programlisting>
      </programlistingco>
      <para>For more details, see the <ulink url="../../../admin-guide/html/ADM.Security.Change_JAAS_real.html">Change the JAAS realm</ulink> section.</para>
      <para xml:id="DEV.Upgrade.Update_extension.Update_APIs">
<citetitle>
<emphasis role="bold">
APIs
</emphasis>
</citetitle>
</para>
      <para>eXo Platform 3.5 has many changes on the data model and APIs. Therefore, if there are any new customized components in your eXo Platform extension that use eXo Platform 3.0 APIs, you need to check if they can work well in eXo Platform 3.5 or not. For more details, see the <link linkend="DEV.eXoPlatformAPIs">eXo Platform 3.5 APIs</link> section. </para>
      <para>Finally, you need to update your customized components if needed. </para>
      <para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="DEV.Upgrade.Prerequisites">Prerequisites</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="DEV.Upgrade.Update_MavenDependenciesConfigurationsComponents">Update Maven dependencies, configurations and components</link>
          </para>
        </listitem>
      </itemizedlist>
    </section>
  </chapter>
</book>
