markItUp! Part I - Installation et personnalisation

Chose promise, chose due. Je profite de la sortie de markItUp! 1.1 pour lancer une petite série d'articles sur l’engin. Ce premier article couvrira l'installation et la personnalisation basique de la barre d’outils.

Si vous ne le savez pas encore, markItUp! est un plugin pour jQuery qui permet de transformer n'importe lequel de vos textareas en éditeur de tags configurable à souhait et ce, de manière totalement inobstrusive.

Voir la démo

Téléchargement et installation

Tout d'abord il faut bien évidement télécharger les dernières versions markItUp! et de jQuery. La dernière version de jQuery est incluse dans le zip de markItUp!, il n’est donc pas la peine de le télécharger à nouveau.

Placez le répertoire /markitup quelque part sur votre site. Ce répertoire contient :

• jquery.markitup.com : Script principal
• jquery.markitup.pack.com : Script principale mais compressé
• sets : Dossier contenant les fichiers de configuration JSon, les Css et images de la barre d'outils de votre éditeur
• skins : Dossier contenant les images et Css de l'éditeur
• templates Dossier contenant les templates de la prévisualisation
• utils : Dossier vide par défaut mais qui est destiné à contenir d'éventuels scripts secondaires.

Inclusions

Une fois le répertoire ajouté, il suffit d'inclure les éléments suivants dans la page désirée.

Dans le Head de la page

<script type="text/javascript" src="jquery.pack.js"></script>
<script type="text/javascript" src="markitup/jquery.markitup.pack.js"></script>
<link rel="stylesheet" type="text/css" href="markitup/skins/markitup/style.css" />

Puis les fichiers de configuration de notre éditeur.

Dans le Head de la page

<script type="text/javascript" src="markitup/sets/default/set.js"></script>
<link rel="stylesheet" type="text/css" href="markitup/sets/default/style.css" />

Ci-dessus, on insère les fichiers livrés par défaut qui proposent une barre d'outils Html. L’objet de ce tutoriel sera de créer une nouvelle barre d'outils à l'éditeur. Ces lignes seront donc à remplacer.

Connexion

Il ne reste plus qu'à expliquer à notre script sur quels textareas agir. Si vous n'êtes pas encore familier avec la syntax jQuery, je vous invite à en consulter la documentation.

Dans le Body de la page

<script language="javascript">
$(function() {
    // agira sur le textare comportant l'id 'myTextarea' par exemple.
    $("#myTextarea").markItUp(mySettings);

    // agira sur les textarea comportant la class 'myTextareas' par exemple.
    $(".myTextareas").markItUp(mySettings);

    // agira sur tous les textareas de la page
    $("textarea").markItUp(mySettings);
});
</script>

Concrétement, prenons l’exemple suivant :

Dans le Body de la page

<script language="javascript">
$(function() {
    $("#myTextarea").markItUp(mySettings);
});
</script>

<textarea id="myTextarea">Du contenu…</textarea>

mySettings est défini dans set.js, nous y reviendrons plus tard.

Personnalisation

MarkItUp! a été développé dans l'idée d'être un moteur d'insertion de tags/contenu personnalisable à souhait, permettant de simplement ajouter ou supprimer des commandes de sa barre d'outils.

Nous allons créer une barre d'outils avec quelques fonctions simples. Elle ne sera pas bien différente de celle fournie par défaut. L’intention est ici prétexte à un tutorial pas à pas.

Création d'un set

Créez un nouveau dossier nommé tutorial dans le dossier /markitup/sets/ et placez y un dossier /images. Ce dossier contiendra les icônes nécessaires à notre future barre d'outils. Copiez-y les icones suivants. Si vous souhaitez plus d’icônes, servez vous dans le très utile pack d’icônes Famfam.

Toujours dans le dossier /tutorial, Placez un fichier vide nommé set.js et un autre nommé style.css. Le fichier set.js est un fichier JSon qui contiendra la définition de chaque bouton de notre barre d'outils. Le fichier style.css quant à lui, contiendra les styles Css des boutons, pour notamment l'application des icônes.

Voilà, notre base est en place. Il nous reste maintenant à remplacer le set par défaut précédemment inclus par ce nouveau set. Remplacez donc default par tutorial dans les liens suivants :

Remplacement du set par defaut par notre tutorial

<script type="text/javascript" src="markitup/sets/tutorial/set.js"></script>
<link rel="stylesheet" type="text/css" href="markitup/sets/tutorial/style.css" />

Les fichiers étant pour l'instant vide, le résultat doit être celui-ci.

Edition d'un set

Barre d'outils et markupSet

Rappelez-vous le mystérieux mySettings de cette ligne $("#myTextarea").markItUp(mySettings) c'est maintenant que ça se passe. Ouvrez les fichiers set.js et style.css et insérez les lignes suivantes.

set.js

mySettings = {	
    markupSet:  [
            {name:'Gras', 
                key:'G', 
                openWith:'<strong>', 
                closeWith:'</strong>', 
                placeHolder:'Texte en gras'
            },
            {name:'Italic', 
                key:'I', 
                openWith:'<em>', 
                closeWith:'</em>', 
                placeHolder:'Texte en italic'
            },
            {name:'Barré', 
                key:'B', 
                openWith:'<del>', 
                closeWith:'</del>', 
                placeHolder:'Texte barré'
        }
    ]
}

style.css

.markItUp .markItUpButton1 a {
    background-image:url(images/bold.png);
}
.markItUp .markItUpButton2 a {
    background-image:url(images/italic.png);
}
.markItUp .markItUpButton3 a {
    background-image:url(images/stroke.png);
}

Rafraichissez votre page et si tout a été fait dans l'ordre, on devrait avoir 3 boutons.

Revenons point par point sur ce qui vient d'être ajouté. Tout d'abord :

mySettings = { }

C'est l'objet contenant votre configuration d'éditeur et qui est passé au plug-in. Cet objet peut accueillir une multitude de propriétés, la principale est markupSet qui définit chaque bouton de la barre d'outils. Les propriétés de boutons utilisées ici sont :

• name : Nom du bouton à afficher.
• key : Raccourci clavier pour actionner ce bouton avec la touche Ctrl.
• openWith : La sélection sera précédée par le contenu de cette propriété.
• closeWith : La sélection sera suivie par le contenu de cette propriété.

Le fichier style.css se contente d'appliquer une feuille de style à notre barre d'outils. Vous remarquerez que markItUp! applique automatiquement une classe .markItUpButton[x] à chaque bouton. Cela permet de pouvoir facilement accéder à un bouton quand on en connait l'ordre. Il est possible d'appliquer un nom de classe spécifique à chaque bouton comme on le verra plus tard. La classe .markItUp qui précède chaque bouton n'est pas obligatoire mais préférable pour éviter les conflits. On verra dans de prochains tutoriaux comment éviter aussi le conflit entre différentes instances d'éditeur si leur barre d'outils est différente.

Allons un peu plus loin dans notre barre d'outils et ajoutons y de nouveaux éléments.

set.js

mySettings = {	
    markupSet:  [
        // ...
        {separator:'----------------' },
        {name:'Image', 
            key:'P', 
            replaceWith:'<img src="[![Source:!:http://]!]" alt="[![Texte alternatif]!]" />' },
        {name:'Lien',
            key:'L', 
            openWith:'<a href="[![Lien:!:http://]!]"(!( title="[![Titre]!]")!)>', 
            closeWith:'</a>', 
            placeHolder:'Texte cliquable'
        }
    ]
}

style.css

.markItUp .markItUpButton4 a {
    background-image:url(images/picture.png); 
}
.markItUp .markItUpButton5 a {
    background-image:url(images/link.png);
}

De nouvelle propriétés et astuces apparaissent ici.

• separator : Ajoute un séparateur.
• replaceWith : La séléction sera replacée par le contenu de cette propriété.
• Tags spéciaux [![ Intitulé :!: Valeur par défaut ]!] : Ces tags permettent d'insérer des valeurs entrées par l'utilisateur au moment de l'insertion.
• Tags spéciaux (!( valeur alternative )!) ou (!( valeur par défaut |!| valeur alternative )!) : Ces tags permettent d'appliquer un contenu alternatif si la touche Alt est pressée pendant le click.

Rien de bien nouveau dans le style.css, donc poursuivons.

set.js

mySettings = {	
    markupSet:  [
        // ...
        {separator:'----------------' },
        {name:'Nettoyer le Html',
            className:'clean',
            replaceWith:function(markItUp) { 
                    return markItUp.selection.replace(/<(.*?)>/g, "") 
                }
            },				
            {name:'Prévisualiser', 
                className:'preview',
                call:'preview'
            }
    ]
}

style.css

.markItUp .clean a {
    background-image:url(images/clean.png);
}
.markItUp .preview a {
    background-image:url(images/preview.png);
}

De nouvelle propriétés et astuces apparaissent ici.

• className : Permet d'appliquer un nom de classe spécifique à un bouton. C'est bien plus pratique pour les configurer quand la barre d'outils contient beaucoup de boutons ou quand leur position est amenée à changer.
• call : Ne sert que dans le cas de la prévisualisation. Call appelle la fonction interne d'ouverture de la fenêtre de prévisuatlisation.
• Certaines propiétés peuvent acceuillir des fonctions : Les propriétés openWith, closeWith, ReplaceWith et placeHolder peuvent contenir des fonctions qui retourneront un contenu spécifique. Ces fonctions reçoivent en paramètre quelques valeurs de l'éditeur, la principale étant le texte sélectionné comme nous le voyons dans l'exemple. D'autres valeurs sont passées dans cet objet. Se référer à la documentation pour plus d'information.

Que manque-t-il donc ?

Nous venons de survoler les principales propriétés de boutons de la propriété principale markupSet. A celles-ci s'ajoutent des callbacks qui seront appelées à différents moments lorsqu'un bouton est cliqué. Ces fonctions reçoivent également quelques valeurs de l'éditeur en paramètre. Se référer à la documentation http://markitup.jaysalvat.com pour plus d'information.

• beforeInsert : Lancé juste avant que du contenu du bouton soit inséré.
• afterInsert : Lancé juste après que du contenu du bouton soit inséré.
• beforeMultiInsert : Lancé juste avant que du contenu du bouton soit inséré sur de multiples lignes par l'appui sur Shift+Ctrl pendant le click.
• afterMultiInsert : Lancé juste après que du contenu du bouton soit inséré sur de multiples lignes par l'appui sur Shift+Ctrl pendant le click.

Insertions sans bouton

Il est possible de configurer le comportement de l'éditeur lorsque certaines touches stratégiques sont pressées. Enter, Ctrl + Enter, Shift + Enter et Tab peuvent être configurées quasiment de la même façon d'un bouton dans le markupSet et acceptent les propriétés openWith, closeWith, replaceWith, beforeInsert, afterInsert et un nouveau paramètre keepDefault.

• KeepDefault : Précise si le comportement normal de la combinaison de touches pressée doit être gardé ou pas.

mySettings = {	
    markupSet:  [
        // ...
    ],
    onShiftEnter: {
        keepDefault:false, 
        replaceWith:'<br />\n'
    },
    onCtrlEnter: {
        keepDefault:false, 
        openWith:'\n<p>', 
        closeWith:'</p>'
    },
    onTab: {
        keepDefault:false,
        replaceWith:'    '
    }
}

Conclusion

Voilà pour ce premier tutorial sur la personnalisation de markItUp!. De nouveaux tutoriaux suivront pour approfondir ce chapitre et couvrir les options restantes. Notamment la prévisualisation, l'utilisation de markups autre que Html (et donc l’utilisation de parsers) et l'intégration à d'autres plug-ins et modules.

En espérant vous avoir éclairé et donné des idées de configuration sans avoir été trop indigeste.

markItUp! Part II, Intégration avancée. Une librairie d'image grâce à Flickr

http://blog.jaysalvat.com/articles/markitup-part-ii-integration-avancee-une-librairie-dimage-grace-a-flickr.php