Un PliciTag est un outil qui va vous permettre d'afficher une information dans une page de votre site. Plici est distribué avec plusieurs PliciTag de bases (comme insérer du code html, exécuter une requête SQL, la liste complète étant disponible sur http://wiki.plici.net/list_plicitag ).

Voir Documentation utilisateur

Il existe plusieurs types prédéfinis de PliciTag, comme les plicitags de détail ou de lien (il est bien sûr possible d'en créer de nouveau). Plus précisemment, il s'agit d'une instruction qui peut être appelée depuis n'importe quelle page, qui va être interprétée par le moteur de Plici pour exécuter le code définit dans le source du PliciTag.

Plusieurs répertoires peuvent accueillir des PliciTag :

- /common_plicitags/ ;

- /view/sites/my/BDD/plicitag/ (où BDD représente le nom d'un site).

Dans le premier cas, on trouve tous les PliciTags qui peuvent être utilisés de manière commune sur tous les sites. Le second répertoire contient les PT propres à chaque site (ils doivent être créés/déposés par le super admin et activés avant de pouvoir être utilisés).

En terme de code PHP, un PT est une classe étendue d'une autre classe nommée xPliciTag. Avant de débuter la création du code, il vous faut déterminer le type de PT que vous voulez concevoir : détail, lien, ou autre chose. Ensuite, il suffit de créer un dossier du nom de votre PT dans le répertoire correspondant au type choisit (ou de créer un nouveau répertoire si ce type n'existe pas déjà.

Exemple :

Pour créer un PT commun, nommé 'monplicitag', de type détail, il faut créer un répertoire 'monplicitag' dans /common_plicitags/detail/. Pour un PT spécifique au site 'toto', de type 'panier' et nommé 'affichagepanier', il faut : - d'abord créer /view/sites/my/toto/plicitag/panier ; - et ensuite /view/sites/my/toto/plicitag/panier/affichagepanier.

Le fichier contenant le code doit s'appeler plicitag_nomduplicitag.class.php (en suivant les exemples ci-dessus il faudra créer pour le premier cas /common_plicitags/detail/monplicitag/plicitag_monplicitag.class.php, et dans le second /view/sites/my/toto/plicitag/panier/affichagepanier/plicitag_affichagepanier.class.php).

Il ne reste plus qu'à écrire votre PT !

Déclaration d'un PT :

Cette classe doit étendre la classe xPlicitag, voici un exemple de code pour PliciTag_time.

// force classe to not be loaded twice if inherited from another class
if (class_exists("PliciTag_time")) return;

class PliciTag_time extends xPliciTag {

function replacePliciTag($params, $content, &$smarty) {
		return "hello World";
	}

}

Quelques points importants :

- Quand vous créez votre PT, il est important de lui donner un nom assez explicite, ainsi que de bien documenter les lignes qui permettent d'identifier l'auteur, la description du PT, etc.

- Le retour de la fonction replacePliciTag doit être une chaîne, sinon votre PT ne fera rien du tout !

- Quand vous souhaitez réaliser un requête SQL (création d’une table, selection, etc.), vous devez préfixer le nom de votre table par : $this→m_table_prefix

Voici la liste des fonctions qui seront appelées pour utiliser la classe de votre PliciTag :

• Fonction « getInformationsPliciTag() »
  • Renvoi un tableau :
    • version ⇒ numdelaversion
    • name ⇒ Lien externe
    • description ⇒ module pour écrire un texte
    • author ⇒ stephane trichet
    • wikiurl ⇒ /essai:essai (sans http://wiki.plici.net)
    • code ⇒ [plicitag tag='contactform'][/plicitag]
      • La clef 'code' n'est utilisée que pour les PliciTag de détail, c'est cette valeur qui est ajoutée automatiquement par l'editeur de text quand on clique sur le bouton 'PliciTag'.
  • Par défaut, renvoi : "Default found" pour chaque element

• Fonction « isWithoutInstallationPliciTag() »
  • Renvoi Vrai si le PliciTag n’a pas besoin d’installation (par exemple si il n’a pas besoin de créer de table en base de donnée), sinon il renvoi Faux.
  • Par défaut, renvoi : TRUE

• Fonction « isReplacingThePageDescriptionPlicitag() »
  • Renvoi Vrai si les paramètres du PliciTag doivent être affichés à la place de la description de la page (FCKEditor) sinon Faux.
  • Par défaut, renvoi : FALSE

• Fonction « installPliciTag() »
  • Elle est lancée lors de l’installation du PliciTag
    • Création de l’environnement du PliciTag (ex : création de table)
  • Renvoi TRUE (il y a une erreur) ou FALSE (aucune erreur)
  • Par défaut, renvoi : FALSE

• Fonction « getIsAlreadyInstalledPlicitag() »
  • Donne au PliciTag le moyen de vérifier son installation
  • Retourn TRUE (il est installé) ou FALSE (n’est pas installé)
  • Par défaut, renvoi : TRUE

• Fonction « getCanUpgradePliciTag() »
  • Elle est lancée lors de la demande de la mise à jour du PliciTag
  • Test la version du PliciTag et regarde si il doit être mis à jour du PliciTag par l’utilisateur
  • Renvoi TRUE (peut être mis à jour) ou FALSE (ne peut être mis à jour)
  • Par défaut, renvoi : FALSE

• Fonction « upgradePliciTag() »
  • Elle est lancée lors de la demande de mise à jour du PliciTag par l’utilisateur Renvoi TRUE (il y a une erreur) ou FALSE (aucune erreur)
  • Par défaut, renvoi : FALSE

• Fonction « unInstallPliciTag() »
  • Elle est lancée lors de la demande de désinstallation du PliciTag
  • Suppression des tables, PLICI s’occupe des fichiers et du répertoire.
  • Renvoi TRUE (il y a une erreur) ou FALSE (aucune erreur)
  • Par défaut, renvoi : FALSE

• Fonction « getCanBeCachedPliciTag() »
  • renvoi TRUE (si le résultat de « getContent » peut être mis en cache)
  • renvoi FALSE (si le résultat de « getContent » ne doit pas être mis en cache)
  • Par défaut, renvoi : TRUE

• Fonction « getTemplateNamePliciTag() »
  • Renvoi une chaîne de caractère indiquant le patron Smarty à lire après l’exécution de « replacePliciTag », la base de recherche du fichier est l’endroit ou se trouve le le plicitag.
  • Si cette fonction renvoi une chaîne de caractère vide, alors on utilise pas Smarty et le contenu de « replacePliciTag » est affiché.
  • Par défaut, renvoi : ""

• Fonction « getOwnSQLTablesPliciTag() »
  • Renvoi un tableau dans lequel chaque valeur est le nom d'une table créée par le PliciTag.
  • Cette fonction est utilisée pour faire fonctionner le PliciTag avec le système de groupage de sites proposé par Plici. Vous devez seulement retourner une liste de vos propres tables, les autres sont gérées par PLICI.
  • Par défaut, renvoi : array()

• Fonction « getBackEndStringPliciTag() »
  • Renvoi un tableau dans lequel chaque clef est l'identifiant à utiliser avec le tag smarty <!–{plici_lang id='identifiant'}–> pour renvoyer une phrase.
  • Cette fonction permet d'être compatible avec le système multi langue de PLICI.
  • Cette fonction retourne les phrases nécessaires pour le BackOffice.
  • Par défaut, renvoi : array()

• Fonction « getFrontEndStringPliciTag() »
  • Renvoi un tableau dans lequel chaque clef est l'identifiant à utiliser avec le tag smarty <!–{plici_lang id='identifiant'}–> pour renvoyer une phrase.
  • Cette fonction permet d'être compatible avec le système multi langue de PLICI.
  • Cette fonction retourne les phrases nécessaires pour le FrontOffice.
  • Par défaut, renvoi : array()

Comme notre PliciTag étend xPliciTag, on peut ne déclarer que les fonctions dont on a besoin.

Pour tout PliciTag, la classe qui le définit n’est chargé qu’une seule fois, ainsi une variable membre pourra être incrémenté de Tag en Tag. Il est possible qu'un PliciTag hérite d'un autre pour l'améliorer.

Place du xPlicitag : core/internal_components/common/plicitag/xplicitag.class.php

Le patron smarty qu’utilise le PliciTag doit seulement utiliser les données fournies par la classe de ce PliciTag, sinon le système de cache entraînera des résultats aléatoires.

Précisions sur l’utilisation d’un patron Smarty, {include file="xx"} va chercher le patron dans le site et {include file=$plicitag_basedir|cat:"test2.tpl"} va le chercher dans le répertoire du PliciTag.

Voici la liste des fonctions qui seront appelées pour utiliser la classe de votre PliciTag pour un lien :

• Fonction « getFormParametersPliciTag($p_page_id) »
  • Renvoi une chaîne de caractère d’HTML qui liste les éléments du formulaire (sans la balise FORM) que l’utilisateur dans l’interface d’administration doit saisir pour paramétrer son PliciTag
  • Paramètres:
    • $p_page_id: identifiant de la page
  • Par défaut, renvoi : ""

• Fonction « insertPliciTag($p_page_id) »
  • Elle est exécutée quand on crée une nouvelle page avec ce PliciTag dans le titre.
  • Elle va disposer dans $_POST des paramètres du formulaire donné par « formParameterPliciTags »
  • Il faut mémoriser les paramètres pour cette page dans la table de ce PliciTag (si besoin)
  • Renvoi TRUE (il y a une erreur) ou FALSE (aucune erreur)
  • Si vous devez ajouter une ligne dans une table de la base de donnée, préférez un REPLACE plutôt qu’un INSERT, en effet, la page a déjà pu être configuré pour ce plicitag.
  • Par défaut, renvoi : FALSE

• Fonction « updatePliciTag($p_page_id) »
  • Elle est exécutée quand on modifie une page avec ce PliciTag dans le titre.
  • Elle va disposer dans $_POST des paramètres du formulaire donné par « formParameters »
  • Il faut mémoriser les paramètres pour cette page dans la table de ce PliciTag (si besoin)
  • Renvoi TRUE (il y a une erreur) ou FALSE (aucune erreur)
  • Par défaut, renvoi : FALSE

• Fonction « isBypassingDesignPliciTag() »
  • Renvoi TRUE si le résultat du tag doit complètement remplacer l’aspect visuel du lien. Sinon FALSE
  • ATTENTION : lors du changement de la valeur de retour de ce PliciTag, vous devez vider le cache du site (modifier une page implique la suppression du cache par exemple).
  • Par défaut, renvoi : FALSE

• Fonction « replacePliciTag($params, $content, &$smarty) »
  • Elle est appelée lors de l’affichage pour savoir par quoi on doit remplacer le PliciTag
  • Elle reçoit
    • $params (array)
      • Valeur minimum disponible
        • page_id
    • $smarty
      • Objet Smarty de l’affichage en cours
  • Elle renvoie le contenu qui sera affiché à la place du PliciTag
  • Par défaut, renvoi : "Default used"

• Fonction « getFrontEndCSSFilesPliciTag() »
  • Elle est appelée lors de l’affichage pour savoir quels fichiers CSS on doit charger
  • Elle renvoie un tableau avec :
    • clef = un ID (un md5 du fichier) pour identifier le fichier et éviter de charger 2 fois le même fichier
    • valeur = le nom du fichier CSS (ex : /plicitag/link/topmenu/my_sub_menu.css)
  • Par défaut, renvoi : array()

• Fonction « getFrontEndJSFilesPliciTag() »
  • Elle est appelée lors de l’affichage pour savoir quels fichiers JS on doit charger
  • Elle renvoie un tableau avec :
    • clef = un ID (un md5 du fichier) pour identifier le fichier et éviter de charger 2 fois le même fichier
    • valeur = le nom du fichier JS (ex : /plicitag/link/topmenu/my_sub_menu.css)
  • Par défaut, renvoi : array()

Dans la description d’une page on peut utiliser un PliciTag avec cette syntaxe :

1. [plicitag tag=’time’]…[/plicitag]
2. [plicitag tag=’time’][/plicitag]
3. [plicitag tag=’time’ format=’s’][/plicitag]

• Fonction « replacePliciTag($params, $content, &$smarty) »
  • Elle est appelée pour lors de l’affichage pour savoir par quoi on doit remplacer le PliciTag
  • Elle reçoit
    • $params (array)
      • Elle reçoit seulement les paramètre du PliciTag et
      • le page_id
    • $smarty
      • Objet Smarty de l’affichage en cours
  • Elle renvoie le contenu qui sera affiché à la place du PliciTag
  • Par défaut, renvoi : "Default used"

• Fonction « getBackEndTemplateNamePliciTag() »
  • Renvoi une chaîne de caractère indiquant le patron Smarty à lire après l’exécution de « getBackEndConfiguration », la base de recherche du fichier est l’endroit ou se trouve le le plicitag.
  • Si cette fonction renvoi une chaîne de caractère vide, alors on utilise pas Smarty et le contenu de « getBackEndConfiguration » est affiché.
  • Par défaut, renvoi : ""

• Fonction « isWithBackEndConfigurationPliciTag() »
  • Elle est appelée lors de l'ajout ou d'une modification d'une page dans l'interface d'administration
  • Renvoit true or false
  • Elle indique si le plici tag a une page de configuration(true)
  • Si le plici tag a une page de configuration, cela fera apparaitre un onglet dans la modification d'une page nommé "PT: nom du plicitag".
  • Cette méthode est accompagnée des méthodes suivantes: « getBackEndConfigurationMultiple », « getBackEndConfiguration », « setBackEndConfiguration » method
  • Par défaut, renvoi : FALSE

• Fonction « getBackEndConfigurationMultiplePliciTag() »
  • Elle est appelée lors de l'ajout ou d'une modification d'une page dans l'interface d'administration
  • Renvoit true or false
  • Elle indique si le plici tag a une page de configuration pour le plici tag(false) ou une page de configuration par appel du plicitag(true)
  • Si le plicitag permet une page de configuration par site, chaque configuration sera séparée par une ligne horizontale dans l'onglet de configuration du plicitag.
  • Par défaut, renvoi : FALSE

• Fonction « getBackEndConfigurationPliciTag($p_attributes, $p_content, &$smarty) »
  • Elle est appelée lors de l'ajout ou d'une modification d'une page dans l'interface d'administration
  • Paramètres:
    • $p_attributes : Tableau des paramètres du plicitag
      • En plus il y a le "page_id"
    • $p_content: Bloc contenu dans le plicitag
  • Renvoit du texte(Un bloc html)
  • Renvoit les éléments nécessaires à la configuration d'un plicitag.
  • Par défaut, renvoi : ""

• Fonction « setBackEndConfigurationPliciTag($p_attributes, $p_content) »
  • Elle est appelée lors de l'ajout ou d'une modification d'une page dans l'interface d'administration
  • Paramètres:
    • $p_attributes : Tableau des paramètres du plicitag
      • En plus il y a le "page_id"
    • $p_content: Bloc contenu dans le plicitag
  • Renvoit rien
  • Modifie la configuration du plicitag. Il faut récupérer les variables dans la variable globale $_POST.
  • Par défaut, renvoi : FALSE

Pour cela, vous devez isoler vos fichiers (tout en contenant l’arborescence /link/nomdutag/..) et le compresser au format tar, gz, tgz, bz2, tbz, zip, ar (ou deb).

Ensuite, il est vivement conseillé de le placer sur le Wiki avec une notice explicative.

Ainsi, tout super utilisateur de Plici pourra utiliser votre PliciTag.

- Je vous propose vivement de regarder dans /common_plicitags/ les exemples de PliciTag qui sont directement disponibles dans Plici. L'exemple type et le plus complet est "common_plicitags/link/externallink/plicitag_externallink.class.php"