Special variables

Variables set by docassemble

There are some special variables that docassemble sets in every interview’s variable store.

_internal

_internal is a Python dictionary that is used by docassemble but that is not intended to be used in interviews.

nav is an object that is used to keep track of sections in your interview. This is relevant if you are using the navigation bar feature. For information about how to use it, see the documentation for the nav functions.

url_args

url_args is a Python dictionary that is used to access parameters passed via URL.

Users start an interview by going to a URL. A basic URL would look like this:

http://example.com/da?i=docassemble.example_inc:data/questions/survey.yml

Here, the only parameter is i, the interview file name.

It is possible to use the URL to pass special parameters to the interview code. For example, if the user started the interview by clicking on the following link:

http://example.com/da?i=docassemble.example_inc:data/questions/survey.yml&from=web

then the interview would load as usual, and the interview code could access the value of the from parameter by looking in the url_args variable in the variable store. For example, the interview could contain the following code:

---
code: |
if 'from' in url_args:
origin_of_interviewee = url_args['from']
else:
origin_of_interviewee = 'unknown'
---
mandatory: True
question: You came from the ${ origin_of_interviewee }.
---

Alternatively, you could use Python’s get method to do the same thing in less space:

---
mandatory: True
question: You came from the ${ url_args.get('from', 'unknown') }.
---

You can test this out by trying the following links:

As soon as the interview loads, the parameters will no longer appear in the browser’s location bar. Nevertheless, the parameters remain available in the url_args dictionary for the life of the interview.

Moreover, you can set new url_args at any time during the course of the interview. For example:

---
mandatory: True
question: You came from the ${ url_args.get('from', 'unknown') }.
subquestion: |
% if url_args.get('fruit', 'apple') == 'apple':
I think your favorite fruit is an apple, but [click here](?fruit=orange)
if you disagree.
% else:
I see that your favorite fruit is not an apple.
% endif
---

You can test this out by trying the following link: https://demo.docassemble.org?i=docassemble.demo:data/questions/testurlarg2.yml&from=wild blue yonder.

The following parameter names are not available for use as URL parameters because they are used for other purposes by docassemble:

  • action
  • cache
  • filename
  • format
  • from_list
  • i
  • index
  • question
  • reset
  • session

role_needed

If you use the multi-user interview feature and the user reaches a point in the interview where input is needed from a different user before proceeding, docassemble will look for a question that offers to sets role_event, and ask that question. docassemble will set the variable role_needed to a list of roles capable of answering the next question in the interview.

Variables that interviews can set

role

If you use the multi-user interview feature, your interview will need to have a default role initial block containing code that sets the variable role to the user’s role.

speak_text

If this special variable is set to True, docassemble will present the user with an HTML5 audio control at the top of the page. When the user clicks it, docassemble will access the VoiceRSS web service to convert the text of the question to an audio file and then play that audio back for the user. This requires enabling the voicerss setting in the configuration.

Since the VoiceRSS service costs money above the free usage tier, docassemble does not send the request to VoiceRSS until the user presses “Play” on the audio control. It also caches the results and reuses them whenever possible.

track_location

If set to True, the web app will attempt to obtain the user’s position, based on GPS or any other geolocation feature enabled in the browser. The location_known(), location_returned(), and user_lat_lon() functions can be used to retrieve the information.

The most common way to use this feature is as follows:

---
include:
- basic-questions.yml
---
initial: True
code: |
track_location = user.location.status()
---

This will cause track_location to be true initially, but once an attempt has been made to gather the location, it will be set to false. The user’s location can subsequently be obtained by accessing the user.location object.

multi_user

If you want to use the multi-user interview feature, you need to set multi_user to True. This is usually done in a “mandatory” or “initial” code block.

When multi_user is set to True, docassemble will not encrypt the interview answers on the server. This is necessary so that different people can access the same interview. When interview answers are encrypted, only the user who started the interview can access the interview answers.

Setting multi_user to True will reduce security somewhat, but it is necessary for allowing the multi-user interview feature.

Interviews can add entries to the menu within the web app.

When menu_items is set to a Python list, docassemble will add entries to the menu based on the items in the list.

Each item in the list is expected to be a Python dictionary with keys label and url. Typically, these entries are generated using the action_menu_item() function, which creates a menu item that runs an “action.” (See the url_action() and process_action() sections of the functions page for more information about what “actions” are in docassemble, and for documentation for the action_menu_item() function.)

---
mandatory: True
code: |
menu_items = [ action_menu_item('Review Answers', 'review_answers') ]
---

Alternatively, you can set items manually:

---
mandatory: True
code: |
menu_items = [ {'url': 'http://google.com', 'label': 'Go to Google!'} ]
---

Since menu items are controlled with code blocks, you can turn them on and off during the course of the interview as necessary.

allow_cron

This variable should be set to True if you want to allow the server to run scheduled tasks from your interview.

Variables that stand in for events

docassemble interviews ask questions or run code when required by interview logic and also when caused to do so by events and actions. These events and actions are identified using variables, which may not ever be defined by an interview.

There are some built-in variable names with special meaning: