When designing your form you might want to provide the fieldworker with additional information or context to a question, such as reading a question aloud, displaying an image for reference or even showing a training video clip. You can embed media files (images, video, audio) in your form as part of any field's display text.

Note: To view the embedded media on their handsets, fieldworkers require version 78 or above of the Gateway mobile app. To get the latest version of Gateway, see here

This article will explain how to embed media into your form and give tips on naming your media files, removing media files, working with languages and media, importing forms with media file references, and accessing media files on the handset.

Embedding media

To embed media in your form, you have to:

  1. Add the media file to your project's Resource Library
  2. Reference the media file in the display text of a field 

1. Add media files to your project

In order to reference media files in your form, you have to add the media files to your project's Resource Library first. Select the project you want to add the media file(s) to from the quick-switch menu, and go to the Design tab of any form in this project (1). Click on the cog icon (2) and select 'Upload Resource'. 

The project's Resource Library will open. Here you can view all the media files currently in your project in alphabetical order (3). You can add more files either by browsing your computer or dragging-and-dropping a file into the upload area on the pop-up (4). You can upload multiple files at the same time. 

The following file types are supported:

  • Image: png, jpeg, jpg, gif
  • Audio: mp3, wav, m4a
  • Video: mp4, webm

Tip: Can't find your .m4a when browsing your files to upload? Try dragging and dropping it from your file explorer window instead. 

The Resource Library shows all the media files added to the project, not to specific forms. There is a size limit of 30MiB per media file. All media files you add to your project will count towards the storage limit of your chosen plan.

A progress bar is shown next to the file you are uploading. If the media file upload fails for some reason (such as loss of connectivity), you will be warned in red that there was a file upload error. Try adding the file again, or contact support if the problem persists. Click 'Done' or close the pop-up once your files have been uploaded. 

Tip: To remove the 'Failed upload' files from the Resource Library, simply refresh the page. 

Important: Media files are added on a project level. This means you can reference the same media file from any of the forms in your project, i.e. Form A and Form B (both in Project Y) can both reference the media files added to Project Y. However, you cannot reference media files across projects, i.e. a form in Project X cannot reference media that was added to Project Y only. In order to reference this media, you will also have to add it to Project X. 

2. Reference media files in fields

You can reference the media files in your project's Resource Library in the display text of any field type in any of your project's forms. Simply type the character '@' to bring up a list of the media files available in your project (1). Either scroll through the list to find the media file you are looking for, or just start typing the file name to filter the results in the drop-down. Select the file you want to reference from the drop-down (2).

The media reference will be wrapped in a light blue colour (3) to differentiate it from the rest of the display text.

You can add references to the media files anywhere in your display text, and you can reference as many media files as you need to in the same field's display text. When viewing the rendered form however, the referenced media files will always be right-aligned, and it is not possible at the moment to change this alignment. 

Tip: You can view and/or listen to your media files from within your Preview. Once media files are added, always Preview your form to confirm that your media files are referenced correctly and display as expected. We recommend using Chrome when previewing your form, as other browsers might not support all the file types mentioned above.

Naming your media files

Once your media file has been uploaded to your project, you cannot rename the file. If you wish to change the file's name, you will have to remove the file and add a new one. Therefore it is important to name your files carefully before you upload them to your projects. 

Things to keep in mind when naming your media files:

  • Be very specific so that it is easy to recognise your files when referencing them later in a form.
  • Where possible, use unique names. Duplicate names will automatically be appended by incrementing numbers.
  • When adding the same media file in different languages, include the language in the file name. This will make referencing these files easier, e.g. "question1_audio_ENG".
  • Avoid using spaces or special characters (e.g. brackets, %, $, #) in your file names. These will automatically be replaced by underscores upon upload.

Removing media files

You can remove media files from your project's Resource Library if you no longer require them. 

Go to your Design tab and click on the cog (1). Select 'Upload Resource' (2). 

Click on the bin icon next to the file you want to delete (3). 

If the media file you are trying to delete is referenced in at least one of your project's published forms, you will be prevented from removing this media file until you remove the reference to it from your form(s). 

Once you have removed the references to this media file and published the changes, you will be able to remove it from your Resource Library.

Media and languages

Media files are language-specific. In other words, if you add a media file to your English form and you then add another language to your form, the same media file will automatically be added to the fields' display text for the new language you've added. 

You can then decide to keep the same media file across all languages, or you can update the media references to point to different media files if they are language-specific (such as audio clips).

Importing forms containing media that is not in your project

Using our 'Import XFormfunctionality, it is possible to import forms containing references to media files that are not already included the project's Resource Library. You will have to upload these media files separately and update the media references in the form after import to reference the correct filenames.

The same applies when exporting a Mobenzi form from one project and importing it into another Mobenzi project. Since media files are project-specific, the media files will not be available in the new project, and will have to be uploaded separately. Again, ensure that all your references to these media files are correct.  

Accessing media on the handset

All media referenced in a form will automatically download onto the fieldworker's handset when the form is assigned to the fieldworker and there is data connectivity. The media files will be stored locally on the fieldworker's handset and will load instantly when launching the form, so that fieldworkers can continue to work offline without incurring any costs after the files have downloaded initially.

Note: fieldworkers will need to upgrade to the latest version of the Gateway Android app to access media resources that have been embedded into a form. 

In the Help module (1), there is a section called 'Project Resources' (2) which gives information to the fieldworker about resources that have been downloaded. 

Depending on the number of media file references in a form, the size of these media files, and the quality of the data connection, there might be a delay in downloading the media files to the handset. The fieldworkers will see red text as placeholder when launching the form, indicating that the resource is not available for that field yet. The fieldworker can select 'Retry' next to the relevant file in the Project Resources section of the Help module.


Note: Fieldworkers might also see a placeholder icon when launching the form. This indicates that the media file has been removed from the fieldworker's device.