Template variables > File Upload

FileUpload template variables are defined for each question in your survey that is of type File Upload. If you are looking for template variables for another question type, please see template variables. This page details the structure of the question template variables so you can know what to expect when designing your templates. There are also some special considerations that template designers should take into account when designing the File Upload question type.

question.
   # Variables in common with all question types
   id
   type = 'FileUpload'
   text
   instructions
   required
   number
   sortorder
   scored
   hidden
   valid
   answered
   inloop[]
   loops.
   template.
   errors[]

   # Additional variables for File Upload question type
   minuploadkb
   maxuploadkb

   answerorder
   answers[]
      # Variables for each answer in question.answers[]
      id
      label
      required
      fixedposition
      minfiles
      maxfiles
      minfilesizekb
      maxfilesizekb
      filetypes
      template.

      files[]
      # Variables for each file in answer.files[]
         uploaded
         name
         size
         f_name
         f_keepname
         f_deletename
         f_uniqueid

[edit] question.

This document assumes that you have the question object in a variable named question. This is most often achieved in a loop, such as:

[% FOREACH question IN survey.questions; %]

or using a custom template function such as getQuestion:

[% question = getQuestion(id); %]

[edit] question.id

Contains the ID # of the question as listed in the survey editor. This is unique across all of your surveys and is used in getQuestion and other custom template functions.

[edit] question.type

This variable will be set to 'FileUpload' for a File Upload question type.

[edit] Considerations for template designers

Due to the mechanisms in which file uploads occur over the web, there are some special considerations that must be taken when designing the template for File Upload question types. Note the following ways that a file upload field differs from other form input types in web browsers:

• A value cannot be set for a file upload field, as it presents a security risk to the respondent.
• When a respondent submits a survey page and then uses their browser's back button to return to the previous page, the form responses will be preserved as the user entered them in most cases. This is usually not the case for a file upload field.
• File uploads can be large, so users will most likely not want to have to re-upload a file just because they want to change a different response on a previous page.

The following mechanisms and conventions are presented to aid you in developing a file upload question template that is easy for the respondent to use and mitigates some of the above factors.

As you loop through each file upload answer that has been defined for a question, the following fields will be available to you:

• f_name - this field should be used as the name attribute so our processor can recognize the file upload.
• f_keepname - this field signals to our processor whether a file that has already been uploaded should be kept as part of the response. This field must appear in their form with a value of 1 whenever you want to allow them to keep a response.
• f_deletename - this field signals to our processors whether a file that has already been uploaded should be deleted from the response. If set to 1, it will remove the file from the response.

The object of these various fields is to make the file upload process as easy as possible for the respondent. Typically, you will want to present the file upload field to the resopndent by itself if they have not yet uploaded a file. Once a file has been uploaded, you will also want to use some combination of f_keepname and f_deletename in order to allow them to manage the file that has already been uploaded.

When this question type is processed, the existing file will be removed from the response if *any* of the following are true:

• f_keepname is not set to 1
• f_deletename is set to 1
• another file is uploaded in f_name field

This means the only way to keep the existing file is to set f_keepname to 1 and not have another file uploaded.

[edit] Example scenarios

The following are some sample ways you can create your file upload question type in order to utilize these functions:

• Use a hidden f_keepname set to 1, and present the respondent with a checkbox named f_deletename that is set to 1. If they check this box, the file will be removed. Also present the respondent with a file upload field and let them know they can replace the current file by uploading a new one.

• Use a select box named f_keepname with options 'Keep File' (value=1) or 'Delete File' (value=0). Also present a file input box that lets them replace the current file.

• Use three radio buttons named f_keepname. The first will have a value of 1 and say 'Keep File'. The second will have a value of 0 and say 'Delete File'. The third would have a value of 0 and say 'Replace File' and present the file upload prompt.

Keep in mind that even if f_keepname is set to 1, if a new file is uploaded in f_name, it will overwrite the existing file. In all of the above examples, you should not use f_keepname unless a file has already been uploaded. This ensures that if they press the back button in their browser to the page where they initially uplaoded a file, whether or not their browser remembered that value will either cause the file to be reuploaded or they will have to reselect it. Either way, the existing file will be deleted and this will keep the interface consistent with the backend so there are no instances where the visitor thought they saw an empty file upload field, but the file remained.

You may want to consider disabling the cache for your survey if you utilize file upload question types.