In the docassemble web app, every screen that a user sees is generated by a question block, which is a section of YAML code that contains a question specifier. (Well, you can also generate a screen using the message() function, but that is an advanced topic.)

All blocks in an interview file must either be initial blocks, code blocks, or contain a question specifier.

The `question` block

question: |
  What is the airspeed velocity of an
  unladen swallow?
fields:
  - Velocity: swallow_velocity

By including the above YAML block in your interview file, you are telling docassemble that if it ever needs to know the value of swallow_velocity, it should ask the user the question “What is the airspeed velocity of an unladen swallow?” and provide the user with an input box labeled “Velocity” in which the user can type the answer.

Like many things in docassemble, the question specifier can contain Markdown and Mako. For example:

question: |
  What is the *airspeed* velocity of an
  unladen ${ african_or_european }
  swallow?
fields:
  - Velocity: swallow_velocity

In this example, the word “airspeed” is italicized, using the Markdown syntax for italics. The type of swallow is given by a variable (african_or_european), the value of which ("African") is incorporated using Mako. (One of the features of Mako is that anything enclosed in ${ ... } is evaluated as Python code.)

The `subquestion` specifier

The optional subquestion adds text underneath the question. It is typically used to explain the question in more detail, if such an explanation is necessary.

question: |
  What is the airspeed velocity of an
  unladen swallow?
subquestion: Be careful how you answer.
fields:
  - Velocity: swallow_velocity

The `under` specifier

The optional under specifier adds text underneath the buttons.

question: |
  What is the airspeed velocity of an
  unladen swallow?
fields:
  - Velocity: swallow_velocity
under: |
  Note: if you did not catch this
  movie reference, you need to
  improve your cultural literacy.

The `right` specifier

The optional right specifier adds text on the right-hand side of the screen, or below the question on small screens.

question: |
  What is the airspeed velocity of an
  unladen swallow?
fields:
  - Velocity: swallow_velocity
right: |
  ### Note
    
  If you did not catch this
  movie reference, you need to
  improve your cultural literacy.

If your interview has questions that use the right specifier, you might want to set the centered feature to False so that the text on the right is wider.

features:
  centered: False
---
question: |
  What is the airspeed velocity of an
  unladen swallow?
fields:
  - Velocity: swallow_velocity
right: |
  ### Note
    
  If you did not catch this
  movie reference, you need to
  improve your cultural literacy.

The `css class` specifier

The optional css class specifier can be used to set a CSS class for the <body> of the screen of a question.

css class: first-question
mandatory: True
question: |
  View the source and look for
  the word `first-question`.

Using questions to set variables

Here is a brief summary of the types of questions that can be asked. More detail about how these question types work is provided in the next section.

True or false: `yesno` and `noyes`

A yesno question will set a variable to True or False when a Yes or No button is pressed. noyes does the opposite.

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

Multiple choice: `choices` or `buttons`

You can ask a multiple-choice question by providing a list of choices:

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

Or, if you would prefer to use one-click buttons instead of “radio buttons” in combination with a “Continue” button, use can use buttons instead of choices.

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

The variable indicated by field will be set to the value supplied in the choices/buttons list.

Acknowledgement button: `field`

If you simply want the user to acknowledge something by clicking “Continue,” provide a field without buttons or choices.

The variable indicated by field will be set to True when the user clicks “Continue.”

field: target_variable
question: |
  Welcome to the interview.
subquestion: |
  When you are ready to begin, press
  Continue.

One or more fill-in fields: `fields`

You can ask the user to fill in multiple fields using fields.

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

There are many other types of input that you can gather with fields, including large text areas, file uploads, radio buttons, and checkboxes. There are a variety of ways you can insert text into the list of fields to help guide the user. If you know HTML, you can insert arbitrary HTML, CSS, and Javascript. Using the show if feature, you can cause fields to appear or disappear depending on the values of other fields.

User’s signature: `signature`

You can ask the user to write his or her signature using signature:

question: |
  Sign your name
subquestion: |
  By signing your name, you agree to
  our terms and conditions.
signature: target_variable
under: |
  ${ user }

The signature will be stored as an image file in the variable indicated by signature.

Ending screens

Sometimes, the purpose of your question is not to gather information but to present an end screen to the user. You can create such “questions” by marking them as mandatory:

question: |
  Congratulations!
subquestion: |
  You are all done with the interview.
mandatory: True

If you have more than one possible ending screen in your interview, use the event feature described below.

Special buttons

Using the buttons or choices syntax described above, you can add special buttons to a screen. These buttons are special because they do not set a variable.

These buttons are particularly useful on “terminal” screens.

question: We are all done.
buttons:
  - Exit: exit
  - Restart: restart
mandatory: True

The above example allows the user to “exit” the interview (i.e., to be redirected to a different web site) or “restart” the interview (i.e., go back to the beginning, with all of the answers forgotten).

There are six special button functions:

restart
new_session
exit
logout
exit_logout
leave
continue
refresh
signin

restart resets the user’s variable store, except that any parameters that were originally passed through as URL parameters will be used again. The user is redirected to the first question of the interview.

new_session does not disturb the current interview session, but starts a new session for the same interview. The original URL parameters are not used.

exit means that the user’s variable store will be erased and the user will be redirected either to the URL given by the associated url text, or if no url is defined, to the exit url defined in the metadata, or if that does not defined, then to the exitpage defined in the configuration. If the user tries to come back to the interview again, he will start the interview again, as though it had never been started. Original URL parameters will be lost.

For example:

question: |
  Congratulations, you found Nemo!
buttons:
  - Try again: restart
  - Learn More: logout
    url: https://en.wikipedia.org/wiki/Amphiprioninae
mandatory: True

Mako can be used in the url text.

logout logs the user out, if the user is logged in.

exit_logout does the same thing as exit, except that it also logs the user out, if the user is logged in.

leave works like exit except that the user’s variable store will be left intact. This means that if the user comes back to the interview again, he will pick up where he left off.

continue means that docassemble will move on from the question without really doing anything. Here is an example of when it is useful:

mandatory: True
code: |
  menu_items = [ action_menu_item('Visit Cow', 'see_cow') ]
---
event: see_cow
question: |
  Moo!
subquestion: |
  [FILE cow.jpg]
  
  Cow illustration designed by
  [Freepik](http://www.freepik.com/free-photos-vectors/animal)
buttons:
  - Continue: continue
---
question: Welcome to the interview
subquestion: |
  Check out the menu in the
  upper-right corner.
mandatory: True

This example uses the actions feature and the menu_items special variable to present a special screen that shows a picture. This screen does not set any variable, but the user can click the button to “continue” with the normal course of the interview.

While using continue can be useful sometimes, it is generally not a good idea to structure interviews around questions that use continue. These questions cannot use the generic object modifier or index variables.

refresh re-runs the interview logic. It has much the same effect as refreshing the page in the browser. It is useful in multi-user interviews when the user is waiting for another user to finish entering information. It can also be useful in interviews that use external data sources.

mandatory: True
code: |
  tell_time
---
event: tell_time
question: |
  The current time is
  ${ current_datetime().format_time() }.
buttons:
  - Tell me again: refresh

signin redirects the user to the docassemble sign-in page.

mandatory: True
code: |
  if user_logged_in():
    goodbye_page
  else:
    sign_in_page
---
question: |
  Please sign in
buttons:
  - Sign in: signin
sets: sign_in_page

Instead of using buttons, you can use choices to get a radio list instead of a selection of buttons.

question: We are all done.
choices:
  - Exit: exit
  - Restart: restart
mandatory: True

The functionality is the same.

The command() function allows you to do similar things with Python code. In addition, the url_of() function provides URLs that accomplish a similar purposes.

Mixing special buttons with buttons that set a variable

Note that since “special” buttons do not set a variable, you should not include a field in the question. If you include a field in the question, docassemble will assume you are creating an ordinary multiple choice question.

If you wish to mix “special” buttons with buttons that set a variable, you can use the command() function in code to trigger the same effects as clicking on a “special” button.

The following example uses a mandatory code block to determine the course of the interview. Depending on the answer to an ordinary multiple choice question, it either exits from the interview or proceeds to another screen.

mandatory: True
code: |
  if user_choice == 'exit':
    command('exit')
  elif user_choice == 'proceed':
    final_screen
---
question: |
  Warning!
subquestion: |
  Proceeding with this interview may
  result in despair-inducing levels
  of liability.
field: user_choice
buttons:
  - Exit: exit
  - Keep going: proceed
---
event: final_screen
question: |
  Hey, I warned you.

Screenshot of exit-buttons-mixed-code example

Another alternative is to use multiple-choice buttons that run code:

question: |
  Warning!
subquestion: |
  Proceeding with this interview may
  result in despair-inducing levels
  of liability.
buttons:
  - I understand:
      code: |
        attitude = 'careful'
  - I do not care:
      code: |
        attitude = 'reckless'
  - Get me out of here: exit
---
mandatory: true
question: |
  % if attitude == 'reckless':
  You are foolish!
  % else:
  Ok, we are proceeding with caution.
  % endif

Screenshot of exit-buttons-mixed example

Special screens: `event`

Some screens are shown to the user when a special event occurs.

For example, if you have a multi-user interview and the interview reaches a point where the user cannot proceed until the other interviewee answers a question, the interview will present the user with a question that explains why he or she needs to wait.

Or, you might want to provide the user with the ability to review his or her answers on a single screen, using the review functionality.

The event specifier advertises to the interview logic that the question should be asked if a special event occurs.

question: |
  This is a special screen.
event: show_special_screen

This specifier can be used to indicate an ending screen, where your interview has more than one possible ending screen and you use interview logic to direct the user to the appropriate screen.

question: |
  Which door do you choose?
field: door_choice
choices:
  - Door Number 1
  - Door Number 2
---
mandatory: True
code: |
  if door_choice == 'Door Number 1':
    good_luck
  if door_choice == 'Door Number 2':
    bad_luck
---
question: |
  You walk into a field of clover.
event: good_luck
---
question: |
  You walk into a stinky swamp.
event: bad_luck

In this example, good_luck and bad_luck are actually names of Python variables. However, they are Python variables that will never be defined. If a reference to these variables is made, as it is in the mandatory code block, docassemble will locate the good_luck and bad_luck questions, just as it looks for questions that offer to define any variable.

See interview logic for more information about how to give direction to your interview by adding code blocks that are marked with the mandatory modifier.

The event specifier is also used to create screens that the user can reach from the menu or from hyperlinks embedded in question text. For more information, see event, url_action(), process_action(), action_menu_item(), and menu_items.

Customizing screen parts

When the user looks at a screen in an interview, there are many different “parts” of the screen. Above, you were introduced to the question, subquestion, under, right, and css class parts.

There are other parts of the screen as well, which by default are empty or have a useful default. The following interview demonstrates where each part is located. Try out the interview and look at the results with different screen sizes.

metadata:
  title: Title
  short title: Short title
  subtitle: |
    This is the subtitle part.
  pre: |
    This is the pre part.
  submit: |
    This is the submit part.
  post: |
    This is the post part.
  under: |
    This is the under part.
  right: |
    This is the right part.
  exit link: leave
  exit label: |
    Exit label
  help label: |
    Help label
  continue button label: |
    Continue button label
  resume button label: |
    Resume button label
  back button label: |
    Back button label

Screenshot of metadata-screen-parts example

The title is the “long title” that appears in the upper-left on a large screen.
The short title appears in the upper-left on a small screen. If not provided, the title is used in its place.
The subtitle is not visible on the screen, but can be seen in the list of Available Interviews.
The logo, if set, will replace the title and short title with custom HTML content, such as an image.
The pre area is above the question.
The submit area is above the buttons, if the screen has buttons.
The under area is directly below the buttons.
The right area is to the right, but if the screen is too small, it wraps and appears under the under area.
The post area is below everything except for image attributions, which are below the post area.
The exit link is not a visible component, but rather a value that is either exit or leave. It controls the operation of the exit link in the upper right corner, which is present if show login is set to False.
The exit label is the visible label of the exit link in the upper right corner, which is present if show login is set to False.
The help label is the default label for the “help” tab. It can be overridden by a label specifier inside a help modifier. If you set a question help button, the help label will be used for the help button, while the label for the help tab will be the less conspicuous word “Help.”
The continue button label is the label for the “Continue” button. If the question is a review question, this is called the resume button label.
The back button label is the label for the back button that appears within the question itself (not the upper-left corner).

There are a variety of ways that you can specify what content should appear in these areas. These ways range from question-specific specifiers to interview-wide defaults to server-wide defaults. You should pick whatever method works best for your purposes.

You can customize many of the screen parts as part of a question block. As explained above, there are specifiers for the question, subquestion, under, and right parts. There are also modifiers for continue button label, resume button label, and back button label. When you set question-specific help, you can indicate a label that will be used as a label for the help tab or the help button.

There are three methods for specifying interview-wide default values for parts of the screen:

Using the set_parts() function in Python code to set default values for the screen parts. You can use Python logic and the get_language() function to set different values for different languages. Mako templating is not supported and formatting must use raw HTML.
Using a default screen parts block to specify dynamic content using Mako templating and Markdown formatting, which is re-evaluated every time the screen loads. Using the language modifier (or a default language block in a separate YAML file), you can write different default screen parts blocks for different languages.
Using a metadata block to specify static content that is the same for all sessions of the interview. Mako templating is not supported and formatting must use raw HTML. You can specify different content to be used for different languages. An advantage of metadata over default screen parts is that it is visible to the Available Interviews list, whereas other methods of setting defaults are not.

Finally, there is a server-wide method for specifying default values, which is to set the Configuration directives main page pre, main page post, etc. Mako templating is not supported and formatting must use raw HTML. These directives allow you to set different content for different languages.

These different methods override each other in this order. A metadata block will override Configuration directives, a default screen parts block will override a metadata block, set_parts() will override a default screen parts block, and question-specific specifiers will override a default screen parts block.

For more information about each method, see its documentation.

The question block

The subquestion specifier

The under specifier

The right specifier

The css class specifier