Assignment 3

Before you get started

Read the brief section about Jinja.

Working with Docx Templates

Let's take a look at a simple interview that automates a Docx template. The interview has two parts: the YAML which contains the interview and its logic, and a regular Microsoft Word document.

---
mandatory: True
code: |
intro
user_name
download
---
question: |
This interview shows how to create a Docx template
---
question: |
What is your name?
fields:
- no label: user_name
---
event: download
question: |
Your document is ready
subquestion: |
${hello_world}
---
attachment:
docx filename: hello_world.docx
variable name: hello_world

Here is what the document looks like inside:

Hello, {{ user_name }}

In our document, we marked the variable with {{ user_name }}. The text {{user_name}} is replaced with the name the user gives us during the interview.

There are different ways to add an attachment to a question. Above, we're using the style that embeds a thumbail of the document right in the page. We also assigned a variable name to the attachment so we can re-use the same attachment in multiple places.

What is a Docx Template?

A docx template is an ordinary Microsoft Word file. You don't use any special Microsoft Word features to turn it into a template. You just type in the special docassemble codes in the right place in your file.

An introduction to Jinja syntax

You can use most of the same features in a Docx template that you can use inside an ordinary Docassemble question block. Docx templates use a similar, but slightly different syntax to what you use inside questions, called Jinja.

  • Variables are marked with double curly braces, like this: {{ variable_name }}
  • if statements come in two varieties:
    • in-line if statements, like this: {% if is_female %}she{% elif is_male %}he{% else %}they{%endif %}
    • Paragraph-level if statements, like this:
{%p if show_paragraph %}
You really like cheese!
{%p endif %}

You can also use {% for ... %} and other Python control structures.

Benefits of Docx templates as compared to PDFs

  • You can completely control the formatting
  • fields expand to take up as much or as little space as they need
  • You can build a table one row at a time, rather than having to include code that represents each possible cell in the table.
  • You can place all formatting code and conditional text in the template, decluttering your interview file.
  • Helper functions and methods can make things even simpler

Example

Docassemble uses objects, a useful way in programming to group a bunch of related fields.

As an example, a built-in object that we use again and again is the Individual object.

---
objects:
- tenant: Individual
---
mandatory: True
code: |
tenant.name.first
tenant.address.address
download
---
question: |
Your name
fields:
- First: tenant.name.first
- Last: tenant.name.last
---
question: |
Where do you live?
fields:
- Street address: tenant.address.address
- City: tenant.address.city
- State: tenant.address.state
choices: states_list()
- Zip: tenant.address.zip
---
event: download
question: |
Download your file
attachment:
docx filename: address_example.docx

Inside the Docx template, we could show the address and name like this:

Hello, my name is {{tenant}}.
Yours sincerely,
{{ tenant.address_block()}}

address_block() is a method of an Individual object that shows the person's full address block, including their name. In a PDF, we would have had to code as many as six different fields to show the same information.

Above we use the second kind of attachment block, one that is part of a question. This style adds a fair amount of text and buttons around the attachment automatically. It also adds an email box by default, so that someone can send themselves a copy of the finished document.

Using the built-in variables from the docassembly line project in your interview

Take a look at the list of variables in the Docassembly Line Documentation.

When you write a Docassemble interview that uses the MAVirtualCourt package, you don't need to write your own questions that use these variables or the attributes that come along with them.

include:
- docassemble.MAVirtualCourt:basic-questions.yml
---
mandatory: True
event: download
question: |
Download your file
attachment:
docx template file: vc_demo.docx

Is enough to fill-in the document below, without adding any additional questions in the YAML:

{{ users }} {{ courts }}
v.
{{user_role}}'s MOTION TO DISMISS
{{ other_parties }}
Comes now the {{ user_role }} and moves that the court dismiss this action because:
{{ users[0].signature}}
{{ users[0].address_block()}}
Signed {{ signature_date}}

Further exploration

  1. Add some more variables to the hello_world.docx template.
  2. Experiment with showing/hiding optional text based on a yesno question.

Further reading

  1. The attachment block
  2. Docx Templates
  3. Docassemble tutorial
  4. Jinja reference (this is similar but not the exact syntax used in Docasssemble)
  5. Docx-template Jinja reference