Using data tables

Now that you can customize the form, let’s make push this further.

Let’s say you need to give contact information about a colleague in your templates. Ideally, you would pick the colleague in the form then somehow access the email, phone number, etc. in the template.

If you have multiple templates where this is needed, managing that information in all those templates one by one would be repetitive and error-prone. You might forget a template or you could make a typo that makes DocuMold generate an error when processing your template. Are you going to retest all your templates each time?

DocuMold’s solution for this is the “Data tables” section, where you can store data in tables, then use it from templates.

This tutorial will guide you through creating and using a data table.

1. Create the data table

1. Login on https://documold.com
2. Click on “Data table” in the menu on the left
3. Click on “New”
4. Give it a name of “Employees”
5. The identifier, like variables, must start with a lowercase letter. Use “employees”
6. Click on “Add a column” three times to reach 4 columns totals
7. Click on the grey header of the first column. In the popup, put “First name” and “first_name” as title and identifier. Then click “Done”
8. For the second column, put “Last name” and “last_name” as title and identifier
9. For the third column, put “Email” and “email”
10. For the fourth column, put “Phone number” and “phone_number”
11. Press “Save new data table” at the bottom

Add these few rows:

Press “Save changes” at the bottom.

2. Start a new Microsoft Word document

The sandbox doesn’t support customizing the form, so we have to use Word documents for this tutorial. Create a new Word document.

Open the document right away in DocuMold. We’ll be able to press “Refresh current template” to see changes to the form quickly.

1. Save your template on your computer, include “template” in the name to help distinguish it. Make sure it’s in the Word 2007 or higher version (365 is also okay)
2. Go back to your DocuMold window
3. Click on “Prepare a template” in the menu on the left
4. Click on “Pick a template” and find the template

Since the template is empty, nothing is displayed yet.

3. Show the list of choices

Add this to your template:

<# @PICK_ONE_QUESTION(contact_person, label: "Contact person",
  help_text: "The employee that can be contacted for any questions",
  choices: DT_CHOICES("employees")) #>

Note: You can split a command on multiple lines. This can make commands easier to read sometimes. However, you cannot make such a split in the middle of the name of a variable, function or action.

Save the template, bring back the DocuMold page and press “Refresh current template”.

You should see a list of choices containing the first names that you entered in the table. That’s the DT_CHOICES function using data from your data table.

4. Customizing the displayed choices

By default, DT_CHOICES displays the first column of the table in the dropdown. You can give it a second “value” to have total control over what is displayed.

Replace the DT_CHOICES with this one:

DT_CHOICES("employees", CONCAT(.first_name, " ", .last_name))

Resulting in:

<# @PICK_ONE_QUESTION(contact_person, label: "Contact person",
  help_text: "The employee that can be contacted for any questions",
  choices: DT_CHOICES("employees", CONCAT(.first_name, " ", .last_name))) #>

Save the template, bring back the DocuMold page and press “Refresh current template”. You should notice that the choices now show both the first name and the last name.

This works because the second value of the DT_CHOICES function is special:

• It is executed once for each row of the data table
• The result for each row will be shown as a choice when filling the form to generate a document
• You can access column values using the column’s identifier with a dot (.) as prefix So in this case: .first_name, .last_name, .email and .phone_number.
• Since the code is executed before you filled the form, no normal variables are available
• Any function can be used as usual. In this case, the CONCAT function is used to concatenate the texts.

5. Using the choice

Because we used DT_CHOICES, the contact_person person variable will contain the entire row of the data table. You can’t write that variable directly to the document (<# contact_person #>), because you need to specify which column you want to use.

Add this to your document:

You can contact <# contact_person.first_name #> <# contact_person.last_name #> at
any time, either by email at <# contact_person.email #> or by phone at <# contact_person.phone_number #>.

The dot (.) picks a value from a row. The left side is the row, the right side is the identifier of the column in the row.

Save the template, bring back the DocuMold page and press “Refresh current template”. Pick someone from the dropdown and press generate example. If you picked Luke, the document should contain something like this:

You can contact Luke Groundrunner at any time, either by email at [email protected] or by phone
at 555-0901.

These values can be used with functions as usual, so <# UPPER(contact_person.last_name) #> would display GROUNDWALKER.

You can find more information on DT_CHOICES in its documentation.

6. Manually accessing a data table

You can also access a data table row directly with a function. Try it! Close your previous generated example, go back to the template and add this to your template:

Here's James number: <# DT_LOOKUP("employees", "first_name", "James").phone_number #>

Save the template, bring back the DocuMold page and press “Refresh current template”. Pick a contact person, then generate an example. The result should look like:

Here's James number: 555-0007

The DT_LOOKUP function receives the identifier of the data table to look into, the identifier of the column to use for the search and the value to find in that column. It returns the whole row that matched, so you can then use the dot . to get the value of your choice, just like with DT_CHOICES.

7. Editing the data table

What makes data tables great is that you can edit them easily and the changes will be available instantly to any template.

Close your generated example. In your browser:

1. Open a new tab
2. Go to https://documold.com
3. Login if you are not already
4. Click on “Data table” in the menu on the left
5. Click on the “Employees” entry

You should see the table with the current data.

Add this content in a fourth row:

Edit the last_name from “Voltage” to “Wattage”.

Press “Save changes” at the bottom.

Switch back to the tab in “Prepare a template”, press on “Refresh current template”. If you open the list of choices, you should see right away the new “The Stone” choice and Austin’s last name has changed.

8. What to avoid editing

If you change the identifier of the table or of the columns, then any template which used those identifiers will generate errors when using them until they are changed. So once an identifier set and used, it’s usually preferable not to change it; especially if colleagues already know and use the old identifiers in their templates.

You can change the order of the column freely, this doesn’t affect what templates do. You can add / remove rows.

9. Conclusion

Using data tables, you can easily share and update information between your templates.

The two ways of using data tables are:

• with the DT_CHOICES function in a @PICK_ONE_QUESTION or @PICK_MANY_QUESTION action
• with the DT_LOOKUP function anywhere.