illu-blog

Associer des données de configuration à un module Contao personnalisé

Lors de la phase de définition technique d’un projet chez Canal-Web, l’une des premières tâche consiste à déterminer la technologie à employer. Dans une grande majorité de cas, le projet reposera sur un CMS tournant avec PHP.

Lorsque le projet concerné concerne la mise en place d’un site vitrine, ou d’un site dont les aspects e-commerce sont minimes, notre choix se tournera souvent vers Contao, même s’il est possible de réaliser des projets beaucoup plus ambitieux avec ce CMS que nous apprécions particulièrement. Son utilisation fréquente par nos équipes depuis plusieurs années nous a permis au fil du temps d’obtenir une vraie expertise sur ses qualités et ses défauts.

Bien que conscient des nombreuses avantages de Contao, un point lui fait souvent défaut, sa documentation. Qu’elle soit officielle ou située sur des forums. Une fois les mains plongées dans le « cambouis », lors de la création d’un module par exemple, il est parfois difficile de trouver la solution à un problème complexe. Le projet étant originellement Allemand, les principaux échanges techniques sont souvent produits dans la langue de Goethe, ce qui limite grandement la propagation de savoir-faire dans l’hexagone.  Je tiens à préciser que ce problème n’en est pas un pour les débutants et non-programmeurs. La documentation est parfaitement traduite à ce jour et permettra aux nouveaux arrivants de prendre en main l’outil sans mal.

Cette introduction ayant pour objectif de vous mettre dans le contexte – Contao souffre d’un manque de documentation en ce qui concerne l’utilisation de son API et nous essayerons à travers ce blog, entre autres, de mettre en lumière certains points obscurs – nous pouvons donc maintenant nous plonger dans le sujet à traiter, la gestion de données de configuration.

Afin d’illustrer ce tutoriel, imaginons que nous somme en train de réaliser un module de gestion d’actualités (que nous appellerons NewsPaper, parce que ça fait classe). Une fois le module installé et une liste conséquente de news produite, je souhaite limiter le nombre d’articles à afficher. Pour ce faire, je vais utiliser le système de configuration global de Contao.

Configuration depuis le code

La méthode la plus simple pour définir cette limite consiste à stocker l’information dans le fichier config.php de notre module (le ficher doit être accessible par ce chemin : NewsPaper/config/config.php). Voici un exemple de définition et d’utilisation de données de configuration :

<br />
  //Définition de l'option</p>
<p>  $GLOBALS['TL_CONFIG']['liste_limite'] = 5;<br />
  //...<br />

 

<br />
  //Utilisation de l'option</p>
<p>  $limite = $GLOBALS['TL_CONFIG']['liste_limite'];</p>
<p>  echo 'Voici les ' . $limite . ' dernières actualités.';<br />
  //...<br />

Si vous êtes familier avec PHP et que vous avez déjà eu affaire aux variables globales,vous avez surement déjà compris comment Contao gère ses données de configuration. Si cela ne vous parle pas et que vous voulez comprendre ce qu’il se passe, je vous conseil de vous rendre sur la page du manuel PHP.

Je ne m’attarderais pas sur la structure de fichiers du supposé module, partant du principe que les personnes intéressées auront déjà prit connaissance des pratiques et conventions utilisées lors de la création d’un module sur Contao (pour les autres, lisez ceci).

Configuration depuis formulaire

À l’heure actuelle, il est possible de modifier la variable liste_limite depuis le fichier où elle a été définie, mais il faut avouer que cela n’est pas très user-friendly. Imaginez qu’il vous viennent un jour l’idée de partager votre travail avec des utilisateurs moins expérimentés, proposer une belle interface utilisateur serait du plus bel effet. Et cela ne devrait pas être trop difficile avec Contao ;).

Nous allons maintenant créer notre champ en l’implémentant directement sur le formulaire de configuration global. Ce formulaire est défini depuis les DCA (Data Container Arrays) sous le nom de tl_settings.

<br />
//Définition de la palette<br />
$GLOBALS['TL_DCA']['tl_settings']['palettes']['default'] .= ';{newspaper},newspaper_limite';</p>
<p>//Définition du champ<br />
$GLOBALS['TL_DCA']['tl_settings']['fields']['newspaper_limite'] = array<br />
(<br />
	'label'                   => array('Nombre d\'articles à afficher', 'Renseigner le nombre d\'articles à afficher dans la liste des actualités.'),<br />
	'inputType'               => 'text',<br />
	'eval'                    => array('mandatory' => true, 'rgxp' => 'digit', 'tl_class' => 'w50'),<br />
);<br />

Détaillons le code ci-dessus ligne par ligne.

$GLOBALS['TL_DCA']['tl_settings']['palettes']['default'] .= ';{newspaper},newspaper_limite';

En premier lieu, nous créons un nouveau groupe de champs, ou palette dans le jargon de Contao. Cette dernière est définie par le terme se trouvant entre accolades. On indique ensuite que la palette contient un champ appelé newspaper_limite.

Vous aurez peut-être remarqué le point-virgule au début de la chaîne de caractères. Cela indique à Contao que la palette précédente est complète, ce qui nous permet de commencer la nôtre en fin de formulaire. En effet, l’élément de tableau ['default'] contient déjà toutes les autres palettes initialisées avant que notre module ai été chargé. Nous utilisons la concaténation afin d’ajouter la nôtre à la chaîne de caractères existante.

$GLOBALS['TL_DCA']['tl_settings']['fields']['newspaper_limite'] = array

Le champ à précédemment été défini comme appartenant à la palette newspaper, mais Contao attend de notre part que nous lui précisions la nature du champ via un tableau associatif accessible via la clé newspaper_limite. Tout cela situé dans $GLOBALS['TL_DCA']['tl_settings']['fields'].

'label'                   => array('Nombre d\'articles à afficher', 'Renseigner le nombre d\'articles à afficher dans la liste des actualités.'),

Les premières données que nous passons sont le label et la description du champ. Contao considère le premier élément du tableau comme l’intitulé du champ, le second affichera une description en dessous de l’input mais il est pas obligatoire d’en renseigner une.

'inputType'               => 'text',

Le type du champ est définis ici, dans ce cas la nous n’afficherons qu’un simple input de type text. Si vous voulez connaitre tous les choix qui sont à votre disposition, consultez les options de champs à la ligne inputType.

'eval'                    => array('mandatory' => true, 'rgxp' => 'digit', 'tl_class' => 'w50'),

Arrive la dernière donnée à passer eval, qui est facultative. Dans l’ordre, j’ai indiqué que le champ serait obligatoire, composé seulement de chiffres et ne prendrait que la moitié de l’espace disponible à l’écran.
En ce qui concerne la dernière option tl_class, l’utilisation de la classe w50 est courante car cela permet de réduire l’encombrement du champ et donc de pouvoir placer deux champs sur la même ligne.
Comme je l’ai indiqué, le champ n’acceptera que les caractères numériques (et le point pour les décimaux). Si vous désirez appliquer d’autres validations de données, consultez le tableau d’évaluation de champs à la ligne rgxp.

Contao est prêt à afficher notre champ mais j’aimerais apporter une dernière amélioration :

<br />
$GLOBALS['TL_DCA']['tl_settings']['fields']['newspaper_limite'] = array<br />
(<br />
	'label'                   => &$GLOBALS['TL_LANG']['tl_settings']['newspaper_limite'],<br />
	'inputType'               => 'text',<br />
	'eval'                    => array('mandatory' => true, 'rgxp' => 'digit', 'tl_class' => 'w50'),<br />
);<br />

Il serait dommage de ne pas profiter du support multilingue que fournir Contao, j’ai donc modifié la définition du label et de la description en faisant appel au fichier de langue de mon module. Une fois le fichier tl_setting.php modifié, il nous faut créer un fichier du même nom dans le dossier stockant les fichiers de traduction française. Cela se situe dans NewsPaper/languages/fr/.

<br />
$GLOBALS['TL_LANG']['tl_settings']['newspaper_limite'] = array('Nombre d\'articles à afficher', 'Renseigner le nombre d\'articles à afficher dans la liste des actualités.');<br />

Et hop! Le module est maintenant disponible en français et prêt à être traduit si besoins est.

Les valeurs par défaut

Si vous bidouillez votre code tout en lisant cet article, vous aurez peut-être remarqué que les données de configuration renseignées dans le fichier config.php font automatiquement office de valeurs par défaut pour les champs que vous ajoutez au formulaire de configuration. Il suffit que les deux noms soient les mêmes pour que Contao fasse la correspondance. C’est ce que nous avons fait dans notre exemple, l’option de configuration stockée dans TL_CONFIG et le champ définis dans le formulaire tl_settings se nomment tous les deux liste_limite.

Une fois que l’option de configuration a été mise à jour via le formulaire, la valeur par défaut est surchargée. Toutes les options surchargées sont stockées dans le fichier localconfig.php situé dans system/config/ en partant de la racine de votre instance.
Pour réinitialiser l’option et utiliser à nouveau la valeur par défaut, il faudra supprimer la ligne correspondante dans le fichier localconfig.php.

Configuration hors module

Dernière chose : il est possible de réaliser tout cela hors de la structure d’un module. Cela n’est pas très utile étant donné que si vous vous donnez le mal de mettre en place des données de configuration, ce n’est pas pour faire le travail à moitié mais cela vaut le coup de savoir que ça existe !

Pour ce faire, il suffit de remplacer tous les fichiers que nous venons d’utiliser par leurs substituts présents dans le même dossier que localconfig.php, c’est à dire system/config/.

La définition des valeurs par défaut se fera par le biais de localconfig.php, toutes les valeurs devront êtres placées avant la ligne ### INSTALL SCRIPT START ### afin de ne pas êtres effacées par Contao lors de la soumission du formulaire de configuration (qui provoque une réécriture automatique du document).

Les palettes et champs auparavant renseignés dans le fichier tl_settings.php (situé dans le dossier dca/ à la racine du module) seront spécifiés à l’aide de dcaconfig.php.

Enfin, les données de traduction seront déplacées dans le fichier langconfig.php. Puisque que c’est ici que prendront place les labels et description de toutes les langues que vous souhaitez mettre à disposition, il faudra les différencier lors de leur définition. Voici comment procéder :

<br />
switch ($GLOBALS['TL_LANGUAGE'])<br />
{<br />
	case 'fr':<br />
		$GLOBALS['TL_LANG']['tl_settings']['newspaper_limite'] = array('Nombre d\'articles à afficher', 'Renseigner le nombre d\'articles à afficher dans la liste des actualités.');<br />
		break;<br />
	case 'en':<br />
		$GLOBALS['TL_LANG']['tl_settings']['newspaper_limite'] = array('Limit of articles to show', 'Defines how many articles will be shown on the list.');<br />
		break;<br />
}<br />

Cela aura pour effet de définir les labels et autres descriptions par rapport à la langue de l’utilisateur au moment de l’initialisation de Contao.


Vous pouvez retrouver tous les fichiers cités dans cet article en téléchargeant cette archive.

Notez cet article

A propos de Peeter Rannou

Peeter est un développeur passionné employé chez Canal-Web depuis maintenant plus de 4 ans. Très actif dans le monde de l'Open Source, il contribue à de nombreux projets sur le web. Suivez son activité sur Twitter via le compte @thedotwriter.

Laissez un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *


Vous pouvez utiliser ces balises et attributs HTML : <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>