<page xmlns="http://projectmallard.org/1.0/"
      type="topic" id="api-datasource" xml:lang="fr">

<info>
  <link type="guide" xref="index#api" />
  <revision docversion="0.1" date="2013-01-04" status="draft"/>
  <credit type="author">
    <name>Frédéric Péters</name>
    <email>fpeters@entrouvert.com</email>
  </credit>
  <desc>Bases de données, autocomplétion, etc.</desc>

</info>

<title>Accès à des référentiels externe</title>

<p>
w.c.s. peut utiliser des référentiels externes pour par exemple alimenter la
liste des choix possibles dans un champ; pour ce faire w.c.s. utilise le
protocole <link href="http://en.wikipedia.org/wiki/JSONP">JSONP</link>.
L'adresse appelée doit répondre aux exigences suivantes :
</p>

<list>
 <item><p>retourner les données, triées, dans un attribut nommé
          <code>data</code> ;</p></item>
 <item><p>présenter chaque élément des données dans un dictionnaire contenant
          deux éléments, <code>id</code> contenant un identifiant unique et
          <code>text</code> contenant le texte de la valeur ;</p></item>
 <item><p>accepter un paramètre <code>callback</code> permettant de définir
          le nom de la fonction Javascript devant être appelée ;</p></item>
 <item><p>accepter un paramètre <code>q</code> permettant de filtrer les
          résultats.</p></item>
</list>

  <screen>
<output style="prompt">$ </output><input>curl https://www.example.net/data/fruits?q=po&amp;callback=cb</input>
<output>cb({
    "data": [
        {
            "text": "Poire",
            "id": "1"
        },
        {
            "text": "Pomme",
            "id": "2"
        }
    ]
});</output></screen>

<note><p>
En plus des clés <code>id</code> et <code>text</code> qui sont obligatoires,
les différents éléments peuvent contenir des clés supplémentaires, pour des
informations annexes. Celles-ci seront alors accessibles dans les variables
de contexte du formulaire.
</p></note>

</page>
