Date de publication: le jeudi 23 octobre 2008 à 19h44
Dernière modification: par Pascal BOYER le mercredi 8 décembre 2010 à 16h03
« Article précédent: eZ Publish : un workflow pour plusieurs événements
» Article suivant: eZ Publish : configurer le moteur de recherche

Objectif

Ce chapitre détaille la gestion des Barres d'outils. Nous ne passerons pas en revue tous les outils préexistants, c'est à dire disponibles consécutivement à l'installation de eZ publish 4.0.1. Cependant vous apprendrez tout ce qu'il est nécessaire de savoir sur les outils pour les mettre en œuvre, en créer de nouveaux et vous familiariserez avec le système des options afférentes.

1 - Définitions

Les outils proposés par eZ publish 4.0.1 sont des fonctionnalités « clés en main » que vous pouvez mettre en place à partir de l'interface d'administration, choisissant ou non de les faire apparaître sur votre site public. Ils se présentent généralement sous la forme de petites « boîtes » indépendantes et disposent d'une couche de gestion intégrée au gestionnaire de contenus rendant leur déploiement et leur administration agréable et modulaire. La figure 3 illustre un exemple de mise en œuvre d'outils sur les pages publiques d'un site.

Ces outils rendent votre site dynamique et permettent bien souvent une interaction avec les visiteurs.

2 - Les outils par défaut

2.1 - Description des outils

Au nombre de 13, ces outils sont:

• basket: affiche un « panier » d'achat pour les sites de commerce en ligne,
• best_seller: affiche les « meilleures ventes » de produits,
• calendar: affiche un calendrier si l'objet affiché sur le site est un objet d'une des classes définies en option,
• create_object: cet outil permet l'édition directe d'objets, sous réserve que l'utilisateur dispose des droits nécessaires.
• drafts: affiche la liste des brouillons en cours d'édition. Cet outil est complémentaire à l'outil create_object.
• link: affiche un lien hypertexte vers le site de votre choix,
• login: affiche une boîte de connexion pour accéder aux espaces privés du site,
• node_list: affiche, en fonction d'un des sept critères de sélection possibles, une liste de x objets,
• notification: affiche un lien pointant vers la page de gestion des notifications de mise à jour des contenus,
• preferred_currency: permet de choisir la monnaie utilisée pour l'affichage des prix des produits,
• searchbox: affiche un champ « Recherche »,
• user_country: permet d'appliquer la T.V.A en vigueur dans le pays sélectionné,
• users: affiche en temps réel le nombre de visiteurs connectés au site (anonymes et authentifiés).

2.2 - Emplacements et modes d'affichage des outils

Vous pouvez disposer les outils sur les espaces prévus à cet effet dans la mise en page standard. Par défaut, trois emplacements différents sont disponibles:

• top: en haut des pages du site public,
• right: à droite des pages du site public,
• bottom: au bas des pages du site public.

Le schéma ci-dessous présente les trois emplacements possibles pour les outils:

Fig. 1 - Emplacement par défaut prévu pour les outils

2.2.1 - Emplacements top et bottom et mode line

Le système eZ publish associe, de manière générale, le processus d'affichage des objets à un mode de visualisation. Aux emplacements top et bottom est ainsi associé le mode d'affichage line (en ligne). Il s'agit d'un affichage linéaire minimaliste permettant de ne pas détériorer outre mesure la mise en page du site.

En effet, tous les outils placés en haut des pages (emplacement top) seront affichés au-dessus du menu du site, ce dernier se trouvant décalé vers le bas au fur et à mesure que des outils sont ajoutés.

De même, les outils placés au bas des pages (emplacement bottom) seront affichés sous les contenus (articles, news, etc...) et au-dessus du pied de page. Pour ces deux emplacements les outils sont affichés horizontalement, les uns à la suite des autres et de droite à gauche.

Si le contenu d'un outil se fait sur plusieurs lignes dans le mode full, alors il sera affiché sur une seule ligne en mode line et de gauche à droite (voir figure 2 ci-dessous).

Tous les outils ne possèdent pas un template d'affichage en mode line. C'est le cas des outils suivants:

• best_seller
• calendar
• create_object
• drafts
• preferred_currency

Bien sûr, rien ne s'oppose à ce que vous créiez vos propres templates d'affichage en mode line pour les outils n'en possédant pas par défaut.

La figure ci-après illustre l'affichage en mode line de l'outil node_list (ligne Latest items) au bas des pages (emplacement bottom):

Fig. 2 - Affichage en position bottom et en mode line de l'outil node_list

2.2.2 Emplacement right et mode full

A l'emplacement right correspond le mode d'affichage full (plein) offrant un affichage plus complet et détaillé de l'outil et de son contenu. La figure ci-dessous présente les deux modes d'affichage line et full des deux outils searchbox et login en fonction de l'emplacement d'affichage.

• La zone supérieure vert pâle correspond à l'emplacement top et au mode d'affichage line.
• La zone latérale rose pâle correspond à l'emplacement right et au mode d'affichage full.
• La zone inférieure mauve correspond à l'emplacement bottom et au mode d'affichage line.

Fig. 3 - Affichage de 4 outils: 1 en zone verte ( top), 2 en zone rose ( right) et 1 en zone mauve ( bottom)

2.3 Interface de gestion des outils

L'interface de gestion des outils est accessible à partir de l'onglet design de l'interface d'administration. Après avoir activé cet onglet, vous obtenez l'affichage suivant:

Fig. 4 - Page d'accueil de l'onglet Design de l'interface d'administration

Dans le menu gauche Design, sélectionnez l'option Gestion des barres d'outils puis sélectionnez, dans le menu déroulant SiteAccess: du cadre Gestion des barres d'outils, le siteaccess public de votre site. N'oubliez pas de valider le choix de votre siteaccess avec le bouton Positionner.

Il ne vous reste plus qu'à choisir dans le cadre Barres d'outils disponibles pour le siteaccess < xxx > l'emplacement ( top, right ou bottom) dont vous souhaitez gérer les outils.

Si vous sélectionnez un emplacement contenant déjà des outils, alors ceux-ci s'afficheront ainsi que l'ensemble des valeurs de leurs options. C'est ce qu'illustre la figure ci-dessous:

Fig. 5 - Interface de gestion des outils. Il s'agit ici de l'interface liée à la position right.

A partir de la page illustrée par la figure 5, et quel que soit l'emplacement sélectionné ( top, right ou bottom), vous pouvez:

• connaître le nom de chacun des outils actuellement positionnés,

• visualiser, grâce à la vignette placée sous le nom de l'outil, l'apparence générale de ce dernier lorsqu'il est affiché sur les pages publiques de votre site. Notez que la vignette diffère selon que le mode d'affichage de l'outil est line ou full,

• supprimer un ou plusieurs outils en cochant les cases situées à gauche des noms des outils puis en cliquant sur le bouton Supprimer la sélection. Il n'est pas nécessaire de recourir au bouton Appliquer les changements pour que l'action sur le bouton Supprimer la sélection soit effective sur le site public,

• ajouter un par un autant d'outils que vous le désirez en les sélectionnant dans le menu déroulant placé sous le bouton Supprimer la sélection puis en validant votre choix avec le bouton Ajouter un outil. Pour qu'un outil soit effectivement affiché sur les pages du site public, vous devez cliquer sur le bouton Appliquer les changements. Ce menu déroulant sera dénommé menu sélection d'outils dans la suite du document.

• ajuster l'ordre d'affichage des outils sur les pages publiques de votre site grâce aux champs positionnées à l'extrême droite des noms des outils. L'ordre que vous définissez prendra effet sur le site public en cliquant simplement sur le bouton Mettre à jour les priorités. L'ordre des outils sera alors également modifié dans la page de gestion des outils,

• modifier les valeurs des options des outils,

• revenir à la gestion des barres des outils (figure 4) en cliquant sur le bouton Retour aux barres d'outils.

Le nombre d'outils qu'il est possible d'afficher est illimité et un même outil peut être affiché plusieurs fois. Par exemple, l'outil link ne permet d'afficher qu'un seul lien. Il sera donc nécessaire d'afficher autant de fois cet outil que vous désirez présenter de liens aux visiteurs de votre site.

2.4 Options des outils

Bien que tous les outils ne possèdent pas forcément d'option (on peut également parler de paramètres des outils ou de degrés de liberté), voici les options des outils par défaut que vous pouvez être amenés à paramétrer:

• Item source: vous permet de choisir, grâce au bouton Parcourir, le nœud dont vous souhaitez afficher les éléments. Par défaut, ce sont les objets du nœud racine du système qui seront affichés. Ceci vous est indiqué par un 2 entre parenthèses. 2 représente l'identifiant du nœud racine du système. Notez (voir figure 5) que l'icône relatif à la classe d'objets auquel appartient le nœud 2 est également affiché (l'icône qui suit le terme Item source et précède eZ publish (2) ). Sur la figure 5 cet icône est celui de la classe d'objets par défaut folder.

• Title: ce champ vous permet de donner un nom à l'outil tel que vous désirez qu'il soit nommé sur les pages publiques de votre site. Une valeur par défaut est toujours proposée (par exemple Latest items dans le cas de l'outil node_list).

• Show in subtree: cette option, que l'on pourrait traduire par « Où dois-je montrer l'outil ? », sert à déterminer, grâce au bouton Parcourir, dans quelle partie du site vous souhaitez que s'affiche l'outil. Par défaut, il n'y a pas de valeur affectée à cette option, si bien que l'outil ne sera pas affiché. Cette option vous permet, par exemple, de n'afficher les 5 derniers sujets du forum que lorsque le visiteur se rend dans la partie forum de votre site. Ou encore, d'afficher dans toutes les parties de votre site, hormis dans la rubrique galerie, les 3 dernières images insérées à votre galerie,

• Number of items: ici, vous précisez combien d'objets vous désirez afficher. Par exemple, si vous destinez l'outil node_list à afficher les 4 dernières photos de votre galerie de photos, alors inscrivez 4 dans ce champ.

• Sort on attribute: permet de définir le critère de tri des objets à afficher. Les critères possibles sont:
  
  • published: c'est la date de publication des objets à afficher qui est prise comme critère de tri.
  • priority: le critère de tri est le niveau de priorité affecté aux objets.
  • name: le critère de tri est le nom des objets.
  • modified: le critère de tri est la date de dernière modification des objets.
  • depth: le critère de tri est la profondeur de l'objet dans l'arborescence. Les objets dont la profondeur est la plus importante seront affichés en premier.
  • class_name: le critère de tri des objets est le nom de la classe dont ils sont un objet.
  • class_identifier: le critère de tri des objets est l'identifiant de la classe dont ils sont un objet.

• Fetch whole tree?: permet de définir si vous souhaitez que les objets soient trouvés en parcourant toute la profondeur de l'arborescence ou simplement dans le premier sous-niveau. Retenez que la racine de l'arbre à parcourir est définie par Item source.

• Show only classes: cette option de l'outil calendar vous permet de déterminer une ou plusieurs classes d'objets. Le calendrier ne s'affichera que lorsqu'un objet instancié par une des classes sélectionnées sera affiché sur le site public.

• Where to place: avec cette option de l'outil create_object vous définissez le nœud qui devra contenir l'objet créé par le visiteur.

• Type: cette option de l'outil create_object permet de définir la classe dont l'objet créé sera une instance.

• Location: cette option de l'outil link permet de spécifier l'URI d'un site.

• Display text: cette option de l'outil link permet de définir le nom du lien qui sera affiché et qui pointera vers le site dont vous avez spécifié l'adresse dans le champ Location.

• Product list: cette option de l'outil best_seller permet de définir le nœud contenant la liste des produits dont il faudra extraire ceux correspondant aux meilleures ventes.

2.5 Les templates et fichiers relatifs aux outils

Le gestionnaire d'outil manipule, en toute transparence pour l'utilisateur, des « notions » qu'il n'est nullement nécessaire de maîtriser pour une utilisation basique des outils. Cependant, dès lors que vous envisagez d'en créer de nouveau, il devient indispensable de comprendre en profondeur le mécanisme interne du système. Ce sont les rouages de ce mécanisme que je vous propose maintenant de découvrir.

2.5.1 Le fichier toolbar.ini

Tout d'abord, voici le contenu du fichier settings/ toolbar.ini de la version eZ publish 4.0.1:

#?ini charset="iso-8859-1"?
# eZ Publish configuration file.
#
# NOTE: It is not recommended to edit this files directly, instead
#       a file in override should be created for setting the
#       values that is required for your site. Either create
#       a file called settings/override/toolbar.ini.append or
#       settings/override/toolbar.ini.append.php for more security
#       in non-virtualhost modes (the .php file may already be present
#       and can be used for this purpose).
 
[Toolbar]
AvailableToolBarArray[]
AvailableToolBarArray[]=top
AvailableToolBarArray[]=right
AvailableToolBarArray[]=bottom
 
[Tool]
AvailableToolArray[]
AvailableToolArray[]=basket
AvailableToolArray[]=preferred_currency
AvailableToolArray[]=user_country
AvailableToolArray[]=calendar
AvailableToolArray[]=link
AvailableToolArray[]=login
AvailableToolArray[]=searchbox
AvailableToolArray[]=node_list
AvailableToolArray[]=users
AvailableToolArray[]=notification
AvailableToolArray[]=best_seller
AvailableToolArray[]=create_object
AvailableToolArray[]=drafts
 
[Toolbar_top]
Tool[]
Tool[]=login
Tool[]=searchbox
 
[Toolbar_right]
Tool[]
 
[Toolbar_bottom]
Tool[]
Tool[]=searchbox
 
[Tool_searchbox]
relative_check=no
 
[Tool_searchbox_description]
relative_check=Relative search?
 
[Tool_calendar]
show_subtree=
show_classidentifiers=
 
[Tool_calendar_description]
show_subtree=Show in subtree
show_classidentifiers=Show only classes
 
[Tool_node_list]
parent_node=2
title=Latest items
show_subtree=
limit=5
sort_by=published
treelist_check=yes
 
[Tool_node_list_description]
parent_node=Item source
title=Title
show_subtree=Show in subtree
limit=Number of items
sort_by=Sort on attribute
treelist_check=Fetch whole tree?
 
[Tool_link]
href=
text=
 
[Tool_link_description]
href=Location
text=Display text
 
[Tool_best_seller]
show_subtree=shop
product_parent_node=2
 
[Tool_best_seller_description]
show_subtree=Show in subtree
product_parent_node=Product list
 
[Tool_create_object]
title=
show_subtree=
placement_node=
type_classidentifier=
 
[Tool_create_object_description]
title=Title
show_subtree=Show in subtree
placement_node=Where to place
type_classidentifier=Type

Ce fichier est composé de quatre sections:

• [Toolbar]: cette section contient le tableau AvailableToolBarArray[] contenant lui-même tous les emplacements possibles pour les outils. Les valeurs de ce tableau sont affichées dans le cadre Barres d'outils disponibles pour le siteaccess <xxx> de la figure 4.

• [Tool]: cette section contient le tableau AvailableToolArray[] contenant lui-même tous les outils disponibles. Le contenu de ce tableau est celui affiché par le menu déroulant sélection d'outils présenté figure 5.

• Viennent ensuite plusieurs sections spécifiques, dont le nom est composé du nom de la section ci-dessus ( Tool) suivi du nom d'un outil.
  Exemple: la section [Tool_node_list] qui définit la boîte à outils node_list.
  Ces sections, que nous désignerons maintenant par section outil, sont composées d'une liste de variables ( parent_node, title, show_subtree, etc...) affectées de valeurs par défaut affichées chaque fois que vous sélectionnez un outil dans le menu déroulant sélection d'outils (figure 5).

• Enfin, sont présentes des sections dont le nom est composé de celui des sections section outil suivi du mot description.
  Exemple: la section [Tool_node_list_description].
  Ces sections, que nous désignerons maintenant par section description, permettent de définir les noms des variables (celles définies par les sections section outil) tel qu'ils doivent être présentés lors de l'affichage des outils dans la page de gestion (figure 5).

La présence des sections section outil et section description dans le fichier settings/ toolbar.ini évolue en fonction des outils activés à partir de l'interface de gestion des outils (figure 5).

2.5.2 Le fichier de surcharge toolbar.ini.append.php

Le fichier de surcharge toolbar.ini.append.php est placé dans le répertoire du siteaccess public de votre site. Si le siteaccess public est plain alors le fichier se trouve dans:

settings/siteaccess/plain/

Ce fichier contient toutes les informations nécessaires au système pour savoir:

• où doivent être affichés les outils sur le site public,
• quels sont les outils devant être affichés,
• quels contenus doivent être affichés,
• et dans quel ordre les outils doivent être affichés.

Conformément au mécanisme de surcharge, le fichier toolbar.ini.append.php étant situé dans le répertoire d'un siteaccess donné, la portée des informations qu'il contient ne sont bien sûr valables que pour ce siteaccess. Si vous avez mis en place plusieurs siteaccess, alors chacun d'eux devra posséder son propre fichier toolbar.ini.append.php.

Lorsque vous sélectionnez, comme indiqué au paragraphe 2.3, le siteaccess dont vous souhaitez gérer les outils, vous indiquez au système qu'il doit lire le fichier toolbar.ini.append.php relatif au siteaccess que vous venez de sélectionner. Si le système ne trouve pas ce fichier dans le répertoire du siteaccess (ce qui est le cas lorsque vous vous rendez pour la première fois sur la page de gestion des outils) alors il affiche le contenu du fichier settings/ toolbar.ini.

Dans le fichier toolbar.ini.append.php ne sont consignées que les options dont la valeur par défaut a été modifiée. Le système lit donc les nouvelles valeurs des options dans le fichier toolbar.ini.append.php et les valeurs par défaut dans le fichier toolbar.ini.

Voici un exemple type du contenu du fichier toolbar.ini.append.php:

[Toolbar_top]
Tool[]
Tool[]=searchbox
Tool[]=login
 
[Toolbar_right]
Tool[]
Tool[]=login
Tool[]=searchbox
Tool[]=users
Tool[]=node_list
 
[Toolbar_bottom]
Tool[]
Tool[]=users
 
[Tool_right_node_list_4]
parent_node=90
show_subtree=2
limit=4
sort_by=priority
treelist_check=no

• Les trois premières sections, [Toolbar_top], [Toolbar_right] et [Toolbar_bottom] définissent chacune un tableau Tool[] contenant la liste des outils devant être affichés sur le site public respectivement aux emplacements top, right et bottom.

• [Tool_right_node_list_4]: le nom de cette section indique à lui seul que l'outil node_list doit être positionné à l'emplacement right et en 4ème position. Vient ensuite la liste des options ainsi que les valeurs que vous leur avez affectées.

2.5.3 Surcharge goblale

Comme vous le savez déjà, eZ publish est doté d'un système de surcharge globale. Sa mise en œuvre permet de définir le comportement du système indépendamment des configurations spécifiques à chacun des siteaccess.

Pour les outils, et particulièrement dans le cas d'un multisite, il vous est possible de définir en un seul endroit et pour tous les siteaccess:

• les emplacements possibles pour les outils,
• le nombre d'outils disponibles,
• les valeurs des options des outils.

Pour mettre en place une surcharge globale permettant de définir, pour tous les sitesaccess, les emplacements possibles ainsi que le nombre d'outils disponibles, vous devez créer un fichier settings/override/ toolbar.ini.append.php dans lequel vous placez, par exemple, ces lignes:

[Toolbar]
AvailableToolBarArray[]
AvailableToolBarArray[]=right
 
[Tool]
AvailableToolArray[]
AvailableToolArray[]=link
AvailableToolArray[]=login
AvailableToolArray[]=searchbox
AvailableToolArray[]=node_list
AvailableToolArray[]=users
AvailableToolArray[]=notification

Ainsi, en accédant à la page de gestion des outils (figure 4) seul l'emplacement right sera proposé dans le cadre Barres d'outils disponibles pour le siteaccess <xxx>.
De même, le menu sélection d'outils (figure 5) ne proposera que la liste d'outils définie ci-dessus par le tableau AvailableToolArray[].

Si votre fichier settings/override/ toolbar.ini.append.php ne contient que les sections [Toolbar] et [Tool], alors les valeurs des options des outils activés seront écrites par le système dans le fichier toolbar.ini.append.php relatif au siteaccess concerné et non dans le fichier settings/override/ toolbar.ini.append.php.

Donc, si vous souhaitez également fixer les valeurs des options des outils pour tous les sitesaccess de votre site, vous devez explicitement déclarer ces valeurs dans le fichier de surcharge globale. Par exemple:

[Toolbar]
AvailableToolBarArray[]
AvailableToolBarArray[]=right
 
[Tool]
AvailableToolArray[]
AvailableToolArray[]=link
AvailableToolArray[]=login
AvailableToolArray[]=searchbox
AvailableToolArray[]=node_list
AvailableToolArray[]=users
AvailableToolArray[]=notification
 
[Tool_right_node_list_1]
parent_node=59
title=Dernières news
show_subtree=2
limit=7
treelist_check=no

De la sorte, quand bien même les administrateurs des siteaccess de votre site modifieraient les valeurs des options de leurs outils, celles-ci n'auraient aucun effet puisque seules celles présentes dans le fichier de surcharge globale seront prises en compte par le système.

2.5.4 Les templates des outils

Comme l'indiquent les paragraphes 2.2.1 et 2.2.2, il existe deux modes d'affichage pour les outils:

• le mode line
• le mode full

A chacun de ces modes correspondent des templates définissant la présentation des outils sur les pages du site ainsi, bien sûr, que le contenu qu'ils doivent afficher. Ces templates sont regroupés dans deux répertoires bien distincts du système:

• design/standard/templates/toolbar/line/ pour le mode line
• design/standard/templates/toolbar/full/ pour le mode full

Les deux répertoires line/ et full/ ci-dessus contiennent une liste de templates dont chacun a un nom composé du même nom que l'outil qu'il définit suivi de l'extension classique des templates, à savoir .tpl

Les templates de ces deux répertoires sont les templates par défaut utilisés par le système.

Ces templates utilisent les variables (et leur valeur) définies par les sections section outil.

2.5.5 Vignettes des outils

Chaque fois que vous sélectionnez un outil et qu'il s'affiche dans la page de gestion des outils (figure 5) une vignette (petite image) s'affiche afin de visualiser l'aspect général de l'outil lorsqu'il est affiché sur les pages publiques de votre site. Comme mentionné au paragraphe 2.3, ces vignettes diffèrent selon le mode d'affichage ( line ou full) de l'outil. Cependant, celles-ci sont toutes placées dans le répertoire:

design/standard/images/toolbar/

Pour que le système distingue la vignette correspondant au mode d'affichage line de celle correspondant au mode full, la convention de nommage des vignettes est la suivante:

• mode full: le nom des vignette est le même que celui de l'outil quelle représente. Par exemple: basket.png
• mode line: le nom des vignette est le même que celui de l'outil quelle représente suivi du mot line. Par exemple: basket_line.png

Vous pouvez également placer les vignettes dans le répertoire suivant:

design/admin/images/toolbar/

3 Création d'un outil

Si vous souhaitez créer vos propres outils, il est indispensable que vous ne modifiez pas les gabarits et fichiers utilisés par défaut car lors d'une mise à jour du système, ceux-ci sont remplacés par les gabarits et fichiers de la nouvelle version de eZ publish. Vous perdriez alors tout votre travail.

:
Pour lancer toutes les commandes qui vont suivre vous devez avoir les droits nécessaires en lecture et écriture dans les différents répertoires du système eZ publish.
D'autre part, toutes les commandes présentées ci-après sont lancées à partir de la racine du répertoire d'installation de eZ publish 4.0.1.

:
On considérera par la suite que le siteaccess public est plain.

3.1 Utiliser ses propres templates et fichiers

Commencez par copier, en le renommant, le fichier de configuration settings/ toolbar.ini dans le siteaccess public de votre site:

cp -p settings/toolbar.ini settings/siteaccess/plain/toolbar.ini.append.php

L'option -p de la commande cp (copy) permet de conserver les attributs des fichers.

Si vous avez créé plusieurs siteaccess, réitérez l'opération ci-dessus pour chacun d'eux.

:
Il est important de retenir que le fait de copier l'intégralité du fichier settings/ toolbar.ini dans le répertoire de chacun des siteaccess de votre site, dissocie du même coup la gestion des outils de chaque siteaccess. Ceci peut être particulièrement intéressant dans le cadre d'un multisite.

Copiez également l'ensemble des fichiers des deux répertoires:

• design/standard/templates/toolbar/line/
• design/standard/templates/toolbar/full/

...dans le répertoire de design de votre siteaccess public. Pour ce faire, commencez par créer les répertoires suivants s'ils n'existent pas:

mkdir design/plain/templates/toolbar

mkdir design/plain/templates/toolbar/line

mkdir design/plain/templates/toolbar/full

Pensez ensuite à affecter à ces nouveaux répertoires le bon propriétaire et groupe propriétaire. Par exemple, sous Debian:

chown -R www-data:www-data design/plain/templates/toolbar

Copiez à présent l'ensemble des fichiers:

cp -p design/standard/templates/toolbar/line/* design/plain/templates/toolbar/line/

cp -p design/standard/templates/toolbar/full/* design/plain/templates/toolbar/full/

Pour que le système utilise les templates que vous venez de copier en lieu et place des templates par défaut, vous devez vider les caches du système (Template & contenu).

3.2 Définir le nom d'un nouvel outil

Supposons que le nouvel outil que vous souhaitez créer se nomme mon_outil. Pour que son nom apparaisse dans le menu déroulant sélection d'outils (figure 5), vous devez commencer par ajouter ce nom, dans le fichier toolbar.ini.append.php, à la liste des outils existants:

[Tool]
AvailableToolArray[]
AvailableToolArray[]=basket
AvailableToolArray[]=preferred_currency
AvailableToolArray[]=user_country
AvailableToolArray[]=calendar
AvailableToolArray[]=link
AvailableToolArray[]=login
AvailableToolArray[]=searchbox
AvailableToolArray[]=node_list
AvailableToolArray[]=users
AvailableToolArray[]=notification
AvailableToolArray[]=best_seller
AvailableToolArray[]=create_object
AvailableToolArray[]=drafts
AvailableToolArray[]=mon_outil            <=== AJOUTEZ CETTE LIGNE

L'emplacement, dans la liste, de la ligne que vous ajoutez n'a aucune importance. Cependant, l'ordre de cette liste sera respectée dans le menu déroulant sélection d'outils (figure 5),

:
N'utilisez, pour nommer votre outil, que des caractères alphanumériques en majuscule ou minuscule et le tiret bas (« _ »). Les espaces sont également à proscrire (bien que possibles).

Il n'est pas besoin de vider les caches pour que la nouvelle entrée apparaisse dans le menu déroulant sélection d'outils.

3.2 Les options de l'outil

Vous pouvez, bien sûr, reprendre toutes les options définies par défaut et décrites au paragraphe 2.4. Pour cela, vous devez créer une section section outil dans le fichier toolbar.ini.append.php. Par exemple:

[Tool_mon_outil]
title=Titre de l'outil
parent_node=2
show_subtree=2
limit=5
href=URI du site
text=Nom du lien

Dans l'exemple ci-dessus, chaque option est suivie d'une valeur par défaut.

:
Attention aux valeurs par défaut que vous employez pour les options parent_node et show_subtree. Elles doivent impérativement correspondre à des nœuds existants sur votre système. Si cela n'est pas le cas et que vous conservez ces valeurs lors de l'activation de votre outil, ce dernier ne s'affichera pas du tout ou sera vide de tout contenu.

:
A ce stade, vous pouvez, à partir de l'interface de gestion des outils, visualiser le résultat des lignes que vous venez d'ajouter au fichier toolbar.ini.append.php.
Si vous rencontrez des problèmes d'affichage des caractères spéciaux et accentués, remplacez le jeu de caractères spécifié par la première ligne par charset="utf-8"?

En plus des options par défaut, vous pouvez créer vos propres options. Par exemple, vous pouvez définir une option qui présente un menu déroulant à choix unique.

Le template qui gère les options des outils est design/admin/templates/visual/ toolbar.tpl

Si vous éditez ce template, vous trouverez, entre autres, ces lignes:

{switch match=cond( $Parameter.name|wash|ends_with( '_node' ), 1,
                                $Parameter.name|wash|ends_with( '_classidentifier' ), 2,
                                $Parameter.name|wash|ends_with( '_classidentifiers' ), 3,
                                $Parameter.name|wash|ends_with( '_subtree' ), 4,
                                $Parameter.name|wash|ends_with( '_check' ), 5,
                                0 )}

La structure de contrôle switch vérifie l'existence de certains événements auxquels elle affecte, par exemple, un nombre. Dans l'exemple ci-dessus, switch contrôle que le nom ( .name) de la variable $Parameter se termine ( ends_with()):

• soit par _node auquel cas la variable match vaudra 1,
• soit par _classidentifier auquel cas la variable match vaudra 2,
• soit par _classidentifiers auquel cas la variable match vaudra 3,
• soit par _subtree auquel cas la variable match vaudra 4,
• soit par _check auquel cas la variable match vaudra 5,
• dans tous les autres cas la variable match vaudra 0.

:
La variable $Parameter contient les noms des options (ou paramètres) définies par les sections section outils (définies au chapitre 2.5.1).
C'est donc la fin des noms de ces options que contrôle, dans le code ci-dessus, la structure switch.

A la suite de ces quelques lignes, vous trouverez 5 structures de la forme:

{case match=x}
....
....
....
{/case}

...permettant de traiter les 5 premiers cas (cas 1 à 5) définis par switch et une dernière structure:

{case}
 <input type="text" name="{$Tool.index}_parameter_{$Parameter.name|wash}" size="20" value="{$Parameter.value|wash}" />
 {/case}

...traitant le dernier cas où match vaut zéro. La fin de la structure de contrôle switch se termine ensuite par le code {/switch}.

Vous l'aurez compris, pour ajouter une option à votre outil mon_outil, vous devez ajouter une ligne à la structure de contrôle switch puis une structure case qui traitera le cas de votre option.

Si vous appelez, par exemple, votre option mon_menu_deroulant, voici ce que devient la structure switch:

{switch match=cond( $Parameter.name|wash|ends_with( '_node' ), 1,
                                 $Parameter.name|wash|ends_with( '_classidentifier' ), 2,
                                 $Parameter.name|wash|ends_with( '_classidentifiers' ), 3,
                                 $Parameter.name|wash|ends_with( '_subtree' ), 4,
                                 $Parameter.name|wash|ends_with( '_check' ), 5,
                                 $Parameter.name|wash|ends_with( '_deroulant' ), 6,            <=== AJOUTEZ CETTE LIGNE
                                 0 )}

Puisque vous désirez que votre option mon_menu_deroulant affiche une menu déroulant, la structure case qui traitera votre option pourrait être de la forme:

{case match=6}
      {let nombre=array('1', '2', '3', '4' )}
      <select name="{$Tool.index}_parameter_{$Parameter.name|wash}">
      {section var=nombre1 loop=$nombre}
         <option value="{$nombre1}" {section show=eq( $nombre1, $Parameter.value )}selected="selected"{/section}>{$nombre1}</option>
      {/section}
      </select>
      {/let}
 {/case}
 {case}
 <input type="text" name="{$Tool.index}_parameter_{$Parameter.name|wash}" size="20" value="{$Parameter.value|wash}" />
 {/case}

Les 9 premières lignes de code (celles que vous devez ajouter) créent un menu déroulant contenant les valeurs 1 à 4.

N'oubliez pas d'ajouter, dans le fichier toolbar.ini.append.php, votre nouvelle option à la liste des options que vous avez déjà définies et de lui affecter une valeur par défaut:

[Tool_mon_outil]
 title=Titre de l'outil
 parent_node=2
 show_subtree=2
 limit=5
 href=URI du site
 text=Nom du lien
 mon_menu_deroulant=1            <=== AJOUTEZ CETTE LIGNE

3.4 Créer la section section description

Cette section doit être également placée dans le fichier settings/siteaccess/plain/ toolbar.ini.append.php

Voici un exemple qui permettra de bien comprendre le sens des options à paramétrer à partir de l'interface de gestion des outils:

[Tool_mon_outil_description]
 title=Nom de l'outil:
 parent_node=Noeud dont il faut afficher les objets:
 show_subtree=Où faut-il afficher l'outil:
 limit=Nombre d'objets à afficher:
 href=Indiquez ici l'URI du site:
 text=Nom du lien:
 mon_menu_deroulant=Choisissez une des quatre valeurs:

:
Vous pouvez insérer des balises HTML dans les descriptions.
Par exemple: show_subtree=Où faut-il afficher l'outil:<span style="color: rgb(255, 102, 0);"><br />...des explications suplémentaires en couleur...</span>

:
Si le nom de l'outil contient un espace, alors la première ligne est de la forme:
[Tool_ mon outil_description]

Après avoir effectué toutes les modifications présentées ci-dessus, voici le résultat obtenu dans la page de gestion des outils lorsque vous ajoutez mon_outil:

Fig. 6 - Affichage du nouvel outil mon_outil dans l'iInterface de gestion des outils.

Il est bien évident que votre outil, à ce stade, ne produira absolument aucun affichage puisque le template devant définir cet outil n'a pas encore été créé.

Comme vous le savez maintenant, ce template devra être placé dans l'un des deux répertoires:

• design/plain/templates/toolbar/line/
• design/plain/templates/toolbar/full/

...en fonction du mode d'affichage auquel vous destinez votre outil.

Dans le code de votre template, vous accédez aux valeurs des options définies dans la section section outil du fichier toolbar.ini.append.php simplement avec la notation classique des variables. Par exemple:

• $title vaudra la valeur de l'option title,
• $parent_node vaudra la valeur de l'option parent_node,
• $mon_menu_deroulant vaudra la valeur sélectionnée dans l'option mon_menu_deroulant.

3.5 Créer une vignette pour l'outil

Pour associer une vignette à votre nouvel outil, il vous suffit le l'afficher une première fois sur votre site public, d'en faire une capture d'écran que vous nommerez du nom de l'outil (par exemple mon_outil.png) et de placer cette image dans l'un des deux répertoires suivants:

design/standard/images/toolbar/
 
design/admin/images/toolbar/

Commentaires