Toastr JS, c’est quoi ?
Toastr est une bibliothèque JavaScript utilisant jQuery et permettant l’affichage de notifications en tout genre : succès, information, mise en garde, erreur. Chaque notification est simplement et entièrement personnalisable.
Mise en place
Toastr est hébergée sur Git : https://github.com/CodeSeven/toastr
Obtenir Toastr
Lorsque vous voulez obtenir Toastr, vous avez le choix entre les deux possibilités expliquées ci-dessous.
Obtenir une version figée
Afin d’obtenir une version fixe et éviter les régressions des versions à venir, il est possible d’installer la bibliothèque dans votre projet :
- pour ceux qui utilisent node.js : npm install –save toastr
- pour les autres : téléchargement du zip depuis git et extraction dans votre projet
Obtenir une version évolutive
Il est aussi possible d’utiliser Toaster sans installation, par simple appel des fichiers CSS et JS suivant :
- https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/css/toastr.min.css
- http://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/js/toastr.min.js
Dans ce cas, la dernière version de Toastr sera toujours utilisée.
Ajouter Toastr à son projet
Dans les deux cas, il vous faudra ajouter les fichiers à votre page HTML tel que :
<head>
<meta charset="UTF-8">
...
<link href="https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/css/toastr.min.css" rel="stylesheet" />
</head>
<body>
...
<script src="http://code.jquery.com/jquery-2.0.3.min.js" ></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/js/toastr.min.js"></script>
...
</body>
J’ai choisi ici de ne pas installer les fichiers, évidemment si vous avez fait l’installation, il vous faudra pointer sur les fichiers en question et non sur l’URL web.
/!\ L’appel du fichier js Toastr doit se faire après l’appel du fichier js jquery
Et voilà ! Vous êtes parés à utiliser Toastr !
Utilisation – les bases
Types de notifications
Dans la présentation je parlais de 4 types de notifications, voici les 4 fonctions Toastr associées :
- success
- info
- warning
- error
Premiers pas
Toastr s’utilise de la même manière pour chacune d’entre elles :
toastr.< function type>(<string message>, <string titre (facultatif)>, <object options (facultatif)>
Faisons notre premier test en ajoutant ce script à notre page HTML :
<script type="text/javascript">
$(function() {
toastr.success('Hé, <b>ça marche !</b>', 'Test');
});
</script>
Hé, ça marche !
/!\ Vous avez remarqué que les tags HTML avaient été interprétés
; dans le cas où vous vouliez les conserver, dans un message d’erreur par exemple, vous devez mettre l’option escapeHtml à true :
toastr.success('Hé, <b>ça marche !</b>', 'Test', {escapeHtml:true})
Pour forcer la fermeture de la notification, il existe deux fonctions :
- toastr.remove() qui ferme la pop-up sans animation
- toastr.clear() qui ferme la pop-up avec animation
Dans les autres cas, la pop-up se ferme automatiquement avec l’option timeOut que nous allons découvrir dans le chapitre suivant.
Options
Pour un aperçu des options de Toastr, je vous conseille cette démo : http://codeseven.github.io/toastr/demo.html
Pour les options dont le nom n’est pas très parlant ou portant à confusion :
- tapToDismiss : booléen, oblige l’utilisateur à valider la pop-up avant sa fermeture
- showDuration/hideDuration : numérique, spécifie le temps durant lequel la pop-up s’ouvre et se ferme en ms
- timeOut : numérique, spécifie le temps durant lequel la pop-up reste ouverte
- extendedTimeOut : numérique, spécifie le temps supplémentaire durant lequel la pop-up restera ouverte après que l’utilisateur l’ai survolée
- showEasing/hideEasinglinear : string, indique la transition d’entrée de la pop-up (de base swing et linear pour plus d’effet, téléchargez jQuery Easing plugin http://www.gsgd.co.uk/sandbox/jquery/easing/)
- showMethod : string, indique l’animation d’ouverture de la pop-up (fadeIn, slideDown/slideUp et show)
- hideMethod : string, indique l’animation d’ouverture de la pop-up (fadeOut, slideDown/slideUp et hide)
- rtl : booléen, pour afficher le texte en lecture de gauche à droite
/!\ L’option positionClass s’applique sur le container des notifications et non sur la notification elle-même ; la première position appliquée est donc maintenue pour toutes les notifications s’affichant avant la fermeture de celle portant l’option.
Exemple : si votre code est :
$(function() {
toastr.success('Notification de <b>succès</b>', 'Success', {positionClass: "toast-top-full-width", escapeHtml:true});
toastr.error ('Notification d\'<b>erreur</b>', 'Error', {positionClass: "toast-top-right"});
});
Le résultat sera :
Pour afficher des notifications à la suite n’ayant pas la même option positionClass il est donc possible d’ajouter un timer javascript ou d’utiliser la méthode toastr.remove().
Accès avancés
Variables globales
Si l’on veut une option valide sur plus d’une pop-up, il est possible de la déclarer de la manière suivante :
toastr.options.escapeHtml = true;
De cette manière, toutes les notifications qui suivront, et dont le paramètre escapeHtml n’aura pas été précisé respectera cette option.
Callbacks
Il est aussi possible d’ajouter les options de callbacks onShown, onHide, onClick et onCloseClick :
toastr.options.onShown = function() { console.log('notification ouverte'); }
Appel de fonction
L’appel d’une fonction peut se faire comme nous l’avons vu dans le chapitre « Utilisation » mais il est aussi possible d’utiliser l’écriture suivante :
toastr[<string type>](<string message>);
Ceci est très pratique si le type de la notification nous est envoyé en tant qu’objet. Par exemple :
var notification = {type:«warning », message:« C’est un warning !», titre:«Attention !»};
toastr[notification.type]( notification.message, notification.titre);
CSS
La modification du CSS est elle aussi possible ;#toast-container > .toast sert à pointer sur le Toastr.
#toast-container > .toast-error peut être utilisé pour pointer sur un type spécifique, ici les pop-up de type erreur.
Et il est possible d’utiliser la pseudo class :before pour changer l’icône précédant le message. Font awesome peut dans ce cas être utilisé.
Pour terminer, je vous invite à visiter cet autre tuto très bien fait sur le blog d’amethyste16.