CKeditor : API

Cet article décrit les différents points d’entrées (pipelines) utilisables pour modifier le comportement du plugin CKeditor plus loin que ne le permet l’utilisation de CFG.

Il y a pour l’instant 6 points d’entrée :

  • ckeditor_config_post
  • ckeditor_json_encode
  • ckeditor_html2spip_pre et ckeditor_html2spip_post
  • ckeditor_spip2html_pre et ckeditor_spip2htlm_post

Utilisation des pipelines

Pour utiliser l’un des deux points d’entrée, vous devez avoir un fichier mes_fonctions.php dans votre répertoires squelettes/ (qui doit donc, lui aussi, avoir été précédemment créé).

Le contenu minimal [1] de ce fichier est :

<?php

function ckeditor_config_post($config) {
/* insérer ici votre code modifiant $config */
    return $config ;
}

function ckeditor_json_encode($object) {
/* insérer ici votre code initialisant $result en fonction du contenu de $object
    le résultat doit être json - encodé */
    return $result ;
}

function ckeditor_html2spip_pre($texte) {
/* insérer ici votre code de modification de $texte */
   return $texte ;
}

function ckeditor_html2spip_post($texte) {
/* insérer ici votre code de modification de $texte */
   return $texte ;
}

function ckeditor_spip2html_pre($texte) {
/* insérer ici votre code de modification de $texte */
   return $texte ;
}

function ckeditor_spip2html_post($texte) {
/* insérer ici votre code de modification de $texte */
   return $texte ;
}
?>

ckeditor_config_post

Ce point d’entrée sert à modifier la configuration qui sera passée à CKeditor lors de son initialisation. La fonction ckeditor_config_post reçoit en entrée un tableau $config contenant la configuration et retourne ce même tableau en sortie (après y avoir apporté diverses modifications).

Par exemple, la configuration actuelle du plugin désactive l’onglet « avancé » de la boîte de dialogue de lien de ckeditor. Cela peut vous déplaire, pour l’activer, il suffit de créer une fonction ckeditor_config_post qui supprimer de l’entrée removeDialogTabs, le paramètre : link:advanced. Par exemple :

function ckeditor_config_post($config) {
       unset($config['removeDialogTabs']) ;
       return $config ;
}

Autre exemple, vous voulez complètement modifier les menus proposés par CKeditor, la configuration par défaut est donc insuffisante, il suffit de créer, à la main, le menu SpipFull ou SpipBasic (plus utile car non modifiable par CFG), par exemple, en insérant dans votre mes_fonctions;php la fonction :

function ckeditor_config_post($config) {
        $config['toolbar_SpipFull'] =
  array(
        array('NewPage','Preview'),
        array('Cut','Copy','Paste','PasteText','PasteFromWord','-','Scayt'),
        array('Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'),
        array('insertHtml','Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak'),
        '/',
        array('Styles','Format'),
        array('Bold','Italic','Strike'),
        array('NumberedList','BulletedList','-','Outdent','Indent','Blockquote'),
        array('Link','Unlink','Anchor'),
        array('Maximize','-','About')
    ) ;
return $config ;
}

Le tableau $config qui est passé en paramètre est l’équivalent php du paramètre javascript : CKEDITOR.config décrit dans la documentation de CKeditor. Il faut juste penser que :

  • si dans documentation on écrit : [ ... ], il faudra taper : array( ... )
  • si dans documentation on écrit : { ... }, il faudra taper : array( ... )
  • si dans documentation on écrit : item : ..., il faudra taper : "item" -> ...
  • etc.
  • si dans la documentation il est fait référence à une constante CKEDITOR.NOM, il faudra la remplacer par : CKEDITOR_NOM

Par exemple, dans la documentation de CKEditor, on peut lire qu’il est possible de modifier les raccourcis clavier utilisé par CKEditor, en passant comme configuration à CKEditor :

config.keystrokes =
[
    [ CKEDITOR.ALT + 121 /*F10*/, 'toolbarFocus' ],
    [ CKEDITOR.ALT + 122 /*F11*/, 'elementsPathFocus' ],

    [ CKEDITOR.SHIFT + 121 /*F10*/, 'contextMenu' ],

    [ CKEDITOR.CTRL + 90 /*Z*/, 'undo' ],
    [ CKEDITOR.CTRL + 89 /*Y*/, 'redo' ],
    [ CKEDITOR.CTRL + CKEDITOR.SHIFT + 90 /*Z*/, 'redo' ],

    [ CKEDITOR.CTRL + 76 /*L*/, 'link' ],

    [ CKEDITOR.CTRL + 66 /*B*/, 'bold' ],
    [ CKEDITOR.CTRL + 73 /*I*/, 'italic' ],
    [ CKEDITOR.CTRL + 85 /*U*/, 'underline' ],

    [ CKEDITOR.ALT + 109 /*-*/, 'toolbarCollapse' ]
];

Dans la fonction ckeditor_config_post cela se traduira par :

$config['keystrokes'] =
array(
    array( CKEDITOR_ALT + 121 /*F10*/, 'toolbarFocus' ),
    array( CKEDITOR_ALT + 122 /*F11*/, 'elementsPathFocus' ),

    array( CKEDITOR_SHIFT + 121 /*F10*/, 'contextMenu' ),

    array( CKEDITOR_CTRL + 90 /*Z*/, 'undo' ),
    array( CKEDITOR_CTRL + 89 /*Y*/, 'redo' ),
    array( CKEDITOR_CTRL + CKEDITOR_SHIFT + 90 /*Z*/, 'redo' ),

    array( CKEDITOR_CTRL + 76 /*L*/, 'link' ),

    array( CKEDITOR_CTRL + 66 /*B*/, 'bold' ),
    array( CKEDITOR_CTRL + 73 /*I*/, 'italic' ),
    array( CKEDITOR_CTRL + 85 /*U*/, 'underline' ),

    array( CKEDITOR_ALT + 109 /*-*/, 'toolbarCollapse' )
);

Faites très attention à ce que ferez du tableau $config : il sera passé tel quel à CKeditor, sans aucun contrôle. En particulier : cela peut empêcher CKeditor de se lancer.

Il faut savoir que le plugin modifie le paramètre $config['toolbar'] à la création de chaque éditeur, il vaut alors soit SpipFull, soit SpipBasic suivant la configuration prévu pour l’éditeur. Il ne sert donc à rien de donner une valeur à ce paramètre : il sera ignoré. C’est la seule modification qui sera faite à ce tableau.

Enfin, il y a une valeur que vous pouvez modifier et qui n’est pas dans la documentation de CKEditor : loadExtraPlugins qui contient une liste de chemins vers un répertoire de plugin (au sens de plugin pour CKEditor - pas de plugin pour SPIP) indexé par les noms des plugins. Par exemple, vous pouvez mettre :

  $config['loadExtraPlugins']['monPlugin'] = '/url/vers/mon/plugin/a/moi/' ;

Il est préférable (vu que ckeditor peut-être appelé depuis un contexte public ou privé) de préciser un chemin absolu vers le plugin.

ckeditor_json_encode

Si vous trouvez que la fonction json_encode fournie un mauvais résultat, vous pouvez utiliser votre propre fonction son_encode.

Ceci est utile :

  • soit pour pretty-printer le code javascript utiliser par le plugin (par exemple pour le lire ...)
  • soit parce que la fonction json_encode n’est pas fournie par votre serveur et que celle intégrée au plugin ne vous convient pas.

Par défaut, le code de cette fonction est équivalent à :

function ckeditor_json_encode($object) {
    return json_encode($object) ;
}

Mais, pour afficher un javacript indenté, vous pouvez utiliser celui-là :

/**
 * 
 * (c) http://recursive-design.com/blog/2008/03/11/format-json-with-php/
 *
 * Indents a flat JSON string to make it more human-readable.
 *
 * @param string $json The original JSON string to process.
 *
 * @return string Indented version of the original JSON string.
 */
function indent($json) {

    $result      = '';
    $pos         = 0;
    $strLen      = strlen($json);
    $indentStr   = "\t";
    $newLine     = "\n";
    $prevChar    = '';
    $outOfQuotes = true;

    for ($i=0; $i<=$strLen; $i++) {

        // Grab the next character in the string.
        $char = substr($json, $i, 1);

        // Are we inside a quoted string?
        if ($char == '"' && $prevChar != '\\') {
            $outOfQuotes = !$outOfQuotes;
        
        // If this character is the end of an element, 
        // output a new line and indent the next line.
        } else if(($char == '}' || $char == ']') && $outOfQuotes) {
            $result .= $newLine;
            $pos --;
            for ($j=0; $j<$pos; $j++) {
                $result .= $indentStr;
            }
        }
        
        // Add the character to the result string.
        $result .= $char;

        // If the last character was the beginning of an element, 
        // output a new line and indent the next line.
        if (($char == ',' || $char == '{' || $char == '[') && $outOfQuotes) {
            $result .= $newLine;
            if ($char == '{' || $char == '[') {
                $pos ++;
            }
            
            for ($j = 0; $j < $pos; $j++) {
                $result .= $indentStr;
            }
        }
        
        $prevChar = $char;
    }

    return $result;
}

function ckeditor_json_encode($object) {
  if (is_array($object)) {  ksort($object) ; }
  return indent(json_encode($object)) ;
}

ckeditor_html2spip_pre et ckeditor_html2spip_post

Ces deux points d’entrée servent à modifier le texte édité par CKEditor et passé à SPIP.
Lors de la sauvegarde du texte créé par CKEditor dans la base de donnée SPIP, celui-ci passe dans un filtre qui permet transformer certains (voir tous) enrichissements HTML en enrichissement SPIP (en particulier les liens et les documents).

Avant d’appliquer ce filtre, la fonction ckeditor_html2spip_pre est appelée. Une fois ce filtre appliqué, la fonction ckeditor_html2spip_post est appelée, puis le texte est passé à SPIP.

Ces deux appels sont conçus pour fonctionner en parallèle avec la préservation de la typographie SPIP [2].

ckeditor_spip2html_pre et ckeditor_spip2html_post

Ces deux points d’entrée servent à modifier le texte stocké dans la base de donnée SPIP ou collé avant qu’il ne soit passé à CKEditor.

Lors de l’initialisation du texte du CKEditor ou du collage d’un texte dans CKEditor celui-ci passe dans un filtre qui permet transformer certains (voir tous) enrichissements SPIP en enrichissement HTML (en particulier les liens et les documents).

Avant d’appliquer ce filtre, la fonction ckeditor_spip2html_pre est appelée. Une fois ce filtre appliqué, la fonction ckeditor_spip2html_post est appelée, puis le texte est passé à CKEditor.

Notes

[1on peut n’y mettre qu’une seule des 6 fonctions

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom