Some notes I took on docassemble, an interview-based document assembly technology platform I am learning some stuff about. I watched this video of a training session at a recent conference and looked at some other resources as well. The video I watched is the beginner tutorial but they have an advanced one I plan on trying soon.
Question Order
docassemble only asks questions it has to based on the logic of the interview and based on which questions are designated as mandatory. So you could have a question in your interview that never gets asked cuz nothing calls it.
docassemble’s default behavior is to use the order of questions in a mandatory question block to determine the order in which to ask questions as demonstrated here. I didn’t predict the ordering of the questions described on that page when I ran the code, because I was expecting the convention to be that the YAML file would be read from top to bottom. I therefore expected the air speed question to be the first one asked, and not the name question. Mandatory blocks are indeed read from top to bottom, so if you have all the question blocks set to mandatory, like in the example discussed here, the ordering would indeed work like how I was initially expecting.
Correction: Actually though, sometimes a mandatory block won’t actually run, as demonstrated here at around 1h30m. See also this timestamp where a technique using the placement of things inside a single mandatory code block and setting a variable for the purposes of flow control is demonstrated.
The default ordering behavior can lead to question ordering that is unintended.
Something I discovered in the docassemble documentation regarding how docassemble handles YAML:
Note that the order of questions or code blocks in the YAML matters where the variable name is the same; the blocks that appear later in the YAML will be tried first.
So consider this toy program:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
|
---
mandatory: True
code: |
user_name
secret_message
# display message
# add esquire to the name
add_esq_to_name
ending_screen
---
question: |
What is your name?
fields:
- Name: user_name
---
code: |
# This is a comment. notice that we assign a value with =, and we test a value with ==
if user_name.lower() == "scotty":
secret_message = "Beam Me Up, Scotty"
else:
secret_message = "No message to report."
---
event: ending_screen
question: |
Hello, ${user_name}
subquestion: |
${secret_message}
---
code: |
user_name = user_name + ", Esq."
add_esq_to_name = True
|
When trying to evaluate for user_name in the mandatory block, docassemble actually tries to run the code block at the end first, and then I think it sees that user_name is undefined, so then it backs up to the block with the  What is your name? question and tries that.
Use of mandatory blocks
Using a single mandatory block can help keep the logic of an interview easier to trace. See this explanation.
If you use a template file (such as a Word document or PDF), and the template is referenced in a mandatory block, docassemble will try to answer questions for the variables inside the template file without you needing to specify the questions in the YAML file. See here at 2h6m.
Python Object Conventions
This thing about ${user} being the equivalent of ${user.__str__()} and giving you a string representation of the object seems really critical for using docassemble for PDFs based on my past experience with Documate.
Syntax Differences Between YAML Files and Word Doc / PDF Templates
In the docassemble YAML files, when you’re doing string interpolation with a variable the syntax is ${variable} (which is apparently Mako syntax), but in a word doc it’s {{variable}} (this is Jina syntax).