Bootstrap Length Detector

Améliorer l'expérience utilisateur lors de la saisie d'un champ grâce à un plugin Jquery et intégration dans le BsFormHelper.

Introduction

Bien souvent, lors du remplissage d’un formulaire, on ne sait pas vraiment quelle est la longueur du champ adéquate et quelle est la longueur maximale. On peut donc remplir ce champ de manière inappropriée et rendre l’information qu’il contient inintéressante ou "non optimale". Par exemple dans le cas du remplissage d'un champ dédié ensuite au référencement.

C’est pourquoi nous avons introduit une nouvelle fonctionnalité dans le BsFomHelper, le lengthDetector. Cette nouvelle fonctionnalité permet d’indiquer, à côté d’un input choisi, des indications par rapport au nombre de caractères tapés.

Ce plugin jquery est inspiré (et forké) de bootstrap-maxlength mais est totalement indépendant. Il peut donc être utilisé dans n'importe quel projet web. Dans les exemples ci-dessous, nous vous allons présenter la façon de l'utiliser avec notre plugin pour CakePHP, le BsHelpers.


Intérêt et exemple concret

Ce plugin va donc permettre d’aider l’utilisateur à renseigner plus précisément les champs d’un formulaire. Avec ce plugin, il est possible de rajouter une indication en lien avec le nombre de caractères tapés ainsi que le nombre maximum de caractères. Cette indication a été conçue pour être épurée et simple de configuration.

On peut par exemple l’utiliser pour le champ meta-description comme ci-dessous :

Exemple Length Detector
Evolutions du Length Detector en fonction du nombre de caractères renseignés dans l'input


Utilisation rapide

Remarque : Il faut être en possession de la dernière version de notre Plugin BsHelpers pour CakePHP pour faire fonctionner le code ci-dessous. Si vous n'utilisez pas CakePHP, reportez vous simplement à la documentation de présente sur Github pour faire fonctionner ce plugin.

Pour faire fonctionner ce plugin rapidement via le BsFormHelper, il suffit de reprendre la syntaxe d’un input classique en rajoutant la classe length-detector, tout en précisant la “maxlength” :


// Meta description
echo $this->BsForm->input('meta_description' , 
   array(
      'class' => 'length-detector',
      'maxlength' => 140,
   )
);

Bien sûr, il est possible d'avoir [beaucoup] plus d'options pour améliorer l'expérience utilisateur...


Utilisation avancée

L'utilisation avancée du plugin length-detector va nécessiter de s'attarder sur le fichier default.js, qui se trouve dans le dossier configs du BsHelpers.

Ce fichier contient en effet la configuration avancée du length-detector, de telle façon à ce que la sa personnalisation et son paramétrage soit fait dans ce fichier et non dans votre vue.

Pour rester dans l'exemple de la meta-description, voici la configuration associée :


$.configs.metaDescription = {
                showOnReady: false,
                alwaysShow: true,
                threshold: 10,
                interval: {
                    0: {
                        limitChars: 15,
                        bsClass: 'danger',
                        message : 'Too short'.
                    },
                    1: {
                        limitChars: 70,
                        bsClass: 'warning',
                        message : 'Could be better'.
                    },
                    2: {
                        limitChars: 110,
                        bsClass: 'success',
                        message : 'This is the right length'.
                    },
                    3: {
                        limitChars: 139,
                        bsClass: 'warning',
                        message : 'Too Long'
                    },                      
                },
                previousClass: '',
                defaultClass: 'warning ',
                limitReachedClass: 'danger label-important ',
                separator: ' / ',
                preText: '',
                postText: '',
                showMaxLength: true,
                placement: 'bottom-right-inside',
                message: null,
                showCharsTyped: true,
                utf8: false,
                appendToParent: false,
                twoCharLinebreak: true,
                allowOverMax: false
            };

Ensuite, il faut rajouter l’attribut “class” dans l’attribut “length-detector-option” de l’input voulu. La valeur sera le nom que vous avez donné dans le fichier de configuration. Dans ce cas c’est "metaDescription".

// Meta description
echo $this->BsForm->input('meta_description' , 
   array(
      'class' => 'length-detector',
      'maxlength' => 140,
      'length-detector-option' => array('class' => 'metaDescription')
   )
);

Cette configuration va principalement permettre de définir des inputs types, qui seront réutilisables n’importe où dans votre application.C'est l'utilisation optimale du plugin. De plus, lors d’une modification dans le fichier de configuration, tous les length-detector associés seront modifiés d’un coup.


Utilisation fine / documentation

Pour modifier un seul input à la volée, il faut renseigner dans l’option "length-detector-option" les options à changer avec leurs nouvelles valeurs. Le changement à la volée dans les vues n'est pas conseillé car il est assez lourd d'un point de vue syntaxe. Il est tout de même disponible. La section ci-dessous fait également office de documentation pour bien comprendre les paramétrages possibles dans le fichier de configuration.

Liste des options disponibles :

  • alwaysShow: (boolean) Affiche en permanence le length detector. Par défaut : true
  • threshold: Nombre de caractères restant avant d’afficher le length detector. (Est annulé si "alwaysShow" = true.)
  • defaultClass: Nom de la classe par défaut du fond. Par défaut : “warning”.
  • limitReachedClass: Nom de la classe de l’élément quand le nombre maximum de caractères est atteint. Par défaut : “danger”.
  • separator: C’est le séparateur entre le nombre de caractères écrit et maximum. Par défaut : "/".
  • preText: Texte affiché avant l’indicateur de caractères écrit. Vide par défaut.
  • postText: Texte affiché après l’indicateur de caractères écrit. Vide par défaut.
  • showMaxLength: Affiche ou non le nombre de caractères maximum. Par défaut : true.
  • showCharsTyped: Affiche ou non le nombre de caractères écrit. Par défaut : true.
  • appendToParent: Affiche le lengthDetector après le parent de l’input plutôt qu’au body.
  • message: (String, function) Permet d’afficher un message générique personnalisé. Ex : 'Vous avez écrit %charsTyped% sur %charsTotal% caractères. %charsRemaining% caractères restant. Cette méthode annule preText, postText et separator. Il est aussi possible de rentrer une fonction qui retourne une chaîne de caractère. Par exemple, function(currentText, maxLength) { return '' + Math.ceil(currentText.length / 160) + ' SMS Message(s)'; }
  • utf8: A ‘true’, les caractères seront comptés avec l’encodage utf-8. Par exemple: ‘€’ prendra 2 caractères.
  • twoCharLinebreak: (boolean) Compte 1 ou 2 caractères pour les retours à la ligne. Par défaut : true (2).
  • allowOverMax: (boolean) Permet d’écrire dans l’input même si le nombre de caractères maximum est atteint.
  • placement: (String, Object, function) Définit le placement du length detector Possible string values are: bottom-right-inside ( default option ), left, top, right, bottom-right, top-right,top-left, bottom-left and centered-right.
    Des placements particuliers peuvent être définis, avec les clefs top, right, bottom, left, and position. Elles sont passés au $.fn.css.
    Une fonction spécifique peut aussi être définie.
  • interval: (Object) Définit des intervalles de caractères écrits en leurs attribuant un style et/ou message propre. Pour définir un intervalle il faut une limite de caractères et une classe ou objet pour définir le style.
    • limitChars: Nombre de caractères limite pour cet intervalle.
    • bsClass: (String, Hexa, Object) Définit le style du length detector.
    • message: (String) Message à afficher pour l’intervalle.

Plus de précision sur l’utilisation de l’option interval. Pour pouvoir utiliser cette option, il faut bien définir chaque intervalle avec une limite de caractères et bsClass défini :

  • limitChars : Un intervalle est défini entre son précédent intervalle et ‘limitChars’ compris. Si il n’y a pas d'intervalle précédent c’est entre 0 et ‘limitChars’. Par exemple, si on veux changer la classe entre 0 et 20 caractères, il faut écrire :
echo $this->BsForm->input('meta_description' , 
	array(
		'label' => 'Meta description',
		'maxlength' => '140',
		'class' => 'length-detector',
		'length-detector-option' => array(
			'interval' => array(
			 	array(
			 		'limitChars' => 20,
			 		'bsClass' => 'success'
			 		)
				)
			 )
		)
	);

Exemple Length Detector
Exemple Length Detector
Passage de l'intervalle entre 20 et 21 caractères


  • bsClass : définit le style du length detector. Dans l’exemple précédent, c’était seulement une classe bootstrap prédéfinie. Cependant, il est possible de personnaliser le style pour chaque intervalle. Les possibilités sont donc infinies ! La première manière est de redéfinir la couleur du fond de l’indicateur. Il faut attribuer à bsClass une couleur, soit par valeur Hexadecimal, soit par valeur rgb(). On peut aussi définir plus de style. Pour ce faire, il faut définir un tableau pour bsClass, à la place d’une chaîne de caractère, comme dans l’exemple ci-dessous :
echo $this->BsForm->input('meta_description' , 
	array(
		'label' => 'Meta description',
		'maxlength' => '140',
		'class' => 'length-detector',
		'length-detector-option' => array(
			'interval' => array(
			 	array(
			 		'limitChars' => 20,
			 		'bsClass' => array(
							'background-color' => '#6495ED',
							'color' => 'midnightblue'
						)
			 		)
				)
			 )
		)
	);

Exemple Length Detector
Gestion des couleurs


  • message : Affiche un message personnalisé pour chaque intervalle. Un message n’est pas forcement définis pour tous les intervalles. Par exemple, pour avoir le rendu ci-dessous. C’est-à-dire un nouvel intervalle et un séparateur différent, on peut écrire le code :
echo $this->BsForm->input('meta_description' , 
	array(
		'label' => 'Meta description',
		'maxlength' => '140',
		'class' => 'length-detector',
		'length-detector-option' => array(
			'separator' => ' | ',
			 'interval' => array(
			 	array(
			 		'limitChars' => 20,
			 		'bsClass' => 'success'),
			 	array(
			 		'limitChars' => 35,
			 		'bsClass' => 'info',
			 		'message' => 'C\'est la bonne longueur.'))
	);

Exemple Length Detector
Gestion du message



Conclusion

Nous avons vu dans cet article comment améliorer l'expérience utilisateur et optimiser le remplissage d'un champ contenant une meta-description. Nous avons également intégré une classe pour un champ title dans le plugin length-detector. N'hésitez pas à proposer d'autres champs ou informations types pour lesquels le nombre de caractères est également important à prendre en considération.

Et si vous avez une remarque ou une idée pour améliorer ce plugin jquery d'une manière générale, n'hésitez pas non plus à utiliser la zone de commentaires ci-dessous.

Les liens importants :