title is defined, it will be displayed in the navigation bar in
the web app. If a
short title is provided, it will be displayed
in place of the
title when the size of the screen is small.
logo is defined, it will be displayed in the navigation bar in
the web app in place of the
short title. The content of
logo should be raw HTML. If you include an image, you should
size it to be about 20 pixels in height.
tab title is provided, it will be displayed as the title
of the browser tab. Otherwise, the
title will be used.
subtitle is provided, it will be displayed as the subtitle of
the interview in the “Interviews” list available to a logged-in
These titles can be overridden using the
metadata block and the
set_title() function can be used to
modify other aspects of the navigation bar.
exit link is provided, the behavior of
the “Exit” link can be modified. (The “Exit” menu option is displayed
show login configuration directive is set to
show login metadata specifier in an interview is set to
False.) The value can be either
leave. If it is
then when the user clicks the link, they will be logged out (if they
are logged in) and their interview answers will be deleted from the
server. If it is
leave, the user will be logged out (if they are
logged in), but the interview answers will not be deleted from the
server. It can be important to keep the interview answers on the
server if background tasks are still running.
exit label is provided, the given text
will be used in place of the word “Exit” on the “Exit” menu option.
This text is passed through the
word() function, so that it can be
translated into different languages.
If you set
unlisted: True for an interview that has an entry in the
dispatch list in your configuration, the interview will be
exempted from display in the list of interviews available at
For more information about this, see the documentation for the
dispatch configuration directive.
metadata block also accepts the specifiers
post. You can use these to provide raw HTML that will be inserted
into the page before the
question heading, before the buttons, and
after the buttons, respectively. You can also set server-wide
defaults for these values using the
main page pre,
main page post directives in the Configuration.
You can also customize these values with the
metadata block also accepts the specifier
error help. This is Markdown-formatted text that will be included
on any error screen that appears to the user during the interview.
You can also provide this text on a server-wide basis using the
error help directive in the Configuration.
metadata block also accepts the specifier
show login, which can be
false. This controls whether
the user sees a “Sign in or sign up to save answers” link in the upper
right-hand corner during the interview. If
show login is not
specified in the
metadata, the Configuration directive
login determines whether this link is available.
objects block creates objects that may be referenced in your
interview. See objects for more information about objects in
If your interview references the variable
will find the above
objects block and process it. It will define
spouse as an instance of the object class
Individual and define
user.case as an instance of the object class
The use of objects in docassemble interviews is highly encouraged.
However, the objects you use as variables need to inherit from the
DAObject. Otherwise, docassemble might not be able to
find the appopriate
code blocks or questions necessary to define
them. This is because of the way docassemble keeps track of the
names of variables.
A code block like this would effectively do the same thing as the
objects block above:
This code is more complicated than normal Python code for object
initialization because the full name of the variable needs to be
supplied to the function that creates and initializes the object. The
DAObject keeps track of variable names.
In some situations, running
spouse = Individual() will correctly
detect the variable name
spouse, but in other situations, the name
cannot be detected. Running
spouse = Individual('spouse') will
always set the name correctly.
Whenever possible, you should use
objects blocks rather than code to
initialize your objects because
objects blocks are clean and
You can also use
objects blocks to initialize attributes of the
objects you create. For information on how to do this, see the
documentation for the
objects from file block imports objects or other data elements
that you define in a separate YAML data file located in the
sources folder of the current package. If the interview file
objects from file block is
data/questions/manage_claims.yml, docassemble will expect the
data file to be located at
For more information about how this works, and about how to format the
data file, see the documentation for the
objects_from_file() function. The example above is equivalent to
claims = objects_from_file('claim_list.yml', name='claims').
include block incorporates the questions in another YAML
file, almost as if the contents of the other YAML file appeared in
place of the
include block. When the
included file is parsed,
files referenced within it will be assumed to be located in the
included file’s package.
When a filename is provided without a package name, docassemble
will look first in the
data/questions directory of the current
package (i.e., the package within which the YAML file being read is
located), and then in the
data/questions directory of
You can include question files from other packages by explicitly
referring to their package names. E.g.,
docassemble.helloworld:questions.yml refers to the file
questions.yml in the
directory of that package.
image sets block defines the names of icons that you can use to
decorate your questions.
The file names refer to files located in the
of the package in which the YAML file is located.
Since most free icons available on the internet require attribution,
image sets block allows you to specify what attribution text
to use for particular icons. The web app shows the appropriate
attribution text at the bottom of any page that uses one of the
icons. The example above is for a collection of icons obtained from
the web site Freepik, which offers free icons under an
image sets block must be in the form of a YAML dictionary, where
the names are the names of collections of icons. The collection
itself is also a dictionary containing terms
images and (optionally)
images collection is a dictionary that
assigns names to icon files, so that you can refer to icons by a name
of your choosing rather than by the name of the image file.
For information on how to use the icons you have defined in an
sets block, see
decoration in the question modifiers section,
in the setting variables section, and “Inserting inline icons” in
the markup section.
images block is just like an
image sets block, except that it
does not set any attribution information. It is simpler because you
do not need to give a name to a “set” of images.
images block is essentially equivalent to writing:
imports loads a Python module name into the namespace in which your
code and question templates are evaluated. The example above is
equivalent to running the following Python code:
modules loads Python modules into the namespace in
which your code and question templates are evaluated, except that it
imports all of the names that the module exports. The example above
is equivalent to running the following Python code:
For example, in this interview we create a Python list and then re-use it in two questions to offer a multiple-choice list.
In Python, the variable
fruits is this:
You can also use the
data block to create more complex data
structures. You can also use Mako in the data structure.
reset block will cause variables to be undefined every time a
This can be helpful in a situation where a variable is set by a
code block and the value of the variable ought to be considered
afresh based on the user’s latest input.
Effectively, this causes variables to act like functions.
Another way to use this feature is to set the
code block. This will have the same effect as
it will apply automatically to all of the variables that are capable
of being assigned by the
reset block and the
reconsider modifier are computationally
inefficient because they cause extra code to be run every time a new
screen loads. For a more computationally efficient alternative, see
As explained in how docassemble finds questions for variables,
if there is more than one
code block that offers
to define a particular variable, blocks that are later in the YAML
file will be tried first.
If you would like to specify the order of precedence of blocks in a
more explicit way, so that you can order the blocks in the YAML file
in whatever way you want, you can tag two or more blocks with
and insert an
order block indicating the order of precedence of the
For example, suppose you have an interview with two blocks that could
define the variable
favorite_fruit. Normally, docassemble will
try the the second block first because it appears later in the YAML
file; the second block will “override” the first.
However, if you actually want the first block to be tried first, you can manually specify the order of blocks:
Another way to override the order in which blocks will be tried is by
supersedes question modifiers.
Sometimes you will use vocabulary that the user may or may not know. Instead of interrupting the flow of your questions to define every term, you can define certain vocabulary words, and docassemble will turn them into hyperlinks wherever they appear in curly brackets. When the user clicks on the hyperlink, a popup appears with the word’s definition.
If you want the terms to be highlighted every time they are used,
whether in curly brackets or not, use
You can also use
auto terms as question modifiers, in which
case the terms will apply only to the question, not to the interview
as a whole.
Here is a complete example.
Subsections are supported, but only one level of nesting is allowed.
If your interview uses multiple languages, you can specify more than
sections block and modify each one with a
If no language is specified, the fallback language
* is used.
In the example above, the
section modifier referred to sections
using the same text that is displayed to the user. However, in some
circumstances, you might want to use a shorthand to refer to a
section, and update the actual section names displayed to the user
without having to make changes in numerous places in your interview.
You can do this by using key/value pairs in your
sections block, and
using the special key
subsections to indicate subsections:
The keywords for section names need to be valid Python names. When choosing keywords, make sure not to use the names of variables that already exist in your interview.
This is because the keywords can be used to make the left-hand navigation bar clickable. If a keyword for a section is a variable that exists in the interview, clicking on the section will cause an action to be launched that seeks a definition of that variable.
Note that if you use
review blocks in an interview with sections,
every question should have a
section defined. Otherwise, when your
users jump around the interview, their section may not be appropriate
for the question they are currently answering. Alternatively, you
code blocks and the
nav.set_section() function to
make sure that the section is set appropriately.
By default, users are only able to click on sections that they have
visited. If you want users to be able to click on any section at any
interview help block adds text to the “Help” page of every
question in the interview. If the question has
help text of its
interview help will appear after the question-specific
You can also add audio to your interview help:
You can also add video to help text using the
See the question modifiers section for an explanation of how audio and video file references work.
You can also provide a
label as part of the
interview help. This
label will be used instead of the word “Help” in the navigation bar as
a label for the “Help” tab.
Note that if you provide question-specific
help, and you include a
label as part of that help, that label will override the default
label provided in the
interview help (except if
button is enabled).
Due to the way docassemble parses interviews, the
needs to be defined before it is used.
\ marks at the end of the lines in the
Without these marks, there would be an extra newline inserted. You
may or may not want this extra newline.
If your interview uses the roles feature for multi-user interviews,
default role specifier will define what role or roles will be
required for any question that does not contain an explicit
When you use the roles feature, you need to have some way of telling your interview logic what the role of the interviewee is.
If you include
code within the same block as your
specifier, that code will be executed every time the interview logic
is processed, as if it was marked as
initial. For this reason, any
default role specifier that contains code should be placed earlier
in the interview file than and
mandatory questions or
In the example above, the interview has two roles: “client” and
“advocate”. The special variables
role are set in the
code block, which is executed every time the interview logic is
In addition, the
set_info() function from
docassemble.base.util is called. This lets the linguistic
docassemble.base.util know who the user is, so that
questions can ask “What is your date of birth?” or “What is John
Smith’s date of birth” depending on whether the current user is John
Smith or not.
This sets the language to use for all of the remaining questions in
the file for which the
language modifier is not specified. The
purpose of this is to save typing; otherwise you would have to set the
language modifier for each question. Note that this does not extend to
If your interview only uses one language, it is not necessary to (and
probably not a good idea to) set a
If you would like your interview to share training data with another
interview, you can use the
machine learning storage specifier to
point to the training data of another interview.
For example, suppose you have developed an interview called
child_custody.yml that uses machine learning, and you have built
rich training sets for variables within this interview. Then you
decide to develop another interview, in the same package, called
child_support.yml, which uses many of the same variables. It would
be a lot of work to maintain two identical training sets in two
In this scenario, you can add the following block to the
ml-child_custody.json is the name of a file in the
directory of the package. This file contains the training data for
child-custody.yml interview. The naming convention for these
data files is to start with the name of the interview YAML file, add
ml- to the beginning, and replace
Now, both the
ml-child_custody.json as “storage” area for training data.
In the Training interface, you will find this data set under the
If you had run the
child-support.yml interview before adding
machine learning storage, you may still see a data set called
child-support in the Training interface. If you are using the
Playground, you may see a file called
ml-child-support.json in the
Sources folder. To get rid of this, go into the Playground and
ml-child-support.json file from the Sources folder.
Then go into the Training interface and delete any “items” that
exist within the
If you want, you can set
machine learning storage to a name that
does not correspond with an actual interview. For example, you could
machine learning storage: ml-family-law.json in both the
child-support.yml interviews. Even though
there is no interview called
family-law.yml, this will still work.
If you are using the Playground, a file called
will automatically be created in the
You can also share “storage” areas across packages. Suppose you are
working within a package called
you want to take advantage of training sets in a package called
docassemble.generalfamilylaw. You can write:
features block sets some optional features of the interview.
debug directive in the Configuration is
True, then by
default, the navigation bar will contain a “Source” link that shows
information about how the interview arrived at the question being
shown. If the
debug directive is
False, then this will not be
This can be overridden in the
features by setting
False depending on the behavior you want.
The following example demonstrates turning the
debug feature off.
On the server that hosts the demonstration interviews, the
True, so the “Source” link is normally shown. Setting
debug: False makes the “Source” link disappear.
If you do not want your interview questions to be centered on the
If you want the progress bar to display the percentage, include
progress bar percentage: True:
navigation feature controls whether a navigation bar is
shown during the interview. You can use the
block or the
nav.set_sections() function to define the sections of
your interview. The
section modifier or the
function can be used to change the current section.
Note that the section list is not shown on small devices, such as
smartphones. To show a smartphone user a list of sections, you can
If you want the navigation bar to be horizontal across the top of the
By default, there is a “Back” button located in the upper-left corner
of the page. (However, the “Back” button is not present when the user
is on the first page of an interview, or the
function has been used, or the
prevent going back modifier is in
Whether this back button is present can be controlled using the
navigation back button feature. This will hide the “Back” button:
You can also place a “Back” button inside the body of a question, next
to the other buttons on the screen, by setting the
question back button
True (the default is
You can also place a “Back” button inside the body of a question on
some questions but not others, using the
back button modifier.
interview help is available, or the
help modifier is
present on a question, the “Help” tab will be present in the
navigation bar. When the
help modifier is present, the “Help” tab
is highlighted yellow and marked with a yellow star. When the user
presses the help tab, the help screen will be shown.
If you set the
question help button to
True, users will be able to
access the help screen by pressing a “Help” button located within the
body of the question, to the right of the other buttons on the page.
question help button is
True, the “Help” tab will not be
Here is an interview in which the
question help button is not
enabled (which is the default).
Here is the same interview, with the
question help button feature
Note that when
question help button is enabled, the label for the
help tab in the navigation bar always defaults to “Help” or to the
label of the
interview help, and it is not highlighted yellow
when question-specific help is available.
By default, the menu in the corner provides logged-in users with the
ability to edit their “Profile” and the ability to go to “My
Interviews,” which is a list of interview sessions they have started.
If you want to disable these links, you can use the
my-functions.js, and a CSS file,
my-styles.css, into the
user’s browser. These files are located in the
of the same package in which the interview is located.
The contents of
The contents of
the interview is loaded, attach a jQuery event handler to
for the event
daPageLoad, which is a docassemble-specific event
that is triggered after each screen loads. (Since docassemble
uses Ajax to load each new screen, if you attach code using
ready() method, the code will run when the browser
first loads, but not every time the user sees a new screen.) The
example above demonstrates this; every time the page loads, the code
will replace the contents of any element with the class
or on the internet at a URL:
Also, if you want to bring in multiple files, specify them with a YAML list:
Here is an example interview that draws a pie chart using Google Charts.
bootstrap theme feature, you can change the look and feel
of your interview’s web interface by instructing your interview to use
a non-standard CSS file in place of the standard CSS file used by
The file can be referenced in a number of ways:
lumen.min.css: the file
lumen.min.cssin the “static” folder of the current package.
docassemble.demo:lumen.min.css: the file
lumen.min.cssin the “static” folder (
data/static/) of the
docassemble.demo:data/static/lumen.min.css: the same.
https://bootswatch.com/lumen/bootstrap.min.css: a file on the internet.
By default, docassemble uses Bootstrap’s “dark” (formerly known
as “inverted”) style of navigation bar so that the navigation bar
stands out from the white background. If you do not want to use the
inverted navbar, set the
inverse navbar feature to
To make this change at a global level, see the
inverse navbar configuration directive.
As explained more fully in the tables section, if you include a
table in an
attachment and the table is too wide, or not wide
enough, you can change the default character width of tables from 65
to some other value using the
table width specifier within the
By default, docassemble caches assembled documents for performance
reasons. To disable the document caching feature for a given
cache documents to
If your users upload digital photos into your interviews, the uploads
may take a long time. Images can be reduced in size before they are
uploaded. To require by default for all uploads in your interview,
maximum image size in the
features block of your interview.
In this example, images will be reduced in size so that they are no taller than 100 pixels and no wider than 100 pixels.
Note that the image file type of the uploaded file may be changed to PNG during the conversion process. Different browsers behave differently.
This is just a default value; you can override it by setting the
maximum image size in a field definition.
If you have an interview-wide default, but you want to override it for
a particular field to allow full-resolution camera uploads, you can
maximum image size field modifier to
If you want to use a site-side default value, set the
maximum image size in the configuration.
It is possible to embed a docassemble interview in a web page using an iframe. However, the user experience on mobile is degraded when an interview is embedded.
If you want the interview to switch to “full screen” after the user
moves to the next screen in the embedded interview, you can do so.
features block, include
go full screen: True.
For more information about implementing an embedded interview like this, see the HTML source of the web page used in this example.
Note that in this example, the user is provided with an exit button
at the end of the interview that directs the user back to the page
that originally embedded the interview. This is accomplished by
url of the exit button to the result of the
If you only want the interview to go full screen if the user is using
a mobile device, use
go full screen: mobile.
Note that this example provides a different ending screen depending
on whether the user is on a desktop or a mobile device. If a desktop
user is viewing the interview in an iframe on a web site, the
interview should not provide an exit button that takes the user to a
web site, because then the user will see a web site embedded in a web
site. The interview in this example uses the
device() function to
detect whether the user is using a mobile device. Note that the
interview logic looks both at
device().is_mobile as well as
device().is_tablet. This corresponds with the functionality of
full screen: mobile, which will make the interview go full screen if
the user has either a mobile phone or a tablet.
You can also set these limits on a per-interview basis using the
recursion limit features.