💡📋 xlsconv: Command-line tool to convert questionnaires from Open Data Kit's XLSForm format into Django models and HTML (for use with https://wq.io/).
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests include on_delete setting for ForeignKey Apr 24, 2018
.travis.yml deprecate Python 2.7 support Jun 12, 2018
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jul 15, 2017
LICENSE update copyright year Jun 12, 2018
runtests.sh integrate and test all wq.start templates Jul 8, 2016
setup.py update version for dev Jun 12, 2018


xlsform-converter (xlsconv)

xlsform-converter converts surveys defined via the XLSForm standard into Django models and HTML5 Mustache templates. This makes it possible to re-use the powerful form building tools provided by the Open Data Kit ecosystem, while leveraging Django's robust support for relational databases like PostgreSQL.

xlsform-converter is designed to facilitate the rapid development of offline-capable data collection apps via the wq framework. The ultimate goal is to provide full compatibility with the form authoring tools provided by ODK (and Enketo, etc.). Note that this is not the same as full XForm compatibility: the client and server components of wq (wq.app and wq.db) use a JSON-based REST API to exchange data and are not directly compatible with their ODK Analogues (ODK Collect and ODK Aggregate, respectively).

For the database itself, the key distinction from other XLSForm tools (including some powered by Django) is that xlsform-converter converts the xlsform fields directly into a Django model definition, rather than representing the entire XForm standard within Django. This means that each row in an XLSForm "survey" tab is mapped to (usually) a single column in a simple relational database table. Repeat questions are handled by creating a second model with a ForeignKey to the parent survey model.

xlsform-converter also supports a couple of additional "constraints" that are not part of the XLSForm standard:

  • wq:ForeignKey('app.ModelName'): Create a foreign key to an existing Django model (presumably not defined in the spreadsheet). This is effectively a more relational version of select_one_external.
  • wq:initial(3): Very similar to repeat_count, but only set for new records.
  • wq:length(5): Text field maximum length (similar to a string-length constraint)

Latest PyPI Release Release Notes License GitHub Stars GitHub Forks GitHub Issues

Travis Build Status Python Support

Included Templates

xlsform-converter uses the following templates to generate Django/wq project files from a given XLSForm.

Django App Templates

Mustache Templates (for use with wq)


If you are using wq, you may be interested in wq.start, which uses xlsconv internally for the wq addform and wq maketemplates commands. Otherwise, you can use xlsconv directly with the following command-line API:

# Recommended: create virtual environment
# python3 -m venv venv
# . venv/bin/activate

# Install xlsconv
pip install xlsconv

# Use the default models.py template
xls2django my-odk-survey.xls > myapp/models.py

# Use the rest.py template (or admin.py, or serializers.py)
xls2django my-odk-survey.xls rest > myapp/models.py

# Use a custom template
xls2django my-odk-survey.xls my_templates/models.py > myapp/models.py

# Use the default edit.html template
xls2html my-odk-survey.xls > templates/survey_edit.html

# Use the list.html template (or detail.html, or popup.html)
xls2html my-odk-survey.xls list > templates/survey_list.html

# Use a custom template
xls2html my-odk-survey.xls my_templates/edit.html > templates/survey_edit.html