VIAMICHELIN JAVASCRIPT API


Examples

Introduction

 

The completion in APIJS represents a set of components in a package called ViaMichelin.Api.Completion.

The completion component allows you to apply an intuitive typing system to an input text. It is easy and fast to implement, as you can check on the quickstart guide.

At entering datas on the input, the completion component will trigger a coherent request according to the entry. The most revelant results will appear under the field. The user will be able to select one the the suggestions or go on typing, while the list of proposal is updating. If the user select a result, it appears on the field.

The completion system suggests informations for countries name, administrative areas, cities and addresses.

 

Easy and fast use

You can get an functionnal completion system address without specify options or event listeners (conf and callbacks).

Only the input text has to be specify on the configuration of the component with the input property.

You can check this example with more details on the quickstart guide.




<div>Saisissez une adresse</div>
<div><input id="address" type="text" /></div>


var conf = { input : document.getElementById("address") };

VMLaunch("ViaMichelin.Api.Completion.Address", conf);

Consult the demonstration page.

 

Regroup informations

The completion suggests you 4 types of results: country, administrative areas, cities, addresses.

By default, the suggestions are listed one after the other, without distinction.

But it is possible to regroup it and interpose the labels of regrouping.

To activate these functionalities, you have to put 2 parameters:

-       grouping at “true”, which specifies if the regrouping has to occur,

-       groupingOptions which specifies the labels of regrouping

 


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

Check the demonstration page.

 

The request parameters

On the configuration of the component, it is possible to influence its behavior or the type of request.

All the options have to be specify inside the variable conf, as a property called parameters.

 

  
var conf = {
  input : document.getElementById("address"),
  parameters : {
    // search list//
  }
};

You can find examples of parameters below.

 

The geographic parameters

The country restriction option

By default, the request is applied all over the world. If you want to restrict to a specific country, you have to indicate the exclusiveCountry parameter.

 


var conf = {
  input : document.getElementById("address"),
  parameters : {
    exclusiveCountry : "FRA"
  }
};

Consult the demonstration page.

Prioritize a country

You can also prioritize a country, without restricting its area, on the request.

You have to specify favoriteCountry parameter on the configuration.


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

Consult the demonstration page.

Prioritize a country and the closest countries around

It is also possible to prioritize a country and the countries around. The closer countries will take more weight on the request. You have to specify favoriteCountrySpacial parameter.

 


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

Consult the demonstration page.

 

The language parameters

Places have sometimes different name depending on the language of the country.

For example, the city of Paris has several names :

- Paris (french) 
- Pariisi (finnish) 
- Παρίσι (greek) 
- Parijs (dutch) 
- Parigi (italian) 
- París (spanish)

 

When the user types the first letters, the request is applied to all the designations available in each place (country, areas, cities, addresses).

Then, if you type “deut”, “Germany” will appear on the suggestions because the germans call their country Deutschland.

 

Filter the languagues on the request

With the lang parameter, only the languages specified will be used for the search.

Then, if you specify French on the configuration, the request will be applied only on the french labels of the different places.


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

Consult the demonstration page.

 

Limit and filtering the result

Limit the quantity of the result

If you want to limit the quatity of the suggestions, you have to specify it with the maxResults parameter.

 


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

Consult the demonstration page.

 

Limit the quantity of the country result

It is also possible to limit the quantity of a type suggestions with the parameter maxResultsCountry, for example.


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

Consult the page demonstration.

 

Handle or limit the quantity of administrative areas

As well as the country, you can limit the administrative area with the maxResultsAdmin parameter.


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

Consult the demonstration page.

 

Limit the quantity of cities suggestions on the result

As well as the previous example, with maxResultsCity for cities limitations.


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

Consult the demonstration page.

 

Limit the number of addresses suggestions

As well as the previous examples, with maxResultsAddress for address limitations.

 


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

Consult the demonstration page.

 

Suggest only the cities

In order to handle the quantity of  a category, you have reset the parameters you want to restrict, like the example below.


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

Consult the demonstration page.

 

Narrow and refine the search

In this example, we limit the quantity of result at 10, without countries and administrative areas and maximum 3 cities.



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


The quantity of adresses hasn’t be specified, addresses will appear on the suggestions after cities to reach at all 10 results.

 

Examples

If you get 4 results for cities, the 3 first results will be selected then 7 addresses for the rest of the result.

If you get 2 results for cities, the 2 first results will be selected then 8 addresses for the rest of the result.

If you get 6 results for cities and 2 addresses, the 3 first results will be selected then 2 addresses for the rest of the result. I won’t get 10 results.

 

Consult the demonstration page.

 

Stylize the list of the results with CSS

It is possible to customize the list of suggestions using only the style sheet.

Several CSS classes are available on the DOM. You can override the actual style by redefine your own style on your css sheet, using the proper class.

 

The HTML generated

In order to override our CSS style, refer to the HTML code example below, generated by the completion.


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

example illustrating a search with "par", and limited to 4 results

Add a class on the root element

It is possible to add a class on the HTML element which contains “vmapi-completion” class.

It will help you to create your style sheets. The class you specified will be added on the HTML element, in addition to vmapi-completion class.

You need to set the wrapperClassName like the example below.

 

Declaration on the style-sheet :



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


Specifying the class on the configuration of the component :

 


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

Consult the demonstration page.

 

Choose the css class

The option corresponding is activeLineClassName.

Its value is the class selected on the keyboard.

Its default value is “vmapi-item-active”.

 

Declaration of the style-sheet :



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


Specify the class on the configuration component :



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

Consult the demonstration page.

 

Customize the items of the suggestions

The option corresponding is lineClassName.

You can customize the items of the suggestions when the cursor mouse goes hover it.

You have to use the activeLineClassName parameter.

Its default value is vmapi-completion-item.

The value taken is the class to apply for  suggestions.

 

Declaration of the class :



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


You have to specify the class on the completion component :



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

Consult the demonstration page.

 

Activate the search on the focus

By default, the suggestions start to be launched at the data entry. But it is possible to activate the search at the focus of the field.

The suggestions will be displayed at the click on the field, if the user already inserted informations.

The search won’t be launched if the field is empty.

To activate the search on the focus, you need to set the searchOnFocus parameter value at “true”.

 



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

Consult the demonstration page.

 

Display the result at the top of the field

You can display the list of suggestions on a reverse sense.

The list will appear above the input field and the results will be ordered from the bottom to the top.

To activate the reverse option, you need to set revertMode parameter value at “true”.

 



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

Consult the demonstration page.