<!doctype linuxdoc system>
<linuxdoc>
 <article>
  <titlepag>
   <title>Documentation daCode&nbsp;: Thèmes et templates</title>
   <author>
    <name>Denis Barbier, <tt/barbier@imacs.polytechnique.fr/</name>
    <and>
    <name> Virginie Vacca, <tt/vvirginie@free.fr/</name>
   </author>
   <date>Mars 2001</date>
   <abstract>Ce document décrit de manière succincte l'utilisation des
   templates dans daCode et la manière de les créer, en vue d'obtenir un
   site thémable.
   </abstract>
  </titlepag>

  <sect>
   <heading>Écriture de thèmes</heading>
   <p></p>
   <sect1>
    <heading>Principe des templates</heading>
    <p>Le principe des templates consiste à dissocier l'architecture du
     site (affichage, positionnement des boîtes) de son contenu et de
     sa mise en forme. Ils permettent ainsi de préserver l'homogénéité
     du site et d'en personnaliser l'affichage sans avoir à retoucher
     le code HTML.
   </p>

   </sect1>

   <sect1>
    <heading>Écriture de templates</heading>
    <p>Les templates mélangent du code HTML, des commentaires (lignes
    commençant par un signe dièse «&nbsp;&num;&nbsp;»), et des
    instructions PHP exécutées par daCode. Celles-ci sont de la
    forme&nbsp;:
    <verb> 
      <!-- daCode: expression -->
     </verb>
   où «&nbsp;expression&nbsp;» est une expression PHP qui doit retourner
   le texte à intégrer à la place de cette ligne. Ces instructions doivent
   tenir sur une ligne.
   <tscreen><verb>
     <!-- daCode: $html->header('Exemple') -->
     <table border="0" cellpadding="3" cellspacing="3" width="100%">
     <tr><td valign="top" width="100" rowspan="2">
     <!-- daCode: $sidebox->dacode() -->
     &lt;/td&gt;<td valign="top" width="80%">
     <!-- daCode: $news->show_news(10,$section,$topic,1,1,$news_id) -->
     &lt;/td&gt;
     &lt;/table&gt;
     <!-- daCode: $html->footer() -->
     </verb></tscreen>
    La première ligne, par exemple, fait appel à la fonction header
    définie dans le fichier
    <tt>src/phplip/themes/&lt;theme&gt;/html.php3</tt>, auquel fait appel
    la classe Html, définie dans <tt>src/phplib/html.php3</tt>. header()
    prend ici en argument le titre de la page, "exemple". 
   </p>
   </sect1>

   <sect1>
    <heading>Utilisation de templates</heading>
    <p></p>
 
    <sect2>
     <heading>Modifier l'affichage des fonctions de daCode</heading>
    <p>Nous allons reprendre l'exemple précédent, que nous nommerons
    "test.tmpl", et l'appeler dans notre page test.php3. Pour créer cette
    page, inspirons-nous par exemple, en l'adaptant, de
    src/htdocs/poll/index.php3&nbsp;:
     <tscreen><verb>
     <?
         //  En-tête commun à tous les scripts de daCode
         $topdir = '..';
         require $topdir."/dacode.php3";

         //  Instances de classes utilisées dans test.tmpl
         $html = LoadClass('Html');
         $sidebox = LoadClass('Sidebox');
         $news = LoadClass('News');

         //  Composition de la page
         $html->parsetemplate('test.tmpl');
      ?>

      </verb></tscreen>
   Il faut définir toutes les variables qui apparaissent dans le
   template. Donc dans cet exemple, les variables $topic et $news_id
   seront vides.
   De même, il faut s'assurer que toutes les variables sont déclarées
   comme globales dans la fonction parsetemplate du fichier
   phplib/html.php3.</p>
    </sect2>

    <sect2>
     <heading>Créer ses propres pages statiques</heading>
     <p>Il suffit pour celà de récupérer le template basic.tmpl
      disponible dans le thème linuxfr et de l'adapter, par exemple, de
      la façon suivante&nbsp;:
     <tscreen><verb>
	<!-- daCode: $html->header($title) -->
       <table align="center" width="80%" border="0">
       <tr>
       <td class="bodytext">
	<!-- daCode: $text -->
	&lt;/td&gt;
	&lt;/tr&gt;
	&lt;/table&gt;
	<!-- daCode: $html->footer() -->
       </verb></tscreen>
   
     Pour l'appeler (appelons-le static.tmpl), il suffira de prodéder
     comme décrit plus haut, mais en définissant cette fois les valeurs de
     $text et $title&nbsp;:

      <tscreen><verb>
       <?
        $topdir = '.';
        require $topdir."/dacode.php3";

        $html = LoadClass('Html');
        $sidebox = LoadClass('Sidebox');
	$title="Ma belle page";
        $text ="mon texte...avec des caractères échappés \ devant
	chaque guillemet";
	$html->parsetemplate('static.tmpl');
       ?>
	
       </verb></tscreen>
    </p>
    </sect2>

   </sect1>

   <sect1>
    <heading>Création d'un nouveau thème</heading>
    <p></p>
    <sect2>
     <heading>Copie d'un thème existant, et personnalisation des
     templates</heading> 
     
     <p>À partir des informations de la section précédente, on se rend
     compte qu'il est très simple de créer un nouveau thème. Les templates
     sont dans le répertoire <tt>phplib/themes/&lt;nom_du_theme&gt;</tt>.
     Si on veut créer un thème « print », on commence par  recopier un
     thème existant, par exemple celui de daweb&nbsp;:

     <verb>cp -R phplib/themes/daweb phplib/themes/print</verb>
     Puis on modifie les fichiers *.tmpl pour modifier la mise en
     page.</p>
    </sect2>

    <sect2>
     <heading>Personnaliser son thème&nbsp;: styles et images</heading>
    
    <p>Une fois les boîtes positionnées à l'aide des templates, il
     suffit de modifier <tt>phplib/themes/print/html.php3</tt>, qui
     contient les header, footer et autres propriétés du document,
     telles que les styles ou les images. Pour personnaliser&nbsp;:
     <itemize>
      <item>les styles&nbsp;: mettre sa nouvelle feuille de
	style dans <tt>htdocs/themes/print/</tt>. Les styles appelés
	(attribut class="") sont modifiables directement dans le
	html.php3&nbsp;;</item>
      <item>les logos et images&nbsp;: ceux-ci sont appelés sous la
	forme <tt>$this->session->imgurl('image')</tt>, où image est
	un fichier au format png que daCode cherchera dans
	<tt>htdocs/themes/print/images/</tt>, en priorité, ou dans
	htdocs/images. Le premier emplacement est vivement recommandé
	si vous souhaitez ensuite pouvoir constituer une archive de
	votre thème. Cf Section <ref id="partage-theme" name="Partager
	 ses thèmes">.</item>
      <item>Les images de Topics&nbsp;: vous voudrez sans doute
	modifier le fond des images actuelles ou créer les vôtres. Pour
       les mêmes raisons que ci-dessus, il est recommandé de les
	placer dans
	<tt>htdocs/themes/print/images/section</tt>. Passer ensuite
	par l'interface graphique d'administration ("gestion des
	topics") pour en définir de nouveaux.</item>
      </itemize>
     </p>
    </sect2>

    <sect2>
     <heading>Appeler son nouveau thème</heading>
    
    <p>Enfin, il faut aussi modifier le fichier config.php3 pour ajouter
   ce nouveau thème :
    <verb>$this->listofthemes = array('linuxfr','slashdot', 'daweb',
     'print');</verb>
    Et, si l'on souhaite en faire le thème par défaut de son site&nbsp;:
      <verb>$this->dft_prefs = array ("theme" => 3 );</verb>
      Où 3 correspond à l'emplacement du thème dans la liste définie
      ci-dessus (numérotée de 0 à n)
    </p>
    </sect2>
   </sect1>
  </sect>

  <sect>
   <heading>Partager ses thèmes<label id="partage-theme"></heading>
   <p></p>
   <sect1>
    <heading>Création d'une archive</heading>
    
    <p>Une fois qu'on a mis au point son nouveau thème, on peut vouloir en
    faire profiter les autres. La méthode est très simple : il suffit de
    définir dans le fichier de configuration
    <tt>src/phplib/config.php3</tt> la variable
    <tt>$this->create_tar_dir</tt> contenant le nom d'un répertoire dans
    lequel PHP peut écrire, d'utiliser son compte d'administrateur sur sa
    version de daCode, et de cliquer sur les « Thèmes » de la boîte
    d'administration. La page suivante montre la liste des thèmes
    actuellement installés, et cliquer sur un lien produit une
    archive.</p>
   
   <p>Par exemple, si <tt>$this->create_tar_dir</tt> vaut <tt>"/tmp/"</tt>
   et que le thème s'appelle "print", le fichier
   <tt>/tmp/daCode-print-0.1.tar.gz</tt> est créé. Le numéro de version
   est pris dans le fichier <tt>src/phplib/themes/print/VERSION</tt> comme
   expliqué ci-dessous.</p>

   </sect1>

   <sect1>
    <heading>Contenu de l'archive</heading>
    <p>Voici par exemple quel pourrait être le contenu de l'archive du
   thème « print » :

     <tscreen><verb>
daCode-print-0.1.1
|-- html
|   |-- images
|   |   |-- image1.png
|   |   |-- image2.png
|   |   |-- logoprint.png
|   |   |-- section
|   |   |   |-- dacode.png
|   |   |   |-- topic1.png
|   |   |   `-- topic2.png
|   |   `-- text-plain.png
|   `-- print.css
`-- templates
    |-- VERSION
    |-- admin.tmpl
    |-- basic.tmpl
    |-- board.tmpl
    |-- doc.tmpl
    |-- html.php3
    |-- myposts.tmpl
    |-- news.tmpl
    |-- newsindex.tmpl
    |-- newssection.tmpl
    |-- poll.tmpl
    |-- search.tmpl
    |-- submit.tmpl
    |-- submitcom.tmpl
    |-- submitpoll.tmpl
    |-- thread.tmpl
    |-- users.tmpl
    `-- webcam.tmpl

      </verb></tscreen></p>
    <p>Le fichier daCode-print-0.1/templates/VERSION est composé des trois
    lignes suivantes:
     <tscreen><verb>
       1
       print
       0.1
      </verb></tscreen>
   </p>
    <p>Il s'agit tout simplement du nom du thème, et du numéro de
   version, la première ligne indiquant le numéro du format utilisé
   (actuellement seule la valeur 1 est reconnue par daCode).  Ce
   fichier est nécessaire pour créer ou extraire les archives avec
   l'interface de daCode.</p>

    <p>Comme on le voit, il est facile de créer cette archive à la main,
   sans utiliser daCode. Il faut mettre les templates dans un
   sous-répertoire templates/, y ajouter un fichier VERSION contenant
   le nom et le numéro de version du thème, et mettre sous html/ les
   fichiers qui sont sous src/htdocs/themes/print/.</p>

   </sect1>

   <sect1>
    <heading>Proposer un thème à un serveur daCode</heading>
    <p>Cette partie n'est pas encore écrite dans daCode, il suffit
   d'ajouter une page permettant à l'internaute d'uploader son
   archive.
   Cette archive sera mise dans le répertoire défini dans la variable
   <verb>$this->upload_tar_dir</verb> du fichier de configuration.</p>
    <p>Vous pouvez également, si vous le souhaitez, soumettre
     directement ce thème au site officiel de daCode</p>
   </sect1>

   <sect1>
    <heading>Installer un nouveau thème</heading>
    <p>Quand un internaute propose un thème, ou quand on met une archive
    dans le répertoire défini dans la variable $this->upload_tar_dir du
    fichier de configuration, l'administrateur du serveur daCode peut
    installer ce nouveau thème.  Pour cela, il doit cliquer sur le même
    lien « Thèmes » de la boîte d'administration. La page suivante montre
    la liste des thèmes actuellement installés, ainsi que les archives
    prêtes à installer.  
    En cliquant sur une de ces archives, une nouvelle
    page apparait qui donne la liste des fichiers contenus dans l'archive,
    ainsi que l'endroit où ils seront placés. On peut visualiser le
    contenu des fichiers en cliquant sur le nom du fichier.  Après avoir
    vérifié le contenu des fichiers, l'administrateur peut choisir
    d'installer ce thème en cliquant sur "installer", et/ou d'effacer
    l'archive.</p>
    
    <p>Cette procédure automatique installe les fichiers au bon endroit,
    même si les répertoires htdocs/ ou phplib/ ont été renommés ou
    déplacés.</p>
    
    <p>Il faut que PHP ait le droit d'écrire dans les répertoires
    <tt>src/htdocs/themes/</tt> et <tt>src/phplib/themes/</tt> pour
    extraire les fichiers.  
    Afin de ne pas mettre ces répertoires en écriture pour PHP, il est
    préférable de donner dans la variable <tt>$this->theme_subdir</tt> le
    nom d'un sous-répertoire, qui, lui, sera le seul à être accessible en
    écriture par PHP.  
    Ainsi, si <tt>$this->theme_subdir="contrib/"</tt>, l'administrateur
    doit créer les répertoires src/htdocs/themes/contrib/ et
    src/phplib/themes/contrib/ et les mettre en écriture pour PHP.</p>  
    
    <p>Le thème "print" sera alors désarchivé dans les répertoires
    <tt>src/htdocs/themes/contrib/print/</tt> et
    <tt>src/phplib/themes/contrib/print/</tt></p>
   
   <p>Enfin, pour que ce thème puisse être utilisé, il faut ajouter ce
   thème dans la variable <tt>$this->listofthemes</tt> du fichier de
   configuration, comme nous l'avons vu plus haut.</p>
   </sect1>
  </sect>

 </article>
</linuxdoc>
