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.

Toastr c'est quoi ?

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 :

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 ! Rire

ok 1

/!\ 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}) 
ok 2

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.

Livre Blanc Complexité programmation

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 (fadeInslideDown/slideUp et show)
  • hideMethod : string, indique l’animation d’ouverture de la pop-up (fadeOutslideDown/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 :

Résultat

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 onShownonHideonClick 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é.

A lire sur le même sujet : Les tests unitaires en Javascript

Pour terminer, je vous invite à visiter cet autre tuto très bien fait sur le blog d’amethyste16.

SoftFluentrecrute

Ne ratez plus aucunes actualités avec la newsletter mensuelle de SoftFluent