Outils pour utilisateurs

Outils du site


Panneau latéral

html_design:codebook

Guide de codage HTML

ATTENTION :
Le moteur de rendu PHPTal utilisé par RBSChange demande une syntaxe XML valide, ainsi :

  • TOUTE BALISE OUVERTE DOIT ÊTRE FERMÉE, ainsi des balises telles que br doivent être écrites <br/> et non <br> (même si HTML5 l'autorise)
  • Tout attribut doit avoir sa valeur entre guillemets

Par ailleurs si vous utilisez des macros PHPTal, le nom de votre macro ne doit pas comporter de caractère '-'.

Templates de page

Nommage des zones de contenu

Il est important de respecter ces noms de zones car lors d'un changement de template sur une page existante, les contenus saisis dans des zones qui ne sont pas présentes dans le nouveau template ne seront plus accessibles.

Les zones usuelles sont les suivantes :

  • content-block : la zone de contenu principale, impérativement présente sur tous les templates
  • sidebar-block : la zone de contenu secondaire, en général dans une barre latérale
  • secondary-sidebar-block : seconde barre latérale

Nommage des ''div'' de mise en page

Il s'agit là des conventions employées dans la charte par défaut. Contrairement aux nommage des zones de contenu, il n'y a pas d'obligation à les suivre car il n'y a pas d'incidence sur le fonctionnement.

Les templates de pages sont découpés en 3 grandes zones, elles-même subdivisées en 3 sous-zones. Les div ont alors les classes suivantes : - “header”, “content” et “footer” pour les zones principales - le nom de la zone principale et un suffixe “-top”, “-middle” ou “-bottom” pour les sous-zones (par exemple “header-top”)

Nommage des blocs éditables

Le nommage des blocs éditables du template est fait à partir de la classe de la sous-zone qui le contient, suffixée par un incrément. Par exemple, les différents blocs éditables de la zone “header-top” sont : “header-top-1”, “header-top-2”, etc.

Là non plus ce nommage n'a aucune incidence sur le fonctionnement, il faut juste que les noms des blocs soient reconnaissables en backoffice. De ce point de vue il vaut mieux éviter de les nommer par la fonction qu'ils ont car ils peuvent être remplacés par d'autres dans l'interface.

Templates de blocs

Ces recommandations sont appliquées sur l'ensemble des templates de blocs des modules standards. Cette homogénéité permet de styler globalement l'ensemble des modules avec un minimum de code CSS. Il est donc recommandé de s'en approcher autant que possible lors des développements spécifiques pour profiter des styles globaux mis en place et éviter de devoir réécrire des styles spécifiques à chaque bloc.

Généralités

  • class=“normal” sur les éléments bloc rajoute une marge homogène en bas
  • class=“normal-margin” pour juste ajouter la marge sur un élément qui a déjà une autre classe (notamment une liste sans puces)
  • penser à mettre un div et non un p autour des propriétés richtext ou bbcodes qui peuvent contenir paragraphes
  • change:h=“” sur les titres qui place les bonnes classes
  • classes h-1 à h-6 pour les autres éléments à rendre comme des titres (notamment les legend des fieldset)
  • ul class=“errors” pour messages d'erreur (automatique si change:errors)
  • ul class=“warnings” pour messages d'avertissement
  • ul class=“messages” pour autres messages (automatique si change:messages)
  • commencer un bloc “primaire” (bloc appelé à être en général le bloc principal de la page : détail de document, liste, etc) au niveau h1 et un bloc secondaire au niveau h2
  • class=“link” sur les liens (automatique si change:link ou change:actionlink)

Formulaires

  • class=“cmxform” sur formulaire (automatique si change:form)
  • toujours un fieldset avec l'ensemble dedans, message d'erreur compris et avec une légende (qui peut remplacer le titre du bloc le cas échéant, avec une classe h-n)
  • ol/li autour des champs
  • class=“button” sur les boutons, inputs et liens ayant un rendu de bouton (automatique sur change:submit)
  • ajouter de la classe “primary” pour le bouton principal du formulaire (ex : enregistrer, valider la commande, etc) et “secondary” pour les action mineures servant rarement (ex : annulation, reset, etc). On a ainsi trois niveaux de boutons possibles
  • p class=“buttons” autour des boutons, placé en dehors de la liste
  • class=“textfield” sur les champ input de type texte (automatique sur change:input)
  • p class=“help-text” pour les paragraphes d'aide, dans le même li que le champ
  • libellés avec double-points systématiques (automatique via les extensions PHPTAL)
  • si requis : class=“required” sur le nœud label commençant par : <em class=“requiredsymbol” title=“(${trans:m.website.frontoffice.this-field-is-mandatory})”>*</em> (automatique via les extensions PHPTAL)
    Exemple :
    <label class="required"><em class="requiredsymbol" title="(${trans:m.website.frontoffice.this-field-is-mandatory})">*</em> Prénom :</label>
  • fieldset en ligne (ex : ensemble de boutons radio) : class=“inline-set” sur le fieldset
    Exemple :
    <fieldset class="inline-set">...</fieldset>
  • sur les champs où c'est pertinent penser à mettre les attributs autocorrect=“off” et autocapitalize=“off” notamment pour l'iPhone et l'iPad (login, email, code, etc)

Listes

Généralités
  • class=“normal” sur les listes ul et ol pour avoir les puces + marge bas comme autres blocs
  • class=“normal” sur les listes de définitions (dl) pour avoir le dt en gras et la marge entre les items
  • pour faire des classes alternées odd/even : utilisation du mot-clé PHPTAL alternateclass
  • séparateurs : cf la section “séparateurs”
  • ne pas oublier la classe “normal-margin” s'il y a lieu de placer une marge basse sans que la classe “normal” n'est pas utilisée
Séparateurs
  • séparateurs : span avec la classe “separator” (marge avant et après) ou “punctuation” (marge seulement après) selon le symbole contenu. Le symbole est entouré d'espaces seulement sur les côtés comportant une marge : “ - ” et “ | ” mais “, ”
    Exemples :
    	<span class="separator"> - </span>
    	<span class="punctuation">, </span>
    
  • de préférence, placer le séparateur sur la même ligne que le contenu qui le précède et sans espace entre. Ceci est impératif quand on a la classe “punctuation”, sans quoi des espaces parasites qui apparaissent
    Exemple :
    	<dl class="inline-list" tal:condition="doc/getPublishedCategoryCount">
    		<dt>${trans:modules.event.fo.categories,ucf}</dt>
    		<dd tal:repeat="category doc/getPublishedCategoryArray">
    			<a change:link="document category">${category/getLabelAsHtml}</a><span tal:condition="not: repeat/category/end" class="punctuation">, </span>
    		</dd>
    	</dl>
    
  • dans les listes à la fin du contenu d'un li (absent sur le dernier élément)
Liste détaillée de docs
  • class=“document-list” sur la liste (ul/ol)
  • class=“document-visual” sur le visuel du document s'il existe
  • classes alternées (cf plus haut)
Liste en ligne
  • class=“inline-list” sur les liste de catégories, mots-clés, etc associés (ul/ol/dl)
  • séparateurs en fin de li/dd (cf plus haut)
Liste de définitions avec items en ligne

Il s'agit d'une liste de définitions où le terme et sa définition sont sur la même ligne.

  • dl class=“inline-items”
  • pas de séparateurs
Listes façon "menu"
  • ul/ol/dl et class=“menu-list”
Listes façon "nuage"
  • ul class=“cloud-list”
  • li style=“font-size: Xem” avec X entre 1 et 2 selon le poid du mot
  • trois niveau de balises rien / em / strong selon le poid du mot

Autre blocs

Résultats de recherche
  • format d'image unique modules.solrsearch.frontoffice/result-visual + class=“document-visual”
  • description dans un p class=“normal”
  • liste de définitions class=“inline-list” pour les autres informations
Détail de document
  • h1 pour le libellé
  • visuel (si présent) avec classe document-visual
  • liste des propriétés dans un dl class=“normal” avec dt pour les libellés de propriétés et dd pour les valeurs

Colonnages

  • div class=“columns” pour le conteneur
  • div class=“column-50|column-25|column-75|column-33|column-66” pour les colonnes contenues
  • Exemple :
    <div class="columns">
    	<div class="column-50">
    		...
    	</div>
    	<div class="column-50">
    		...
    	</div>
    </div>
    

Divers

  • liens de navigation vers les pages de listes et autres : ul class=“mini-navigation” placé avant le titre
    Exemple :
    <ul class="mini-navigation">
    	<li>
    		<img change:img="front/rss.gif" alt="" />
    		<a class="link" change:link="module blog; action ViewFeed; parentref blog/getId">${trans: m.blog.frontoffice.blog-rss-link,ucf}</a>
    	</li>
    </ul>
    <h1 change:h="">${blog/getLabelAsHtml}</h1>
    
  • mise en exergue d'une portion de texte (ex : résultats de recherche) : class=“highlight”
    Exemple :
    Lorem <em class="highlight">Ipsum</em> is simply dummy text of the printing and typesetting industry.
  • masquer un élément lorsque JavaScript est désactivé : class=“js”
  • masquer un élément lorsque JavaScript est activé : class=“nojs” (à privilégier par rapport à la balise noscript)
  • affichage d'une version raccourcie courte remplacée par la version complète au clic : class=“ctoggle” sur le conteneur et class=“short” et class=“full” sur les deux alternatives
    Exemple :
    <div class="ctoggle">
    	<div class="short">Toto...</div>
    	<div class="full">Toto, tata et titi.</div>
    </div>
    

Feuilles de styles

jQuery UI

Plusieurs blocs de Change utilisent jQuery UI. Jusqu'à la version 3.5.x, les styles associés étaient inclus automatiquement en choisissant un thème via la configuration du projet. À partir de la version 3.6, ces styles ne sont plus inclus automatiquement et doivent être inclus par le thème. Ces styles peuvent être générés sur le site de jQuery UI.

Dans le thème par défaut il s'agit de la feuille de style jqueryui.css qui a été modifiée pour prendre en compte les habillages.

Variables dans les CSS

La version 3.6 introduit une syntaxe permettant d'utiliser des variables dans les feuilles de styles. Ceci permet notamment de faciliter l'utilisation du module habillage sur des propriétés CSS3 complexes dont les valeurs ne peuvent pas être éclatées en plusieurs propriétés simples (exemple : arrière-plans multiples ou gradients).

La syntaxe retenue se base sur une sous-partie du draft de recommandation suivant : http://www.w3.org/TR/css-variables/

On déclare les variables dans une section :root et elles valent pour l'ensemble des styles (il n'est pas possible de les redéfinir pour des contextes particuliers comme le propose la spécification). On recommande également de ne déclarer de variables d'habillage que sur des variable CSS et non de façon dispersée sur l'ensemble des feuilles de styles. Dans le thème par défaut ces déclarations sont toutes regroupées dans la feuille de style variables.css.

Exemple :

/* Déclarations */
:root {
	var-ma-variable: #123;
	var-ma-variable-skinable: #abc /* @var mavariableskinable */;
}

/* Utilisation */
body {
	color: var(ma-variable);
	background-color: var(ma-variable-skinable);
}

Attention à bien déclarer votre feuille de styles 'variables.css' EN PREMIER.

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