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 and files to your project

Media files need to be added to the project's Resource Library in order to reference media in your form. Select the project you want to add the media file(s) to from the quick-switch menu, and go to the Design tab of the form(1). Click on the settings cog in the toolbar and select 'Project Resources(2). 

The project's Resource Library will open. You can add more files either by browsing your computer or by dragging-and-dropping a file into the upload area on the pop-up (3). You can upload multiple files at the same time. The media files in your project will be listed in alphabetical order (4) and can be downloaded by clicking on the download icon (5) of the specific file.

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

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. 

Notes regarding project resources: 

  • The following file types are supported:
  • There is a size limit of 30MiB per file. 
  • All resource you add to your project will count towards the storage limit of your chosen plan.
  • Resource 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 file, 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, or in the option list of select fields 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 currently it is not possible 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.

Advanced Media Settings:

Your media can be can have additional properties added such as auto-play, centred, left or right aligned or stretched to fit. To apply these properties to your media, simply add the  '~' symbol and select from the list of available properties.

  • auto-play: Plays audio or videos automatically when the users arrives on the page
  • stretchtofit: Stretches images or video to fill the width of the page
  • centred: Centres an image, video or audio control on the page
  • left: Aligns an image, video or audio control to the left of the page
  • right: Aligns an image, video or audio control to the right of the page

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 (1), click on the settings cog to select 'Project Resources' (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.