Créer une apparence (Skin) sur mesure (pour Plone 1.x) [How-To]

Ceci explique comment construire un nouveau 'look' pour un site Plone. C'est un processus assez simple et la méthode suivante a été conçue pour rendre simple l'application de nouvelles skins pour des sites sur d'autres serveurs en copiant simplement un dossier contenant tous les éléments personnalisés dans le dossier  plone_styles  (voir étape 1 ci-dessous) et en appliquant qq changements dans la ZMI.

Paramétrer une skin personnalisée

1. Créez un nouveau dossier sur le système de fichiers local au serveur concernant les styles Plone, sous Windows ça donne  C:\...\Plone\Data\Products\CMFPlone\skins\plone_styles\
   Pour me rendre la vie plus facile j'ai copié/collé un des dossiers que j'ai renommé. Vous pouvez juste créer un dossier vide et le remplir ensuite avec les fichiers concernés  (voir plus bas).
   (Note du traducteur : dés qu'il faut attaquer le système disque local j'ai un doute sur la propreté de la méthode, toujours est-il que ça marche et qu'il est toujours possible de faire marche arrière)
   
   
2. Après avoir fait un "Refresh" - dans la ZMI allez sur /Plone/portal_skins et cliquez sur l'onglet properties.
   
   
3. Pour ajouter ma nouvelle skin je lui donne un nom, j'ai copié/collé un autre champ contenant les ‘paths’ des layers et donné à la skin le même nom que celui du dossier créé plus haut où la nouvelle skin sera stockée. Si vous voulez supprimer l'une des  skins qui seront accessibles dans les préférences et options de Plone c'est ici que vous devez supprimer les entrées.
   
   
4. Pour tester rapidement les changements, je recommande d'ouvrir le 'Control Panel' de la ZMI dans une nouvelle fenêtre et d'aller ensuite sur  "Product Management" puis CMFPlone. Cliquez sur le bouton "refresh" en haut à droite. Rafraichissez chaque fois que vous voulez voir le résultat des changements effectués. Il faut aussi réactualiser la page dans le navigateur. Vous aurez ainsi une fenêtre réservée à la ZMI que vous pourrez rafraichir quand nécessaire et vers laquelle vous pourrez basculer à tout moment.

   Note. Les changements sur les images - ex le logo etc peut ne pas s'afficher dans le browser sans un rafraichissement complet. Essayez Ctrl-F5 ou videz le cache et faites un rafraichissement normal ...

Custom Style Sheets (CSS) - styles personnalisés

Copiez ploneCustom.css depuis le dossier plone_styles dans votre dossier portal_skins\custom. Vous pouvez personnaliser des éléments contenus dans  plone.css (styles par défaut de Plone) en les incluant dans ce fichier personnalisé (par un bête copier coller du contenu de plone.css dans plonecustom.css)
- les éléments seront d'abord examinés dans ce fichier personnalisé (plonecustom.css). Vous pouver également définir des classes personnalisées que vous pourrez inclure dans vos propres templates. (les changements seront vus après un ZMI/Plone/Refresh.)

Stylesheet_properties.props

De même, si vous ne voulez pas d'ennui après un plantage il vaut mieux copier ce fichier depuis le dossier plone_styles dans votre dossier custom . C'est une autre 'feuille de style' qui concerne les éléments standards contenus dans Plone. Vous noterez que plone.css définit quelques propriétés avec le préfixe &dtml- suivi d'un nom (par exemple: &dtml-mainBackground; ). Ce nom fait référence à une entrée dans le fichier stylesheet_properties où cet élément de  'style' (ex couleur, police etc) est défini. Voilà donc une nouvelle méthode permettant de changer des valeurs dans stylesheet_properties pour appliquer les changements à tous les éléments css définis de cette manière. Il est également possible d'ajouter de nouveaux éléments dans le fichier stylesheet_properties et d'en faire référence dans un fichier css personnalisé en utilisant le préfixe &dtml-nompropriete; .

(Vous devez faire un rafraichissement complet (Ctrl-F5) ou vider votre cache pour voir les résultats des changements sur ce fichier.)

A PARTIR D'ICI CE N'EST PLUS UNE TRADUCTION DU HOWTO
car j'ai amené quelques précisions utiles.

Les paramètres décrits dans le tableau ci-dessous correspondent aux différents champs du style_sheet_properties standard tels qu'ils sont utilisés dans le plone.css standard lui aussi (et éventuellement plonecustom.css ou encore dans n'importe quelle feuille de style css que vous créez). Vous pouvez tout à fait créer votre propre plonecustom.css qui ne ferait pas usage de ces paramètres ou bien les utiliserait d'une autre façon. Le style_sheet_properties permet donc à quelqu'un de modifier tous ces paramètres sans avoir à connaître le codage d'une css. C'est moins puissant que la modification directe du css car toutes les caractéristiques des styles ne sont pas disponibles, cependant ça présente quelques avantages  :
- si on veut utiliser plusieurs skins (apparences) chaque skin possèdera son propre style_sheet_properties.
- une seule propriété de stylesheetproperties peut être utilisée pour modifier plusieurs classes de style en une seule opération.
- vous pouvez, comme pour n'importe quel objet Zope,  ajouter de nouvelles propriétés à la style_sheet_properties, et de cette manière caractériser les différences entre une apparence et une autre ou caractériser ce qui fait la différence entre votre site Plone et celui du voisin.

Ouf !!!

Templates personnalisés

Pour véritablement modifier la mise en page il faudra à un moment ou un autre s'attaquer aux templates et en particulier au main_template situé dans /votresitePlone/portal_skins/plone_templates/ toujours grâce à la ZMI. Vous choisissez main_template et, comme d'habitude, vous cliquez sur "custom".
Plutôt que de seulement traduire le HOWTO qui est un peu timide de ce point de vue (on trouve quand-même la suite plus bas), je vous propose de modifier le main_template et en particulier de corriger un problème soulevé par tous les utilisateurs des sites Plone utilisant le main_template standard  :
Dans le site Plone de base vous remarquerez que si le contenu d'un document est trop large, soit à cause d'une image, ou à cause d'un texte sans espace trop long (lignes de code par exemple), alors la largeur du contenu s'agrandit mais les entêtes et les pieds de page ne suivent pas, et ça fait tout de suite site "amateur", du point de vue graphique j'entends.  Pour éviter ce problème la solution est simple : il faut intégrer les blocs entête et pied de page dans un même tableau. Il y a la solution la plus simple qui consiste à créer un nouveau tableau, mais ça alourdit le code pour rien.
Il suffit en réalité de faire commencer le tableau utilisé pour le contenu, en haut de page (après la balise <body>), de mettre le bloc d'entête dans une ligne(<tr>) comportant une seule colonne (<td colspan="3"> car le contenu central comporte lui 3 colonnes), de faire la même chose pour le bloc pied de page, et de déplacer la balise de fermeture du tableau (</table>) avant la balise </body>.
Vous remarquerez que les balises <tbody> et </tbody> ont également été déplacées avec les balises <table> et </table>, ces balises qui ne servent pas à grand-chose dans le main_template standard de plone me servent ici à créer des marges d'une couleur de fond différente, car j'ai appliqué dans le plone_custom.css une couleur de fond blanc à la page (style body) et une couleur de fond bleu au style tbody, de plus j'ai créé pour la page (<body>) une marge de 10px partout.  Mais si vous voulez que le corps central du site possède des propriétés différentes des entêtes et pied de page vous pouvez placer la balise <tbody> de manière à ce qu'elle encadre seulement les 3 colonnes du corps central du site.  

Assez parlé voici le code source de mon main_template :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml"
      xml:lang="en"
      lang="en"
      metal:define-macro="master"
      tal:define="member here/portal_membership/getAuthenticatedMember;
        portal here/portal_url/getPortalObject;
        global portal_url portal;
        actions python:here.portal_actions.listFilteredActionsFor(here);
        site_properties here/portal_properties/site_properties;
        ztu modules/ZTUtils;
        actions options/actions|actions|nothing;
        obj_actions actions/object;
        wf_actions actions/workflow;
        folder_actions actions/folder;
        local_actions python:actions.get('object_tabs', []);
        isFolder python:test(here.getTypeInfo().getId() in site_properties.use_folder_tabs,1,0);
        template_id options/template_id|template_id|template/getId|nothing;
        slots_mapping options/slots_mapping|here/prepare_slots|nothing;
        Iterator python:modules['Products.CMFPlone'].IndexIterator;
        tabindex python:Iterator(pos=30000);"
      tal:attributes="lang site_properties/default_language|default;
                      xml:lang site_properties/default_language|default;">

<head metal:use-macro="here/header/macros/html_header">
  <metal:block metal:fill-slot="base">
    <metal:block metal:define-slot="base">
       <base href=""
             tal:condition="here/aq_explicit/isPrincipiaFolderish|nothing"
             tal:attributes="href python:here.absolute_url()+'/'" />
       <metal:block tal:condition="not:here/aq_explicit/isPrincipiaFolderish|nothing">
          <base href=""
                tal:define="path python:'/'.join(here.portal_url.getRelativeContentPath(here)[:-1])"
                tal:attributes="href python:here.portal_url()+'/'+path+test(len(path)>0,'/','')" />
       </metal:block>
    </metal:block>
  </metal:block>

  <metal:block fill-slot="head_slot"
               tal:define="language here/Language;
	                   lang python:test(language,
                                            language,
                                            site_properties.default_language);
                           charset site_properties/default_charset|string:utf-8">

    <metal:block tal:define="dummy python:request.RESPONSE.setHeader('Content-Type', 'text/html;;charset=%s' % charset)" />
    <metal:block tal:define="dummy python:request.RESPONSE.setHeader('Content-Language', lang)" />
    <metal:block tal:define="dummy python:request.RESPONSE.setHeader('Expires', 'Sat, 1 Jan 2000 00:00:00 GMT')" />
    <metal:block tal:define="dummy python:request.RESPONSE.setHeader('Pragma', 'no-cache')" />
    <metal:block tal:define="dummy python:request.RESPONSE.setHeader('Last-Modified', DateTime().toZone('GMT').rfc822())" />

    <metal:block define-slot="head_slot" />
  </metal:block>

  <metal:block fill-slot="css_slot">
    <metal:block define-slot="css_slot" />
  </metal:block>

  <metal:block fill-slot="javascript_head_slot">
    <metal:block define-slot="javascript_head_slot" />
  </metal:block>
</head>

<body>
<table class="columns">
    <tbody>
        <tr>
            <td colspan="3" align="left" valign="top">
              <div metal:use-macro="here/header/macros/portal_header">
                Header stuff
              </div>
            </td>
        </tr>
        <tr>
            <td class="left" metal:define-macro="left_column"
	                     tal:define="slots_mapping options/slots_mapping|slots_mapping|nothing;
	                                 site_properties options/site_properties|site_properties|nothing;
	                                 portal_url options/portal_url|portal_url|nothing;
                                         Iterator python:modules['Products.CMFPlone'].IndexIterator;
                                         tabindex python:Iterator(pos=10000);"
	                     tal:condition="slots_mapping/left|nothing">
                <metal:block tal:repeat="slot slots_mapping/left|slots_mapping/left">
                <tal:block tal:define="global pathexpr python:slot[0];
                                       global usemacro python:slot[1]"
                           tal:condition="usemacro">
                    <metal:block metal:use-macro="python:path(pathexpr)" />
                </tal:block>
                <span tal:condition="not: usemacro"
                      tal:replace="structure python:path(pathexpr)" />
                </metal:block>
            </td>
            <td class="main"
                tal:define="global show_border python:here.showEditableBorder( template_id=template_id
                                                                             , actions=actions );
                            Iterator python:modules['Products.CMFPlone'].IndexIterator;
                            tabindex python:Iterator(pos=0);">

                <metal:block define-slot="super"
		             tal:condition="show_border" >

                <div id="contentTabs" metal:define-macro="contentTabs"
	                  tal:define="isFolder options/isFolder|isFolder|nothing;
	                              folder_actions options/folder_actions|folder_actions|nothing;
	                              local_actions options/local_actions|local_actions|nothing;
	                              obj_actions options/obj_actions|obj_actions|nothing;
	                              template_id options/template_id|template_id|nothing"
	                  i18n:domain="plone">

                    <tal:block tal:repeat="action python:test(isFolder, folder_actions+obj_actions+local_actions, obj_actions+local_actions)">
                        <a class="" href=""
                           tal:attributes="class python:test(action['url'][action['url'].rfind('/')+1:]==template_id, 'selected', 'plain');
			                   href action/url;">
                            <span tal:omit-tag="" i18n:translate=""><span tal:replace="action/name">dummy</span></span>
                        </a>
                    </tal:block>

                </div>

                <div id="contentBar">
                &nbsp;
                </div>

                </metal:block>

                <div class="document"
                     tal:attributes="class python:test(show_border, 'editableDocument', 'document')">

                    <div id="content">

                        <metal:block metal:use-macro="here/header/macros/portal_message">
                        Message box
                        </metal:block>

                        <div class="documentActions"
                             metal:define-macro="documentActions"
			     tal:define="portal_url portal_url|here/portal_url">

                            <metal:block define-slot="documentActions"
			                 tal:content="nothing">
                            Document actions slot
                            </metal:block>

                            <a href=""
                               tal:condition="site_properties/allow_sendto | nothing"
                               tal:attributes="href python:'%s/portal_form/sendto_form' % here.absolute_url()">
                                <img i18n:attributes="title" alt="Send to"
                                     tal:attributes="src string:$portal_url/mail_icon.gif"
                                     src="mail_icon.gif" title="Send this page to somebody" />
                            </a>

                            <a href="javascript:this.print();">
                                <img i18n:attributes="title" alt="Print"
                                     tal:attributes="src string:$portal_url/print_icon.gif"
                                     src="print_icon.gif" title="Print this page" />
                            </a>
                        </div>

                        <metal:block metal:define-slot="header" tal:content="nothing">
                        Header slot
                        </metal:block>

                        <metal:block metal:define-slot="main" tal:content="nothing">
                        Page body text
                        </metal:block>

                        <metal:block metal:define-slot="sub">
                        <tal metal:use-macro="here/viewThreadsAtBottom/macros/discussionView" />
                        </metal:block>
                    </div>
                </div>
            </td>

            <td class="right" metal:define-macro="right_column"
	                      tal:define="slots_mapping options/slots_mapping|slots_mapping|nothing;
	                                  portal_url options/portal_url|portal_url|nothing;
                                          Iterator python:modules['Products.CMFPlone'].IndexIterator;
                                          tabindex python:Iterator(pos=20000);"
	                      tal:condition="slots_mapping/right">
                <metal:block tal:repeat="slot slots_mapping/right">
                    <tal:block tal:define="global pathexpr python:slot[0];
                                           global usemacro python:slot[1];"
                               tal:condition="usemacro">
                        <metal:block metal:use-macro="python:path(pathexpr)" />
                    </tal:block>
                    <span tal:condition="not: usemacro"
                          tal:replace="structure python:path(pathexpr)" />
                </metal:block>
            </td>
        </tr>
        <tr>
            <td colspan="3" align="left" valign="top">
              <hr size="" class="netscape4" />
              <div class="footer" metal:use-macro="here/footer/macros/portal_footer">
               Footer
              </div>
            </td>
        </tr>
    </tbody>
</table>
</body>
</html>

Je n'ai pas mis le schéma présenté dans le howto quant à la structure de la page car il manque de clarté.

Voilà ce qui compte pour changer le look d'un site :

1. La struture du template main_template avec ses tableaux, ses blocs inclus dans les tableaux, et ses appels aux autre templates comme le portal_header qui fabrique le bloc d'entête.
   
2. Les balises html du template et leurs correspondances dans la feuille de style plone.css ou plone_custom.css si vous avez personnalisé vos styles. Si je veux un style particulier pour l'ensemble de ma page je changerais dans le plone_custom.css ce qui se trouve entre les accolades pour l'attribut body (body { ...}). Ensuite il peut y avoir soit des attributs de classe s'appliquant seulement à une balise, par exemple "td.pabo {...}" s'appliquera à la balise <td> avec la classe "pabo" et s'écrira donc dans le template <td class="pabo" ...>, soit des attributs de classe écrits simplement ".pabo {...}" et qui s'appliqueront partout où on trouvera la classe (class="pabo"), soit des attributs s'appliquant uniquement à un élément portant un nom (exemple le bloc <div id="monbloc"> ou le tableau <table id="montableau">) et dans ce cas le style s'écrira "#moncalque {...}" ou encore "#montableau {...}" .
3. Le style_sheet_properties qui servira dans le cas d'un site devant être décliné en plusieurs skins et qui permet d'inclure des variations sans avoir à retoucher le style lui-même.

Plone est offert avec toute une batterie d'outils mais il faut cibler leur usage et éviter d'alourdir le temps de fabrication des pages, par conséquent la bonne démarche est sans doute de tout reprendre à zéro avec un main_template tout neuf et d'inclure petit à petit les objets nécessaires.

A PARTIR D'ICI REPRISE DE LA TRADUCTION DU HOWTO

Vous pouvez également vous intéresser aux éléments créés grâce au langage de templating Template Attribute Language (TAL). Il est utilisé pour incorporer des éléments dynamiques dans vos gabarits (templates) personnalisés. Mon intérêt pour cette technique est venue du désir  d'ajouter la date du jour dans un entête personnalisé. N'étant pas programmeur par profession, au départ j'ai trouvé ça très complexe. Ma première étape fut les pages d'aide suivantes  :

http://www.zope.org/Documentation/Articles/ZPT1 et http://www.zope.org/Documentation/Articles/ZPT2

J'ai eu ensuite un bon aperçu de la manière dont fonctionne le calendrier (calendar_slot.pt que l'on trouve sur  C:\...\Plone\Data\Products\CMFPlone\skins\plone_templates\ui_slots) et le module DateTime (DateTime.pt situé sur C:\...\Plone\Zope\lib\python\DateTime).

J'ai utilisé le code suivant pour ajouter la date (svp notez que le tableau (<table> est utilisé pour mes besoins ergonomiques propres et n'est pas utile pour le fonctionnement):

<table tal:define="DateTime python:modules['DateTime'].DateTime; current python:DateTime(); day python:request.get('day', DateTime().Day()); dd python:request.get('dd', DateTime().dd()); month python:request.get('month', DateTime().Month()); year python:request.get('year', DateTime().year());"> <tr> <td> <span tal:replace="string:$day">Monday </span> <span tal:replace="string:$dd">01 </span> <span tal:replace="string:$month">January </span> <span tal:replace="string:$year" >2001</span> </td> </tr> </table>

Andrew R. Halko (de la mailing list des utilisateurs de Plone) m'a suggéré le code suivant plus compact :

<table tal:define="now modules/DateTime/DateTime" > <tr> <td> <span tal:replace="now/%A %d %B %Y">Monday 01 January 2001</span> </td> </tr> </table>

Selon l'article de Zope il semblerait que tal:define ne puisse être utilisé plus d'une fois dans une balise.  Ici j'ai besoin de l'utiliser une fois  seulement (dans le tag TABLE) - c'est utilisé pour importer le module python (DateTime) pour manipuler les dates. Il définit ensuite les éléments du module dont nous aurons besoin - dans ce cas le Jour, dd (le jour en format numérique), le mois et l'année.
Pour insérer ces éléments dans ma page j'ai utilisé les balises <span>, tal:replace et les 'String expressions' (see the section on this in ZPT2). La balise  <span> est juste utilisée comme container pour chaque élément individuel et ne change rien au rendu de la page. Le code tal:replace code est utilisé pour remplacer ce qui se trouve entre les balises <span> et </span> par les éléments dynamiques produits par le module python et supprime également les balises <span>.  Si j'avais voulu garder ces balises j'aurais plutôt utilisé  tal:content.

Pourquoi est-ce pratique ? Le plus grand intérêt de TAL est qu'il ne fout pas en l'air  la manière dont le HTML est affiché dans un éditeur web WYSIWYG comme Dreamweaver.  En effet tous les éléments TAL seront ignorés par l'éditeur WYSIWYG. Ca signifie qu'un designer peut travailler sur le the look de la page sans avoir à se soucier de ce que vont devenir les  contenus dynamiques. Toutefois - Dreamweaver n'a pas accès aux contenus dynamiques (ceux créés avec Zope) donc pour les besoins du design les éléments à l'intérieur des balises <span> sont affichés. Dans ce cas précis le contenu du tableau s'affichera dans l'éditeur wysiwyg " Monday 01 January 2001", tandis que dans mon site il affichera la date.

De même - réactualisez l'écran pour voir le contenu dans Plone.

Encore deux pages qui peuvent valoir le coup pour clarifier le langage TAL:

http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx

http://www.zope.org/Documentation/Books/ZopeBook/current/AdvZPT.stx