Spec proposal: Media in external secondary intances

Development
1

The ODK core team would like to add support for referencing form media (images, audio and video) in external secondary instances that can be used in the form in select options, defaults and as question answers. This is the first part of a set changes that should eventually add support for entity media.

Changes

The changes proposed are:

XForm

  1. Additional specification around how non jr:// links should be handled by clients when used in as question/select media, defaults or as question answers (the latter including "dynamic defaults"). A value like myFile.jpg should be treated as a relative path for either form media (equivalent to jr://<type>/myFile.jpg) or instance media (<instance media dir>/myFile.jpg). Clients should first attempt to load form media and then fallback to instance media if no form media exists for the given value.

  2. Add a reference attribute to value nodes within text (for itext). If true, it indicates to a client that the element value is a column mapping, as opposed to a literal value to be used directly:

    <text id="c1-itemset:label">
  <value reference="true">label_column</value>
  <value form="image" reference="true">image_column</value>
  <value form="audio" reference="true">audio_column</value>
  <value form="video" reference="true">video_column</value>
</text>

XLSForm

Add a new sheet secondary_instances that allows configuring media/translation column mappings for secondary instances:

name label image image::English (en) audio::French (fr)
c1 label image image_en audio_fr

This will create the /itext/translation/text/ nodes required (as detailed above) which will be identified as <instance_name>-itemset:label from the itemset in question nodes for select_one_from_file:

<select1 ref="/test_name/q1">
  <label ref="jr:itext('/test_name/q1:label)"l/>
  <itemset nodeset="instance('c1')/root/item">
    <value ref="name"/>
    <label ref="jr:itext('c1-itemset:label’)" />
  </itemset>
</select1>

Future expansion

  • The secondary_instances sheet could have a column that defines the actual csv file name for the instance allowing name to act as an identifier for the configuration rather than the file and the identifier. This would unlock having different column configurations for different questions.
  • The XForm generated by XLSForm for internal and external selects use itext slightly differently. In the future, internal selects could adopt the approach being proposed here as well.
2

I just wanted to also add a quick note on Central's support for uploading media that's referenced by a secondary instance rather than the form itself: for clients to be able to download media files referenced by an external secondary instance, Central will either need to stop gating against arbitrary media file uploads or process the secondary instance in some way to determine the additional media files that can be uploaded. Whichever way this ends up working is a detail of Central's feature set rather than a change to any specification however, so I've not mentioned it in the main text above.

3

I am super excited about this, the eventual linking of media with entities opens up so many options and removes a lot of additional workarounds.

Eagerly watching this space :slight_smile:

Does this mean that media would still be uploaded (and duplicated) against all forms that reference the external instance, at least initially?

4

It depends on how it's implemented in Central, but I imagine that can be optimized in the future.