Un Readme

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`)