Vicopo est un moyen léger et rapide rechercher une ville française et implémenter des propositions à la volée, l'autocomplétion d'un champ de ville ou de code postal et la conversion de l'un vers l'autre.
Testez-la ci-dessous en tapant le début d'un code postal ou du nom d'une ville :
API jQuery :
API en JS pur (ne nécessite aucune autre librairie) actuellement en beta-test :
Placez le code ci-dessus n'importe où sur votre page,
et insérez le script en fin de page (par exemple avant </body>) :
<script src="vicopo-vanilla.min.js"></script>
Si vous utilisez jQuery, insérez le script après jQuery (par exemple avant </body>) :
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script> <script src="vicopo-jquery.min.js"></script>
Ajoutez l'attribut data-vicopo à un élément et passez-lui en paramètre un
sélecteur qui pointera vers un champ(<input>,
<select> ou <textarea>).
Quand la valeur du champs change, l'élément sera duppliqué autant de fois
qu'il y a de villes commençant par la valeur tapée ou dont le code postal
commence par la valeur tapée (la recherche commence à partir de 2 caractères tapés).
À l'intérieur de ces éléments, les balises portant les attributs
data-vicopo-code-postal, data-vicopo-ville
seront respectivement pourvus du code postal et de la ville. Si ces balises
sont des champs, utilisez data-vicopo-val-code-postal et
data-vicopo-val-ville pour que les informations soient assignées
en tant que valeur.
Ajoutez l'attribut data-vicopo-click à ce même élément pour rendre les
choix clicables, cet attribut prend en valeur un objet JSON dont les clés sont les
sélecteurs et les valeurs la donnée à insérer au clic ("ville",
"code" ou n'importe quel texte dont les mots "code" et "ville" seront
remplacé par le code postal et la ville du choix sur lequel l'utilisateur a cliqué.
Alternativement, ajoutez l'attribut data-vicopo-get="ville" à l'élement
de saisie (input, textarea, etc.) et remplir le champ avec la ville au clic.
Utilisez data-vicopo-get="code" pour remplir le champ avec le code postal
ou data-vicopo-get="code ville" / data-vicopo-get="ville code"
pour obtenir les 2 dans l'ordre voulu.
Lors de l'appui sur Entrée, on récupère la première ville et
on l'applique comme nouvelle valeur du champ.
L'ajout optionnel de .vicopoTargets().vicopoClean() permet
d'effacer la liste de suggestions.
Les méthodes .vicopo(), .codePostal()
et .ville() appliquées à un élément jQuery permettent
de récupérer dans une variable le résultat de la recherche
à chaque lettre saisie dans le champ.
Les méthodes $.vicopo(), $.codePostal()
et $.ville() prennent en premier paramètre le code
postal ou la ville (partiel ou entier) recherché et en second
paramètre une fonction de callback appelée avec le terme recherché
en premier paramètre, les villes trouvées en second et en troisième
'code' pour une recherche de code postal ou 'city' pour une
recherche de ville.
https://vicopo.selfbuild.fr/cherche/680
{
input: "680",
cities: [
{
code: 68040,
city: "INGERSHEIM"
},
{
code: 68000,
city: "COLMAR"
}
]
}
Le paramètre cherche (ou search) permet de faire une
recherche parmi les villes et codes postaux. Utilisez ville
(ou city) pour chercher uniquement dans les villes, code
ou code-postal pour chercher dans les codes postaux
seulement.
https://vicopo.selfbuild.fr/ville/mul?format=callback
maFonction( { input: "mul", cities: [ { code: 67350, city: "MULHAUSEN" }, { code: 78790, city: "MULCENT" }, { code: 41500, city: "MULSANS" }, { code: 72230, city: "MULSANNE" }, { code: 68100, city: "MULHOUSE" }, { code: 68200, city: "MULHOUSE" }, { code: 57260, city: "MULCEY" } ] } )
Ce format JSONP peut être utilisé pour exécuter du code DSL (Dynamic Script Loading)
https://vicopo.selfbuild.fr/code/680?format=xml
<vicopo> <input>680</input> <cities> <city>INGERSHEIM</city> <code>68040</code> </cities> <cities> <city>COLMAR</city> <code>68000</code> </cities> </vicopo>
https://vicopo.selfbuild.fr/ville/argel?format=yaml
--- input: argel cities: - code: 65400 city: ARGELES-GAZOST - code: 40700 city: ARGELOS - code: 64450 city: ARGELOS - code: 65200 city: ARGELES-BAGNERES - code: 34380 city: ARGELLIERS - code: 11120 city: ARGELIERS - code: 66700 city: ARGELES-SUR-MER - code: 40430 city: ARGELOUSE ...
Comme n'importe quel web-service HTTP, vous pouvez appeler Vicopo depuis un programme ou un serveur en utilisant votre langage préféré (PHP, Node.js, Python, Ruby, C, C#, etc.), voici un exemple en PHP :
$ville = 'Lille'; $vicopoUrl = 'http://vicopo.selfbuild.fr/city/' . urlencode($ville); $json = @json_decode(file_get_contents($vicopoUrl)); $codePostal = ! is_object($json) || empty($json->cities) ? 'introuvable' : $json->cities[0]->code; echo $codePostal;
Vicopo est disponible via composer require kylekatarnls/vicopo :
<?php use Vicopo\Vicopo; print_r(Vicopo::http(75001)); print_r(Vicopo::https('paris'));
Vicopo est disponible sous node.js directement via npm install vicopo
dans un invité de commande puis require('vicopo') :
var ville = 'Lille'; var vicopo = require('vicopo'); vicopo(ville, function (err, cities) { if (err) { throw err; } else { console.log(cities); } });
Vicopo est disponible sous Ruby directement via gem install vicopo
dans un invité de commande puis require 'vicopo' :
require 'vicopo' ville = 'Lille' puts Vicopo.http ville
Vicopo est disponible sous Python directement via pip install vicopo
dans un invité de commande puis require 'vicopo' :
from Vicopo import Vicopo ville = Vicopo.http(75001) ville = Vicopo.http('paris')