@PREFILL (aka @SETVALUE) Action Tag

Initial Considerations

The @PREFILL Action Tag sets a field's value to static text or dynamic/piped text whenever a data entry form or survey page is loaded, in which it will always overwrite an existing value of the field.

• The format must follow the pattern @PREFILL="????", in which the desired value should be inside single or double quotes.

• A field with @PREFILL will always be read-only, thus its value cannot be modified manually on the data entry form or survey page.

• For text fields, you may pipe and concatenate values from other fields in the project - e.g., @PREFILL='Name: [first_name] [last_name], DOB: [dob]'.

• For checkbox fields, simply separate the desired checkbox values with commas - e.g., @PREFILL='1,3'.

• For radio and dropdown fields, include the desired pre-fill value in single quotes - e.g., @PREFILL='2'.

NOTE:

• The piped value does *not* get applied during any data imports (via API or Data Import Tool) but only operates when viewing survey pages and data entry forms.

• A field with @PREFILL will have its value updated ONLY when the page loads, which means that its value will not be updated in real-time if you modify other fields on the same page that are piped into the @PREFILL tag. It is best practice to have any fields that are called into @PREFILL completed before the pre-fill field appears (i.e. on a previous instrument or previous page of a survey).

• If being used on a date or datetime field, the date value inside the quotes must be in Y-M-D format - e.g., @PREFILL='2007-12-25' - regardless of the field's set date format.

• The differences between @PREFILL and @DEFAULT are:

  • @DEFAULT is only applied when an instrument has no data yet, whereas @PREFILL will always be applied on an instrument, meaning that @PREFILL will always overwrite the value if a field value already exists

  • Fields with @DEFAULT can be modified by the user or survey participant, whereas @PREFILL makes the field un-modifiable

TIP: To pipe the value of one multiple choice field into another multiple choice field, make sure you append ':value' to the variable being piped - e.g., @PREFILL='[my_dropdown:value]' where the variable name of the piped field is [my_dropdown]

The Process 

1. Using @PREFILL for text fields:

   1. With free text and piped text fields:
      In Online Designer, create a text field. In this example I want to pipe in the participants' age and dob from a previous instrument. My action tag includes free text and piped text fields @PREFILL='Age: [age], DOB: [dob]'

       

      Open

      

      Note if you already have the instrument open, after creating this [age_dob] field, you’ll note it is blank. This is because the value is updated only when the page loads, which means that its value will not be updated in real-time. Refreshing the page, or exiting and re-entering the instrument will update the field, assuming the fields piped into the @PREFILL tag have been complete (in this case, [age] and [dob]).

      Here is an example of how the text field looks with the @PREFILL tag:

       

      Open

      

      
      
      

   2. With a piped checkbox field:
      In Online Designer, create a text field. In this example I want to pipe in the participants' previous location of living from a previous instrument. My action tag includes a piped checkbox field @PREFILL='[cities:checked]'

      The participant completes the checkbox field [cities] on a previous instrument, as shown:

      
      Now, here is an example of how the text field looks with the @PREFILL tag calling [cities]
      …Designer view:
      
      

      …And this is what the field would look like when viewing the form:
      
      

      
      
      

   3. With a piped radio or dropdown field:
      In Online Designer, create a text field. In this example I want to pipe in the participants' favorite food from a previous instrument. My action tag includes a piped radio field @PREFILL='[food]'
      
      The participant completes the radio field [food] on a previous instrument, as shown:
      
      

      Now, here is an example of how the text field looks with the @PREFILL tag:
      …Designer view:

      …And this is what the field would look like when viewing from the form:
      
      

      Alternatively, instead of pre-filling the word “chips,” you can also pre-fill with the coded value of the piped radio or dropdown field by adding :value such as @PREFILL='[food:value]'
      
      Here’s the Designer view:
      
      

      …And this is how it would look on the form:
      
      

      
      
      

2. Using @PREFILL for checkbox fields
   For checkbox fields, simply separate multiple checkbox values with commas - e.g. @PREFILL='1,3'

   
   Here is an example of how the checkbox field looks with the @PREFILL tag:

   …Designer view:

   …And this is what the field would look like when viewing the form:

    

3. Using @PREFILL for radio or dropdown fields
   For radio or dropdown fields, simply enter the pre-fill value in single quotes such as @PREFILL='1'
   
   Here is an example of how the radio field looks with the @PREFILL tag:
   …Designer view:
   
   

   …And this is what the field would look like in the form:
   
   

   
   Alternatively, you may want to pre-fill a radio field based on a participant’s response to a previous radio field. Here’s an example:
   
   The participant selects their favorite food on a previous instrument:
   
   

   
   …This is then called into a future pre-filled radio field. Designer View of the pre-filled field:
   
   

   …Form view of the pre-filled field:
   
   

Practical use considerations:

• Use this action tag to combine previous fields into a single field for future use, such as a notes field that would print as a mailing label (e.g. @PREFILL='[first_name] [last_name] [address] [city], [state] [zip]').

• Do not use this action tag to show previous fields in future instruments. You can simply pipe fields into a header or descriptive field to accomplish this purpose.

• You can use as many action tags as you want for a single field, but if you do use more than one tag for a field, make sure to put a space or line break between them.

• Because the action tags are used as part of the Field Annotation, they are not displayed anywhere on the page.