guide complet · FR

Construire un questionnaire
de zéro, cellule par cellule.

XLSForm est le standard qui transforme un simple tableur en formulaire numérique complet — avec logique de saut, validation, GPS, photos et plusieurs langues — prêt à tourner sur ODK Collect, KoboToolbox ou Enketo. Ce guide construit une enquête ménage pas à pas et documente tous les types de questions et réglages, avec des exemples à copier et convertir avec rxform.

1 · Anatomie d’un XLSForm

Un XLSForm est un fichier .xlsx (ou .xls/.ods) avec jusqu’à trois feuilles principales :

• survey — les questions, dans leur ordre d’apparition. Colonnes minimales : type, name et label.
• choices — les listes d’options des questions à choix. Colonnes minimales : list_name, name et label.
• settings — titre, identifiant, version, langue par défaut et autres réglages du formulaire (une seule ligne de données).

Règles d’or pour la colonne name (questions, groupes et options) :

2 · Le premier formulaire

Le plus petit formulaire utile tient en trois lignes de la feuille survey :

La question de la ligne 4 utilise la liste oui_non, définie dans la feuille choices :

Et la feuille settings donne son identité au formulaire :

Convertissez, et c’est prêt :

$ rxform enquete_menage.xlsx
enquete_menage.xml

3 · Tous les types de questions

Texte et nombres

• text — texte libre. Pour une zone plus haute, parameters = rows=5.
• integer / decimal — nombres, avec le pavé numérique sur l’appareil.
• range — curseur ; bornes via parameters = start=0 end=10 step=1. Avec appearance = rating, des étoiles.

Dates et heures

Apparences utiles pour date : month-year, year et no-calendar.

Choix et listes

• select_one LISTE — une réponse. appearance : minimal (menu déroulant), likert, quick (avance seul), columns…
• select_multiple LISTE — plusieurs réponses ; stockées séparées par des espaces, d’où l’interdiction d’espaces dans les name des options.
• rank LISTE — l’enquêté ordonne les options.
• select_one LISTE or_other — ajoute l’option « Other » et une question automatique « Specify other. ».

Des colonnes supplémentaires dans choices sont permises et deviennent des données de l’option — la base des filtres en cascade :

Sélections en cascade (choice_filter)

Dans le filtre, les colonnes de la liste s’écrivent par leur nom (region) et les réponses précédentes en ${region}. Pour mélanger les options : parameters = randomize=true (avec seed=42 pour un ordre reproductible).

Localisation

geopoint capture un point (précision cible en mètres via parameters) ; geotrace, une ligne ; geoshape, un polygone fermé.

Médias et fichiers

image avec appearance = signature devient un champ de signature ; draw, dessin libre. max-pixels réduit la taille des photos sur l’appareil.

Notes et confirmations

• note — texte affiché, sans réponse. Accepte les ${références} : « Merci, ${enqueteur} ! ». Seul type qui peut omettre name (rxform en génère un).
• acknowledge — exige un « ok » explicite de l’enquêté.

Champs invisibles

calculate calcule une valeur en XPath (fonctions if(), concat(), selected(), count(), round()…) ; hidden stocke une valeur remplie par default ou des intégrations.

Métadonnées — collectées toutes seules

• start/end — horodatage d’ouverture/fin ; today — la date ; deviceid, username, phonenumber, email — identification de l’appareil/du compte.
• audit — journal d’audit de la saisie ; avec parameters = location-priority=balanced location-min-interval=60 location-max-age=120, il journalise aussi la position pendant l’entretien.
• start-geopoint — capture silencieuse de la position à l’ouverture ; background-audio enregistre l’audio de l’entretien ; background-geopoint capture la position quand la question du trigger est renseignée.

4 · Logique du formulaire

Toute la logique utilise ${nom} pour référencer des réponses précédentes.

relevant — sauter des questions

La question n’apparaît que si l’expression est vraie. Combinez avec and/or ; pour les choix multiples, selected(${services}, 'eau').

constraint — valider les réponses

Le point . est la réponse elle-même. Le message s’affiche quand la règle échoue.

required, default, read_only

• required = yes (ou une expression) empêche d’avancer sans réponse.
• default accepte une valeur fixe (42) ou une expression dynamique (today(), ${region}) évaluée à l’ouverture — y compris ${last-saved#secteur} pour hériter du dernier envoi.
• read_only = yes affiche sans permettre l’édition.

trigger — recalculer au changement

Avec trigger, le champ est (re)défini chaque fois que la question référencée change — ici, en vidant enfants quand taille_menage est modifié. S’il y a une calculation, elle s’exécute à ce moment-là (au lieu d’en continu).

5 · Groupes, répétitions et boucles

Groupes

• appearance = field-list affiche tout le groupe sur un seul écran.
• table-list — pour une suite de select_one partageant une liste, affiche une matrice (lignes × colonnes).
• Le relevant du groupe s’applique à tout son contenu.

Répétitions

Le bloc se répète une fois par résident. Sans repeat_count, l’enquêteur ajoute les répétitions à la main ; avec une expression (ou un nombre), le compte est automatique. À l’intérieur, position(..) donne l’indice courant et indexed-repeat() lit les valeurs d’une autre répétition.

Boucles sur une liste

Génère un bloc par option de la liste services, en substituant %(label)s et %(name)s — une question « Comment évaluez-vous le service Eau ? », une autre « …Assainissement ? », etc.

6 · Plusieurs langues

Il suffit de suffixer les colonnes traduisibles avec ::Langue (code) : label, hint, guidance_hint, constraint_message, required_message, image, audio et video — dans survey et choices. Fixez la langue initiale dans settings → default_language = Français (fr). L’application gagne un menu de langues.

Média par question : les colonnes image/audio/video associent des fichiers (ex. carte_reponse.jpg) envoyés avec le formulaire.

7 · Apparences (appearance)

8 · Paramètres (parameters)

La colonne parameters reçoit des paires clé=valeur séparées par des espaces :

9 · La feuille settings

10 · Données externes et entités

Grandes listes en fichier

Le CSV requiert des colonnes name et label (ou indiquez-en d’autres avec parameters = value=code label=description) ; le GeoJSON utilise id/title et active appearance = map. Le fichier est téléversé avec le formulaire.

Recherches avec pulldata()

Cherche dans cibles.csv la colonne cible de la ligne où secteur = la réponse. Il y a aussi ${last-saved#champ} (valeur du dernier envoi) et la feuille entities, qui permet au formulaire de créer et mettre à jour des registres partagés entre formulaires (ex. enregistrer des ménages lors d’une visite et les retrouver à la suivante) — via save_to sur les questions et create_if/update_if/label sur la feuille.

11 · Erreurs courantes — et comment rxform prévient

• Type mal orthographié → [sheet 'survey', row 3, column 'type'] unknown question type 'integr' — did you mean 'integer'?
• Référence cassée → '${agge}' does not match… — did you mean 'age'?
• Liste inexistante → pointe la ligne et suggère la liste la plus proche.
• Groupe non fermé → pointe la ligne du begin_group et réclame le end_group.
• Noms dupliqués entre frères, nom avec espace/accent, question visible sans label, options répétées dans une liste — le tout avec feuille, ligne, colonne et cause probable.

12 · Convertir et publier

# convertir
$ rxform enquete_menage.xlsx
enquete_menage.xml

# vérifier les erreurs d’édition = simplement lancer — le message pointe la cellule
$ rxform enquete_menage.xlsx --stdout > /dev/null

1. KoboToolbox : téléversez le .xlsx lui-même (Kobo convertit côté serveur avec pyxform — rxform produit exactement le même XML, donc il sert de validation locale instantanée) ou déployez le XML via l’API.
2. ODK Central : publiez le .xlsx ou le .xml généré ; joignez les CSV/GeoJSON des listes externes.
3. Enketo : les formulaires publiés reçoivent automatiquement un lien web.

guide · rxform — retour à l’accueil · référence officielle xlsform.org