Before you get started
We will discuss the first few sections of this assignment in class. To refresh your memory and reflect on your own, I recommend skimming the Overview of Docassemble, Description of YAML, and the section describing Mako. If you run into any trouble, please ask for help on the class Slack channel.
Introduction to the Docassemble Playground
We will use the Docassemble playground for all exercises. Log in to the Docassemble server at https://interviews.lemmalegal.com. When you are loggged in, click on your name, and then select the Playground option to reach the Playground.
The Playground is made up of several elements.
- The main text editing window
- A list of example blocks that can be directly inserted into the text editing window
- A list of variables and functions available in the current interview file
- The save and run button, used to run the interview and view results.
- The share button which also gives you a link that can be shared
In computer programming, the traditional first exercise in a new programming language is to display the text "Hello, World."
Let's erase the text in the playground and replace it with the text below:
Docassemble interviews contain a series of
specifiers followed by text, such as the
question specifier. The
question specifier tells docassemble that what follows will be the title of a screen displayed to the user.
When you save and then run this sample, you will notice an error.
The mandatory specifier
Take a minute to read the error message. In Docassemble, your interview can contain many questions and branches that are never shown to the user. This error is telling us that none of the questions are marked as
mandatory, or required, so Docassemble doesn't know what to display. Let's fix that.
mandatory specifier marks this block as required. Now when we run the interview, we'll see the text "Hello, World" on the screen without any errors.
Note: you should normally have only ONE
mandatoryblock in a single interview. We'll discuss good practices around this later.
The purpose of Docassemble is to gather information from the users. Let's ask the user's name so we can greet them personally.
We introduced several new ideas in this interview. Notice that each screen in the interview is separated by three dashes, like this:
We introduced a new
fields. Instead of single line of text, this
specifier takes a list. Each field in the list is indented and begins with a single dash, like this:
-. Each item has a label, followed by a colon, followed by the name of the variable that the user's input will be assigned to.
To learn more about the format of a Docassemble interview, read the section on the YAML format.
We also introduced
variables. A variable is simply a placeholder.
user_name is a variable that is a placeholder for the user's name. Inside the Docassemble interview, we can display a variable by surrounding it with
Mako tags, like this:
Note: We don't need to tell Docassemble to mark the second question as mandatory. Because the mandatory question requires the variable
user_name, Docassemble automatically asks the first question that provides a definition.
Docassemble uses Mako tags to control displaying variables and basic logic inside the interview file. Let's try out using an
if statement: the most basic building block of logic.
In this iteration, we introduce the
line continuation marker,
|. This allows us to have more than one line of text in a row that is part of the same field. Text that follows the
line continuation marker is always indented. Usually, we use two spaces as indentation.
We also introduce the
subquestion specifier. A
subquestion is displayed in a smaller font than the main
if statement is written on its own line. Notice that the line must end in a
:. Also notice that when we check the value of a variable, we need to use a double
=. We also need to tell Docassemble when the optional text ends and the main text starts back up with the
Note: YAML is picky about indentation. If you run into an error, check to make sure each line is indented the same way as the example above.
- Modify the Hello, World exercise so that it ask for the user's first and last names separately.
Turning in your work
Please use the course Blackboard to turn in your work this week. I would like you to provide me a link so that I can run your interview, and a copy of the interview code. To obtain the link, use the green "Share" button. Right-click and Copy link. Use the "Download" button to download a copy of your YAML. Turn both of these in by 5:30 PM on Wednesday.