Création / modification d'un plugin wysiwyg

Définition

La fonction d'un plugin WYSIWYG

Un plugin WYSIWYG est une interface disponible dans la barre d'outil WYSIWYG d'un champ de type texte HTML, permettant d'insérer un élément de l'un des modules directement dans le champ de texte, en tant que contenu textuel.

Un exemple visuel :

Cet exemple montre un texte en train d'être édité.

Remarquez que l'image insérée est le logo d'Automne. Il ne s'agit pas d'une image simple, mais d'un élément faisant partie d'un module "médiathèque".

L'insertion dans le texte peut être de deux types :

• Insertion de HTML autour d'un texte sélectionné dans le wysiwyg.
  Exemple : ajouter un lien sur un texte vers un document géré par un module ou une vers une page affichant le détail d'un l'élément du module.

• Insertion de HTML a un endroit donné du texte (à la position du curseur).
  Exemple : ajouter le code HTML décrivant un élément donné d'un module tel qu'une actu, une fiche de données, un document et ses méta-données, etc.

Il est possible de créer plusieurs plugin WYSIWYG pour chacun des objets créé avec le générateur de modules Polymod : leur nombre n'est pas limité.

Deux points importants :

• Les modules WYSIWYG ne permettent que l'insertion de données existantes d'un module dans un texte (ils n'ont pas pour but de permettre la création ou la modification de données).

• Les éléments insérés dans un texte suivront l'évolution de l'élément source dans le module.Par exemple, un document inséré dans un texte sera modifié dynamiquement si le document source est modifié dans le module. Et de la même façon, il sera supprimé si le document source est supprimé.

Comment insérer un plugin WYSIWYG dans une barre d'outils WYSIWYG

S'il existe au moins 1 plugin WYSIWYG disponible parmi tous les objets d'un module polymod, il est alors possible d'ajouter le bouton correspondant à ce module dans les propriétés des barres d'outils (voir Modèles des barres d'outils WYSIWYG).

Par exemple, si j'ai un plugin WYSIWYG pour mon objet « Actualité » dans mon module « Actualités », je peux éditer la barre d'outils WYSIWYG « Défaut » et ajouter le bouton « Actualités ».

Le fait d'ajouter ce bouton à la barre d'outils va permettre d'utiliser les plugins WYSIWYG du module polymod concerné pour les champs de type texte HTML qui utilisent cette barre d'outils.

L'accès au bouton du module polymod dans la barre d'outils est soumis aux droits d'accès au contenu correspondant à ce module.

Une fois dans l'édition d'un champ de type texte HTML (contenu dans une rangée de type texte o bien dans un autre module Polymod) avec barre d'outils WYSIWYG où vous avez le bouton du module polymod concerné, vous pouvez utiliser ce bouton pour accéder à l'interface de sélection et d'insertion des éléments.

L'affichage des éléments est paramétrable lors de la création du plugin WYSIWYG.

Ainsi on peut tout à fait limiter le nombre de résultats, afficher les éléments d'une catégorie spécifique, ordonner la recherche par un tri ascendant sur une donnée particulière, etc.

Propriétés

Lors de l'édition d'un plugin WYSIWYG, les champs suivants sont disponibles :

Titre :

Permet de donner un titre au plugin WYSIWYG. Ce titre sera utilisé dans la barre d'outils pour permettre de sélectionner le plugin souhaité, en fonction du module polymod.

Description :

Permet d'indiquer une description complémentaire pour le plugin WYSIWYG : généralement la description indique la nature du plugin et ses fonctions. Par exemple « Permet d'afficher le titre d'une actualité avec un lien vers le détail ».

Uniquement les objets répondant à ces paramètres :

Permet de filtrer les éléments qui seront affichés comme disponibles lors de la sélection des éléments dans l'interface du plugin WYSIWYG.

Définition XML :

Permet de définir les informations à afficher dans le champ de texte lorsqu'un élément polymod est inséré. Il s'agit du coeur du plugin : lorsque l'utilisateur a sélectionné son élément dans l'interface de sélection des éléments et valide l'insertion dans le champ, le résultat affiché dans le champ texte est défini par la définition XML (voir détail ci-dessous).

Par exemple on peut choisir de n'afficher que le titre de l'élément, ou la totalité des champs, ou encore une image avec un lien, etc... Les possibilités sont multiples.
Voir l'aide disponible en dessous du champ.

Définition XML d'un plugin WYSIWYG :

Voila une explication sur la syntaxe à employer pour les modules WYSIWYG.

Vous trouverez une aide dynamique sur l'interface de création du plugin WYSIWYG.

<atm-plugin language="languageCode">
    <atm-plugin-valid>
        ...
    </atm-plugin-valid>
    <atm-plugin-invalid>
        ...
    </atm-plugin-invalid>
    <atm-plugin-view>
        ...
    </atm-plugin-view>
</atm-plugin>

Le tag atm-plugin-valid sera lu si l'objet sélectionné est valide (non supprimé, validé et en cours de publication, et dont l'utilisateur a les droits de consultation).

Le tag atm-plugin-invalid (facultatif) sera lu si l'objet sélectionné est invalide (supprimé, non validé ou dont les dates de publication sont dépassées ou si l'utilisateur n'a pas les droits de consultation de cet objet).

Le tag atm-plugin-view (facultatif) remplacera le tag atm-plugin-valid dans l'éditeur de texte visuel (WYSIWYG). Il est principalement utilisé pour afficher une version simplifié des données et ainsi faciliter la modification du contenu de l'éditeur.

languageCode : Code du langage relatif au contenu parmi les codes suivants, parmi les codes disponibles pour votre application (par défaut "fr" et "en").

{plugin:selection} : Sera replacé par la valeur textuelle sélectionnée dans l'éditeur (facultatif).
 

Voici deux exemples valables sur le module médiathèque, inclus dans la démo d'Automne :

Affichage d'un lien vers un document sélectionné reprenant le titre du document :

<atm-plugin language="fr">
    <atm-plugin-valid>
        <a href="{Media:Fichier:filePath}/{Media:Fichier:filename}" target="_blank" title="Télécharger le document '{Media:Fichier:fileLabel}' ({Media:Fichier:fileExtension} - {Media:Fichier:fileSize}Mo)"><atm-if what="{Media:Fichier:fileIcon}"><img src="{Media:Fichier:fileIcon}" alt="Fichier {Media:Fichier:fileExtension}" title="Fichier {Media:Fichier:fileExtension}" />
    </atm-plugin-valid>
</atm-plugin>
Ce code affichera un lien vers le document comportant l'icône du type de document et le nom du document.

Si le document n'existe plus ou n'est pas disponible pour l'utilisateur, il n'y aura rien d'affiché (car le tag <atm-plugin-invalid> n'est pas spécifié ici).

Affichage d'un lien vers un document sélectionné sur un texte sélectionné dans le WYSIWYG :

<atm-plugin language="fr">
    <atm-plugin-valid>
        <a href="{Media:Fichier:filePath}/{Media:Fichier:filename}" target="_blank" title="Télécharger le document '{Media:Fichier:fileLabel}' ({Media:Fichier:fileExtension} - {Media:Fichier:fileSize}Mo)"><atm-if what="{Media:Fichier:fileIcon}"><img src="{Media:Fichier:fileIcon}" alt="Fichier {Media:Fichier:fileExtension}" title="Fichier {Media:Fichier:fileExtension}" />
    </atm-plugin-valid>
    <atm-plugin-invalid>
        {plugin:selection}
    </atm-plugin-invalid>
</atm-plugin>
Ce code affichera un lien vers le document comportant l'icône du type de document le texte sélectionné dans le wysiwyg.

Si le document n'existe plus ou n'est pas disponible pour l'utilisateur, il n'y aura que le texte sélectionné dans le wysiwyg sans aucun lien (le tag atm-plugin-invalid ne contient que {plugin:selection} qui représente le texte sélectionné dans le wysiwyg).