h2. Goal {anchor:id=DEV.CreateYourOwnPortal.Goal}
This tutorial will help you to create a new layout and skin, and give some best practices you should know and respect when creating a new layout and skin for your portal and page.

h2. Assumptions {anchor:id=DEV.CreateYourOwnPortal.Assumptions}
- You have an extension named "MyPortal", and you need to create a site called "MySite" inside this portal.
- The _{{{<myportal_path>}}}_ below is replaced by the based path of your "MyPortal" extension.
- If you see any folder/file which does not exist, you should create a new one.

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

{note}
This section is related to the configuration. You can see a sample [here|http://svn.exoplatform.org:3840/projects/ecms/tags/2.1.0-GA/packaging/ecmdemo/webapp/src/main/webapp/WEB-INF/conf/sample-portal/portal/portal/acme/portal.xml]. You can leave all the portlet's preferences as blank, that means the default value will be taken and you do not need to care about it at this time.
{note}

* For example, you will have a layout like this:

!images/samplelayout.jpg|align="center"!

In which:

* Branding: A branding application
* Top navigation: A top navigation application

A table column container with three nested containers:

* Left Column and Right Column: contain one application for each.
* Main content: contains the page body.

And here is the "short version" of _portal.xml_.

* _{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/portal/portal/mysite/portal.xml{noformat}_

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

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

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

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

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

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

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

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

As you see in the *portal.xml* file above, every *container* tag has an *id* attribute, for example "<container id = '*RightColumn*'>". When you create a CSS file, the property applied for this container should have the following name manner:

{code}
${container_id}TDContainer
{code}

and the details of this container: 

{code}
RightColumnTDContainer
{code}

The reason is, when you have a look in the file system: _{noformat}/groovy/portal/webui/container/UITableColumnContainer.gtmpl{noformat}_ shown above, you will see this code fragment:

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

So, in the *table* element (which represents the outer container), there are many *td* elements, each of which has the *class* attribute that equals to the *id* of the corresponding child component plus the "TDContainer" string literal.

To learn more, see [Customize portal and page's style|#customize-portal-and-page-style].

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

{note}
This section is related to the configuration. You can see a sample [here|http://svn.exoplatform.org:3840/projects/ecms/tags/2.1.0-GA/packaging/ecmdemo/webapp/src/main/webapp/WEB-INF/conf/sample-portal/portal/portal/acme/pages.xml]. You can leave all the portlet's preferences as blank, that means the default value will be taken and you do not need to care about it at this time.
{note}

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

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

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

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

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

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

h2. Customize portal and page's style {anchor:id=customize-portal-and-page-style}
If you want your skin to be applied for every page, do as follows:

*1.* Go to *Sites Explorer >* *Shared* drive *> CSS* folder.

*2.* Create a new CSS document which contains your stylesheet. You can use any name for this document and put a priority number.

If you want your skin to be applied for your *MySite* page only, do as follows:

*1.* Open the browser *> Sites Explorer* portlet *> Sites management* drive *> MySite/css* folder.

*2.* Create a new CSS document which contains your stylesheet for the portal and the page layout. You can use any name for this document and put a priority number.

{warning}
This document should contain *ONLY* one stylesheet for the page and portal level.
{warning}

The following is one sample stylesheet:

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

.RightColumnTDContainer { 
/* ... */
  
}

/* ... */
{code}

{note}
The order of applying CSS files (of site and web content) depends on their own *priority* property value. It means that we can apply the site CSS first and then web content CSS, or vice versa.
{note}

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

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

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

For example: _{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/template/list/ACustomizedCLVTemplate.gtmpl{noformat}_

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

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

_{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/template/configuration.xml{noformat}_

{code:xml}
<external-component-plugins>
  <target-component>org.exoplatform.services.cms.views.ApplicationTemplateManagerService</target-component>
  <component-plugin>
    <name>ACustomizedCLVTemplate</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.cms.views.PortletTemplatePlugin</type>
    <description>This is a sample customized CLV template</description>
    <init-params>
      <value-param>
        <name>portletName</name>
        <value>Content List Viewer</value>
      </value-param>
      <value-param>
        <name>portlet.template.path</name>
        <value>war:/conf/myportal/customized/template</value>
      </value-param>
      <object-param>
        <name>default.folder.list.viewer</name>
        <description>Default folder list viewer groovy template</description>
        <object type="org.exoplatform.services.cms.views.PortletTemplatePlugin$PortletTemplateConfig">
          <field name="templateName">
            <string>ACustomizedCLVTemplate.gtmpl</string>
          </field>
          <field name="category">
            <string>list</string>
          </field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
</external-component-plugins>
{code}

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

To customize the CLV template's style, do as follows:

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

*2.* Create a new CSS document which contains your stylesheet for the portal and the page layout. You can use any name for this document and put a priority number.

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

* The following is one sample stylesheet:

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

.ListContents { 
/* ... */
  
}

/* ... */
{code}

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

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

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

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

First, you need to create a new document definition.

* _{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/ACustomizedDocument.xml{noformat}_
	
{code}
	node type name :exo:customizedDocument
	properties: exo:name(type : String), exo:title(type : String), exo:content(type : String)
{code}

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

* _{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/definition-configuration.xml{noformat}_

{code:xml} 
<external-component-plugins>
  <target-component>org.exoplatform.services.jcr.RepositoryService</target-component>
  <component-plugin>
    <name>ACustomizedDocument</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.jcr.impl.AddNodeTypePlugin</type>
    <priority>200</priority>
    <init-params>
      <values-param>
        <name>autoCreatedInNewRepository</name>
        <description>ACustomizedDocument document definition</description>
        <value>war:/conf/myportal/customized/document/ACustomizedDocument.xml</value>
      </values-param>
    </init-params>
  </component-plugin>
</external-component-plugins>
{code}

Next, create the templates for this document, including:

* Dialog: see the sample [here|http://svn.exoplatform.org:3840/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]

_{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/dialog.gtmpl{noformat}_

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

* View: see the sample [here|http://svn.exoplatform.org:3840/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]

_{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/view.gtmpl{noformat}_

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

* Stylesheet: see the sample [here|http://svn.exoplatform.org:3840/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]

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

_{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/stylesheet.css{noformat}_


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

.ACustomizedDocument {
  /* ... */
}

/* ... */
{code}

* You also need to import them to database.

_{noformat}<myportal_path>/src/main/webapp/WEB-INF/conf/myportal/customized/document/template-configuration.xml{noformat}_

{code:xml}
<external-component-plugins>
  <target-component>org.exoplatform.services.cms.templates.TemplateService</target-component>
  <component-plugin>
    <name>addTemplates</name>
    <set-method>addTemplates</set-method>
    <type>org.exoplatform.services.cms.templates.impl.TemplatePlugin</type>
    <init-params>
      <value-param>
        <name>autoCreateInNewRepository</name>
        <value>true</value>
      </value-param>
      <value-param>
        <name>storedLocation</name>
        <value>war:/conf/myportal/customized/document</value>
      </value-param>
      <value-param>
        <name>repository</name>
        <value>repository</value>
      </value-param>
      <object-param>
        <name>template.configuration</name>
        <description>configuration for the localtion of nodetypes templates to inject in jcr</description>
        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig">
          <field name="nodeTypes">
            <collection type="java.util.ArrayList">
              <value>
                <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$NodeType">
                  <field name="nodetypeName">
                    <string>exo:customizedDocument</string>
                  </field>
                  <field name="documentTemplate">
                    <boolean>true</boolean>
                  </field>
                  <field name="label">
                    <string>Customized Document</string>
                  </field>
                  <field name="referencedView">
                    <collection type="java.util.ArrayList">
                      <value>
                        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                          <field name="templateFile">
                            <string>view.gtmpl</string>
                          </field>
                          <field name="roles">
                            <string>*</string>
                          </field>
                        </object>
                      </value>
                    </collection>
                  </field>
                  <field name="referencedDialog">
                    <collection type="java.util.ArrayList">
                      <value>
                        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                          <field name="templateFile">
                            <string>dialog.gtmpl</string>
                          </field>
                          <field name="roles">
                            <string>webdesigner:/platform/web-contributors</string>
                          </field>
                        </object>
                      </value>
                    </collection>
                  </field>
                  <field name="referencedSkin">
                    <collection type="java.util.ArrayList">
                      <value>
                        <object type="org.exoplatform.services.cms.templates.impl.TemplateConfig$Template">
                          <field name="templateFile">
                            <string>stylesheet.css</string>
                          </field>
                          <field name="roles">
                            <string>*</string>
                          </field>
                        </object>
                      </value>
                    </collection>
                  </field>
                </object>
              </value>
            </collection>
          </field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
</external-component-plugins>
{code}

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

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

{code:xml}
<external-component-plugins>
  <target-component>org.exoplatform.services.wcm.deployment.WCMContentInitializerService</target-component>
  <component-plugin>
    <name>Content Initializer Service</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.wcm.deployment.plugins.XMLDeploymentPlugin</type>
    <description>XML Deployment Plugin</description>
    <init-params>
      <object-param>
        <name>ACME Logo data</name>
        <description>Deployment Descriptor</description>
        <object type="org.exoplatform.services.deployment.DeploymentDescriptor">
          <field name="target">
            <object type="org.exoplatform.services.deployment.DeploymentDescriptor$Target">
              <field name="repository">
                <string>repository</string>
              </field>
              <field name="workspace">
                <string>collaboration</string>
              </field>
              <field name="nodePath">
                <string>/sites content/live/acme/web contents/site artifacts</string>
              </field>
            </object>
          </field>
          <field name="sourcePath">
            <string>war:/conf/wcm/artifacts/site-resources/acme/Logo.xml</string>
          </field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
</external-component-plugins>
{code}
