VIAMICHELIN JAVASCRIPT API


Exemples

Introduction

La completion dans l'APIJS est un ensemble de composants regroupés sous le package ViaMichelin.Api.Completion.

Le composant ViaMichelin.Api.Completion.Address permet d'appliquer à un champ texte une saisie intuitive d'adresse. Il est simple à utiliser et très rapide à mettre en place comme vous pouvez le constater dans le quickstart guide.

Lors de la saisie de l'utilisateur, le composant de completion va déclencher une recherche d'adresse en cohérence avec les caractères saisis. Les résultats les plus pertinents seront proposés en dessous du champ texte. 
L'utilisateur pourra en choisir un, ou continuer à taper, la liste de propositions se mettant à jour. Si l'utilisateur clique sur un résultat, celui-ci s'affiche dans le champ texte à la place de sa saisie.

Les catégories proposées par l'autocomplétion sont les suivantes : pays, zones d'administratives, villes et adresses.

 

Utilisation simple et rapide

Vous pouvez disposer d'une completion d'adresse fonctionnelle sans avoir besoin de spécifier d'option ou d'écouter d'événements.

Seul le champ texte concerné est alors à spécifier dans la configuration du composant avec la propriété input.

Si vous ne l'avez pas lu, vous pourrez retrouver cet exemple de façon plus détaillée dans le quickstart guide.

<div>Saisissez une adresse</div>
<div><input type="text" id="address" /></div>
		
var conf = {
  input : document.getElementById("address")
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

 

Regrouper les informations

Comme évoqué dans l'introduction, les résultats proposés en retour de l’auto complétion, peuvent représenter :  une ville, une adresse postale ou une zone administrative.

Par défaut, aucun ordre de classement  n’est appliqué à l’appel de ce composant.  

Cependant, il est possible de regrouper les résultats par catégorie (pays, admin, ville, adresses). L’algorithme propose d’abord, les premières suggestions liées aux pays, ensuite les régions et enfin  villes et adresses. 

Pour activer cette fonctionnalité, il faut renseigner les 2 paramètres suivants : 

            - grouping en mettant sa valeur à true 
            - groupingOptions qui permet de spécifier les valeurs des libellés de chaque catégories

var conf = {
  input : document.getElementById("address"),
  grouping : true,
  groupingOptions : {
    labels : {
      COUNTRY : "Pays",
      ADMIN : "Régions",
      CITY : "Villes",
      ADDRESS : "Adresses"
    }
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

 

Les paramètres de recherche

Dans la configuration du composant, il est possible d'agir sur son comportement, ou sur la recherche de données. 
Toutes les options concernant la recherche de données sont à spécifier dans en tant que propriétés de l'objet parameters.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    // liste des paramètres de recherche
  }
};
		

Vous trouverez des exemples de paramètres ci-dessous.

 

Les paramètres géographiques

Restreindre à un pays

Par défaut, la recherche d'adresses se fait sur le monde entier. 
Si vous souhaitez restreindre la recherche à un pays spécifique, il est faut spécifier le paramètre exclusiveCountry.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    exclusiveCountry : "FRA"
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Favoriser un pays

Vous pouvez mettre en avant les résultats d'un pays sans restreindre la recherche à celui-ci. 
Pour cela, il faut spécifier le paramètre favoriteCountry.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    favoriteCountry : "FRA"
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Favoriser un pays et les pays qui en sont proches

Il est également possible de ne pas seulement favoriser les résultats d'un pays, mais également ceux des pays qui en sont proches : plus un pays sera proche, plus ses résultats auront du poids. 
Pour cela, il faut spécifier le paramètre favoriteCountrySpacial.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    favoriteCountrySpacial : "FRA"
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

 

Les paramètres de langue

La completion propose des lieux en cohérence avec votre saisie. Ces lieux ont parfois plusieurs noms, selon la langue qui les désigne.

Par exemple, pour la ville de Paris, nous pouvons trouver les désignations suivantes : 
- Paris (français) 
- Pariisi (finois) 
- Παρίσι (grec) 
- Parijs (néerlendais) 
- Parigi (italien) 
- París (espagnol)

Lorsque l'utilisateur saisit les premières lettres, la recherche va s'effectuer sur toutes les désignations disponibles de chaque lieu (pays, régions, villes, adresses)

Ainsi si vous saisissez deut, vous verrez comme proposition l'Allemagne, car les allemands nomment leur pays Deutschland.

Filtrer les langues de recherche

Avec le paramètre lang, seules les langues spécifiées seront utilisées pour la recherche. 
Ainsi, si vous spécifiez le français, la recherche ne se fera que sur les libellés français des différents lieux.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    lang : ["fra"]
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

 

Limiter/filtrer les résultats

Limiter le nombre de résultats

Si vous souhaitez limiter le nombre de propositions, il faut spécifier le paramètre maxResults.

var conf = {
input : document.getElementById("address"),
parameters : {
    maxResults : 4
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Limiter le nombre de résultats "pays"

Il est aussi possible de ne limiter que le nombre de propositions de pays avec maxResultsCountry.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    maxResultsCountry : 2
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Limiter le nombre de résultats "zones administratives"

De la même manière que les pays avec maxResultsAdmin.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    maxResultsAdmin : 2
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Limiter le nombre de résultats "villes"

De la même manière avec maxResultsCity.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    maxResultsCity : 2
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Limiter le nombre de résultats "adresses"

De la même manière avec maxResultsAddress.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    maxResultsAddress : 3
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Ne proposer que des villes

Pour ne pas avoir certains types de propositions, il faut indiquer le nombre maximum de résultat de ce type à 0.

var conf = {
  input : document.getElementById("address"),
  parameters : {
    maxResultsCountry : 0,
    maxResultsAdmin : 0,
    maxResultsAddress : 0
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Limiter plus finement les résultats

Dans cet exemple, nous souhaitons avoir 10 résultats maximum. Nous ne voulons pas de pays ou de zones administratives, et pas plus de 3 villes.

var conf = {
  input : document.getElementById("address"),
  parameters : {,
    maxResults : 10
    maxResultsCountry : 0,
    maxResultsAdmin : 0,
    maxResultsCity : 3
  }
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Le nombre d'adresses n'étant pas spécifié, les propositions d'adresses viendront compléter les villes jusqu'à avoir 10 résultats.

Exemples 
Si j'ai 4 correspondances de villes, je verrai les 3 premières puis 7 adresses. 
Si j'ai 2 correspondances de villes, je verrai les 2 villes et 8 adresses. 
Si j'ai 6 correspondances de villes et seulement 2 d'adresses, je verrai 3 villes et 2 adresses. Je n'aurai pas mes 10 résultats.

Consultez la page de démonstration.

 

Mettre en forme la liste de propositions avec CSS

Il est possible d'agir sur l'aspect de la liste de propositions de la completion en utilisant uniquement les feuilles de style.

De nombreuses classes CSS sont présentes dans le DOM généré. Vous pouvez les surcharger dans votre CSS pour mettre en forme la liste selon votre guise.

Le HTML généré

Afin de créer vos surcharges en CSS, prenez connaissance du HTML généré par la completion pour sa liste de propositions avec l'exemple ci-dessous.

<div class="vmapi-completion">
  <div class="vmapi-completion-list-wrapper">
    <ul class="vmapi-completion-list">
      <li class="vmapi-completion-item" rawvalue="Paraná">
        <span class="vmapi-item-highlight">Par</span>aná, Brésil
      </li>
      <li class="vmapi-completion-item" rawvalue="Pará">
        <span class="vmapi-item-highlight">Par</span>á, Brésil
      </li>
      <li class="vmapi-completion-item" rawvalue="Pardubický">
        <span class="vmapi-item-highlight">Par</span>dubický (<span class="vmapi-item-highlight">Par</span>dubice), Tchèque, République
      </li>
      <li class="vmapi-completion-item" rawvalue="Arica y Parinacota">
        Arica y <span class="vmapi-item-highlight">Par</span>inacota, Chili
      </li>
    </ul>
  </div>
</div>
		exemple en recherchant "par" avec limitation à 4 résultats

Ajouter une classe sur l'élément racine

Il est possible d'ajouter la classe de votre choix sur l'élément racine, celui comportant la classe vmapi-completion. Cela vous permettra par exemple de réaliser plus facilement votre surcharge CSS. 
La classe spécifiée sera ajoutée à l'élément racine en plus de vmapi-completion.

Pour cela, il faut renseigner le paramètre wrapperClassName de la manière suivante.

Déclarons une classe CSS :

.vmapi-completion.red-border {
  border:3px solid red;
}
		

Et spécifions la au composant de completion :

var conf = {
  input : document.getElementById("address"),
  wrapperClassName : "red-border"
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Création d'une classe CSS dynamiques au passage de la souris sur un item proposé

 

Vous avez la possibilité de modifier l'apparence des items au passage de la souris de façon dynamique.

Pour ce faire, vous disposez du paramètre activeLineClassName. Ce paramètre permet d’appliquer un style sur l’item survolé à la souris, ou sélectionné au clavier.

Sa valeur par défaut est vmapi-item-active.

Déclarons une classe CSS :

.pink-line {
  background-color:pink;
  color:blue;
}
		

Et spécifions la au composant de completion :

var conf = {
  input : document.getElementById("address"),
  activeLineClassName : "pink-line"
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Choisir la classe CSS appliquée à chaque ligne de proposition

L'option concernée est lineClassName.

Elle prend comme valeur la classe à appliquer à chaque ligne de proposition. 
Sa valeur par défaut est vmapi-completion-item.

Déclarons une classe CSS :

.cyan-line {
  background-color:cyan;
  color:blue;
}
		

Et spécifions la au composant de completion :

var conf = {
  input : document.getElementById("address"),
  lineClassName : "cyan-line"
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

 

Lancement de la recherche au focus

Par défaut, la recherche de propositions se lance lorsqu'un caractère est saisi. Mais il est possible de choisir de lancer la recherche au focus sur le champ.

Les propositions s'afficheront lorsque l'utilisateur cliquera sur le champ s'il y a déjà des caractères saisis. 
La recherche ne se lancera pas si le champ est vide.

Pour activer la recherche au focus, il faut utiliser le paramètre searchOnFocus avec la valeur true.

var conf = {
  input : document.getElementById("address"),
  searchOnFocus : true
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.

Afficher la liste au dessus du champ

Il est possible d'afficher la liste de propositions en mode inversé. 
La liste sera affichée au dessus du champ de saisie et les résultats seront ordonnés de bas en haut.

Pour activer le mode inversé, il faut utiliser le paramètre revertMode avec la valeur true.

var conf = {
  input : document.getElementById("address"),
  revertMode : true
};
VMLaunch("ViaMichelin.Api.Completion.Address", conf);
		

Consultez la page de démonstration.