Application Designer Directory Structure

There are many folders and files within the Application Designer directory. Fortunately, the only ones that are of interest for a non-software-developer are:

  • app/ - folder containing everything that will be pushed to the Android device.

  • Gruntfile.js - contains the definitions of tasks that push files to the Android device, launch the Chrome browser, and pull data and log files off the Android device.

Initially, you will only be concerned with the contents of your app/ directory – the set of files that are placed on the Android device. As your sophistication grows, you may want to define your own grunt tasks to automate repetitive steps in your deployment and device management processes. Adding or modifying tasks is beyond the scope of this document; please refer to the grunt website (see Getting Started Building an Application for the link to that site).

For completeness, here is the full list of the files and sub-folder in this directory. Again, you generally do not need to be concerned with the contents or specifics of any of these:

  • app/ - folder containing everything that will be pushed to the Android device.

  • devEnv/ - contains the HTML for the 6 tabs of the Application Designer.

  • grunttemplates/ - contains template files used by grunt tasks.

  • node_modules/ - contains additional software installed by npm, such as external tools used by grunt.

  • scanFormDesigner/ - contains the Scan Form Designer tool.

  • test/ - contains tests of the computer-based simulated device environment.

  • themeGenerator/ - contains the HTML and JavaScript for the ODK-X ThemeGenerator CSS style and theme customization tool (accessed via the Customize tab).

  • xlsxconverter/ - contains the HTML and JavaScript for the ODK-X XLSX Converter tool that converts XLSX form definitions into formDef.json files (accessed via the XLSX Converter tab).

  • .bowerrc - JSON configuration for the bower tool.

  • .editorconfig - when your text editors are configured to use it, enables consistent formatting to files across all contributors to your application design. See EditorConfig.

  • .hgignore - source code management configuration.

  • .hgtags - source code management configuration.

  • .jshintrc - configuration for JSHint - a program that flags suspicious usage in programs written in JavaScript.

  • bower.json - used to control library management through bower. By default, the .bowerrc file has been configured to install these libraries in app/framework/libs/ so that you have access to them when your app is pushed to the phone.

  • deleteDefAndProp.sh - MacOSX shell script to traverse the relevant parts of the app/ directory and delete the definition.csv and properties.csv files.

  • Gruntfile.js - contains the definitions of tasks that push files to the Android device, launch the Chrome browser, and pull data and log files off the Android device.

  • index.html - the main HTML for the ODK-X Application Designer web page.

  • macGenConverter.js - MacOSX command-line wrapper for the XLSX Converter tool (converts a single XLSX file piped into stdin into a formDef.json on stdOut).

  • macGenFormDef.sh - MacOSX shell script to traverse relevant parts of the app/ directory and generate formDef.json files from XLSX files.

  • package.json - configuration information for npm.

  • README - description linking back to this document.

The app/ Folder

Everything in this folder mimics what is on the Android device. The directory looks as follows:

  • config - user-defined configuration for your application.

  • data - file attachments, and, on the device, the database.

  • output - on the device, logging files and exported CSV and media files.

  • system - files managed by the ODK-X tools (do not modify).

The app/config/ Folder

This folder is synced to the device. It contains all of the form and table configuration files and initialization scripts. This is the sub-folder in which you will be primarily working.

This folder contains:

  • assets

  • tables

The app/config/assets/ Folder

  • css/ - contains the common CSS files for ODK-X Tables detail, list and home screens, and for app forms in ODK-X Survey (odk_survey.css).

  • csv/ - contains the data files to be initially read and loaded into the ODK-X Survey and Tables databases.

  • fonts/ - contains the fonts used throughout the application.

  • framework/ - contains the framework.xlsx and other relevant framework files.

  • img/ - contains the images used throughout the application.

  • js/ - contains JavaScript used by the ODK-X Tables custom home screen and/or the ODK-X Survey custom forms list

  • libs/ - contains the various libraries used throughout the application like jQuery and D3.

  • tables.init - contains the initialization directives for which data (CSV) files should be loaded at initial start-up of the ODK-X tools.

  • index.html - the HTML for the ODK-X Tables custom home screen, if it is enabled in the ODK-X Tables configuration settings.

The app/config/tables/ Folder

This folder has a predefined directory structure, but the content is entirely dependent upon the needs of your application.

The zip file for the ODK-X Application Designer populates this with all the subfolders used by each of the ODK-X Tables and the ODK-X Survey demonstration zip files. Ultimately, when you have completed your application design, this folder will contain none of these original folders but would instead contain only the folders which you have created.

Note

Unlike ODK Collect, which stores each submission in a separate file, ODK-X Survey and ODK-X Tables store their combined collected submission data in data tables (one row per submission).

ODK-X Tables can display the contents of a table through one or more custom list views; it can display individual submissions through one or more custom detail views. Graphical views are simply list views in which the data is presented graphically using a library such as D3. All of these custom views are defined here.

ODK-X Survey, unlike ODK Collect, has the additional flexibility of supporting multiple forms to create, access and update data within a single common data table. This enables creating multi-stage workflows such as initial screenings and follow-ups, or registrations and status-updates (submission data can be editable, or not, based upon the form used at that workflow stage).

To accommodate these various capabilities, the tables directory is structured such that individual data tables each have their own directory within the tables directory. The table's table_id is the name of this sub-directory. When defining a new data table, begin with a form whose form id is the table id.

The app/config/tables/table_id/ Folder

A canonical table_id sub-folder contains:

  • definition.csv - defines the data columns in this table. Generated when the form_id XLSX file underneath this table_id is processed by the XLSX Converter.

  • properties.csv - defines the appearance properties for this table. Example properties are the detail view HTML file name, the list view HTML file name, the default view type of the table, etc. Generated when the form_id XLSX file underneath this table_id is processed by the XLSX Converter.

  • forms/ - contains directories for each ODK-X Survey form that manipulates this table. The names of these sub-directories are the form_id values of those forms. Within each sub-directory, there is a form_id.xlsx file defining the ODK-X Survey form and the formDef.json generated by the XLSX Converter when it processed that form definition file. If the form has form-specific images or media files, custom CSS, layouts, or prompt types, those files should reside within the form's sub-directory (nested sub-folders are permitted).

  • html/ the custom HTML files for the ODK-X Tables list and details views of the table's contents.

  • css/ - contains CSS files specific to this table.

  • js/ the JavaScript files needed for the custom ODK-X Tables HTML list and detail views (found in the html/ directory).

ODK-X Scan is currently split in where it stores its configuration for mark-sense forms. The current location for the ODK-X Scan templates is under app/config/scan/form_templates directory. This will likely change and lead to additional sub-directories here.

The app/data/ Folder

The ODK-X Application Designer stores user data in this directory. The database itself is in the webDb directory. Any data files associated with a row in the database are stored within this folder under the tables/<table-id>/instances directory.

The app/output/ Folder

The ODK-X Application Designer provides various grunt tasks to pull files off the Android device. These files include JSON objects for debugging, exported CSVs, and the database itself. The grunt tasks store these files here. There is also a logging directory which contains logs that are useful for debugging issues.

The app/system/ Folder

This folder contains the files that the ODK-X tools depend upon and which are expected to be changed only when different versions of the ODK-X APKs are released.

Warning

Files in this folder are managed by the ODK-X tools. If you change any of these files, the tools may detect the change and restore the file when they next start. The goal is that only the ODK-X core team should have to modify things in this folder. If you feel you need to modify anything in this directory, please contact us.

The general structure is:

  • js/ - contains JavaScript for the Java to JavaScript interfaces common to both ODK-X Tables and ODK-X Survey.

  • libs/ - contains 3rd party JavaScript libraries used by ODK-X Tables and ODK-X Survey.

  • survey/ - contains JavaScript used by ODK-X Survey to render forms.

  • tables/ - contains JavaScript used by ODK-X Tables to render the custom home screen, list, detail, and graphical views created by the Application Designer.

  • tables.deleting - information related to data deletion

  • tables.pending - information related to pending data changes

  • index.html - the generic HTML for all ODK-X Survey forms.