API editeur : Différence entre versions

Version actuelle en date du 8 décembre 2009 à 09:34

API pour implémenter un éditeur

syntaxe utilisée dans le nom des fonctions :

• Editor : le html de l'éditeur
• Content : le contenu à stoquer dans la base
• Html : le contenu transformé en html pour l'affichage

Pour le HTML nécessaire à l'éditeur, un objet sera utilisé. Pour afficher l'éditeur au moment de la modification d'un texte :

<source lang="php"> include_once $GLOBALS['babInstallPath']."utilit/editorincl.php";

$editor = new bab_contentEditor($uid); $editor->setRequestFieldName('textarea_name'); $editor->setContent($content); $editor->setParameters(array('height' => 300)); $editor_html = $editor->getEditor(); </source>

setRequestFieldName est optionnel, il permet de définir le nom du champ posté, si la méthode n'est pas appelée, $uid est utilisé comme nom dans le html

Avant d'enregistrer dans la base :

<source lang="php"> $editor = new bab_contentEditor($uid); $editor->setRequestFieldName('textarea_name'); $content = $editor->getContent(); $format = $editor->getFormat(); </source>

Pour afficher du contenu qui a été enregistré avec l'éditeur :

<source lang="php"> $editor = new bab_contentEditor($uid); $editor->setContent($content); $html = $editor->getHtml(); </source>

Pour chaque éditeur, un enregistrement doit être ajouté sur cet événement : bab_eventEditors

<source lang="php"> include_once $GLOBALS['babInstallPath']."utilit/eventincl.php"; bab_addEventListener('bab_eventEditors', 'xxx_getEditorDetails', 'xxx.php'); </source>

Il faut prévoir une fonction qui permet d'identifier l'éditeur :

<source lang="php"> function xxx_getEditorDetails($event) {

   $event->addEditor($uid, 'Editor label', 'Editor description');

} </source>

Pour les fonctions externes qui insèrent du html dans l'éditeur, chaque fonction doit s'inscrire sur cet événement :

bab_eventEditorContentToHtml cet événement sera appelé au moment de l'affichage de la popup avec les listes des fonctions qui permettent d'insérer du html dans l'éditeur. S'enregistrer sur cet événement permet d'ajouter des fonctions comme l'insertion d'un fichier du gestionnaire de fichier ou une fiche annuaire.

si $babBody n'est pas utilisé pour l'affichage des pages, il faut inclure manuellement des fichiers :

<source lang="php">

$babBody->addJavascriptFile($GLOBALS['babInstallPath'].'scripts/bab_dialog.js');
$babBody->addJavascriptFile($GLOBALS['babInstallPath'].'scripts/text_toolbar.js');
$babBody->addStyleSheet('text_toolbar.css');

</source>

API pour créer un module éditeur

Des événements seront définis pour permettre de fournir un éditeur à partir d'un module :

bab_eventEditorContentToEditor permet de créer le template HTML de l'éditeur, cet événement sera appelé par $editor->getEditor()

bab_eventEditorRequestToContent cet événement sera appelé par $editor->getContent()

bab_eventEditorContentToHtml cet événement sera appelé par $editor->getHtml()

Création d'un module ovidentia qui propose un éditeur WYSIWYG

Les modules peuvent fournir un éditeur pour les formulaires de modification du contenu du noyau et des autres modules, il faut obligatoirement traiter les 3 événements de la gestion des éditeurs afin que la gestion du html soit sécurisée.

Il est possible d'effectuer des action spécifiques en fonction du paramètre "uid" de l'éditeur. Cette fonctionnalité est optionnelle.

Ajout du bouton "Ovidentia"

pour afficher le popup de sélection des fonctionalités ovidentia, il faut créer dans l'éditeur un bouton qui appelle la fonction javascript insert_ovidentia().

la fonction est déclarée dans le fichier text_toolbar.js qui est inclu sur la page contenant l'éditeur. Par exemple, dans le cas de FCKeditor qui est executé dans une FRAME, on lance parent.insert_ovidentia();

Rendre l'éditeur compatible avec la popup "Ovidentia"

dans le fichier text_toolbar.js, il existe une variable globale global_editor, avant d'appeller la fonction </code>insert_ovidentia()</code>, il faut mettre un objet avec au moins 2 fonctions dans cette variable globale.

exemple (on utilise parent quand l'éditeur est executé dans une FRAME) :

<source lang="javascript">

   parent.global_editor = {
       'insertHTML' : function(text) {
           FCK.InsertHtml(text);
       },
       
       'getSelectedHTML' : function() {
       
           if ( FCKBrowserInfo.IsGecko ) {
               var oSel = FCK.EditorWindow.getSelection();
               var range = oSel.getRangeAt(0);
               return range.cloneContents().textContent;
           } else {
               // TODO selection pour ie
               return ;
           }
       }
   }

</source>

pré requis pour qu'un éditeur soit compatible avec ovidentia

• Ajout d'un bouton personnalisé qui appelle du javascript (ouverture d'une popup ovidentia)
• Possibilité de récupérer le html sélectionné par API au moment du click sur le bouton
• Possibilité d'insérer du html à la place de la sélection par API
• Le code récupéré doit être transformable en XHTML 1.0 transitional
• la hauteur de la textarea doit être paramétrable en pixel

Gestion des éditeurs

Lors de l'installation du module, il faut enregistrer les événements de notification pour que le module soit prévenu lors des actions effectuées sur les différentes implémentations de l'éditeur.

<source lang="php"> include_once $GLOBALS['babInstallPath']."utilit/eventincl.php"; bab_addEventListener('bab_eventEditorContentToHtml', 'fcke_contentToHtml', 'addon/fckeditor/events.php', 'fckeditor'); bab_addEventListener('bab_eventEditorRequestToContent', 'fcke_requestToContent', 'addon/fckeditor/events.php', 'fckeditor'); bab_addEventListener('bab_eventEditorContentToHtml', 'fcke_contentToHtml', 'addon/fckeditor/events.php', 'fckeditor'); </source>

Lors de chaque appel d'une fonction événementielle, un paramètre sera envoyé contenant les informations de l'éditeur ; c'est l'objet bab_editor qui sera inclu dans l'objet de l'événement déclenché. Le module aura accès à ces informations :

événement bab_eventEditorContentToHtml :

• uid : identifiant unique de l'éditeur en chaine de caractère, par exemple : "bab_article_head" pour l'introduction d'un article
• request_field_name : nom du champ html
• height : la hauteur demandée pour la case d'édition en pixel
• content : contenu à modifier

la propriété output_editor devra être renseignée lors de cette action

événement bab_eventEditorRequestToContent :

• uid
• request_field_name : nom du champ html

les propriétés output_content et output_content_format devront être renseignées lors de cette action

événement bab_eventEditorContentToHtml :

• uid
• content : contenu à afficher
• format : format des donnés

La propriété output_html devra être renseignée lors de cette action si le format des donnés correspond au format géré par l'éditeur

Récupérer la liste des instances de l'éditeur

Partout ou l'éditeur est utilisé, le nom de l'éditeur a été inscrit dans l'événement bab_eventEditors, pour récupérer la liste des éditeurs, il faut créer un objet d'événement :

<source lang="php">

$event = new bab_eventEditors(); bab_fireEvent($event);

$editors = $event->getEditors(); </source>

API pour ajouter un ou plusieurs boutons dans la popup "Ovidentia"

Sur les éditeur, il y a un bouton ovidentia qui offre une liste de fonctions a intégrer dans le texte. Il est possible pour un module d'Ovidentia d'ajouter une entrée dans la liste qui pointe vers la page de son choix.

IL faut s'enregistrer sur l'événement bab_eventEditorFunctions.

Exemple de code utilisé par le noyau pour ajouter le bouton image :

<source lang="php">

function bab_onEditorFunctions($event) {

   if ('bab_article_head' === $event->uid
    || 'bab_article_body' === $event->uid
    || 'bab_faq_response' === $event->uid) {

       $event->addFunction(
           bab_translate('Images'), 
           bab_translate('Insert image from ovidentia content image manager'), 
           '?tg=images',
           'scripts/htmlarea/images/ed_bab_image.gif'
       );
   
   }

</source>

la fonction bab_onEditorFunctions a été enregistrée sur l'évènement bab_eventEditorFunctions, au moment de l'afficheage de la popup avec la liste, la fonction bab_onEditorFunctions est appellée avec l'objet bab_eventEditorFunctions.

Dans ce cas, on doit afficher le bouton Images que si l'éditeur est celui des articles (introduction et corps) ou les réponses aux questions des FAQs.

Les paramètres qui doivent êtres passés à la méthode addFunction() sont :

• nom (libellé du lien)
• Description
• url de la page
• emplacement de l'icone (relatif au noyau d'ovidentia)

Insérer du contenu à partir de la popup

editorInsertText() :

Pour qu'une page de la popup insère du contenu, il faut appeler la fonction javascript editorInsertText(), cette fonction est déclarée dans le fichier text_toolbar.js inclue dans la page de l'éditeur.

getSelection() :

Pour obtenir en texte le contenu de la sélection, on peut appeller la fonction getSelection qui est déclarée dans le fichier text_toolbar.js

exemple simple pour insérer une image :

<source lang="javascript">

   opener.bab_dialog._return({
       'callback'     : 'editorInsertText',
       'param'        : '<img src="youpi.jpg" alt="'+opener.getSelection()+'" />'
   });
   
   window.close();

</source>

La popup de l'éditeur passe toujours par l'API javascript bab dialog donc on l'utilise pour remonter l'information vers l'éditeur