To instruct docassemble to store user input that it receives in response to a question, you need to include in your question a variable name to hold the information. You also need to indicate what type of variable it is (e.g., text, a date, a number), and how you want to ask for the input (e.g., with a label).

This section explains the many ways that variables can be populated using questions.

A note about variable names

Variable names are Python identifiers, which means they can be any sequence of uppercase or lowercase letters, digits, and underscores, except the first character cannot be a digit. No spaces are allowed and no punctuation is allowed except for the underscore, _.

The following are valid variable names:

• fried_fish1
• NyanCat
• nyancat (variables are case-sensitive, so this is not the same as the above)
• __f645456DG_greij_43 (but why would you use something so ugly?)
• USER_PHONE_NUMBER (ok, but why are you yelling?)

The following are not valid variable names, and if you try to use such variable names you will may get an error or unexpected results:

• 8th_plaintiff (you can’t begin a variable name with a number; Python will say “invalid syntax”)
• Nyan-Cat (this is arithmetic: Nyan minus Cat)
• fried.fish1 (this is valid code, but Python will think you are referring to the attribute fish1 of the object fried)
• user's_phone_number (apostrophes are not allowed; Python recognizes them as single quotes)
• favorite animal (spaces are not allowed)
• beneficiary#1 (punctuation marks other than _ are not allowed)
• applicant_résumé (only plain alphabet characters can be used)
• user.__ssn (attributes beginning with __ are not allowed)
• for or license.for (attributes cannot share names with built-in Python syntax. Names like for, while, or in will result in errors if used as variable names or attribute names. See reserved variable names for a list of names that cannot be used.

If you find yourself using variable names like automobile_one and automobile_two, you should learn about groups and generalizing. It would make more sense to work with variables automobile[0] and automobile[1], or automobile[i].

If you find yourself using variable names like employment_income, self_employment_income, and retirement_income, you should learn about the DADict (a type of group). It would make more sense to work with variables like income['employment'], income['self-employment'], and income['retirement']. Then you could generalize the questions you ask.

And if you find yourself using variable names like defendant_spouse_ssn and defendant_spouse_date_of_birth, you should learn about objects. It would make more sense to work with variables like defendant.spouse.ssn and defendant.spouse.birthdate. There are many advantages of working with objects, such as being able to write defendant.age_in_years() and defendant.spouse.age_in_years() to calculate the ages of people based on their birthdates.

See reserved variable names for a list of variable names that you cannot use because they conflict with built-in names that Python and docassemble use.

Multiple choice questions (one variable only)

Yes or no questions

yesno and noyes

yesno causes a question to set a boolean (true/false) variable when answered.

question: |
  Are you at least 18 years of age?
yesno: over_eighteen

GitHub

In the example above, the web app will present “Yes” and “No” buttons and will set over_eighteen to True if “Yes” is pressed, and False if “No” is pressed.

noyes is just like yesno, except that “Yes” means False and “No” means True.

question: |
  Are you at least 18 years of age?
noyes: user_is_minor

GitHub

Note that yes/no fields can also be gathered on a screen along with other fields; to make screens like that, use fields below.

yesnomaybe or noyesmaybe

These are just like yesno and noyes, except that they offer a third choice, “I don’t know.” If the user selects “I don’t know,” the variable is set to None, which is a special Python constant that represents the absence of a value.

question: |
  Is Topeka the capital of Kansas?
yesnomaybe: topeka_is_capital_of_kansas
---
question: |
  % if topeka_is_capital_of_kansas:
  You were right that Topeka is the capital of Kansas.
  % elif topeka_is_capital_of_kansas is None:
  You should know your state capitals!
  % else:
  Actually, Topeka is the capital of Kansas.
  % endif
mandatory: True

GitHub

Note that both False and None are considered to be “false” values in Python. So if you write:

% if not topeka_is_capital_of_kansas:
You are a dummy!
% endif

then the phrase “You are a dummy!” will be shown both if the value is False and also if the value is None. If you need to test specifically for the “I don’t know” answer, use is None.

Multiple choice buttons

A question block with buttons will set the variable identified in field to a particular value depending on which of the buttons the user presses.

buttons must always refer to a list, so that docassemble knows the order of the buttons.

If an item under buttons is a YAML key-value pair (written in the form of - key: value), then the key will be the button label that the user sees, and the value will be what the variable identified in field will be set to if the user presses that button.

question: |
  How would you like to pay for your
  car?
field: target_variable
buttons:
  - Buy it: purchaser
  - Lease it: borrower

GitHub

An item under buttons can also be plain text; in that case docassemble uses this text for both the label and the variable value.

question: |
  What type of belly button do you
  have?
field: target_variable
buttons:
  - Innie
  - Outie
  - No belly button

GitHub

In other words, this:

field: user_gender
question: What is your gender?
buttons:
  - Male
  - Female

GitHub

is equivalent to this:

field: user_gender
question: What is your gender?
buttons:
  - Male: Male
  - Female: Female

GitHub

You can also provide the label and the corresponding value by using a dictionary containing keys label and value.

You can customize the appearance of buttons by specifying a css class and/or a color in the dictionary.

field: user_gender
question: What is your gender?
buttons:
  - value: male
    label: Male
    css class: male-button
    color: info
  - value: female
    label: Female
    css class: female-button
    color: danger

GitHub

The color should refer to one of the Bootstrap colors (primary, secondary, success, danger, warning, info, light, link, or dark).

If you want one of the choices to be shown or not shown conditionally, you can use show if to specify a Python expression. If the expression evaluates to true, then the choice will be included, and if it evaluates to false, it will be excluded.

field: target_variable
question: Which flour shall we use?
buttons:
  - value: almond
    label: Almond
  - value: oat
    label: Oat
  - value: wheat
    label: Wheat
    show if: gluten_tolerant
  - value: spelt
    label: Spelt
    show if: gluten_tolerant

GitHub

Using code to generate the choices

A powerful feature of buttons (which also works with choices, dropdown, and combobox) is the ability to use Python code to generate button choices. If an item under buttons is a key-value pair in which the key is the word code, then docassemble executes the value as Python code, which is expected to return a list. This code is executed at the time the question is asked, and the code can include variables from the interview. docassemble will process the resulting list and create additional buttons for each item.

field: target_variable
question: |
  Your use of this system does not
  mean that you have a lawyer.  Do
  you understand this?
buttons:
  code: |
    [{'understands': "I understand"},
     {'does not understand': "I do not understand"},
     {'unsure': "I'm not sure"}]

GitHub

Note that the Python code needs to return a list of key-value pairs (Python dictionaries) where the key is what the variable should be set to and the value is the button label. This is different from the YAML syntax.

This is equivalent to:

field: target_variable
question: |
  Your use of this system does not
  mean that you have a lawyer.  Do
  you understand this?
buttons:
  - "I understand": understands
  - "I do not understand": does not understand
  - "I'm not sure": unsure

GitHub

You can mix choices that are specified manually with choices that are specified with code:

field: target_variable
question: |
  Your use of this system does not
  mean that you have a lawyer.  Do
  you understand this?
buttons:
  - "I understand": understands
  - code: |
      [{'does not understand':"I do not understand"}, {'unsure':"I'm not sure"}]

GitHub

Instead of using key-value pairs to represent what the variable is set to and the label, you can use value and label as keys in the dictionary. You can also use the dictionary keys css class and color to modify the appearance of the buttons, and show if to conditionally include the button.

field: target_variable
question: |
  Your use of this system does not
  mean that you have a lawyer.  Do
  you understand this?
buttons:
  code: |
    [{'label': "I understand",
      'value': 'understands',
      'css class': 'good',
      'color': 'success'},
     {'label': "I do not understand",
      'value': 'does not understand',
      'css class': 'clueless',
      'color': 'danger'},
     {'label': "I object",
      'value': 'objects',
      'css class': 'ornery',
      'show if': is_annoying,
      'color': 'danger'},
     {'label': "I'm not sure",
      'value': 'unsure',
      'css class': 'unsure',
      'color': 'warning'}]

GitHub

The color should refer to one of the Bootstrap colors (primary, secondary, success, danger, warning, info, light, link, or dark).

As explained below, you can also use code to decorate the buttons with images.

If you need the variable to have a data type other than text, you need to specify a datatype.

field: target_variable
question: |
  Your use of this system does not
  mean that you have a lawyer.  Do
  you understand this?
datatype: boolean
buttons:
  code: |
    [{'label': "I understand",
      'value': True,
      'css class': 'good',
      'color': 'success'},
     {'label': "I do not understand",
      'value': False,
      'css class': 'clueless',
      'color': 'danger'}]

GitHub

The possible datatype values include boolean (True or False), threestate (True, False, or None), and other data types.

True/False buttons

You can use buttons as an alternative to yesno where you want different text in the labels.

question: |
  Are you satisfied?
field: user_is_satisfied
buttons:
  - "You bet": True
  - "No way": False

GitHub

In order for the variable to be set to the special Python values True and False, you need to make sure that the only values you list are True and False, and nothing else, just like in the example above. If you include a different value, your variable will be set to 'True' or 'False', which could cause problems.

Multiple choice list

To provide a multiple choice question with “radio buttons” and a “Continue” button, use field with a choices list:

question: |
  What type of shoes do you wear?
field: target_variable
choices:
  - Sneakers
  - Sandals
  - Clogs
  - Other

GitHub

You can specify a default value using default:

question: |
  What type of shoes do you wear?
field: target_variable
default: Sandals
choices:
  - Sneakers
  - Sandals
  - Clogs
  - Other

GitHub

Another way to set a default is by adding default: True to the choice that you want to be the default.

question: |
  What type of shoes do you wear?
field: target_variable
choices:
  - Sneakers: sneakers
  - Sandals: sandals
    default: True
  - Clogs: clogs
  - Other: other

GitHub

You can also provide help text for a radio button using help:

question: |
  What type of shoes do you wear?
field: target_variable
choices:
  - Sneakers: sneakers
    help: |
      Comfortable shoes.
  - Sandals: sandals
    help: |
      For summer.
  - Clogs: clogs
    help: |
      For hippies.
  - Other: other
    default: True
    help: |
      Because the other types suck.

GitHub

You can customize the appearance of a particular item by specifying color and css class:

question: |
  What type of shoes do you wear?
field: target_variable
choices:
  - Sneakers: sneakers
    help: |
      Comfortable shoes.
    css class: sneakers
    color: secondary
  - Sandals: sandals
    help: |
      For summer.
    css class: sandals
    color: danger
  - Clogs: clogs
    help: |
      For hippies.
    css class: clogs
    color: warning
  - Other: other
    default: True
    help: |
      Because the other types suck.
    css class: othershoe
    color: success

GitHub

The color should refer to one of the Bootstrap colors (primary, secondary, success, danger, warning, info, light, link, or dark).

If you want a choice to be included conditionally, you can use show if to specify a Python expression that indicates when the choice should be included or not.

question: |
  Are you proper?
yesno: is_proper
---
question: |
  What type of shoes do you wear?
field: target_variable
choices:
  - Dress shoes: dress_shoes
    show if: is_proper
  - Boat shoes: boat_shoes
    show if: is_proper
  - Sneakers: sneakers
    show if: not is_proper
  - Sandals: sandals
    show if: not is_proper
  - Crocs: crocs
    show if: not is_proper
  - Other: other

GitHub

These customizations can also be specified when building a list of choices using code:

question: |
  What type of shoes do you wear?
field: target_variable
choices:
  code: |
    [{'sneakers': "Sneakers",
      'help': "Comfortable shoes.",
      'css class': "sneakers",
      'color': "secondary"},
     {'sandals': "Sandals",
      'help': "For summer.",
      'css class': "sandals",
      'color': "danger"},
     {'clogs': "Clogs",
      'help': "For hippies.",
      'css class': "clogs",
      'color': "warning"},
     {'crocs': "Crocs",
      'help': "For teenagers",
      'show if': not is_adult,
      'css class': "crocs",
      'color': "warning"},
     {'other': "Other",
      'default': True,
      'help': "Because the other types suck.",
      'css class': "othershoe",
      'color': "success"}]

GitHub

Multiple choice dropdown

To provide a multiple choice question with a dropdown selector, use field with a dropdown list:

question: |
  What type of shoes do you wear?
field: target_variable
dropdown:
  - Sneakers
  - Sandals
  - Clogs
  - Other

GitHub

Multiple choice combobox

To provide a multiple choice question with a “combobox” selector, use field with a combobox list:

question: |
  What is your favorite color?
field: favorite_color
combobox:
  - Red: red
  - Green: green
  - Purple: purple

GitHub

The “combobox” selector allows users to choose a selection from a list or enter a value of their own.

Adding images to buttons and list items

To add a decorative icon to a buttons choice, use a key/value pair and add image as an additional key.

question: |
  What is the most important question
  to ask?
field: interrogatory
buttons:
  - "When?": when
    image: calendar
  - "Where?": where
    image: map

GitHub

This works with choices as well:

question: |
  What is the most important question
  to ask?
field: interrogatory
choices:
  - "When?": when
    image: calendar
  - "Where?": where
    image: map

GitHub

It is not possible to decorate dropdown or combobox choices with images.

In these examples, calendar and map are the names of decorations that are defined in an images or image sets block.

If you create the list of choices with code, you can specify an image by including an additional key/value pair within an item, where the key is image.

question: |
  What is the most important question
  to ask?
field: interrogatory
buttons:
  code: myoptions
---
code: |
  myoptions = \
    [{"when": "When?",
      "image": "calendar"},
     {"where": "Where?",
      "image": "map"}]

GitHub

There is an additional feature available when you assemble buttons with code: you can use DAFile or DAFileList objects to indicate the image. This example uses an uploaded image file as the source of the image for one of the buttons:

question: |
  What is the most important question
  to ask?
field: interrogatory
buttons:
  code: myoptions
---
code: |
  myoptions = \
    [{"when": "When?",
      "image": uploaded_file},
     {"where": "Where?",
      "image": "map"}]
---
question: |
  Please upload an image.
fields:
  - Image: uploaded_file
    datatype: file

GitHub

Embedding question and code blocks within multiple choice questions

Multiple choice questions can embed question blocks and code blocks. These questions are just like ordinary questions, except they can only be asked by way of the questions in which they are embedded.

You embed a question by providing a YAML key-value list (a dictionary) (as opposed to text) as the value of a label in a buttons, choices, or dropdown list.

question: What is your favorite color?
buttons:
  - Red:
      question: Dark red or light red?
      field: favorite_color
      buttons:
        - Dark Red
        - Light Red
  - Green:
      question: Dark green or light green?
      field: favorite_color
      buttons:
        - Dark Green
        - Light Green

GitHub

While embedding question blocks can be useful sometimes, it is generally not a good idea to structure interviews with a lot of embedded questions. You will have more flexibility if your questions stand on their own. Embedded blocks cannot use the generic object modifier or index variables.

It is also possible for multiple-choice questions to embed code blocks that execute Python code. (If you do not know what code blocks are yet, read the section on code blocks first.) This can be useful when you want to set the values of multiple variables with one button.

question: What kind of car do you want?
buttons:
  - Ford Focus:
      code: |
        car_model = "Focus"
        car_make = "Ford"
  - Toyota Camry:
      code: |
        car_model = "Camry"
        car_make = "Toyota"

GitHub

The question above tells docassemble that if the interview logic calls for either car_model or car_make, the question should be tried. When the user clicks on one of the buttons, the code will be executed and the variables will be set.

To undo a user’s choice on a question that embeds blocks, tag the question with an id and call the forget_result_of() function with the ID.

Questions with only a “continue” button

question: |
  Welcome to the interview!
subquestion: |
  Your participation means a lot to us.
continue button field: user_saw_intro

GitHub

A question with merely a continue button field will offer the user a “Continue” button. When the user presses “Continue,” the variable indicated by continue button field will be set to True.

If you are using fields and you want the “Continue” button to set a variable to True the way that this question type does, you can add the continue button field specifier.

Questions that collect one or more fields on a screen

So far, we have discussed questions that set a single multiple-choice variable and the use of continue button field to set a single variable to True. These are helpful when you are collecting True or False values or multiple choice values. However, docassemble’s primary tool for collecting information in is the fields specifier. fields allows you to collect many different types of information and to collect more than one piece of information on a screen.

question: Tell me about yourself
fields:
  - Favorite color: user_favorite_color
  - Description of your ideal vacation: user_ideal_vacation
    input type: area
    required: False

GitHub

The fields specifier must refer to a YAML list of one or more “fields”. Each list item must consist of one or more key/value pairs. One of these keys (typically) is the label the user sees, where the value associated with the key is the name of the variable that will store the user-provided information for that field. The other key/value pairs in the item (if any) allow you to modify how the field is displayed to the user.

These field modifiers are distinguished from label/variable pairs based on the key; if the key uses one of the names listed below, it will be treated as a field modifier; if it is anything else, it will be treated as a label.

The next section describes the different types of variables you can gather with fields and the different types of user interfaces you can use.

Data types and input types

Within a fields question, there are many possible datatype values that you can use. These affect what the user sees and how the input is stored in a variable.

The possible values of datatype are:

• user
• camera
• environment
• camcorder
• checkboxes
• multiselect
• currency
• date
• datetime
• email
• file
• files
• integer
• microphone
• ml
• mlarea
• noyes
• noyesmaybe
• noyesradio
• noyeswide
• number
• object
• object_checkboxes
• object_multiselect
• password
• range
• text (the default)
• time
• yesno
• yesnomaybe
• yesnoradio
• yesnowide

In most cases, datatype controls both the user interface and the format in which the data is stored. But for certain multiple choice questions, you can use datatype to indicate how you want the data stored, and use input type to indicate the type of user interface to use. The possible values of input type are:

• area
• dropdown
• radio
• combobox
• ajax
• hidden

The following subsections describe the available datatypes and input types that you can assign to a field within fields.

Plain text

A datatype: text provides a single-line text input box. This is the default datatype, so you never need to specify it unless you want to.

question: |
  What are your favorite things to eat?
subquestion: |
  Please be specific.
fields:
  - Vegetable: target_variable
  - Fruit: other_target_variable

GitHub

input type: area provides a multi-line text area.

question: |
  Tell me the story of your life.
fields:
  - Life Story: target_variable
    input type: area

GitHub

You can change the number of rows in the text area using the rows specifier:

question: |
  Tell me the story of your life.
fields:
  - Life Story: target_variable
    input type: area
    rows: 10

GitHub

The default number of rows is four.

Passwords

datatype: password provides an input box suitable for passwords.

question: |
  Enter your username and password.
fields:
  - Username: user_name
  - Password: target_variable
    datatype: password

GitHub

Dates

datatype: date provides a date entry input box. The style of the input box depends on the browser.

question: |
  What is your date of birth?
fields:
  - Birthdate: target_variable
    datatype: date

GitHub

Validation is applied to ensure that the date can be parsed by dateutil.parser.parse.

The variable resulting from datatype: date is a special Python object of the class DADateTime, which is a subclass of the standard Python class datetime.datetime. So if the name of the date variable is date_of_filing, then you can do things like:

question: |
  When did you file the complaint?
fields:
  - Date: date_of_filing
    datatype: date
---
code: |
  response_deadline = date_of_filing.plus(days=20)
  christmas = response_deadline.replace(month=12, day=25)
---
mandatory: True
question: |
  % if christmas > response_deadline:
  Your response is due
  ${ int(date_difference(starting=date_of_filing, ending=christmas).weeks) }
  weeks before Christmas.
  % else:
  Your response is due soon after Christmas!
  % endif

GitHub

Note that the field on the screen only asks for a date, but DADateTime represents both a date and a time. The time portion of the DADateTime object will be set to midnight of the date. If you want a DADateTime with a time other than midnight, you can use the .replace_time() or .replace() methods of DADateTime to generate a new object with the same date but a different time.

For more information about working with date variables, see the documentation for the date functions. These functions are generally very flexible about formats, so you can pass a string like '12/25/2018' or a date object, and the function will produce the correct result either way.

In particular, if you want to format a date variable for inclusion in a document or a question, you will probably want to use the .format_date() method or the format_date() function.

To set a default value, you can set default to any value that can be understood as a date.

question: What is your date of birth?
fields:
  - Your birthday: birthdate
    datatype: date
    default: |
      ${ today().minus(years=100) }

GitHub

Likewise, to set limits, you can set min and/or max to a string that can be recognized as a date.

question: What is your date of birth?
fields:
  - Your birthday: birthdate
    datatype: date
    max: ${ today() }

GitHub

Times

datatype: time provides an input box for times. The style of the input box depends on the browser.

Validation is applied to ensure that the time can be parsed by dateutil.parser.parse.

question: |
  What time is your appointment?
fields:
  - Time: target_variable
    datatype: time

GitHub

The resulting variable will be an object of type datetime.time.

To indicate a default time, write a default value in the format 13:43:23. If you have a datetime.time variable called meeting_start and you want the value of meeting_start to be the default time for a field, you can set the default value to ${ meeting_start }. This has the same effect as str(meeting_start) or meeting_start.strftime('%H:%M:%S').

If you want to format a time variable for inclusion in a document or a question, see the .strftime() method or the format_time() function.

If you want to gather both a date and a time from a user, and combine the values together into a single DADateTime object, you can do so with the .replace_time() method. For example:

question: |
  When is your appointment?
fields:
  - Date: appt_date
    datatype: date
  - Time: appt_time
    datatype: time
---
code: |
  appt_datetime = appt_date.replace_time(appt_time)

GitHub

If you want to format a date and time for inclusion in a document or a question, see the .format_datetime() method or the format_datetime() function.

Combined dates and times

datatype: datetime provides an input box for dates and times together in one field. The style of the input box depends on the browser. Note: not all browsers have a “widget” for combined date and times, and users might be confused if they are presented with a plain text box. For this reason, use of datatype: datetime is not recommended until browser support for the datetime-local becomes more widespread.

Validation is applied to ensure that the time can be parsed by dateutil.parser.parse.

question: |
  When is your appointment?
fields:
  - Date and time: target_variable
    datatype: datetime

GitHub

The resulting variable will be an object of type DADateTime. The object can be formatted using the .format_datetime() method or the format_datetime() function.

E-mail addresses

datatype: email provides an e-mail address input box.

question: |
  What is your e-mail address?
fields:
  - E-mail: target_variable
    datatype: email
    required: False

GitHub

Numbers

datatype: integer indicates that the input should be a valid whole number.

datatype: number indicates that the input should be a valid numeric value.

question: |
  Describe your possessions.
fields:
  - Number of cars: number_cars
    datatype: integer
  - Ounces of gold: gold_ounces
    datatype: number

GitHub

You can use the optional field modifier step to limit the number to a certain number of decimal places:

question: |
  How much gold and silver do you have?
fields:
  - Ounces of gold: gold_ounces
    datatype: number
  - Ounces of silver: silver_ounces
    datatype: number
    step: 0.001

GitHub

Currency

datatype: currency indicates that the input should be a valid numeric value. In addition, the input box shows a currency symbol based the locale defined in the configuration.

question: |
  How much is your house worth?
fields:
  - Value: target_variable
    datatype: currency
    min: 0

GitHub

The variable will be set to a number, just as if datatype: number was used. For information about how to display currency values, see the currency() function.

If the locale convention places the currency symbol after the number, the currency symbol will be placed before the field; otherwise it will be placed after the field.

If the currency symbol defined by the locale is not the currency you want to use, you can include an initial block that calls set_locale() with the currency_symbol keyword parameter set to the symbol you want to use. This will set a default value for datatype: currency fields and for the currency() function.

Keep in mind that the variable stored by a datatype: currency field is just a number, so it is not aware of the currency denomination that was presented to the user when the information was collected.

You can also override the currency symbol on a field-by-field basis by setting the currency symbol field modifier.

question: |
  How much is your house worth?
fields:
  - Value: house_value
    datatype: currency
    min: 0
    currency symbol: €
---
question: Your home value
subquestion: |
  Your house is worth
  ${ currency(house_value, symbol=u'€') }.
mandatory: True

GitHub

As this interview demonstrates, the currency() function accepts an optional keyword parameter symbol that allows you to override the symbol that is displayed.

Sliders

datatype: range shows a slider that the user can use to select a number within a given range. The range must be supplied by providing min and max values. An option step value can also be provided, the default of which is 1.

question: |
  On a scale from 1 to 10, how
  much do you like these animals?
fields:
  - Possums: possum_preference
    datatype: range
    min: 1
    max: 10
    step: 0.5
  - Rabbits: rabbit_preference
    datatype: range
    min: 1
    max: 10

GitHub

You can also include an optional scale, which you can set to logarithmic.

question: |
  What is the airspeed velocity,
  in miles per hour, of an
  unladen swallow?
fields:
  - Velocity: velocity
    datatype: range
    min: 1
    max: 10000
    step: 10
    default: 10
    scale: logarithmic

GitHub

File uploads

Using the file or files datatypes within a fields list, you can allow users to upload one or more files.

datatype: file indicates that the user can upload a single file. The variable is set to a DAFileList object containing the necessary information about the uploaded file.

question: |
  Please upload a picture of yourself.
fields:
  - Picture: user_picture
    datatype: file
---
question: |
  You're so adorable, François!
subquestion: |
  ${ user_picture }
mandatory: True

GitHub

datatype: files indicates that the user can upload one or more files. The variable is set to a DAFileList object containing the necessary information about the uploaded files.

question: |
  Please upload pictures of yourself.
fields:
  - Pictures: user_pictures
    datatype: files
---
question: |
  Look at all those adorable photos!
subquestion: |
  ${ user_pictures }
mandatory: True

GitHub

If you want to limit uploads to particular file types, you can use accept to specify Python code that returns a custom accept attribute. The value of accept is passed directly into the accept attribute in the HTML and into the accept method of the jQuery Validation Plugin.

question: |
  Please upload a JPEG or PNG of yourself.
fields:
  - Picture: user_picture
    datatype: file
    accept: |
      "image/jpeg, image/png"

GitHub

Note that the syntax is very specific: the double quotation marks are part of the string itself.

Since the accept method of the jQuery Validation Plugin only works with MIME types, you can only specify MIME types here, not file extensions.

By default, docassemble styles the upload using the Bootstrap File Input plugin. If you do not want the Bootstrap File Input plugin to be used, you can set file css class to None.

question: |
  Please upload a JPEG or PNG of yourself.
fields:
  - File: user_file
    datatype: file
    file css class: None

GitHub

If you set file css class to None, then the class of the <input type="file"> element will be form-control, which is the standard class that Bootstrap uses to style file input elements. You can set file css class to any other class of your choosing if you want to use a different class than form-control. The file css class modifier can use Mako templating.

If no file css class is specified, the class of the input element will be dafile, which causes the Bootstrap File Input plugin to be activated.

Note that file css class is different from css class; the css class modifier simply adds additional classes to the class attribute of the input element, whereas file css class replaces the default class, which is dafile.

If your users upload digital photos into your interviews, the uploads may take a long time. You can configure an upload field so that images are reduced in size before they are uploaded by modifying your field definition with a maximum image size. The image will be reduced in size so that is no taller than or wider than the number of pixels designated by maximum image size.

In this example, images will be reduced in size to no more than 100 pixels in height or width:

question: |
  Please upload a picture of yourself.
fields:
  - Picture: user_picture
    datatype: file
    maximum image size: 100
---
question: |
  You're so small!
subquestion: |
  ${ user_picture }
mandatory: True

GitHub

Note that the image file type of the uploaded file may be changed to PNG during the conversion process. Different browsers behave differently.

If you have a lot of document upload fields, you can set a default maximum image size on an interview-wide basis with the maximum image size interview feature and on a site-wide basis with the maximum image size configuration directive. If you have a default set up, but you want to override it for a particular field, you can set the maximum image size field modifier to None.

If you are using maximum image size, you can also cause images to be converted to PNG, JPEG, or BMP by the browser during the upload process by setting the image upload type to png, jpeg, or bmp.

question: |
  Please upload a picture of yourself.
fields:
  - Picture: user_picture
    datatype: file
    maximum image size: 100
    image upload type: jpeg
---
question: |
  You're so small!
subquestion: |
  ${ user_picture }
mandatory: True

GitHub

By default, any file that a user uploads during a session will be deleted when that session is deleted. If you want the file to continue to exist after the session is deleted, you can set the field modifier persistent to True. The modifier also accepts Python code; if the code evaluates to a true value, the file will persist. This has the same effect as calling the .set_attributes() method on the file variable using the keyword attribute persistent.

By default, any file that a user uploads will only be downloadable by the user or by an administrator. If you want the file to be accessible to anyone, set the field modifier private to False. The modifier also accepts Python code; if the code evaluates to a false value, the file will be available to anyone. This has the same effect as calling the .set_attributes() method on the file variable using the keyword attribute persistent.

If you set private: False, then the file is available to anyone, including non-logged in users. Even a bot that guesses URLs could download the file. If you want to share with particular users, you can indicate specific users using the allow users modifier. If allow users refers to a YAML list, the list is expected to be a list of e-mail addresses of users or integers indicating the numeric user IDs of users. If allow users refers to text, the text is treated as a single item. If allow users refers to a YAML dictionary, the single key of which is code, you can define the list with Python code. The code is expected to evalute to an e-mail address, an integer user ID, an Individual with the email attribute set, or a list or DAList of any of the above. You can also use the .user_access() method to control which users have access to a file.

Instead of granting access to specific other users, you can grant access to categories of users by referencing privileges by name, such as user, developer, or advocate. If the allow privileges modifier refers to a YAML list, the list items are expected to be text items like user or developer. If allow privileges refers to a string, it is treated as a single item. If it refers to a YAML dictionary, the single key of which is code, you can define the privileges using Python code, which is expected to evaluate to text (e.g., 'user') or a list of text strings (e.g., ['user', 'developer']). You can also use the .privilege_access() method to control which users have access to a file.

There are a few other data types that result in file uploads:

datatype: camera is just like file, except it limits the allowable file types to image files.

datatype: user is just like camera, except with an HTML5 input type that suggests using the device’s front (user-facing) camera.

datatype: environment is just like camera, except with an HTML5 input type that suggests using the device’s rear (environment-facing) camera.

datatype: camcorder is just like file, except it limits the allowable file types to video files.

datatype: microphone is just like file, except it limits the allowable file types to audio files.

For more information about uploading files, and for instructions on uploading signature images, see the Uploads subsection.

Yes/no fields

datatype: yesno will show a checkbox with a label, aligned with labeled fields. datatype: noyes is like datatype: yesno, except with True and False inverted.

question: |
  Please provide the following information.
fields:
  - "What is your favorite food?": favorite_food
  - note: Check which foods you like.
  - Apples: likes_apples
    datatype: yesno
  - Turnips: dislikes_turnips
    datatype: noyes

GitHub

datatype: yesnowide will show a checkbox with a label that fills the full width of area. datatype: noyeswide is like datatype: yesnowide, except with True and False inverted.

question: |
  Please provide the following information.
fields:
  - note: Check which foods you like.
  - Peaches: likes_peaches
    datatype: yesnowide
  - Pears: dislikes_pears
    datatype: noyeswide

GitHub

Sometimes, when you are using a series of these checkboxes, you might want to have a “none of the above” selection. To do this, add a field for the selection, and associate it with a variable. (Your interview does not need to use the variable.) Then modify the field with uncheck others: True.

question: |
  Please provide the following information.
fields:
  - "What is your favorite food?": favorite_food
  - note: Check which foods you like.
  - Apples: likes_apples
    datatype: yesnowide
  - Turnips: likes_turnips
    datatype: yesnowide
  - Neither: dislikes_both_foods
    datatype: yesnowide
    uncheck others: True

GitHub

This will cause the field to act as a “none of the above” field for all the other yes/no checkbox fields on the page. If you want the field to only relate to specific other fields, use a list of the variable names of those fields instead of True.

question: |
  Please provide the following information.
fields:
  - "What is your favorite food?": favorite_food
  - note: Check which foods you like.
  - Apples: likes_apples
    datatype: yesno
  - Turnips: likes_turnips
    datatype: yesno
  - Neither: dislikes_both_foods
    datatype: yesno
    uncheck others:
      - likes_turnips
      - likes_apples
  - note: Check which rocks you like.
  - Granite: likes_granite
    datatype: yesno
  - Obsidian: likes_obsidian
    datatype: yesno
  - I do not like these rocks: dislikes_both_rocks
    datatype: yesno
    uncheck others:
      - likes_granite
      - likes_obsidian

GitHub

Other times, when you are using a series of these checkboxes, you might want to have an “all of the above” selection. To do this, add a field for the selection, and associate it with a variable. (Your interview does not need to use the variable.) Then modify the field with check others: True.

question: |
  Please provide the following information.
fields:
  - "What is your favorite food?": favorite_food
  - note: Check which foods you like.
  - Apples: likes_apples
    datatype: yesnowide
  - Turnips: likes_turnips
    datatype: yesnowide
  - Both: likes_both_foods
    datatype: yesnowide
    check others: True

GitHub

This will cause the field to act as an “all of the above” field for all the other yes/no checkbox fields on the page. If you want the field to only relate to specific other fields, use a list of the variable names of those fields instead of True.

question: |
  Please provide the following information.
fields:
  - "What is your favorite food?": favorite_food
  - note: Check which foods you like.
  - Apples: likes_apples
    datatype: yesno
  - Turnips: likes_turnips
    datatype: yesno
  - Both: likes_both_foods
    datatype: yesno
    check others:
      - likes_turnips
      - likes_apples
  - note: Check which rocks you like.
  - Granite: likes_granite
    datatype: yesno
  - Obsidian: likes_obsidian
    datatype: yesno
  - I like both of these rocks: likes_both_rocks
    datatype: yesno
    check others:
      - likes_granite
      - likes_obsidian

GitHub

datatype: yesnoradio will show radio buttons offering choices “Yes” and “No.”

datatype: noyesradio is like datatype: yesnoradio, except with True and False inverted.

question: |
  Please provide the following information.
fields:
  - "Do you like apricots?": likes_apricots
    datatype: yesnoradio
  - "Do you like pineapple?": dislikes_pineapple
    datatype: noyesradio

GitHub

datatype: yesnomaybe will show radio buttons offering choices “Yes,” “No,” and “I don’t know.” The resulting Python values are True, False, and None.

question: |
  Please answer the following question.
fields:
  - "Is Topeka the capital of Kansas?": topeka_is_capital_of_kansas
    datatype: yesnomaybe

GitHub

datatype: noyesmaybe is like datatype: yesnomaybe, except with True and False inverted.

question: |
  Please answer the following question.
fields:
  - "Was Washington the first U.S. president?": washington_not_the_first_president
    datatype: noyesmaybe

GitHub

When you provide help text for a yesno field, the help will be available as a popup accessible from a button located to the right of the field.

question: |
  Please provide the following information.
fields:
  - "What is your favorite food?": favorite_food
  - note: Check which foods you like.
  - Apples: likes_apples
    datatype: yesno
    help: Round fruit of a tree of the rose family
  - Turnips: dislikes_turnips
    datatype: noyes
    help: Round root with white flesh

GitHub

Checkboxes

datatype: checkboxes will show the choices list as checkboxes. The variable will be a DADict (a type of dictionary specific to docassemble) with items set to True or False depending on whether the option was checked.

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - apple
      - peach
      - pear
  - "What is your favorite fruit overall?": favorite_fruit
---
question: |
  Thank you for your thoughts.
subquestion: |
  % if likes_fruit['apple']:
  You like apples.
  % endif
  % if likes_fruit['peach']:
  You like peaches.
  % endif
  % if likes_fruit['pear']:
  You like pears.
  % endif
  Your favorite, though, is ${ favorite_fruit }.

  In other words, you like
  ${ likes_fruit.true_values() }.

  Your favorite, though, is ${ favorite_fruit }.

  In Python, `likes_fruit` is a `DADict`:
  `${ repr(likes_fruit) }`.
mandatory: True

GitHub

As you can see in this example, the keys of the resulting dictionary are the names of fruit, the values that are checked are True, and the values that were not checked are False.

In the example above, the keys of the dictionary are the same as the labels displayed to the user. If you want labels to be different from the keys, you can specify the choices in the following manner:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples: apple
      - Peaches: peach
      - Pears: pear
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

You can also express the checkboxes as a list of dictionaries where each dictionary has the keys label and value.

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - label: Apples
        value: apple
      - label: Peaches
        value: peach
      - label: Pears
        value: pear
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

The all_true(), all_false(), any_true(), any_false(), true_values(), and false_values() methods of DADict can be used to analyze the values set by a checkboxes field. For example:

mandatory: True
question: |
  Your fruit preferences
subquestion: |
  % if likes_fruit.all_true():
  You like all the fruit.
  % elif likes_fruit.all_false():
  You don't like any of the fruit.
  % elif likes_fruit.any_true():
  You like at least one fruit.
  % endif

  % if likes_fruit.any_false():
  There is at least one fruit you don't like.
  % endif

GitHub

If you want to require the user to select a minimum or maximum number of checkboxes, you can use the minlength and/or maxlength field modifiers.

You can generate checkbox choices with code:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    code: |
      [
        {'apple': 'Apples'},
        {'peach': 'Peaches'},
        {'pear': 'Pears'}
      ]
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

Default values for checkboxes

To set default values in a checkbox list, you have a few options.

If you want to select just one option, just indicate the name of the option:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    default: Pears
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

If you want to select multiple options, indicate a YAML list:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    default:
      - Pears
      - Apples
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

You can also indicate your defaults in the form of a YAML dictionary:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    default:
      Pears: True
      Apples: True
      Peaches: False
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

You can also use Python code to generate the defaults:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    default:
      code: |
        ['Pears', 'Apples']
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

Your Python code can also return a dictionary:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    default:
      code: |
        {'Pears': False, 'Peaches': False, 'Apples': True}
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

If you generate the checkbox options with code, you can include defaults directly within your code when you use a list of dictionaries:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    code: |
      [
        {'apple': 'Apples', 'default': True},
        {'peach': 'Peaches'},
        {'pear': 'Pears'}
      ]
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

This also works if your code returns a list of lists:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    code: |
      [
        ['apple', 'Apples', True],
        ['peach', 'Peaches'],
        ['pear', 'Pears']
      ]
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

Multiselect

datatype: multiselect works much like datatype: checkboxes, except it uses the HTML <select> element with the multiple flag set. On desktop browsers, multiple items can be selected by clicking items while holding down the Ctrl or Command key and clicking each item.

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: multiselect
    choices:
      - apple
      - peach
      - pear
  - "What is your favorite fruit overall?": favorite_fruit
---
question: |
  Thank you for your thoughts.
subquestion: |
  % if likes_fruit['apple']:
  You like apples.
  % endif
  % if likes_fruit['peach']:
  You like peaches.
  % endif
  % if likes_fruit['pear']:
  You like pears.
  % endif
  Your favorite, though, is ${ favorite_fruit }.

  In Python, `likes_fruit` is
  `${ repr(likes_fruit) }`.
mandatory: True

GitHub

Unlike datatype: checkboxes, the datatype: multiselect field does not support the use of a “None of the above” option.

You can use the rows specifier to indicate how many rows tall the multiselect box should be:

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: multiselect
    choices:
      - apple
      - peach
      - pear
    rows: 2
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

Multiple-choice dropdown

If you provide a list of choices or some choice-generating code for a field within a list of fields, the user will see a dropdown. The variable will be set to the value of the selected choice.

question: | 
  What type of shoes do you wear?
fields:
  - Shoe Type: target_variable
    choices: 
      - Sneakers
      - Sandals
      - Clogs
      - Other

GitHub

You can also include input type: dropdown:

question: | 
  What type of shoes do you wear?
fields:
  - Shoe Type: target_variable
    input type: dropdown
    choices: 
      - Sneakers
      - Sandals
      - Clogs
      - Other

GitHub

The input type: dropdown does not actually have any effect, since dropdown is the default input type. (The other options for input type are radio and combobox.)

The code option, which uses Python code to generate the list of choices, is often used in combination with exclude, which excludes one or more items from the list of choices.

Multiple-choice combobox

input type: combobox shows a choices list as a combobox instead of as a dropdown select element (which is the default).

question: |
  What is your favorite color?
fields:
  - Color: favorite_color
    input type: combobox
    choices: 
      - Red
      - Green
      - Purple
---
mandatory: True
question: All done
subquestion: |
  Your favorite color is
  ${ favorite_color }.

GitHub

The “combobox” selector allows users to choose a selection from a list or enter a value of their own.

Combobox that fetches choices from the server

input type: ajax looks like a combobox, but is really a dropdown selector that retrieves its choices from the server using Ajax, based on what the user types. It is useful when the number of possible values in the dropdown is too large to send to the browser all at once, and you want to allow the user to find the item they want to select by typing the start of a word or phrase.

To use input type: ajax, you also need to supply an action specifier. The browser will use the JavaScript function url_action_call() to call the given action. The text that the user types into the field will be passed to the action as the wordstart argument. The action needs to return a JSON list of items.

The following example uses the words file (from the wamerican package) as a data source for the combobox options.

question: |
  What is your favorite word?
fields:
  - Word: favorite_word
    input type: ajax
    action: wordlist
---
event: wordlist
code: |
  set_save_status('ignore')
  wordstart = action_argument('wordstart').lower()
  results = list()
  import codecs
  with codecs.open('/usr/share/dict/words', mode='rU', encoding='utf-8') as words_file:
    for line in words_file:
      lower_line = line.lower()
      if lower_line.startswith(wordstart):
        results.append(line.rstrip())
  json_response(results)

GitHub

The code block that carries out the action should always begin with set_save_status('ignore'). If you leave this out, then a step will be added to the interview each time the results are fetched. The code block should always end by calling json_response() that returns the relevant choice or choices.

The data that you pass to json_response() can be in one of three forms:

1. A list of pieces of text;
2. A dict in which the keys are the underlying values (what the variable will be set to) and the values are labels (what the user sees and types); or
3. A list of lists, where the first item in each sub-list is the underlying value and the second item is the label.

If you use the second or third option, note that docassemble will only store the underlying value in the variable, even though the user typed the label. In order for your datatype: ajax field to function properly if the question is revisited during a review process or the use of the Back button, your action needs to be able to accept as input either the underlying value or the label. In the following example, note the special return value if the wordstart argument matches a key in the dictionary.

question: |
  What is your favorite fruit?
fields:
  - Word: favorite_fruit
    input type: ajax
    action: fruitlist
---
event: fruitlist
code: |
  set_save_status('ignore')
  original = action_argument('wordstart')
  wordstart = original.lower()
  results = []
  for key, val in {'x234': 'Apple', 'y432': 'Orange', 'h293': 'Peach'}.items():
    if key == original:
      json_response([[key, val]])
    if val.lower().startswith(wordstart):
      results.append([key, val])
  json_response(results)

GitHub

If you press the Back button to return to the datatype: ajax field, the initial value of the field will be 'x234', 'y432', or 'h293'. This value will be sent to the action to be looked up, and then the screen will show the label rather than the value.

In order to avoid sending too many requests to the system, the requests are throttled so that they happen no more than once every two seconds.

The list will not start showing results until the user types at least four characters. If you want to use a different number of characters as the minimum, set trigger at. For example:

question: |
  What is your favorite word?
fields:
  - Word: favorite_word
    input type: ajax
    action: wordlist
    trigger at: 3

Radio buttons

input type: radio shows a choices list as a list of radio buttons instead of as a dropdown select element (which is the default). The variable will be set to the value of the selected choice.

question: |
  Describe your car.
fields:
  - Number of wheels: wheels_on_car
    datatype: integer
  - Type: car_type
    input type: radio
    choices:
      - Convertible
      - Hatchback
      - Sedan
  - Model: car_country
    input type: radio
    choices:
      - BMW: Germany
      - Buick: United States
      - Honda: Japan
      - Toyota: Japan

GitHub

Multiple-choice with objects

datatype: object is used when you would like to use a variable to refer to an existing object. You need to include choices, which can be a list of objects.

objects:
  protagonist: Individual
  antagonist: Individual
---
code: |
  protagonist.name.first = "Harry"
  protagonist.name.last = "Potter"
  antagonist.name.first = "Tom"
  antagonist.name.last = "Riddle"
---
question: Who is the villain?
fields:
  - The villain is: villain
    datatype: object
    default: antagonist
    choices:
      - protagonist
      - antagonist

GitHub

If choices refers to a variable that is a list of things, the list will be unpacked and used as the list of items from which the user can select. If choices refers to a string, that string is expected to be a Python expression that returns a list of objects. If choices refers to a YAML list, then each item in the list is expected to be a Python expression that returns either an object or a list of objects.

objects:
  protagonist: Individual
  antagonist: Individual
  actors: PartyList
---
mandatory: True
code: |
  protagonist.name.first = "Harry"
  protagonist.name.last = "Potter"
  antagonist.name.first = "Tom"
  antagonist.name.last = "Riddle"
  actors.append(protagonist)
  actors.append(antagonist)
  actors.auto_gather = False
  actors.gathered = True
---
question: Who is the villain?
fields:
  - The villain is: villain
    datatype: object
    choices: actors

GitHub

By using datatype: object in combination with disable others, you can create questions that either set the attributes of an object or set the object equal to another object.

objects:
  cook: Individual
  gardener: Individual
  maid: Individual
---
question: |
  Who is the cook?
fields:
  - Somebody already mentioned: cook
    datatype: object
    disable others: True
    choices: |
      [person for person in [cook, gardener, maid] if person.name.defined()]
  - First Name: cook.name.first
  - Last Name: cook.name.last
  - Suffix: cook.name.suffix
    required: False
    code: name_suffix()
---
question: |
  Who is the gardener?
fields:
  - Somebody already mentioned: gardener
    datatype: object
    disable others: True
    choices: |
      [person for person in [cook, gardener, maid] if person.name.defined()]
  - First Name: gardener.name.first
  - Last Name: gardener.name.last
  - Suffix: gardener.name.suffix
    required: False
    code: name_suffix()

GitHub

In this example, if the gardener and the cook are the same person, the interview effectively does the following in Python:

gardener = cook

Please note that datatype: object cannot be used with the generic object modifier if the variable being set is x.

datatype: object_radio is like datatype: object, except the user interface uses radio buttons rather than a pull-down list.

objects:
  protagonist: Individual
  antagonist: Individual
---
code: |
  protagonist.name.first = "Harry"
  protagonist.name.last = "Potter"
  antagonist.name.first = "Tom"
  antagonist.name.last = "Riddle"
---
question: Who is the villain?
fields:
  - The villain is: villain
    datatype: object_radio
    default: antagonist
    choices:
      - protagonist
      - antagonist

GitHub

For a fuller discussion on using multiple-choice object selectors, see the section on selecting objects, below.

datatype: object_checkboxes is similar to datatype: object, except it results in an object of type DAList (or a subtype thereof) consisting of zero or more items selected by the user. The choices specified in choices (optionally modified by exclude) will be presented to the user as checkboxes. The .gathered attribute of the variable will be set to True after the elements are set. See groups for more information.

objects:
  protagonist: Individual
  antagonist: Individual
---
mandatory: True
code: |
  protagonist.name.first = "Harry"
  protagonist.name.last = "Potter"
  antagonist.name.first = "Tom"
  antagonist.name.last = "Riddle"
---
question: Who are the villains, if any?
fields:
  no label: villain
  datatype: object_checkboxes
  choices:
    - protagonist
    - antagonist

GitHub

You can use datatype: object_checkboxes on variables that already exist in your interview. You would need to do this if you wanted the variable to be a subtype of DAList. If you use a variable name that already exists, note that the question will only be used when the .gathered attribute is needed. To avoid questions asking for .there_are_any and .there_is_another, set .auto_gather to False. For example:

modules:
  - docassemble.base.legal
---
objects:
  protagonist: Individual
  antagonist: Individual
---
mandatory: True
code: |
  protagonist.name.first = "Harry"
  protagonist.name.last = "Potter"
  antagonist.name.first = "Tom"
  antagonist.name.last = "Riddle"
---
question: Who are the villains, if any?
fields:
  no label: villain
  datatype: object_checkboxes
  choices:
    - protagonist
    - antagonist
---
objects:
  villain: PartyList.using(auto_gather=False)
---
question: |
  % if villain.number() == 0:
  There are no villains here.
  % else:
  The ${ villain.as_noun() }
  ${ villain.does_verb("include") }
  ${ villain }.
  % endif
subquestion: |
  The class name of `villain` is
  `${ villain.__class__.__name__ }`.
mandatory: True

GitHub

Note the placement of the objects block that defines villain as a PartyList. If this objects block came before the question that defines villain, then the question block would take precedence over the objects block and define villain as a plain DAList. Since the objects block is placed after the question, it supersedes the question, and defines villain as a PartyList. The question will still be asked, however, because even if villain is defined, it is not yet gathered; the question will be asked when a definition of villain.gathered is needed.

When you use an already-existing DAList, you can set default values of the checkboxes in the object_checkboxes list. In this example, we use the .append() method to initialize the list of villains.

mandatory: True
objects:
  protagonist: Individual
  antagonist: Individual
  villain: PartyList.using(auto_gather=False)
---
mandatory: True
code: |
  protagonist.name.first = "Harry"
  protagonist.name.last = "Potter"
  antagonist.name.first = "Tom"
  antagonist.name.last = "Riddle"
  villain.append(antagonist)
---
mandatory: True
question: Who are the villains, if any?
fields:
  no label: villain
  datatype: object_checkboxes
  choices:
    - protagonist
    - antagonist

GitHub

This example illustrates a second method of making sure that villain gets defined as a PartyList: marking the objects block with mandatory: True. This causes each variable in the objects list to be defined as an object before the rest of the interview logic is evaluated.

datatype: object_multiselect is similar to datatype: object_checkboxes, except it uses the HTML <select> element with the multiple flag set. On desktop browsers, multiple items can be selected by clicking items while holding down the Ctrl or Command key and clicking each item.

question: Who are the villains, if any?
fields:
  no label: villain
  datatype: object_multiselect
  choices:
    - protagonist
    - antagonist

GitHub

Machine learning

From the user’s perspective, datatype: ml works just like datatype: text (which is the default if no datatype is indicated), and datatype: mlarea works just like datatype: area.

From the interview developer’s perspective, however, the variable that is set is not a piece of text, but an object representing a classification of the user’s input, based on a machine learning model that is “trained” to classify user input.

question: |
  Describe how you feel.
fields:
  - no label: mood
    datatype: ml
---
mandatory: True
question: |
  You sound ${ mood }.

GitHub

For more information about how to use machine learning variables, see the machine learning section.

Hidden field

input type: hidden results in an invisible field that can only be changed from its default value by JavaScript.

question: |
  What is your favorite fruit?
fields:
  - Fruit: favorite_fruit
  - field: favorite_vegetable
    input type: hidden
    default: turnip

GitHub

This can be useful if you want fields to be populated by the address autocomplete feature but you do not want the fields to be shown to the user.

If you think you need to use input type: hidden, but you are not using the address autocomplete feature and you have not written your own JavaScript code to populate the field, then you most likely should not use input type: hidden, and should perhaps use a code block instead. The input type: hidden feature exists solely for interacting with JavaScript and is not part of docassemble’s logic system.

No browser-based input validation is performed on a field with input type: hidden. If you need input validation on a input type: hidden field, use validation code. An error message cannot be displayed next to a hidden field.

objects:
  - doctor: Person
---
question: |
  Who is your doctor?
fields:
  - Name: doctor.address.name
    address autocomplete:
      types:
        - doctor
      fields:
        - address_components
        - geometry
        - name
        - place_id
  - Address: doctor.address.address
  - Unit: doctor.address.unit
    required: False
  - City: doctor.address.city
  - State: doctor.address.state
    code: states_list()
  - Zip: doctor.address.zip
  - field: doctor.address.place_id
    input type: hidden
  - field: doctor.address.latitude
    datatype: number
    input type: hidden
  - field: doctor.address.longitude
    datatype: number
    input type: hidden
validation code: |
  if not doctor.address.place_id:
    validation_error('You need to choose a doctor from the pull-down list.')
---
depends on:
  - doctor.address.name
code: |
  doctor.name.text = doctor.address.name
---
mandatory: True
question: |
  The `place_id` of ${ doctor } is
  `${ doctor.address.place_id }`.
subquestion: |
  The office is located at
  `${ repr((doctor.address.latitude, doctor.address.longitude)) }`.

GitHub

Raw data

By default, inputs with the datatype of text (which is the default) will be sanitized of any HTML. If you want to allow users to include HTML, set the datatype to raw.

question: |
  Type HTML into both fields.
fields:
  - HTML: html_input
    datatype: raw
  - Non-HTML: text_input
---
mandatory: True
question: |
  Result
subquestion: |
  HTML:
  
  ${ html_input }
  
  Non-HTML:
  
  ${ text_input }

GitHub

Custom data types

You can use custom data types by declaring a subclass of CustomDataType in a Python module with class attributes that describe the data type. For example, here is an example that defines a Social Security number (SSN) as a data type:

from docassemble.base.util import CustomDataType, DAValidationError, word
import re

class SSN(CustomDataType):
    name = 'ssn'
    container_class = 'da-ssn-container'
    input_class = 'da-ssn'
    javascript = """\
$.validator.addMethod('ssn', function(value, element, params){
  return value == '' || /^[0-9]{3}-?[0-9]{2}-?[0-9]{4}$/.test(value);
});
"""
    jq_rule = 'ssn'
    jq_message = 'You need to enter a valid SSN.'
    @classmethod
    def validate(cls, item):
        item = str(item).strip()
        m = re.search(r'^[0-9]{3}-?[0-9]{2}-?[0-9]{4}$', item)
        if item == '' or m:
            return True
        raise DAValidationError("A SSN needs to be in the form xxx-xx-xxxx")
    @classmethod
    def transform(cls, item):
        item = str(item).strip()
        m = re.search(r'^([0-9]{3})-?([0-9]{2})-?([0-9]{4})$', item)
        if m:
            return m.group(1) + '-' + m.group(2) + '-' + m.group(3)
        else:
            return item

This will allow you to write:

question: |
  What is your Social Security Number?
fields:
  - SSN: user.ssn
    datatype: ssn

The user will not be able to proceed without entering a valid SSN, and if the user enters an SSN without hyphens, the input will be accepted, but hyphens will be added to the variable user.ssn.

The available class attributes are:

• name (required) - the datatype name. The only valid characters are alphanumeric characters, the hyphen, and the underscore.
• container_class - a CSS class for the parent container. By default, this will be set to da-field-container-datatype- followed by the name.
• input_class - a CSS class for the <input> element. By default, this will be set to da followed by the name.
• input_type - the type for the <input> element. By default, this will be set to text.
• javascript - JavaScript code related to the data type. By default, this will be None. If not None, the attribute is treated as JavaScript code that is run when every interview on your server first loads. This is typically used to extend the capabilities of the jQuery Validation Plugin. In the example above, the javascript defines a new validation rule. For more information on how to extend the jQuery Validation Plugin, see the documentation for jQuery.validator.addMethod(). The javascript code can be used to initialize any fields on the screen that have the custom datatype. For example, if your container_class is da-ssn, your javascript could be:

$(document).on('daPageLoad', function(){
  $(".da-ssn").each(function(){
    $(this).after("<div>You better get this right!</div>");
  });
});

• jq_rule - the name of the jQuery Validation Plugin rule to enable on the field, if any. This is typically used to refer to a rule you define in the javascript attribute. If you want to enable multiple jQuery Validation Plugin rules, you can set this to a list of rule names.
• jq_message - the message to display to the user when the jq_rule is not satisfied. The message will pass through the word() function to support multiple languages, and it can be overridden with validation messages. Instead of setting jq_message to a string, you can set it to a dictionary in which the keys are jQuery Validation Plugin rule names and the values are error messages. For example, if you want a custom message to display when the user leaves the field blank, you can set jq_message to something like jq_message = {'ssn': 'You need to enter a valid SSN.', 'required': 'We really need your SSN.'}. If no message is provided for a rule, a generic message is used. If jq_rule is a list of rules, jq_message must be expressed in dictionary format.
• skip_if_empty - the default is True. This is rarely used, so you can probably ignore it. This is relevant when the datatype is used on a multiple-choice question and there are zero choices to present to the user. If skip_if_empty is True, then the variable is not set to any value. If skip_if_empty is False, then the variable will be set to the output of the .empty() class method.
• is_object - the default is False. If you have a transform() class method that returns something that cannot be defined with with repr(), set this to True.
• parameters - the default is []. If you want to pass parameters from the YAML to data attributes of the resulting <input>, you can list the parameter names here. For example, if parameters is set to ['kind'], and you include kind: basic as a field modifier in the YAML of the field, then the HTML of the <input> element will contain data-kind="basic". You can extract these data values using JavaScript.
• code_parameters - the default is []. This is just like parameters, except the values in the YAML are treated as a Python expression, and the data value is set to the output of this evaluation. Make sure that the Python expression evaluates to something sensible, like a string.
• mako_parameters - the default is []. This is just like parameters, except the values in the YAML are treated as Mako, and the data value is set to the rendered text.

The available class methods are:

• validate() - the validate() class method is used for server-side input validation. The raw value from the POST request is passed to this method as the first positional parameter. The method should return True if the value is valid. If the value is invalid, the method should raise a DAValidationError exception with a message. The message given to DAValidationError will pass through the word() function before it is presented to the user, so you can use the words directive in the Configuration to support multiple languages. If the method returns a false value, the error message will be “You need to enter a valid value.” If a validate() class method is not provided, no input validation will be performed.
• transform - the transform() class method is used to perform any necessary transformations on the data received from the browser. The raw value from the POST request is passed to this method as the first positional parameter. The method should return the transformed value. In the example above, the transform() class method ensures that Social Security numbers that are entered without hyphens (which are accepted) will contain hyphens when the variable user.ssn is actually defined. If a transform() class method is not provided, the variable will be set to the raw value from the POST request (a string).
• default_for - the default_for() method is used when the user visits a question when the variable is already defined. If the output of your transform method is not suitable for placing into the field as the default value, you can define a default_for() class method that returns the text that should be inserted into the field. The default_for() class method takes a single positional parameter, which is the value of the variable. For example, if your transform() method returns a Python object, you can write a default_for() class method that takes the object as its parameter and returns plain text (an str) that is a suitable default value to insert into the field. If you do not define a default_for() class method, an attempt will be made to obtain a default value by running str() on the variable.
• empty - this is rarely used, so you can probably ignore it. The empty class method is used when skip_if_empty is False. Instead of not defining the variable, docassemble will set the value of the variable to the output of this method. If no empty() method is provided, the value None is used.

If you provide client-side input validation, it is also a good idea to provide server-side validation, even though it might never be triggered. There are ways that users might accidentally or deliberately bypass client-side input validation. So even if you have a jQuery Validation Plugin rule that works, it is a good idea to include a validate() class method.

Python classes, when loaded into the Python web application, are loaded globally across all threads of the server; they are not loaded just for one interview or just for one session. Likewise, the name attribute associated with a CustomDataType class is also global on the server. For this reason, you may wish to “namespace” your CustomDataType names, using a name like aag_ssn instead of of ssn (e.g., if your company name is AAG). That way, if a number of different packages are used together, it is less likely there will be “name collision.”

By default, docassemble will load the JavaScript for any CustomDataType data types that are used in the interview YAML. However, if fields are created by Python code, docassemble cannot detect what CustomDataType data types will be used. In this circumstance, you can manually list them under custom datatypes to load specifier under features, and the necessary JavaScript will be loaded.

How custom data types work

When the server starts, it looks through all of the packages under the docassemble namespace and loads every .py file that contains a class definition (unless the line # do not pre-load is present). It is during this initial loading time that CustomDataType class definitions are processed and loaded. As a result, you do not need to load the .py file in your interview with modules or imports when you use a datatype from a CustomDataType class in your YAML.

When choosing a name for your CustomDataType, do not use a name that someone else might use. Because CustomDataType class definitions are processed when the server starts, all CustomDataType definitions are global to the server; they are not specific to a particular interview, session, or user. If another module is installed on the system (including in the Playground of some other user) that defines a CustomDataType with the same name as that which you are trying to define, one definition will overwrite the other and you may get confusing results.

Options for items in fields

The following are the keys that have special meaning within a list item under fields.

datatype

datatype affects how the data will be collected, validated and stored. For a full explanation of how this is used, see above.

input type

The input type is similar to datatype. It is used in situations where the datatype might be date, number, etc., but you want the field to use a particular type of multiple-choice input element, such as a list of radio buttons or a combobox. For a full explanation of how this is used, see above.

required

required affects whether the field will be optional or required. If a field is required, it will be marked with a red asterisk, and input validation will be enforced to make sure the user provides a value.

If the user skips a non-required field, the variable will be blank for text-based fields, 0.0 for number and currency fields, 0 for integer fields, and None for multiple-choice and yes/no fields.

Some datatypes are never marked with a red asterisk. For example, range and yesno fields are set to real values by default, so the user cannot actually skip the question.

The value of required can be True or False. By default, all fields are required, so you never need to write required: True unless you want to.

question: |
  What are your favorite things to eat?
subquestion: |
  You may not like any vegetables,
  but at least tell me your favorite
  fruit.
fields:
  - Vegetable: target_variable
    required: False
  - Fruit: other_target_variable

GitHub

Instead of writing True or False, you can write a Python expression. This expression will be evaluated for whether it turns out to be true or false. For example, instead of True or False, you could use the name of a variable that is defined by a yesno question.

question: Do you like soda?
yesno: user_likes_soda
---
question: |
  What are your favorite
  things to drink?
fields:
  - Favorite Beverage Overall: favorite_beverage
  - Favorite Soda: favorite_soda
    required: user_likes_soda

GitHub

Instead of using a true/false variable, you could use a conditional expression such as favorite_fruit == 'apple'.

Note that the Python expression is evaluated on the server, before the screen loads in the browser. Whether a field is required or not cannot be controlled in real time when the user is looking at the screen.

disabled

If the disabled field modifier is set to True or to a Python expression that evaluates to a true value, the field will be displayed as normal, but will be disabled.

question: |
  What are your favorite things to eat?
subquestion: |
  (It goes without saying that you love turnips.)  
fields:
  - Fruit: favorite_fruit
  - Vegetable: favorite_vegetable
    disabled: True
    default: turnips

GitHub

When the field is disabled, this also has the effect of required: False.

When the user presses the Continue button, the variable associated with the field will be ignored; it will not be defined or changed.

Note that if the interview logic has arrived at the question because it needs the value of a variable that is listed as a field under fields in the question, but you have disabled the field, the interview logic will ask the question again after the user presses Continue. You can avoid this problem by defining the variable with a different block, and using a different variable name for the disabled field.

question: |
  What is your favorite vegetable?
fields:
  - Vegetable: favorite_vegetable
---
question: |
  What are your favorite things to eat?
fields:
  - Fruit: favorite_fruit
  - Vegetable: favorite_vegetable_placeholder
    disabled: True
    default: |
      ${ favorite_vegetable }

GitHub

Note that the disabled modifier is unrelated to the disable if, js disable if, and disable others modifiers.

under text

You can guide users as to how they should fill out a text field by displaying text under the field. You can use Mako templates within under text.

question: |
  What are your favorite things to eat?
subquestion: |
  Please be specific.
fields:
  - Vegetable: target_variable
    under text: E.g., eggplant, turnips
  - Fruit: other_target_variable
    under text: E.g., apples, oranges

GitHub

hint

You can guide users as to how they should fill out a text field by showing greyed-out text in a text box that disappears when the user starts typing in the information. In HTML, this text is known as the placeholder. You can set this text for a text field by setting hint. You can use Mako templates within hints.

question: |
  What are your favorite things to eat?
subquestion: |
  Please be specific.
fields:
  - Vegetable: target_variable
    hint: e.g., eggplant, turnips
  - Fruit: other_target_variable
    hint: e.g., apples, oranges

GitHub

The hint is also used to provide the default text the user sees when they fill out a multiple-choice dropdown or a combobox input element within a fields question.

help

You can provide contextual help to the user regarding the meaning of a field using the help field modifier. A question mark icon can be clicked on to show the help text in a popup. You can use Mako templates within help text.

question: |
  What are your favorite things to eat?
subquestion: |
  If you don't know what a vegetable or
  fruit is, click the question mark icons.
fields:
  - Vegetable: target_variable
    help: |
      A plant.
  - Fruit: other_target_variable
    help: |
      The pulpy, edible seed vessels
      of certain plants.

GitHub

default

You can provide a default value to a field using default. You can use Mako templates in default text.

question: |
  What are your favorite things to eat?
subquestion: |
  Please be specific.
fields:
  - Vegetable: target_variable
    default: eggplant
  - Fruit: other_target_variable
    default: |
      ${ greatest_fruit }
---
code: |
  greatest_fruit = "apples"

GitHub

choices

The choices field modifier is used with multiple-choice fields. It must refer to a list of possible options. The list can be a list can be a list of plain text items (in which case the label and the variable value are the same) or a list of key/value pairs (in which the key is the label seen by the user and the value is the value to which the variable will be set).

question: |
  What is your favorite fruit?
fields:
  - Fruit: favorite_fruit
    choices:
      - "${ 'Apples' }": apple
      - Oranges: orange
      - Pears: pear

GitHub

When the datatype is object, object_radio, or object_checkboxes, choices indicates a list of objects from which the user will choose. For more information about using objects in multiple choice questions, see the section on selecting objects, below.

code

If you have a multiple-choice question (radio buttons, checkboxes, dropdown) and you want to reuse the same selections several times, you do not need to type in the whole list every time. You can define a variable to contain the list and a code block that defines the variable.

Adding code to a field makes it a multiple-choice question. The code itself refers to Python code that generates a list of possible options for a multiple choice field. The code field modifier is used in place of a choices field modifer, which you would use to specify the choices manually.

question: |
  What is your favorite fruit?
fields:
  - Fruit: favorite_fruit
    datatype: radio
    code: |
      myoptions
---
question: |
  What is your brother's favorite
  fruit?
fields:
  - Fruit: favorite_fruit_of_brother
    datatype: radio
    code: |
      myoptions
---
code: |
  myoptions = [
                {'apple': "Apples"},
                {'orange': "Oranges"},
                {'pear': "Pears"}
              ]

GitHub

The Python code runs at the time the question is asked. Therefore, you can use the code feature to create multiple-choice questions that have dynamically-created lists of choices.

The Python code needs to be a single Python expression (which can be a simple variable, or something more complex, like a list comprehension). The result of the expression can take several forms.

It can be a list of single-item dictionaries, as in the example above.

It can be a dictionary (in which case you cannot control the order of items):

code: |
  myoptions = {
                'apple': "Apples",
                'orange': "Oranges",
                'pear': "Pears"
              }

GitHub

It can be a list of text items (in which case the values and labels will be the same):

code: |
  myoptions = ["Apples", "Oranges", "Pears"]

GitHub

It can be a list of two-element lists:

code: |
  myoptions = [
                ['apple', 'Apples'],
                ['orange', 'Oranges'],
                ['pear', 'Pears']
              ]

GitHub

You can specify a default by including a three-element list where the third element is True if the choice should be selected by default.

code: |
  myoptions = [
                ['apple', 'Apples'],
                ['orange', 'Oranges', True],
                ['pear', 'Pears']
              ]

GitHub

You can include “help text” for a choice by including a fourth element in one of the lists, where the element contains the help text you want to be available. The user can see the help text by touching the question mark button.

code: |
  myoptions = [
                ['apple', 'Apples', None, 'Apples are good in pies.'],
                ['orange', 'Oranges', None, 'Oranges are a type of citrus fruit.'],
                ['pear', 'Pears', None, 'Pears are an acquired taste.']
              ]

GitHub

If your code is a list of tuples, it will be treated the same as a list of lists.

If your code is a list of dictionaries, you can include a 'default' key in the dictionary indicating a true or false value that represents whether the choice should be selected by default.

code: |
  myoptions = [
                {'apple': "Apples",
                 'default': True},
                {'orange': "Oranges"},
                {'pear': "Pears"}
              ]

GitHub

Similarly, you can include help text in a list of dictionaries by including a 'help' key in the dictionary indicating the help text that should be available to the user.

code: |
  myoptions = [
                {'apple': "Apples",
                 'default': True,
                 'help': "Apples are good in pies."},
                {'orange': "Oranges",
                 'help': "Oranges are a type of citrus fruit."},
                {'pear': "Pears",
                 'help': "Pears are an acquired taste."}
              ]

GitHub

Instead of specifying the choices using key-value pairs where the keys are what the variable is set to and the values are the labels, you can use keys label and value to reference the label and the corresponding variable value.

code: |
  myoptions = [
                {'label': "Apples",
                 'value': 'apple'},
                {'label': "Oranges",
                 'value': 'orange'},
                {'label': "Pears",
                 'value': 'pear'}
              ]

GitHub

exclude

If you build the list of choices with code, you can exclude items from the list using exclude, where the value of exclude is Python code.

question: |
  What is your favorite fruit?
fields:
  - Fruit: favorite_fruit
    datatype: radio
    code: |
      myoptions
---
question: |
  What is your brother's favorite
  fruit, assuming he does not like
  ${ favorite_fruit }?
fields:
  - Fruit: favorite_fruit_of_brother
    datatype: radio
    code: |
      myoptions
    exclude: |
      favorite_fruit
---
code: |
  myoptions = [
                {'apple': "Apples"},
                {'orange': "Oranges"},
                {'pear': "Pears"}
              ]

GitHub

In this example, the value of exclude is a single variable. If given a list of things, it will exclude any items that are in the list.

none of the above

If you use datatype: checkboxes, then by default a “None of the above” choice is added.

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

You can turn off the “None of the above” choice by setting the none of the above option to False.

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    none of the above: False
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

You can also change the phrase from “None of the above” to something else, even a Mako expression. Just set none of the above to the text you want to be displayed.

question: |
  Please fill in the following information.
fields:
  - Requested options: car_options
    datatype: checkboxes
    choices:
      - Sunroof
      - Automatic transmission
      - Heated seats
    none of the above: |
      Nothing ${ "at all" }

GitHub

If you use datatype: object_radio, you can use none of the above in the same way. If the user selects the “none of the above option,” the variable will not be defined when the user presses Continue.

This option can be useful when you are using the disable others feature:

question: |
  Who is the trustee?
fields:
  - no label: trustee
    datatype: object_radio
    disable others: True
    none of the above: Someone else
    choices:
      - agent
  - First name: trustee.name.first
  - Middle name: trustee.name.middle
    required: False
  - Last name: trustee.name.last
  - Suffix: trustee.name.suffix
    required: False
    code: name_suffix()

GitHub

You can also use datatype: object_radio and none of the above in combination with show if:

question: Who is the villain?
fields:
  - The villain is: villain
    datatype: object_radio
    default: antagonist
    none of the above: Someone else
    choices:
      - protagonist
      - antagonist
  - First name: villain.name.first
    show if:
      variable: villain
      is: null
  - Last name: villain.name.last
    show if:
      variable: villain
      is: null

GitHub

all of the above

If you use datatype: checkboxes, you can optionally include an “All of the above” option.

question: |
  Please tell me what you think.
fields:
  - "Select the fruits you like": likes_fruit
    datatype: checkboxes
    choices:
      - Apples
      - Peaches
      - Pears
    all of the above: True
    none of the above: False
  - "What is your favorite fruit overall?": favorite_fruit

GitHub

You can change the phrase from “All of the above” to something else, even a Mako expression. Just set all of the above to the text you want to be displayed.

question: |
  Please fill in the following information.
fields:
  - Requested options: car_options
    datatype: checkboxes
    choices:
      - Sunroof
      - Automatic transmission
      - Heated seats
    all of the above: |
      I want to pay a lot
    none of the above: False

GitHub

shuffle

shuffle can be used on multiple-choice fields (defined with code or choices). When True, it randomizes the order of the list of choices; the default is not to “shuffle” the list.

question: |
  For which of the following obscure
  candidates do you wish to vote?
fields:
  - Candidate: candidate
    datatype: radio
    shuffle: True
    choices:
      - Aaron Aardvark
      - Albert Arnold
      - Felicia Fellowes
      - Miranda Moore
      - Zachariah Zephyr

GitHub

show if

You can use the show if field modifier if you want the field to be hidden under certain conditions. There are three methods of using show if, which have different syntax.

Using the first method, the field will appear or disappear in the web browser depending on the value of another field in the fields list that is visible on the screen. Under this method, show if refers to a YAML dictionary with two keys: variable and is, where variable refers to the variable name of the other field, and is refers to the value of the other field that will cause this field to be shown.

This can be useful when you have a multiple-choice field that has an “other” option, where you want to capture a text field but only if the user selects the “other” option.

question: |
  What kind of car do you drive?
fields:
  - Make: car_make
    choices:
      - Honda
      - Toyota
      - Mazda
      - Other
  - Other make: car_make
    show if:
      variable: car_make
      is: Other

GitHub

Note that you can only use this syntax to refer to other fields on the screen; you cannot refer to arbitrary Python variables in your interview answers. This method of show if is JavaScript-based, and takes place in the browser. The interview answers are in Python, on the server. The web browser does not have access to all of the Python variables in the interview answers; it only has access to the values of fields that are displayed in the user interface.

The second method is like the first, but is a shorthand syntax for the special case where the other field in fields is a yes/no variable. Under this method, show if refers to the other field’s variable name. If that yes/no input is set to a “yes” value, the field will be shown, and otherwise the field will be hidden.

question: |
  Please fill in the following information.
fields:
  - "Do you like fruit?": likes_fruit
    datatype: yesnoradio
  - "What's your favorite fruit?": favorite_fruit
    show if: likes_fruit

GitHub

As with the first method, the variable name referred to by show if: must be a variable name associated with a field on the screen (listed under fields); it cannot refer to any arbitrary Python variable.

Note that if show if refers to a field that is itself hidden by a show if, then the condition is considered to be false.

question: |
  Please fill in the following information.
fields:
  - "Do you like fruit?": likes_fruit
    datatype: yesnoradio
  - "Do you like apples?": likes_apples
    datatype: yesnoradio
    show if: likes_fruit
  - "Why do you like apples?": reason_for_liking_apples
    show if: likes_apples
  - "Why do you hate apples?": reason_for_hating_apples
    show if:
      variable: likes_apples
      is: False
  - "Do you like Fuji apples?": likes_fuji
    datatype: yesnoradio
    show if: likes_apples
  - "Why do you like Fuji apples?": reason_for_liking_fuji_apples
    show if: likes_fuji

GitHub

Under the third show if method, the field is either shown or not shown on the screen when it loads, and it stays that way. You can use Python code to control whether the field is shown or not. Unlike the first method, you are not limited to using variables associated with fields in the fields list; you can use any Python code; however, you cannot refer to any of the variables that are defined by the current question. Under this method, show if must refer to a YAML dictionary with one key, code, where code contains Python code. The code will be evaluated and if it evaluates to a positive value, the field will be shown.

question: |
  Please fill in the following information.
fields:
  - Favorite fruit: fruit
  - Favorite vegetable: vegetable
  - Favorite fungus: mushroom
    show if:
      code: |
        2 + 2 == 3

GitHub

With all of these methods, if any field is not visible on the screen when the user presses the Continue button, no variable will be set to anything for that field; it as if the field was never part of the question. Therefore, you should always make sure that your interview logic (including a document that your interview logic assembles) does not expect these hidden fields to have a definition.

For example, suppose you have this question:

question: What is your favorite fruit?
fields:
  - Fruit: favorite_fruit
    choices:
      - Apple
      - Orange
      - Peach
  - Favorite apple: favorite_apple
    show if:
      variable: favorite_fruit
      is: Apple

Suppose your interview assembles a document that contains this content:

Favorite fruit: {{ favorite_fruit }}

Favorite apple: {{ favorite_apple }}

In this case, you may find that when favorite_fruit is Orange or Peach and you press Continue, you will end up back at the same screen again. This is because your document is requiring a definition of favorite_apple. You may have assumed that favorite_apple will be defined as the empty string, but that is not how it works.

The way to fix this is to put your logic into the document:

Favorite fruit: {{ favorite_fruit }}

Favorite apple: {% if favorite_fruit == ‘Apple’ %}{{ favorite_apple }}{% else %}N/A{% endif %}

This way, your interview logic will not include the value of favorite_apple unless it is applicable.

You may be tempted to write something like this:

Favorite apple: {% if defined(‘favorite_apple’) %}{{ favorite_apple }}{% else %}N/A{% endif %}

However, this is a bad practice that will lead to problems. For example, if your users revise their answers, the interview answers could reach a state in which favorite_apple is defined but favorite_fruit is not Apple, in which case it would be inappropriate to display the favorite_apple in the document. Or, the user might change favorite_fruit from Orange to Apple, in which case favorite_apple would be undefined even though it should be defined. If you weren’t using defined(), the assembly of your document would have ensured that the favorite_apple question would be asked. Always base your interview logic on actual facts, not the defined-ness of variables.

If you need to set a default value of a field that could be hidden by a show if, you can specify a code block following the question:

question: What is your favorite fruit?
fields:
  - Fruit: favorite_fruit
    choices:
      - Apple
      - Orange
      - Peach
  - Favorite apple: favorite_apple
    show if:
      variable: favorite_fruit
      is: Apple
---
code: |
  if favorite_fruit != 'Apple':
    favorite_apple = 'N/A'
depends on:
  - favorite_fruit

The depends on modifier will ensure that favorite_apple is invalidated if and when the value of favorite_fruit changes.

Note that the first and second methods (as well as the js show if methods discussed below) are JavaScript-based (“client side”), while the third is Python-based (“server side”). The client-side JavaScript code context is only aware of fields that exist on the screen in the user’s web browser, not the variables in the interview answers; the user’s browser does not know the values of all the Python variables in the interview answers. Conversely, the server-side Python context is only aware of the interview answers, and is not aware of the values of fields on the screen.

The show if field modifer is not intended to be used as a primary mechanism of controlling interview logic; it is more of a feature for customizing the user interface. Thus whatever logic you express in show if will probably have to be repeated elsewhere. If instead of using show if you gathered the field in a separate question, you would only need to specify the logic in one place.

hide if

This works just like show if, except that it hides the field instead of showing it.

question: |
  Please fill in the following information.
fields:
  - "Do you have fruit?": has_fruit
    datatype: yesnoradio
  - "What fruit do you need?": fruit
    hide if: has_fruit

GitHub

hide if cannot be combined with show if.

enable if and disable if

The enable if and disable if field modifiers work just like show if and hide if, except that instead of visibly hiding the fields and labels, it disables the input elements.

The use of code inside of enable if and disable if is not supported. The disabled modifier allows you to cause a field to be disabled based on a Python expression.

enable if and disable if cannot be combined with show if or hide if on the same field.

js show if

Sometimes you might want to do more complicated evaluations with on-screen variables than you can do with show if and hide if. When you use the show if and hide if field modifiers to refer to fields that are on the screen, you are able to test whether the fields are true, or have particular values, but you cannot do anything more complex, such as test whether the value is one of two values, or the values of two fields. You also can’t combine show if, hide if, and disable if on the same field.

The js show if and js hide if features allow you to use any arbitrary JavaScript expression to determine whether a field should be shown or not. In these expressions, the special JavaScript function val() is used to obtain the values of fields. Given the name of an on-screen field as a string, the val() function returns the current value of that field.

JavaScript is its own complete language with different syntax than Python, but with some similarities.

• Instead of and, use &&
• Instead of or, use ||
• Instead of ==, use === (== will often work as well but may have subtle differences)
• Just like in Python, you can group expressions with parentheses ()
• Instead of True, False and None, JavaScript has true, false, and null as well as undefined