Media and attachments

A form's attachments are the files that travel with it to every phone and web form: pictures and recordings shown with questions, preload CSV files, field plug-ins, and the enumerator list. They are listed in the form's manifest, and each phone downloads only the files it does not already have.

Media in questions and choices

Put a file name in media:image, media:audio or media:video (per language too) on a question, a note, a group or a choice, and attach a file of that name. The picture is shown, or the recording offered, with the label. A form may carry hundreds of pictures; a folder of 400 choice images uploaded as one .zip is normal.

Attaching files

• With the form. Add the files in the same upload as the workbook, as many as the form has, all at once: images, audio, video, .csv files, field plug-ins, or a .zip of any of them. A .zip is unpacked and its files attached; an .xlsx data file is converted to the .csv the form reads.
• Afterwards. Add files, in a form's Upload panel, attaches more files to the deployed version without a new one, several at once and by the same rules. A form's Attachments panel lists its files, previews pictures, recordings and video, adds or removes files, and downloads everything as one .zip. Sizes are shown there.
• In the form designer. Each media box has an Upload… button; the file goes with Deploy and becomes an attachment of the new version.

A .zip you uploaded as a package stays one package in the list, and is kept exactly as uploaded with the version it came with. A field plug-in (.fieldplugin.zip) is always kept whole, wherever it is in the upload; when a .zip also holds the plug-in's source code (a folder with manifest.json, template.html and script.js), the source code is left out.

Which file is the form

• The workbook uploaded as itself, not inside a .zip, is the form, whatever the .zip files beside it hold.
• A .zip that holds another form is not this form's package. The .zip a field plug-in's page gives for download is one: it carries the plug-in beside its sample form, its source code and its README. Only the field plug-ins in it are attached, and the deploy says what was left out.
• A workbook the form reads by name, with pulldata('name', …), search('name', …), instance('name') or name.csv, is its data file, even when it has a sheet called survey. Two forms that do not read each other are refused: upload one form at a time, each with its own attachments.
• With no workbook uploaded as itself, a .zip that holds the form and its media is the form's package, and the form is taken from inside it.

When you publish a new version, Keep existing file attachments carries the previous version's files forward; untick it to ship only the files in this upload.

How names are matched

The form refers to a file by name, and phones look it up by that name, so the names have to agree. Two things make this forgiving:

• names are matched without regard to letter case: a form that asks for Ben_list.csv finds an upload called ben_list.csv, and the phone is told the name the form uses;
• a file called .csv that is really an Excel workbook (it happens) is recognised and converted, rather than served as nonsense.

Every deploy names any preload file the form reads that nothing has attached, because without it every preloaded answer would arrive empty, which in the field looks like the survey working.

What is served, and how

Attachments are served from your server, never from a third party. A file someone uploaded (a form's media, a field plug-in, a photo a respondent sent) is never served as a web page: pictures, recordings and plain text open in the browser, everything else is downloaded, and nothing in such a file can run as script on the console's address.

Form attachments are not sealed by encryption at rest, because every phone that downloads the form receives them. Keep preload files to the columns the form needs; see Encryption at rest.