Browse Source

Un Readme

pull/1/head
Matthieu Marcillaud 3 years ago
parent
commit
e599057a98
  1. 75
      Readme.md

75
Readme.md

@ -0,0 +1,75 @@
# Select2 Plugin pour SPIP
Ce plugin pour SPIP intègre la bibliothèque javascript [Select2](https://select2.org/) qui améliore l’usage des sélecteurs (balises `<select>`) natifs des navigateurs en facilitant entre autre la recherche d’un terme dans la liste.
## 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.
Il est possible d’activer Select2 sur l’espace public depuis cette configuration.
## Compléter la configuration par défaut
Select2 dispose de 2 manières de modifier sa configuration, soit par les attributs `data-xx` sur la balise `select`, soit en complétant ou modifiant la configuration en rappelant `.select2()` en javascript.
Par exemple :
```html
<select class="select2" id="s1" name="demo" data-placeholder="Ça va ?">
<option></option>
<option value="oui">Yep!</option>
<option value="non">Bof.</option>
</select>
```
```javascript
jQuery("#s2").select2({"placeholder": "La forme ?"});
```
La [documentation de Select2](https://select2.org/configuration) sera donc à étudier :)
## Addition du plugin SPIP
Un tout petit exemple de configuration supplémentaire non présente dans le javascript par défaut est ajouté au plugin SPIP : `data-sort-alpha="true"`. Si cet attribut est présent, les options de sélection seront triées par ordre alphabétique. Cela est réalisé de la sorte : 
```javascript
jQuery('select.select2[data-sort-alpha=true]').select2({
/*'sorter': data => data.sort((a, b) => a.text.localeCompare(b.text))*/
sorter: function(data) {
return data.sort(function(a, b) {
return a.text.localeCompare(b.text);
})
}
});
```
Il est assez facile de la sorte de compléter Select2 pour ses propres besoins.
## Autocomplete Ajax
On peut indiquer une URL de recherche à Select2 afin qu’il obtienne la liste des choix en fonction de la recherche tapée par l’utilisateur. Un exemple est proposé dans le plugin, visible sur la page de test.
Par exemple :
```html
<select class="select2" id="chiens" name="chiens[]"
data-placeholder="Quelle race de chien ?"
data-ajax-url="[(#URL_API{select2_autocomplete/demo/dogs}|attribut_html)]"
data-minimum-input-length="1"
>
</select>
```
L’API doit retourner un format spécifique (cf action/select2_autocomplete.php) pour fonctionner par défaut, mais du javascript supplémentaire peut servir pour adapter des apis déjà existantes. Cf. documentation [Ajax de Select2](https://select2.org/data-sources/ajax).
## 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();
```
Il faudra également adapter les styles CSS spécifiques si vous en utilisiez, par exemple en fournissant `css/select2_public.css` (corrolaire de `css/chosen_public.css`)
Loading…
Cancel
Save