In addition to being able to format the text that you wish to display for a particular field, you are also able to include multimedia content (images, video and audio) and documents (PDFs) - referred to as resources. This is useful in many situations, such as:
- Playing an audio clip that verbally communicates a question/instruction in low literacy settings or where the fieldworker might not know the local language.
- Displaying animations or videos to help explain a complex concept.
- Allowing a fieldworker/respondent to choose from a list of images rather than text options.
- Including reference or training material which needs to be reviewed as part of the data collection process.
To utilise a resource in a form, you need to upload it to the "Resource Library" for the project that houses the form. The same resources can be used by any form within the project and resources download automatically to all fieldworkers in the project ensuring they can be accessed offline in the field.
Resources can be referenced in both field display text and in option labels (in the case of choice field types).
This article covers:
- Adding and managing project resources
- Referencing a resource in a form
- Resources and languages
- Importing or moving forms
- Troubleshooting missing resources on a handset
Adding and managing project resources
Any resource that you want to include in a form needs to be uploaded to your project Resource Library - which can be accessed when designing/editing any form. Click on the settings cog in the toolbar and select 'Project Resources'.
This will open the Resource Library for the project and display any existing resources (4) which are listed in alphabetical order. If you need to, you can download existing resources (5) to your computer (e.g. to edit them).
You can easily add a new resource to the project by dragging and dropping a file from your computer into the window (3) or clicking on "Browse your PC". You can upload multiple files at the same time. Resource filenames can only contain letters, underscores and numbers and any illegal characters will be removed automatically when you upload the file.
You'll see a progress bar as each file uploads and a confirmation message once it has completed uploading or failed for any reason, such as the file being too large (resources must be less than 30MB each). If a file upload fails due to a temporary issue (such as connectivity), simply try uploading it again. The following file types can be uploaded:
- Images: png, jpeg, jpg, gif
- Audio: mp3, wav, m4a
- Video: mp4, webm
- Documents: pdf, csv (to pre-populate a form or dynamically generate an option list)
Note: Not all file types are supported by all web browsers and handset versions.
If you upload a resource with a filename that already exists, you'll be prompted to choose to either overwrite the resource or keep both files (which will rename the file you are uploading to make it unique).
Note: you cannot rename a resource once it has been uploaded so we recommend giving the resource a descriptive filename before you upload it. If your form is available in multiple languages, you might need your resources to be available in different languages too - in this case, it helps to include the language in the resource filename so you know which one to reference in each language variation.
Resources are managed at a project level. This means you can reference the same resource (file) from any of the forms in the same project, i.e. "Form 1" and "Form 2" (both in "My Project") can both reference the resources added to the "My Project" Resource Library. However, you cannot reference files across projects, i.e. a form in "Your Project" cannot reference a resource that was added to "My Project". In order to reference a resource in both projects, it has to be uploaded to each project's Resource Library.
To delete a resource from the Resource Library, simply click on the trashcan/bin icon. You will be prevented from deleting a resource that is still being referenced by a form. You need to remove any references to a resource (and re-publish the form after removing the reference) before you can completely delete a resource from the project.
Referencing a resource in a form
To display a resource in a form, simply enter the "@" symbol when entering display text (1). This will bring up a list of all available resources from the project Resource Library for you to choose from. The list will update as you type to display matching resources and their type (e.g. image, video). To select a resource, click on it - the reference to the filename will be inserted in the display text (2).
When you finish editing, the resource reference will be highlighted (3) to differentiate it from the rest of the display text.
You can insert resources anywhere in a field's display text, or in option labels, and you can include multiple resources. By default, images and videos will be displayed left-aligned and on new lines. You can alter the appearance, layout and behaviour of a resource by typing the "~" symbol at the end of the resource filename. This will bring up a list of available modifiers allowing you to centre-, left-, or right-align images, video and audio controls. For images and videos, you can also stretch the media to maximise the available space. You can also configure video and audio clips to play automatically when the page loads. PDFs can be set to display inline (only applicable when the form is accessed via a desktop web browser).
Tip: Use the Preview feature to test your media has been referenced and appears correctly.
Resources and languages
If your form is available in more than one language, you might want to reference a different resource, depending on the language selected. If you add a media file to the default language of a form and then add another language variation, the same media file will automatically be used.
If you wish to reference a different resource, simply select a difference resource file when editing the display text in that language.
Importing or moving forms
When you import a form, it might contain references to resources that are not in your project Resource Library. You will have to upload these files separately and update the resource references in the form after import to reference the correct filenames.
The same applies when moving a form from one project to another. Since resources are project-specific, the files might not be available in the new project, and will have to be uploaded separately. Again, ensure that all your references to all resources are correct using the Preview feature before publishing.
Troubleshooting missing resources on a handset
Resources download automatically and are stored locally on a fieldworker's handset. This allows the resources to display instantly and for fieldworkers to work offline and avoids incurring data costs once the files have downloaded initially.
If any resources are missing (e.g. they have not been able to download due to poor connectivity), an error will be displayed where the resource was supposed to appear in the form. Ensure fieldworkers have upgraded to the latest version of the Mobenzi Gateway Android app. It may take a few minutes for all resources to download, depending on connectivity.
If resources are still missing, the fieldworker can manually retry any failed resource downloads from the Help module (1) by expanding "Project Resources" (2). This will list any resource downloads that have failed. The fieldworker can tap "retry" and monitor the download progress until all resources have successfully downloaded.