Un thème RBS Change définit une charte graphique : gabarits de page, gabarits de bloc, styles CSS, images et Javascript. Il est matérialisé par un dossier du nom du thème, placé dans le dossier themes/
du projet.
Les gabarits de page sont des fichiers XML, définissant le contenu de l'élément <body/>
de la page :
L'installation d'un thème se fait en décompressant le contenu du thème dans le dossier themes/
puis en appelant la commande change.php theme.install <themeName>
.
Exemple : installation du thème webfactory
wget http://rbschange.fr/static/themes/webfactory-1.0.zip unzip webfactory-1.0.zip -d themes/ change.php theme.install webfactory
La commande changedev.php theme.init <themeName>
initialise la structure d'un thème. Dans le dossier themes/<themeName>/
on trouvera :
templates/
: gabarits de pagemodules/
: gabarits de blocstyle/
: styles CSSimage/
: imagesjs/
: javascriptskin/
: formulaire d'habillage du thème
Le gabarit de page définit le contenu de l'élément <body/>
de la page.
<?xml version="1.0" encoding="UTF-8"?> <change:templates xmlns:change="http://www.rbs.fr/change/1.0/schema"> <change:template id="mytpl"> <div id="mymaindiv"> ... </div> </change:template> </change:templates>
Générera une page du type :
<html xmlns="http://www.w3.org/1999/xhtml"> ... <body> <div id="mymaindiv"> ... </div> </body> </html>
Pour placer un bloc, on utilise l'élément <change:templateblock/>
en renseignant l'attribut type
avec le nom du bloc.
Exemple: placement du bloc modules_website_thread
, qui génère un “Fil d'Ariane” :
<?xml version="1.0" encoding="UTF-8"?> <change:templates xmlns:change="http://www.rbs.fr/change/1.0/schema"> <change:template id="mytpl"> <div id="mymaindiv"> ... <change:templateblock type="modules_website_thread" /> </div> </change:template> </change:templates>
Les paramètres de configuration du bloc sont transmis en tant qu'attribut de l'élément <change:templateblock />
, en préfixant par "__" le nom du paramètre de configuration.
Ainsi pour placer le bloc modules_website_taggedmenu
, configuré pour afficher le menu tagué “contextual_website_website_menu-header”, en utilisant le gabarit “header” sur une profondeur maximale de “1”, on écrira :
<?xml version="1.0" encoding="UTF-8"?> <change:templates xmlns:change="http://www.rbs.fr/change/1.0/schema"> <change:template id="mytpl"> <div id="mymaindiv"> ... <change:templateblock type="modules_website_taggedmenu" __tag="contextual_website_website_menu-header" __template="header" __depth="1" /> </div> </change:template> </change:templates>
Les modules standards fournissent un certain nombre de blocs usuels :
Pour définir une zone éditable, on utilise l'élément <change:content/>
en renseignant l'attribut id
, de valeur unique au sein du gabarit.
Exemple : définition d'une zone éditable de nom “content-block”
<?xml version="1.0" encoding="UTF-8"?> <change:templates xmlns:change="http://www.rbs.fr/change/1.0/schema"> <change:template id="mytpl"> <div id="mymaindiv"> ... <change:content id="content-block" /> </div> </change:template> </change:templates>
Nous recommandons de définir l'identifiant de la zone libre principale de contenu à “content-block”.
Il est conseillé de créer une déclinaison allégée du gabarit pour l'éditeur de contenu de page :
On conservera essentiellement :
L'éditeur de page vit dans un environnement XUL, différent d'XHTML. On utilisera en particulier les éléments XUL <vbox />
et <hbox />
, “boîtes” dont les fils s'empilent respectivement “verticalement” et “horizontalement”.
Exemple : un gabarit trois colonnes
<hbox id="container"> <vbox id="left-column"> <change:content id="left-content-block" /> </vbox> <vbox id="main-column"> <change:content id="content-block" /> </vbox> <vbox id="right-column"> <change:content id="right-content-block" /> </vbox> </hbox>
Côté CSS, il est important de fixer les tailles et d'éviter l'usage de la directive float
:
#container { width: 1000px; float: none; } #left-column { width: 200px; float: none; } #main-column { width: 600px; float: none; } #right-column { width: 200px; float: none; }
On pourra placer ces instructions dans une feuille dédiée et l'importer de manière sélective depuis la feuille css du gabarit grâce à la directive import :
@import url(/themes/mytheme/style/bostyle.xul.css);
Pour déclarer la déclinaison, créer un nouvel élément <change:template />
en définissant l'attribut content-type
à “xul” :
<?xml version="1.0" encoding="UTF-8"?> <change:templates xmlns:change="http://www.rbs.fr/change/1.0/schema"> <change:template id="mytpl"> ... </change:template> <change:template id="mytpl" content-type="xul"> <hbox id="..."> ... </hbox> </change:template> </change:templates>
Le fichier install.xml
est un script XML d'importation qui déclare et complète les gabarits de page :
@doctype
peut valoir XHTML-1.0-Transitional
ou XHTML-1.0-Strict
@cssscreen
et @cssprint
contiennent la liste des feuilles à charger, séparées par des virgules, pour les media “screen” et “print” respectivement.@useprojectcss
vaut “true”, les CSS des modules du projet sont chargées (feuilles “frontoffice.css”) @js
contient la liste des Javascript à charger, séparés par des virgules@useprojectjs
vaut “true”, les Javascript des modules du projets sont chargés (fichier “frontoffice.js”)
L'exemple suivant, themes/mytheme/install.xml
, montre l'enregistrement des fichiers “templates/tpl1.xml” et “templates/tpl2.xml” du thème “mytheme”.
<?xml version="1.0" encoding="UTF-8"?> <script> <binding fileName="modules/theme/persistentdocument/import/theme_binding.xml"/> <rootfolder module="theme"> <theme id="mytheme" byCodename="mytheme" label="My theme" description="This is my first theme"> <pagetemplate byCodename="mytheme/mytpl1" doctype="XHTML-1.0-Transitional" useprojectcss="false" cssscreen="themes.mytheme.common,themes.mytheme.tpl1"/> <pagetemplate byCodename="mytheme/mytpl2" doctype="XHTML-1.0-Transitional" useprojectcss="false" cssscreen="themes.mytheme.common,themes.mytheme.tpl2" js="themes.mytheme.js.tpl2" /> </theme> </rootfolder> </script>
Les deux gabarits sont de type “XHTML 1.0 Transitional” et n'utilisent que leurs CSS : style/common.css
plus style/tpl1.css
et style/tpl2.css
respectivement. De plus, l'usage du gabarit “tpl2” provoque le chargement du fichier js/tpl2.js
.
Une fois le fichier install.xml
proprement renseigné ou modifié, la commande change.php theme.install <themeName>
devra être appelée.
Un thème peut “surcharger” (ou redéfinir) les gabarits de blocs définis par les modules. Pour ce faire, le thème déclare le gabarit dans le dossier modules/
en reprenant l'arborescence originale.
Ainsi pour surcharger le gabarit templates/Website-Block-Thread-Success.all.all.html
du module website dans le thème “mytheme”, on créera le fichier themes/mytheme/modules/website/templates/Website-Block-Thread-Success.all.all.html
Le thème peut embarquer des feuilles de styles CSS que les gabarits de page peuvent utiliser (attribut ''@cssscreen'' de l'élément <pagetemplate/>
). Les feuilles CSS du thème sont des fichiers “.css” placés dans le dossier style/
.
Pour faire référence à l'image imageName.png
du thème themeName
, on utilise l'URL /media/themes/<themeName>/<imageName>.png
: lors du rendu de cette URL, un lien symbolique vers l'image du thème est généré.
Exemple : référence au media “mylogo.png” du thème “mytheme” dans une feuille de style CSS :
#logoLocation { background-image: url(/media/themes/mytheme/mylogo.png) }
La directive @import
permet la factorisation des feuilles CSS.
Exemple : inclusion de la feuille “modules/media/style/fancybox.css”
@import url(/modules/media/style/fancybox.css)
La directive @import
permet un inclusion sélective selon le navigateur à l'origine de la requête.
Exemple : importation de la feuille iecss.trident.6.css“ du thème “mytheme”, si le navigateur est IE version 6 :
@import url(/themes/mytheme/style/iecss.trident.6.css)
Exemple : importation de la feuille “bostyle.xul.css” du thème “mytheme”, dans le contexte de l'éditeur de contenu de page :
@import url(/themes/mytheme/style/bostyle.xul.css)
De manière générale, une importation sélective ressemble à @import url(/…/mafeuille.nav.version.css)
, où nav représente le moteur de rendu et version la version de ce moteur. Pour plus d'informations, voyez le fichier framework/config/browscap.ini
.
Quand le gabarit de page n'est pas spécialisé pour l'éditeur de page, le contenu HTML du gabarit est transformé comme suit :
<body/>
est transformé en un élément XUL <vbox/>
d'identifiant égal au nom du gabarit<div />
sont transformés en :<vbox />
, s'il n'ont pas d'attribut orient
ou s'il vaut “vertical”<hbox />
, si l'attribut orient
vaut “horizontal”
Les règles CSS utilisant les balises <body/>
ou <div/>
venant du gabarit ne seront donc pas appliquées. Pour viser ces éléments, on préférera donc des sélecteur n'utilisant que les identifiants des éléments plutôt que leur nom.
Pour plus de détails sur la transformation effectuée, voyez la feuille XSL website/lib/pageEditContentTransform.xsl
.
N.B. : Le contenu HTML des blocs reste lui inchangé.
Le fichier website/config/richtext.xml
définit les classes CSS applicables aux éléments XHTML depuis les éditeurs WYSIWYG.
Dans l'exemple suivant, on définit les classes CSS applicables aux éléments <h1/>
, <h2/>
et <pre/>
: respectivement “heading-one”, “heading-two” et “normal” ou “code”. Un cas particulier est fait du dernier élément, <span/>
, élément ”inline“ qui sera crée autour de la sélection de texte courante et qui doit porter l'attribut block=false
.
<?xml version="1.0" encoding="UTF-8"?> <styles> <style tag="h1" label="&modules.website.bo.general.Richtext-Title1;"> <attribute name="class" value="heading-one"/> </style> <style tag="h2" label="&modules.website.bo.general.Richtext-Title2;"> <attribute name="class" value="heading-two"/> </style> <style tag="pre" label="&modules.website.bo.general.Richtext-Pre;"> <attribute name="class" value="normal"/> </style> <style tag="pre" label="&modules.website.bo.general.Richtext-Code;"> <attribute name="class" value="code"/> </style> <style tag="span" block="false" label="&modules.website.bo.general.Richtext-InlineCode;"> <attribute name="class" value="some-inline-class"/> </style> </styles>
N.B. : hors des classes définies ici, les éléments seront nettoyés automatiquement lors de la sauvegarde ou du copier-coller.
Pour spécialiser ce fichier, surchargez le dans le dossier override/
du projet.
modules.generic.frontoffice
et modules.generic.richtextbo
.modules.uixul.cRichtextField
est ajoutée.De plus, les éléments html et body ont respectivement les identifiants “richtext-html” et “richtext-body”.
Pour changer le fond de tous les richtext pour “black”, on pourra donc par exemple déclarer dans modules.generic.richtextbo
:
body#richtext-body { background-color: black; }
Pour appliquer les même règles uniquement dans le contexte de l'éditeur de page, on mettra les mêmes instructions CSS dans la feuille du gabarit de page.
Un thème peut être décliné facilement par l'utilisateur final : un formulaire permet à l'utilisateur du backoffice de modifier certaines valeurs CSS, en fonction de ce que le thème aura définit “habillable”. De cette édition résulte un document “habillage” qui pourra être appliqué au niveau d'une page, d'une rubrique ou d'un site.
Rendre habillable un thème repose sur un principe relativement simple :
Pour associer une variable à une propriété CSS donnée, il suffit de rajouter un commentaire en fin d'instruction CSS.
Exemple : déclaration de la variable “headerbgimage” correspondant à la propriété CSS “background-image” de l'élément d'identifiant “header” :
#header { background-image: url(/media/themes/mytheme/default-header.png)/*@var headerbgimage*/; }
Le formulaire d'habillage est définit par le fichier skin/skin.xml
. Les champs, matérialisés par des éléments <field />
, sont regroupés en sections / sous-sections, matérialisées par des éléments <section />
:
<?xml version="1.0" encoding="UTF-8"?> <sections> <section name="Asection"> <field name="headerbgimage" type="imagecss" initialvalue="/media/themes/mytheme/default-header.png"/> </section> <section name="Anothersection"> <section name="subsection"> ... </section> </section> </section>
Le champ “headerbgimage” ainsi crée permet de renseigner la valeur de la variable du même nom : l'utilisateur pourra sélectionner un élément du thème, de la médiathèque ou directement sélectionner un fichier depuis son disque dur (celui-ci sera alors placé dans le dossier “Inbox” de la médiathèque).
Le contrôle de formulaire utilisé dépend de l'attribut type :
color
: la valeur est une couleur,dropdownlist
: la valeur est un élément de la liste indiquée par l'attribut listid
,imagecss
: la valeur est une image venant du thème ou de la médiathèque,size
: la valeur est une “taille” (width, height, …),text
: la valeur est un texte “libre”, c'est le type attribué par défaut.
La commande changedev.php theme.generate-skin <themeName>
permet l'initialisation du fichier skin/skin.xml
. Cette commande scanne l'ensemble des fichiers styles/*.css
du thème, y repère les variables et crée une entrée y correspondant, en reprenant la valeur par défaut. Reste à ordonner et organiser les champs en des sections cohérentes si nécessaire.