MultiSelect UI

Introduction

MultiSelect UI transforme l’élément Select d'HTM en un vrai widget élégant avec le soutien Themeroller permettant ainsi de faire des multiple sélections, un joli filtre integré, etc... le widget hérite du core de jQueryUI toutes ses fonctionnalités, ses effets et est facilement intégrable.
Cette widget a été crée en base par Eric Hynds, j'ai repris son code et j'ai apporté les améliorations suivantes:

• La gestion du width se fait d'une façon dynamique au lieu de fixer pour chaque select un width spécifique le width du multiselect s'adapte au texte de l'option sélectionné,
• L'intégration se fait d'une façon plus facile vu que le nom et les Class du Select sont reportés sur le nouveau MultiSelect, pour éviter de changer vos services de base ni vos scripts JavaScript de base,
• Une option Open a été rajouté pour créer des selects toujours ouvert sur la page,
• Les boutons radio sont remplacés par des checkbox ce qui rend l'utilisation de plusieurs selects avec le même name possible.
• Une gestion plus correcte du height a été rajouté,

Démonstration

Utilisation:

• L'intégration de cette widget est facile. D’abord vous incluez les fichiers ci-dessous:
• jQuery 1.4.2+
• jQuery UI 1.8 la gestion des widgets et le core Ui est indispensable, les effets de jQueryUI sont à intégrer si seulement vous voulez les utiliser
• Un thème jQuery UI
• le widget jquery.multiselect.js
• le fichier CSS jquery.multiselect.css
• le widget du filtrage jquery.multiselect.filter.js
• le fichier CSS du filtre jquery.multiselect.filter.css

• Après vous construisez un Select Html normal

<select id="exemple" name="exemple" multiple="multiple">
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
  <option value="3">Option 3</option>
  <option value="4">Option 4</option>
  <option value="5">Option 5</option>
</select>

• Et enfin, vous initialisez le widget dans $(document).ready({}); pour ceux qui utilisent jQuery sinon dans le window.onload

$(document).ready(function(){
   $("#exemple").multiselect();
});

Options:

Pour la personnalisation de notre Multiselect, cette dernière accepte dans sa création une ou plusieurs options cités ci dessous:

// exemple:
$("select").multiselect({ 

    checkAllText: "Cocher tout!",

    autoOpen: "true!", 

    height: "250", 

    classes: "ui-multiselect-menu-block",
});

Option	Description	Valeur par Default
header	Soit une valeur booléenne indiquant si oui ou non afficher l'en-tête, ou une chaîne de carctère . Si vous passez une chaîne, les valeurs par défaut "Cocher tout", "Décocher tout",et "Fermer" liens seront remplacés par le texte spécifié .	true
height	Hauteur du conteneur des options (zone de défilement) en pixels. Si réglé sur "auto", la hauteur sera calculée en fonction du nombre de cases à cocher dans le menu.	175
minWidth	La largeur minimale du widget entier en pixels. Le réglage à "auto" permet du désactiver .	225
checkAllText	Le texte du lien “Cocher tout”.	Check all
uncheckAllText	Le texte du lien “Décocher tout”.	Uncheck All
noneSelectedText	Le texte affiché par défaut dans le multiselect quand aucune option n'a été sélectionné.	Select options
selectedText	Le texte à afficher dans le multiselect lorsque les options sont sélectionnées (si selectedList est initialisée à faux ). Le signe dièse (#) sera automatiquement remplacé par le nombre des checkboxes sélectionnés. Si deux signes dièse sont présents dans ce paramètre, le second sera remplacé par le nombre total des checkboxes disponibls. Exemple : " # sur # sont séléctionné(s) " . Ce paramètre accepte également une fonction anonyme avec trois arguments: le nombre des checkboxes cochés, le nombre total des checkboxes, et un tableau DOM des checkboxes cochés . Voir les exemples pour l'utilisation .	# selected
selectedList	Une valeur numérique (ou booléenne "faux" pour la désactivation) indiquant si oui ou non le widget listera les options sélectionnés sur le multiselect, et combien. Un nombre supérieur à 0 indique le nombre maximum des options de la liste à afficher avant de basculer sur l'option selectedText. Une valeur de 0 ou faux pour la désactivation .	false
show	L'effet qui va être utilisé quand le menu du multiSelect s'ouvre. Pour contrôler la vitesse utiliser un tableau: ['slide', 500]	empty string
hide	L'effet qui va être utilisé quand le menu du multiSelect se ferme. Pour contrôler la vitesse utiliser un tableau: ['explode', 500]	empty string
autoOpen	Une valeur booléenne indiquant si oui ou non le menu sera automatiquement ouvert lorsque le widget est initialisée .	false
multiple	Si cette option est mise à "false" une seule option pourra être sélectionné (comme dans un select non multiple)	true
classes	Les Classes supplémentaire(s) que vous voudrez appliquer à la fois au bouton ou menu du widget pour une personnalisation plus poussée. Séparez plusieurs classes par un espace. Vous aurez besoin de faire la différence entre le bouton et menu à la portée de votre CSS : /* button */ .ui-multiselect.myClass {} /* menu */ .ui-multiselect-menu.myClass {}	empty string
position	Cette option vous permet de positionner le menu où vous voulez par rapport au bouton; centrée, au dessus, au dessous (valeur par défaut ), etc... Elle fournit également la détection de collision pour retourner le menu au dessus de son bouton lorsqu'il se retrouve en bas de la fenêtre. Si vous ne définissez pas cette option ou si l'utilité de position n'a pas été inclus, le menu s'ouvre en dessous du bouton. Nécessite l'utilitaire jQuery UI 1.4.3+ et jQuery position utility.	empty object

Événements

Lier un des événements ci dessous à votre multiselect, soit à travers le gestionnaire d'événements ou pendant l'initialisation.

// Lier à un évènement bind  

  $("#multiselect").bind("multiselectopen", function(event, ui){
     // Mettre l’évènement ici
  });
// Passé pendant initialisation
  $("#multiselect").multiselect({
     open: function(event, ui){
             // Mettre l'événement ici
    }
  }); 

évènement	Description
create	Se déclenche lorsque le widget est créé pour la première fois. Nécessite l'utilitaire jQuery UI Core 1.8.6+
beforeopen	Se déclenche juste avant que le menu s'ouvre. Empêche le menu de l'ouverture en retournant false au gestionnaire.
open	Se déclenche après l'ouverture du widget.
beforeclose	Se déclenche juste avant la fermeture du menu. Empêche le menu de fermeture en retournant false au gestionnaire.
close	Se déclenche après la fermeture du widget.
checkall	Se déclenche lorsque toutes les options sont cochées soit en cliquant sur le lien "cocher tous" dans l'en-tête, ou quand la méthode "checkall" est appelée dans le script (voir la section suivante).
uncheckall	Se déclenche lorsque toutes les options sont décochées soit en cliquant sur le lien "décocher tous" dans l'en-tête, ou quand la méthode "uncheckall" est appelée dans le script (voir la section suivante).
optgrouptoggle	Se déclenche lorsqu'un groupe d'option est cliqué. Cet événement reçoit l'objet d'événement d'origine comme premier argument, et une table de valeurs comme seconde argument: $("#multiselect").bind("multiselectoptgrouptoggle", function(event, ui){ /* event: l'objet de l'événement d'origine, souvent "click"   ui.inputs: un tableau de checkboxes (éléments DOM) à l'intérieur du optgroup (groupe d'option)   ui.label: le libellé de l'optgroup (groupe d'option)   ui.checked: si oui ou non les cases à cocher ont été cochées ou décochées dans le toogle (booléen) */ });
click	Se déclenche lorsqu'un checkbox a été coché ou décoché $("#multiselect").bind("multiselectclick", function(event, ui){ /* event: l'objet de l'événement d'origine, souvent "click"   ui.value: la valeur du checkbox ui.text: libellé du checkbox ui.checked: si oui ou non les cases à cocher ont été  cochées ou décochées (boolean) */ });

Méthodes

Après l'initialisation d'une instance, vous pouvez interagir avec le widget en appelant l'une des méthodes ci dessous:

      // exemple:

      $("#multiselect").multiselect("nom_de_méthode");

Méthode	Description
open	Ouvre le menu du widget
close	Ferme le menu du widget
refresh	Recharge les options du select. Si vous ajouter/supprimer dynamiquement des options du select original depuis l'ajax ou à travers les méthodes du manipulation du DOM appeler "refresh" afin d'appliquer les changements sur le widget.
disable	Désactive le widget (menu et button).
enable	Active le widget (menu et button).
checkAll	Coche tous les checkbox.
uncheckAll	Décoche tous les checkbox.
isOpen	Retourne un booléen dénotant si le widget est actuellement ouvert ou non.
getChecked	Retourne un tableau des checkbox cochés.
widget	Retourne le conteneur menu (tous les checkbox à l'intérieur).
option	Modifie ou retourne la valeur d'une option de création du multiSelect même après l'initialisation du widget. La modification d'une option prend effet immédiatement.
destroy	Détruis le widget, et réaffiche le select original.

Le plugin filtrage:

Un widget de filtrage est disponible qui, une fois initialisé sur une instance de sélection multiple, permet d'insérer une zone de texte à l'intérieur de l'en-tête du widget pour filtrer les options correspondants à l'entrée.

      // exemple de création d'un multiselect avec filtre:
      $("#multiselect").multiselect("").multiselectfilter();