Purpose
This How-To explains step-by-step the integration of a graphical layout by creating of an Ametys v3 skin. This documentation covers only the very first steps, please read the rest of the documentation to go deeper in the development.
The reader must have a minimum of knowledge on these fields: HTML, CSS, XML, XSL, I18N
Definitions
What is a graphical layout?
A graphical layout is a set of items which will make up the graphical identity of our website. A layout has mainly two parts: the graphical elements and the page templates.
- The graphical elements are statics files like the images, the styles (css files) and eventually the javascripts files.
- The page templates are like the power point slide templates, meaning the different pages structures or content arrangement you want to use on your website.
In our example, we have 2 templates, one called 'index', another called 'page'. The 'index' template will be used for the website homepage, the 'page' one for the other pages of the site.
The graphical layout used in this how-to has been downloaded for the website http://www.freecsstemplates.org/ : thegreenhouse
The downloaded zip file contains some images and a default.css files (the graphicals elements) and an index.html we will use to define the page templates.
We have changed a little bit this layout by adding a new page 'about.html' (with a different template as the index) and by extending the css file (for example addition of style for table). You can download our version of the template here: thegreenhouse.zip
This graphical layout will be integrated into the CMS Ametys as a skin.
What is an Ametys skin?
A skin in Ametys is a container for a graphical layout. It's the graphical layout itself and its configuration. The configuration part will define how to use the skin in the backoffice of the CMS. You can find more information about the skins here.
In Ametys, the skins are stored in the directory: Ametys\webapp\cms\skins
The sub-directory containing all the skin's files gives to the skin its name. The application comes with a demo skin called 'demo'.
In this How-To, our skin is called 'thegreenhouse'.
So, in order to integrate our graphical layout in Ametys, you have to create a new skin.
We will then now describe step by step how to create a skin.
Step 0: Installation of Ametys v3
Install the latest demo version of the WebCMS Ametys v3.0. See installation documentation.
Step 1: Give your skin a name
Create in the directory "Ametys\webapp\cms\skins" a sub-directory. This sub-directory is then called the skin directory.
Example: "Ametys\webapp\cms\skins\thegreenhouse"
Step 2: Copy the graphical elements in your skin
Create in the skin directory the path "resources\img" and copy inside the images of your layout. Of course, it's possible to create some sub-directories to organize deeper the images.
Create in the skin directory the path "resources\css" and copy inside the css files of your layout. Of course, it's possible to create some sub-directories to organize deeper the css.
Warning: change in the css files the path to the images
Example: path for body background = ../img/img01.gif
Step 3: The templates
The templates are the definition of the website page structures. It's a set of xsl files which will be then later used to generate the html pages.
The templates are stored in the skin directory under "templates", so create a sub-directory "templates".
More information about the templates here.
In your example (like in the demo skin), we have two templates:
- the index template (screenshot)
- with the menu on the top,
- a banner below,
- a center part with a left area and a right area
- a footer.
- the page template (screenshot)
- with the menu on the top,
- a banner below,
- a center part
- a footer.
Each template has it own sub-directory, so create in the "templates" directory 2 sub-directories "index" and "page" (like in the demo skin).
Definition of the template's zones
The template sub-directories contain a file "template.xml" which describes the template and its zones.
Details:
Root node: <template>, contains all the following child nodes.
Node: <label>, contains the label (or the name) of the template.
Important: Please note that you can put here directly the text of the label in the value of the node.
Example: <label>Name of the template</label>
But you can use i18n keys, like:
<label i18n="true">SKIN_BO_ZONING_PAGE_LABEL</label>
The value of the node is then the name of the i18n key, the attribute 'i18n' is set to true to inform the application that the node value is an i18n key.
The corresponding i18n dictionaries (one per language) are stored in the skin directory under the sub-directory 'i18n'. So create in the skin dir, a sub-dir 'i18n' and put inside the i18n files message.xml, message_fr.xml (one par language) ...
In the rest of this HowTo, we will use i18n keys instead of setting directly the text.
So, for our 2 templates, the labels are:
for the 'index' template
<label i18n="true">SKIN_BO_ZONING_INDEX_LABEL</label>
and for the 'page' template
<label i18n="true">SKIN_BO_ZONING_PAGE_LABEL</label>
Node: <description>, contains a short description of the template.
Node: <thumbnail>, contains the filename of the thumbnail used in the cms to illustrate the template in the different menus.
This node has 3 children: <small> with the 16px icon, <medium> with the 32px icon and <large> with the 48px icon.
In your example, only the medium is used:
<thumbnail>
<medium>thumbnail_32.png</medium>
</thumbnail>
The images are then stored in the template directory under 'resources' (ex: Ametys\webapp\cms\skins\thegreenhouse\templates\page\resources\thumbnail_32.png)
Node: <zones>, contains the description of each zone of the template. A zone is a area in the page where dynamical contents can be displayed.
In our example, the template 'index' has 2 zones in the center part: zone on the left and a zone on the right. The template 'page' has only one zone in the center.
Node: <zone>
Attibute 'id': Unique id of the zone, we recommend to have at least a zone called 'default'
Node <label>: Label of the zone
Node <description>: Description of the zone
The template's stylesheets
The stylesheets (or XSL files) are used to generate from the contents and other dynamical data the html pages of website.
The stylesheet files of a template are stored in the directory 'stylesheets'. Ex: Ametys\webapp\cms\skins\thegreenhouse\templates\page\stylesheets
As you can notice, the both templates in our example have a common structure, same menu on the top, same banner, same footer. The html code will then be very similar.
For this common part, we will use common stylesheet files stored in the skin directory under 'stylesheets' (Ametys\webapp\cms\skins\thegreenhouse\stylesheets).
The common stylesheets
The stylesheet 'commons.xsl' includes all xsl templates common to all layout. In our example, the headers are almost common, the menu, the banner and the footer are common.
<xsl:template name="template">
<html>
<head>
<xsl:call-template name="meta" />
<title>
<xsl:if test="/cms/page" ><xsl:value-of select="/cms/page/@title" /> - </xsl:if><i18n:text i18n:key="SKIN_HOMEPAGE_TITLE" i18n:catalogue="skin.{$skin}"/>
</title>
<xsl:call-template name="common-css" />
<xsl:call-template name="additionnal-css" />
</head>
<body>
<xsl:call-template name="main-navigation"/>
<xsl:call-template name="banner"/>
<div id="wrapper">
<div id="content">
<xsl:call-template name="content-template"/>
</div>
</div>
<xsl:call-template name="footer"/>
</body>
</html>
</xsl:template>
As you can, we are also using i18n keys define in the same message.xml file.
The xsl:template 'meta' generates the metadata of the html pages.
The xsl:template 'common-css' generates all the common css link.
The xsl:template 'additionnal-css' is redefined in each page template to include the specific css of the page.
The xsl:template 'main-navigation' generates the menu.
The xsl:template 'banner' generates the banner.
The xsl:template 'content-template' generates the content part, it's different for each page template.
The xsl:template 'footer' generates the footer.
stylesheet of each template
Each template requires a xsl:template file, called 'template.xsl' and stored in the template directory under 'stylesheets'.
In our example, the both tempales 'index' and 'page' are very similars.
No additional css are required, that why the template 'additionnal-css' is defined as empty (doesn't insert anything).
The template 'content-template' contains the definition of the center part of pages for our layout. The template 'page' has only one zone with content, the template 'index' has two.
The template 'page':
<xsl:template name="content-template"> <div> <zone name="default" level="2"/> </div> </xsl:template>
The zones are defined with the tag 'zone' and with the attribute 'name' which calls back the zone id defined in the template.xml (see previous step).
A last attribute 'level' defines the level of the content title.
A zone is container of Ametys contents. Each content has a title (mandatory), a sub-title and a body. The content's title is a h1 if zone's level is 1, an h2 if level = 2 ... The content's sub-title is also a h but +1 compare to the title (meaning starts by h2 if level = 1, h3 if level = 2 ...)
And finally the body itself can contain up to 3 levels of titles in h tags starting with the same tag as the sub-title.
common variables
Copy the required file 'attributes-labels.xsl' from the demo skin into your skin directory under 'stylesheets'.
Do the same with 'io/docbook2html.xsl'.
More information here.
Step 4: Customize the CMS according to the layout
It's time now to integrate the layout in the CMS itself in order to use it at the edition of the website and for its preview.
In this chapter, we will explain how to customize the HTML editor in the CMS in order to use the style of the layout. Some default styles are already defined, but you can also define our own.
The file 'conf/edition-styles.xml' defines the styles used in the CMS at the content edition.
Headers and paragraph styles
In the node <para> you can edit the style you want to use at the content edition. For each <style> we define the corresponding button (user control of the style in the cms toolbar) and the style itself in the html editor.
Before this operation, we should include the css files containing the style of the 2 parts, that why the first child of the node <para> is a node <import> with two elements <button> (import the style used for the buttons) and <inline-editor> (import the style for the content edition).
Please note here that all these styles for a specific element must be similar in order to not confuse the end user.
So now, in your example, we have 3 css files: default.css (used on the generated html files, meaning our website or the preview), the backoffice-button.css (for the cms toolbar) and the content.css (for the cms editor part).
Let start with the style 'Title 1', this defines the style of the header of level 1 in the html editor. Warning, depending of the level set in the zones, this element may be later on the website a h3 or h4 (in our case an h3).
The style is defined like this:
<style> <button> <label i18n="true">SKIN_BO_EDITOR_STYLES_PARA_TITLE1_LABEL</label> <description i18n="true">SKIN_BO_EDITOR_STYLES_PARA_TITLE1_DESCRIPTION</description> <cssclass>htmleditor-h1</cssclass> </button> <inline-editor>h1</inline-editor> </style>
The <label> is the text displayed in the drop down list and the <description> the text of its tool-tip. As seen before, we can internationalize the text by using i18n keys.
The title 1 (h3) in the content part on the website looks like this: 
In the editor tool bar: 
And in the edition part: 
The style of the label in the drop down is then defined by the class .htmleditor-h1 in the backoffice-button.css.
Here:
.htmleditor-h1 {
font-family:Georgia,"Times New Roman",Times,serif;
font-size: 0.9em;
font-weight: bold;
letter-spacing: 2px;
text-transform: uppercase;
color:#468259;
}
The class reuse the style of h3 defined in default.css
The <inline-editor> gives the corresponding tag to use in the html editor. A text with this style will then be included in <h1> tags. This style has also to be defined, here in the content.css file:
.mceContentBody h1 {
color: #468259;
font-size: 0.9em;
font-weight: bold;
font-family: Georgia,"Times New Roman",Times,serif;
margin: 0;
padding: 0;
text-transform: uppercase;
margin-bottom: 1em;
letter-spacing: 2px;
}
Please note the class prefix '.mceContentBody', it's important to use this prefix to be sure to limit the usage of this style only to the html editor.
With the same principle you can define the style of the headers h2 and h3 and paragraphs.
<style> <button> <label i18n="true">SKIN_BO_EDITOR_STYLES_PARA_NORMAL_LABEL</label> <description i18n="true">SKIN_BO_EDITOR_STYLES_PARA_NORMAL_DESCRIPTION</description> <cssclass>htmleditor-p</cssclass> </button> <inline-editor>p</inline-editor> </style>
.htmleditor-p {
font:small/1.8em Arial,Helvetica,sans-serif;
color:#838B91;
background: url("../img/img10.gif") repeat-x scroll 0 0 transparent;
}
.mceContentBody p {
color:#838B91;
font:small/1.8em Arial,Helvetica,sans-serif;
margin: 0px;
margin-bottom: 15px;
padding: 15px 20px 0px 20px;
background: url("../img/img10.gif") repeat-x scroll 0 0 transparent;
}
Style of Tables
The node <table> contains then the defintions of the different types of table used in the cms. Per default, the cms defines 2 table styles: class 'simple' and class 'invisible', these two classes should then be defined in the website css (here default.css, used also for the preview) and in the content edition css (here content.css).
In our example, we start to define first the style common to all type of table.
In default.css:
.posts table,
.posts table tr th,
.posts table tr td {
border-collapse: collapse;
}
.posts table tr th {
padding: 5px;
}
.posts table tr td {
padding-left: 5px;
}
In content.css:
.mceContentBody table,
.mceContentBody table tr th,
.mceContentBody table tr td {
border-collapse: collapse;
}
.mceContentBody table tr th {
padding: 5px;
}
.mceContentBody table tr td {
padding-left: 5px;
}
.mceContentBody table caption {
color : #808080;
font-size : 0.9em;
padding-bottom: 5px;
}
Then, we define the class 'simple':
In default.css:
.posts table.simple,
.posts table.simple tr th {
border: 1px solid #468259;
}
.posts table.simple tr td {
border: 1px dotted #468259;
}
In content.css:
.mceContentBody table.simple,
.mceContentBody table.simple tr th {
border: 1px solid #468259;
}
.mceContentBody table.simple tr td {
border: 1px dotted #468259;
}
Then, the class 'invisible':
.posts table.invisible,
.posts table.invisible tr th,
.posts table.invisible tr td {
border: 0px none transparent;
}
.mceContentBody table.invisible,
.mceContentBody table.invisible tr th,
.mceContentBody table.invisible tr td {
border: 1px dotted #468259;
}
The definition are different here, the class 'invisible' is not really invisible in the content in order to see the table when we edit the content.
Of course, it's possible to define some customized table styles. It's the case of the class 'datastrong'.
We declare this new style in the 'edition-styles.xml' file in the node <table>. We import the edition css file in the node <import>. The style itself is then declared in the node <style> as seen before.
The <icon> sets the path of the 32px image used in the toolbar and the <inline-editor> contains the class name.
<table> <import> <inline-editor>css/content.css</inline-editor> </import> <style> <button> <icon>img/bo/Table_Data_Strong_32.png</icon> <label i18n="true">SKIN_BO_EDITOR_STYLES_TABLE_DATASTRONG</label> <description i18n="true">SKIN_BO_EDITOR_STYLES_TABLE_DATASTRONG_DESC</description> </button> <inline-editor>datastrong</inline-editor> </style> </table>
In the default.css file, this call is defined like this:
.posts table.datastrong {
border: 1px solid #468259;
}
.posts table.datastrong tr.odd {
background-color: #E3EAE4;
}
.posts table.datastrong tr.even {
background-color: #FFFFFF;
}
.posts table.datastrong tr th {
background-color: #468259;
color: #FFFFFF;
font-weight: bold;
text-align: center;
}
.posts table.datastrong tr td {
border: 1px solid #468259;
}
Style of links
It's the same mechanisms as for the table. There are 2 predefined styles: 'simple' and 'invisible'. In our example, both have the same style on the website.
a {
background: url(../img/img03.gif) repeat-x left bottom;
text-decoration: none;
color: #468259;
}
a:hover {
background: none;
text-decoration: underline;
}
A customized style 'download' is declared like this (small icon on the left):
<link>
<import>
<inline-editor>css/content.css</inline-editor>
</import>
<style>
<button>
<icon>img/bo/Link_Download_32.png</icon>
<label i18n="true">SKIN_BO_EDITOR_STYLES_LINK_DOWNLOAD</label>
<description i18n="true">SKIN_BO_EDITOR_STYLES_LINK_DOWNLOAD_DESC</description>
</button>
<inline-editor>download</inline-editor>
</style>
</link>
a.download,
a.download:hover {
padding-left: 20px;
background-image: url(../img/img13.png);
background-position: left;
background-repeat: no-repeat;
}
.mceContentBody a.download,
.mceContentBody a.download:hover,
.mceContentBody a.download:link,
.mceContentBody a.download:visited,
.mceContentBody a.download:active
{
padding-left: 20px;
background-image: url(../img/img13.png);
background-position: left;
background-repeat: no-repeat;
}
style of lists
unorderedlist
There are 2 predefined styles 'disc' and 'square'.
.posts ul.disc {
list-style-type : disc;
}
.posts ul.square {
list-style-type : square;
}
.mceContentBody ul {
color:#838B91;
font:small/1.8em Arial,Helvetica,sans-serif;
}
.mceContentBody ul.disc {
list-style-type : disc;
}
.mceContentBody ul.square {
list-style-type : square;
}
In our example, we define the style 'heart'.
<unorderedlist> <import> <inline-editor>css/content.css</inline-editor> </import> <style> <button> <icon>img/bo/UnorderedList_Heart_32.png</icon> <label i18n="true">SKIN_BO_EDITOR_STYLES_UNORDEREDLIST_HEART</label> <description i18n="true">SKIN_BO_EDITOR_STYLES_UNORDEREDLIST_HEART_DESC</description> </button> <inline-editor>heart</inline-editor> </style> </unorderedlist>
.posts ul.heart {
list-style: url(../img/img12.gif);
}
.mceContentBody ul.heart {
list-style-image: url(../img/img12.gif);
}
Ordered list
Only the predefined styles 'arabic', 'lowerroman', 'upperroman', 'loweraplha' and 'upperalpha' are defined.
.posts ol {
color:#838B91;
font:small/1.8em Arial,Helvetica,sans-serif;
}
.posts ol.arabic {
list-style-type: decimal;
}
.posts ol.lowerroman {
list-style-type: lower-roman;
}
.posts ol.upperroman {
list-style-type: upper-roman;
}
.posts ol.loweralpha {
list-style-type: lower-alpha;
}
.posts ol.upperalpha {
list-style-type: upper-alpha;
}
.mceContentBody ol {
color:#838B91;
font:small/1.8em Arial,Helvetica,sans-serif;
}
.mceContentBody ol.arabic {
list-style-type: decimal;
}
.mceContentBody ol.lowerroman {
list-style-type: lower-roman;
}
.mceContentBody ol.upperroman {
list-style-type: upper-roman;
}
.mceContentBody ol.loweralpha {
list-style-type: lower-alpha;
}
.mceContentBody ol.upperalpha {
list-style-type: upper-alpha;
}
Style of images
TODO
Step 5: Tags
TODO : tags/tags.xml
Step 6: Error pages
Create at least 3 static error pages: 404.html, 500.html and 502.html. These pages are static because used when the tomcat server is down.
Please note that the variable {$skincontext} = /skins/{skin_name}/resources/, in our example the path to the resources is then:
<link href="/skins/thegreenhouse/resources/css/default.css" rel="stylesheet" type="text/css" />
Of course, it can be different according to your Apache configuration.
Step 7: Create website + set skin + set rights
The skin is almost ready, you can create a new website in the CMS and set the new skin to this site.
You can download the skin of this how-to here.
Back to top