Creating and configuring a charter templatev1.0.0, v1.1.0, v1.2.0, v1.3.0
Last published:04/03/2019à 10:30LaureLopez
This page is intended for integrators with a minimum knowledge of HTML, CSS, XML, XSL, I18N ... and familiarity with the integration of a Ametys graphic charter. See the Graphic integration page.
Setting up a graphic charter requires setting up its template. In other words, a charter can only be customized via the Graphic Charter Workshop if it is linked to a charter template.
The graphic charter becomes an "instance" of the model.
A model has an additional directory named "model" with :
variant parameters: model/variants/**
image parameters: model/images/**
the ribbon configuration file with all parameters: model/cms-ribbon.xml
colors and color themes file: model/colors.xml
the available styles file css : model/css-styles.xml
the default values file: model/default-css.xml
The last 4 files are configuration files. They are described in more detail in the Model configuration files section.
Setting up a graphic template
Style parameters (resources/css/*.css)
The CSS parameters are used to modify style elements: font, font size, color, character styles (bold, italic, underlined), margins, background color, alignment, etc.
A style parameter is declared directly in the CSS file, on the same line as the parameterizable CSS property, in the form of a comment, as follows:
Warning The css parameter must appear on a single line, without braces. For example, a parameter declared as follows will not be detected:
Oops!
Copy to clipboard failed. Open the code and copy it manually.
body{ background-color: #ffff00/* AMETYS ("page.body.bgcolor", "Couleur de fond") */; }
body{ background-color: #ffff00/* AMETYS ("page.body.bgcolor", "Couleur de fond") */; }
body{ background-color: #ffff00/* AMETYS ("page.body.bgcolor", "Couleur de fond") */; }
write instead:
Oops!
Copy to clipboard failed. Open the code and copy it manually.
body{
background-color: #ffff00/* AMETYS ("page.body.bgcolor", "Couleur de fond") */;
}
body{
background-color: #ffff00/* AMETYS ("page.body.bgcolor", "Couleur de fond") */;
}
body{
background-color: #ffff00/* AMETYS ("page.body.bgcolor", "Couleur de fond") */;
}
Important The same css parameter can be present in several places in the same css file, or in several css files. Case in point: the choice of level 1 title color applies both in the main css (ametys.css), the mobile css (ametys-mobile.css) and in css for wysiswyg editing(editor-content.css).
Oops!
Copy to clipboard failed. Open the code and copy it manually.
Variant parameters are used in complex cases, when it is necessary to replace one or more files (XSL, images, css files , javacripts, ....).
The model/variants directory contains a subdirectory for each variant parameter. The directory name is the parameter identifier.
The model/variants/[VARIANT] directory contains as many directories as there are possible values for this variant.
Each model/variants/[VARIANT]/[VALUE] directory contains files which reproduce the root tree of a skin and which will be added to it (and overwritten if necessary) when the variant is applied.
In the Graphic Design Workshop, each variant is represented by a gallery (menu). The elements in the gallery are made up of the different possible values for this variant.
Optionally, the model/variants/[VARIANT] directory can contain PNG format icons, thumbnail_32.png (32 x 32 pixels) and thumbnail_16.png (16 x 16 pixels), which will be used for the generated menu. This directory can also contain a VARIANT file.xml for the menu label and description (with or without i18n keys).
Optionally, the directory model/variants/[VARIANT]/[VALUE] can also contain a PNG image in the form [VALUE].png, which will be used for the gallery item. This directory can also contain a VALUE file.xml for the label and description of the menu item (with or without i18n keys).
Here's an example:
Here's an example of variant parameters defining 3 variants for the side menu ("vmenu"):
with a border separating menu items ("borders" variant),
with a background image on menu items ("boxes" variant),
simple, without border or background color ("simple" variant)
Parameter declaration
Ribbon element
Effect on the graphic charter
The vmenu.xml file contains the parameter label and description:
File vmenu.xml
Oops!
Copy to clipboard failed. Open the code and copy it manually.
VALUE].xml files(simple.xml, borders.xml and boxes.xml) contain the label and description of the variant, which appears in the gallery. Example with the simple.xml file:
Simple file.xml
Oops!
Copy to clipboard failed. Open the code and copy it manually.
When applying the "boxes" variant, for example, all directories and files in the model/variant/vmenu/boxes directory are copied to the directory of the working version of the skins/[CHART_NAME] charter.
Image parameters (model/images/xxx)
An image-type parameter is a variant parameter but limited to one image.
Image parameters are declared in the model/images directory.
In this directory, each customizable image is represented by a directory named after the image, whose path is identical to the path relative to the resources/img directory in the charter. This directory contains all the images of choice. Images can be sorted into sub-folders.
This variant directory can contain a [filename] file.xml for the menu name and description (with or without keys i18n)
Here's an example:
Here's an example of an image parameter used to modify the charter banner.
Parameter declaration
Ribbon element
Effect on the graphic charter
File header.xml
Oops!
Copy to clipboard failed. Open the code and copy it manually.
The template features 8 banners in 2 groups ("Abstract" and "Nature"),
For any image setting, you can select your own image from your hard disk by clicking on"From file".
When this parameter is applied, the resources/img/header.jpg image is replaced by the chosen image.
Text parameters (**/*.xsl)
Text parameters are used to modify the text elements of a XSL file.
They can be used, for example, to modify a variable XSL or untranslated text contained in a XSL.
It is declared directly in the XSL file in the form of a comment, as follows:
Oops!
Copy to clipboard failed. Open the code and copy it manually.
<xsl:variable name="foo">Paramètre de variable<!-- AMETYS("txt.params.foo", "Foo", "Description de foo") --></xsl:variable>
<xsl:variable name="foo">Paramètre de variable<!-- AMETYS("txt.params.foo", "Foo", "Description de foo") --></xsl:variable>
<xsl:variable name="foo">Paramètre de variable<!-- AMETYS("txt.params.foo", "Foo", "Description de foo") --></xsl:variable>
or
Oops!
Copy to clipboard failed. Open the code and copy it manually.
<xsl:variable name="foo">Paramètre de variable<!-- AMETYS("txt.params.foo", I18N_FOO_LABEL, I18N_FOO_DESC) --></xsl:variable>
<xsl:variable name="foo">Paramètre de variable<!-- AMETYS("txt.params.foo", I18N_FOO_LABEL, I18N_FOO_DESC) --></xsl:variable>
<xsl:variable name="foo">Paramètre de variable<!-- AMETYS("txt.params.foo", I18N_FOO_LABEL, I18N_FOO_DESC) --></xsl:variable>
The parameter identifier must be unique.
The label is optional. It can be a key i18n defined in the model catalog.
The description is optional. It can be a key i18n defined in the model catalog.
For i18n keys, it is declared in the message file.xml by default only. No need to recall the skinfactory identifier in each language. A default value is also required. See : Translation parameters above.
Sample declaration
Oops!
Copy to clipboard failed. Open the code and copy it manually.
The model/cms-ribbon.xml file contains the ribbon generated from the model parameters. It contains all parameters, with their identifiers, sorted by tabs and groups.
Simple example with 3 parameters
Oops!
Copy to clipboard failed. Open the code and copy it manually.
You don't need to create this file when you create your template, as it will be generated automatically according to the template parameters the first time you open the Graphic Design Workshop.
However, this file can be manually modified to reorganize parameters into groups / menus / sub-menus or to modify labels and icons.
Oops!
Copy to clipboard failed. Open the code and copy it manually.
The choice of parameter identifiers can help you organize parameters more easily into tabs, groups, menus or sub-menus.
In fact, depending on the identifiers, the parameters will be automatically organized into tabs / groups / menus and sub-menus according to the following conventions:
Identifier format
[tab].[group].[item].
The parameter is placed in the "tab" tab and the "group" group.
Oops!
Copy to clipboard failed. Open the code and copy it manually.
The model/cms-ribbon.xml file is re-generated each time the model is modified. Parameters that no longer exist are commented out. New parameters are added at the end of the file, or at the end of a group or menu, depending on their identifier, and labels and icons are retained.
Example: Removing the "header.slogan.size" parameter and adding the "header.menu.bgcolor" parameter
Oops!
Copy to clipboard failed. Open the code and copy it manually.
Menus and submenus are all generated with an icon. Wherever possible, the icon is deduced from the menu identifier.
For example, 2 parameters CSS whose identifiers are "content.text.link.color" and "content.text.link.text-decoration". When generating the cms-ribbon.xml file, they will automatically be placed in the "content" tab, then the "content.text" group, then the "content.text.link" menu. The icon automatically chosen for the menu will be the link icon (/plugins/skinfactory/resources/img/button/link_32.png) :
Oops!
Copy to clipboard failed. Open the code and copy it manually.
If no icon can be deduced from the menu identifier, then the icon is used.
You can modify the icons used in menus by specifying the path to your own icons. Some icons are supplied by plugin. They are listed in the table below with their path.
This file contains the values that will be proposed in the menus for each style css listed: font-family, font-size, border-style, border-width, letter-spacing, text-indent, line-height, width, height, margin, padding and since version 1.2.0 border-radius, background-position and background-repeat.
Oops!
Copy to clipboard failed. Open the code and copy it manually.
Pour chaque item, vous devez définir un label (<label>) et une valeur (<value>).
Vous pouvez ajouter une icone (<icon>) et/ou une classe css (<cssclass>)
Sample menus
Default values (file model/default-values.xml)
The model/default-values.xml file contains default parameter values.
For parameters of type CSS, i18n or text, the default values can be taken respectively from the css, messages.xml or XSL file where they are located. There is therefore no need to re-specify them in this file.
However, this is not the case for variants and images. For these 2 types of parameters, a default value must be specified in this file.
The file is built as shown below:
Oops!
Copy to clipboard failed. Open the code and copy it manually.
Le thème par défaut peut être également préciser ici, dans la balise <color-theme>.
Special case of theme colors
For CSS type parameters referencing a color (color, border-color, background-color), it may be useful here to specify a default color if this is a color chosen in a theme.
For colors chosen in a theme, it's not the hex color that's saved but the position of the color in the theme: color-theme-1, color-theme-2, color-theme-3, ...
When a graphic template is generated, the colors are defined according to the default model, and the user can then easily adapt this template by choosing a different color theme.
Oops!
Copy to clipboard failed. Open the code and copy it manually.