114 lines
3.3 KiB
Plaintext
114 lines
3.3 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
||
type="topic" id="api-fill" 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>Transmission de données</desc>
|
||
|
||
</info>
|
||
|
||
<title>Complétion et soumission d'un formulaire</title>
|
||
|
||
<p>
|
||
w.c.s expose une API autorisant les logiciels tiers à transmettre des données
|
||
structurées permettant la complétion d'un formulaire. Deux modes d'opération
|
||
sont possibles, dans le premier l'ensemble des données est fourni en une étape
|
||
unique (mode données), dans le second les données sont fournies en fonction des
|
||
différentes pages définies dans le formulaire (mode flux).
|
||
</p>
|
||
|
||
<section id="data">
|
||
<title>Mode données</title>
|
||
|
||
<p>
|
||
Ce mode est le plus simple et le plus adapté au développement d'un système
|
||
tout automatique, sans interaction avec un utilisateur.
|
||
</p>
|
||
|
||
<p>
|
||
La complétion d'un formulaire se fait par une requête <code>POST</code> à
|
||
l'adresse <code>/api/formdefs/<var>slug</var>/submit</code>, le contenu de
|
||
la requête doit être un dictionnaire contenant obligatoirement un attribut
|
||
<code>data</code> et optionnellement un attribut <code>meta</code> et un
|
||
attribut <code>context</code>.
|
||
</p>
|
||
|
||
<p>
|
||
L'attribut <code>data</code> est obligatoire et contient un dictionnaire
|
||
dont les clés sont les identifiants des champs du formulaire et les valeurs
|
||
le contenu de ces champs.
|
||
</p>
|
||
|
||
<p>
|
||
L'attribut <code>meta</code> est optionnel et contient une série de
|
||
paramètres supplémentaires concernant le formulaire.
|
||
</p>
|
||
|
||
<table shade="rows">
|
||
<title>Métadonnées</title>
|
||
<tr>
|
||
<td><p><code>draft</code></p></td>
|
||
<td><p><code>true</code> pour enregistrer le formulaire comme étant un
|
||
brouillon.</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><code>backoffice-submission</code></p></td>
|
||
<td><p><code>true</code> pour enregistrer le formulaire comme étant
|
||
saisi depuis le backoffice.</p></td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p>
|
||
L'attribut <code>context</code> est également optionnel et contient une
|
||
série de renseignements supplémentaires sur le contexte de l'envoi du
|
||
formulaire. Les attributs reconnus sont <code>channel</code>,
|
||
<code>thumbnail_url</code>, <code>user_id</code> et <code>comments</code>.
|
||
</p>
|
||
|
||
<p>
|
||
L'exemple suivant complète un formulaire d'inscription à une newsletter, qui
|
||
demanderait trois champs, prénom, nom et adresse électronique.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Content-type: application/json" \
|
||
-H "Accept: application/json" \
|
||
-d@donnees.json \
|
||
https://www.example.net/api/formdefs/newsletter/submit</input>
|
||
<output>{"err": 0, "data": {"id": "1"}}</output>
|
||
</screen>
|
||
|
||
<p>
|
||
Le fichier de données utilisé (<file>donnees.json</file>) contient le
|
||
dictionnaire JSON suivant :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"data": {
|
||
"1": "Marc",
|
||
"2": "L.",
|
||
"3": "marc@example.net"
|
||
}
|
||
}
|
||
</code>
|
||
|
||
</section>
|
||
|
||
<section id="flow">
|
||
<title>Mode flux</title>
|
||
|
||
<p>
|
||
Ce mode est à utiliser si l'on veut exposer à un usager les différentes
|
||
étapes de la complétion d'un formulaire.
|
||
</p>
|
||
|
||
</section>
|
||
|
||
</page>
|