@ -5,19 +5,41 @@ Ce plugin pour SPIP intègre la bibliothèque javascript [Select2](https://selec
## Fonctionnement
Select2 est actif dans l’espace privé pour tous les select ayant la classe CSS `select2`.
La configuration (Menu : Squelettes > Select2) permet de compléter les sélecteurs utilisés.
Select2 est actif dans l’espace privé
- pour tous les `select` ayant la classe CSS `select2`
- pour tous les `input` ayant la classe CSS `select2`
La configuration (Menu : Squelettes > Select2) permet de compléter les sélecteurs utilisés pour les `select`.
Il est possible d’activer Select2 sur l’espace public depuis cette configuration.
**Important:** L’identifiant (l’attribut `id`) de la balise `select` doit être unique sur la page ; Select2 ne peut s’activer qu’une fois par identifiant (le dernier appelé).
**Important:** L’identifiant (l’attribut `id`) de la balise `select`ou `input`doit être unique sur la page ; Select2 ne peut s’activer qu’une fois par identifiant (le dernier appelé).
## Compléter la configuration par défaut
Select2 dispose de 2 manières d’adapter sa configuration :
- soit en transmettant des options en JSON lors de l’appel à la fonction jQuery `.select2()` (ou `.spip_select2()` qui l’enrichit légèrement)
- soit par les attributs `data-xx` sur la balise `select`, qui prennent alors le pas sur les options transmises à l’initialisation.
### En appelant directement une méthode javascript
Par exemple :
- soit la fonction jQuery `.select2()` de la librairie d’origine, et en lui transmettant des options
- soit la fonction jQuery `.spip_select2()` qui enrichit la précédente
- soit `SpipSelect2.on_select(select, options)`, dont la fonction jQuery `.spip_select2` est un alias
- soit `SpipSelect2.on_input(input, options)`
Par exemple
```javascript
jQuery("select").select2({"placeholder": "La forme ?"});
jQuery("select").spip_select2({"placeholder": "La forme ?"});
SpipSelect2.on_select(document.querySelector("select"), {"placeholder": "Que dire ?"});
### Via des attributs data sur la balise `select` ou `input`
Ces attributs prennent alors le pas sur les options transmises à l’initialisation.
Par exemple
```html
<selectclass="select2"id="select1"name="demo"data-placeholder="Ça va ?">
<option></option>
@ -26,10 +48,6 @@ Par exemple :
</select>
```
```javascript
jQuery("#select2").select2({"placeholder": "La forme ?"});
```
La [documentation de Select2](https://select2.org/configuration) sera donc à étudier :)
@ -37,8 +55,12 @@ La [documentation de Select2](https://select2.org/configuration) sera donc à é
Des options supplémentaires non présentes dans le javascript par défaut sont ajoutées au plugin SPIP.
Ces options sont disponibles :
- si vous utilisez les classes CSS prévues sur les `select` (`.select2` ou tout autre configurée en plus par vos soins)
- si vous appelez directement la fonction `.spip_select2()`
- si vous utilisez les classes CSS prévues (`.select2` ou tout autre configurée en plus par vos soins)
- si vous appelez directement une des fonctions
- `SpipSelect2.on_select()`
- `SpipSelect2.on_input()`
- jQuery `.spip_select2()`
**Mais pas** si vous appelez directement la méthode `.select2()` native.
@ -74,14 +96,14 @@ un span `.select2-rendered__match` sur le terme recherché, qui est par défaut
### Action sur les input.select2
Le plugin permet de traiter des input (text) en les gérants via Select2, moyennant un mécanisme javascript qui recrée un select à côté de l’input, masque l’input, et mappe le résultat de la saisie
Le plugin permet de traiter des input (text) en les gérant via Select2, moyennant un mécanisme javascript qui recrée un select à côté de l’input, masque l’input, et mappe le résultat de la saisie
dans select2 dans la valeur de l’input qui sera posté. Ça gère aussi des saisies multiples
dès lors qu’un `data-separateur` tel que `data-separateur=","` est indiqué.
Cela s’applique
- automatiquement sur les `input.select2`
- ou manuellement via la méthode `input.spip_select2_on_input(options = {})`
- ou manuellement via la méthode `SpipSelect2.on_input(input, options = {})`
## Addition à la librairie javascript Select2
@ -115,18 +137,3 @@ L’API doit retourner un format spécifique (cf action/select2_autocomplete.php
### onAjaxLoad ...
**Attention** avec l’autocomplete ; Si vous appelez directement `.select2()` (ce n’est pas le cas `.spip_select2()` utilisé par le plugin cependant), chaque requête ajax pour obtenir la liste des éléments recherchés va déclencher la fonction SPIP `onAjaxLoad`. Votre code ne doit pas redémarrer l’initialisation des `select` déjà gérés par `Select2` dans ce cas (sinon vous verrez le sélecteur se refermer aussitôt !).
## Remplacer le plugin Chosen
Ce plugin peut remplacer le plugin [Chosen](https://plugins.spip.net/chosen.html).
Pour cela il faut soit déclarer la classe CSS `.chosen` dans la configuration du plugin Select2 pour qu’il s’applique dessus, soit appeler directement Select2 dans son propre code javascript, tel que :
```javascript
jQuery('select.chosen').select2();
// ou
jQuery('select.chosen').spip_select2();
```
Il faudra également adapter les styles CSS spécifiques si vous en utilisiez, par exemple en fournissant `css/select2_public.css` (corollaire de `css/chosen_public.css`)
