Outils pour utilisateurs

Outils du site


Panneau latéral

ref:themes

Thèmes

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 :

  • Des zones fixes : HTML statique ou blocs paramétrés d'une certaine manière
  • Des zones éditables où le rédacteur de page dépose, paramètre et agence les blocs de son choix

Installation d'un thème

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

Création d'un thème

La commande changedev.php theme.init <themeName> initialise la structure d'un thème. Dans le dossier themes/<themeName>/ on trouvera :

Structure d'un gabarit de page

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>

Placement de bloc

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 :

  • Menus
  • Fil d'Ariane
  • Navigation multilingue
  • Formulaire de recherche
  • XHTML “statique”

Zone éditables

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”.

Créer une déclinaison pour l'éditeur de page

Il est conseillé de créer une déclinaison allégée du gabarit pour l'éditeur de contenu de page :

  • Focus utilisateur sur l’essentiel : le contenu
  • Problème de place : dans le contexte de l'éditeur de page, la page n'est qu'un des éléments présents à l'écran et l'écran n'est pas extensible…
  • Chargement plus rapide

On conservera essentiellement :

  • L'emplacement des zones de contenu
  • Les tailles relatives des différents éléments

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

Le fichier install.xml est un script XML d'importation qui déclare et complète les gabarits de page :

  • Précision du type du document XHTML : l'attribut @doctype peut valoir XHTML-1.0-Transitional ou XHTML-1.0-Strict
  • Feuilles CSS associées au gabarit :
    • Les attributs @cssscreen et @cssprint contiennent la liste des feuilles à charger, séparées par des virgules, pour les media “screen” et “print” respectivement.
    • Si @useprojectcss vaut “true”, les CSS des modules du projet sont chargées (feuilles “frontoffice.css”)
  • JavaScript associés au gabarit :
    • @js contient la liste des Javascript à charger, séparés par des virgules
    • Si @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.

Surcharge des gabarits de bloc

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

Styles CSS du thème

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/.

Faire référence aux images du thème

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)
}

Importation de feuilles CSS

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.

Styler les éléments du gabarit dans le contexte de l'éditeur de page

Quand le gabarit de page n'est pas spécialisé pour l'éditeur de page, le contenu HTML du gabarit est transformé comme suit :

  • L'élément <body/> est transformé en un élément XUL <vbox/> d'identifiant égal au nom du gabarit
  • Les éléments <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é.

Configuration du richtext

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="&amp;modules.website.bo.general.Richtext-Title1;">
    <attribute name="class" value="heading-one"/>
  </style>
  <style tag="h2" label="&amp;modules.website.bo.general.Richtext-Title2;">
    <attribute name="class" value="heading-two"/>
  </style>
  <style tag="pre" label="&amp;modules.website.bo.general.Richtext-Pre;">
    <attribute name="class" value="normal"/>
  </style>
  <style tag="pre" label="&amp;modules.website.bo.general.Richtext-Code;">
    <attribute name="class" value="code"/>
  </style>
  <style tag="span" block="false" label="&amp;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.

Apparence des éléments du richtext lors de l'édition

  • Dans les richtext, l'apparence des éléments est réglée par les feuilles modules.generic.frontoffice et modules.generic.richtextbo.
  • Dans le contexte d'un éditeur de document, la feuille modules.uixul.cRichtextField est ajoutée.
  • Dans le contexte de l'éditeur de contenu de page, les feuilles du gabarit et les éventuelles feuilles des ancêtres de la page sont ajoutées.

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.

Habillage du thème

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 :

  1. Associer des variables aux valeurs de propriétés CSS utilisées par le thème
  2. Créer un formulaire permettant l'édition de ces variables

Déclarer une variable CSS

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

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.

Initialisation du formulaire

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.

ref/themes.txt · Dernière modification: 2017/01/19 14:54 (modification externe)