Logo Docs
Logo Docs

Customizing the form

As a template grows, it becomes important to customize the form used to give variables their value. This makes the template easier to use.

This tutorial will show you how to:

  • Have a different label for a variable. Ex: “Client name” instead of “client_name”
  • Choose the order in which the fields are displayed
  • Provide help text to the user
  • Offer choices to the user (by displaying a dropdown)

1. Start a new Microsoft Word document

The sandbox cannot show the full form, so we have to use Word documents for this tutorial. We’ll talk about the sandbox can still be helpful at the end.

For now, create a new Word document.

2. Use the template in DocuMold

Open the document right away in DocuMold.

  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. Login on https://documold.com
  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, no variable is displayed yet.

Important: Keep this page open, we’ll be able to press “Refresh current template” to see changes to the form quickly.

3. Add some variables

Add these lines to your template:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

4. View the new form

Save the template, bring back the DocuMold page and press “Refresh current template”. You should see the 3 text boxes with names like your variables.

5. Reordering

The variables in the form are in alphabetical order. This is the default behaviour when no information was provided about them.

Currently, client_name is not in first place in the form, but it feels more natural for it to be. Let’s do that.

At the end of the document, add the following lines:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

<# @TEXT_QUESTION(client_name) #>
<# @TEXT_QUESTION(client_country) #>
<# @TEXT_QUESTION(client_date_of_birth) #>

These use the @TEXT_QUESTION action. Instead of writing something in the document, @TEXT_QUESTION tells DocuMold how to display the form for that variable. Actions were introduced in the Conditional content tutorial.

When you generate a document, these commands will be removed.

Save your template, go in DocuMold and press the “Refresh current template” button, you should now see the 3 variable names with text box in the same order as the @TEXT_QUESTION actions are in the document.

Note: variables without an associated @...QUESTION action are placed alphabetically after all of those with a @...QUESTION action.

6. Cleaner labels

Go back to the template and add , label: "Client's date of birth" before the closing parenthesis of client_date_of_birth’s @TEXT_QUESTION action.

The document should now look like this:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

<# @TEXT_QUESTION(client_name) #>
<# @TEXT_QUESTION(client_country) #>
<# @TEXT_QUESTION(client_date_of_birth, label: "Client's date of birth") #>

Save your template, go in DocuMold and press the “Refresh current template” button. The form should now show Client's date of birth instead of client_date_of_birth.

@TEXT_QUESTION has lots of optional parameters for lots of different things. To allow giving a value only to the parameters of interest, the name of the parameter receiving the value must be specified with a colon (:), such as: label: "Client's date of birth".

Add a label: to the remaining @TEXT_QUESTION actions. You should end up with something like this:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

<# @TEXT_QUESTION(client_name, label: "Client's full name") #>
<# @TEXT_QUESTION(client_country, label: "Client's country") #>
<# @TEXT_QUESTION(client_date_of_birth, label: "Client's date of birth") #>

Save your template, go in DocuMold and press the “Refresh current template” button to make sure everything is as expected and there are no errors.

7. Example value

When working on templates, you will fill the form many times as you try the template and visualize the result to validate its behaviour.

To avoid always having to write a value for each field, you can provide an example of value which will be prefilled into the form, but only when using “Prepare a template”. Let’s add one for client_name.

Add , example_value: "Anna Logwatch" before the closing parenthesis of client_name’s @TEXT_QUESTION action.

The document should now look like this:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

<# @TEXT_QUESTION(client_name, label: "Client's full name", example_value: "Anna Logwatch") #>
<# @TEXT_QUESTION(client_country, label: "Client's country") #>
<# @TEXT_QUESTION(client_date_of_birth, label: "Client's date of birth") #>

To see it in action:

  1. Save the template
  2. Go back to DocuMold
  3. Click on “Prepare a template” in the menu on the left to refresh the page
  4. Click on “Pick a template” and find the template again

The form should appear, but have the “Anna Logwatch” already filled as “Client’s full name”. You are free to change it when you need to, but this way you don’t need to always fill it for your tests.

This will not happen through “Use a template”. If you want it to happen there too, you can use the initial_value: parameter. This can be useful when you expect a field to give the same answer more most of the time.

8. Help text

Some fields of a template may be complex. The help_text: parameter allows you to provide as much information as needed to users that need it.

Add it with a bit of text to the client_country variable’s @TEXT_QUESTION. It should look like this:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

<# @TEXT_QUESTION(client_name, label: "Client's full name") #>
<# @TEXT_QUESTION(client_country, label: "Client's country", help_text: "This is the country where the client is doing business from.") #>
<# @TEXT_QUESTION(client_date_of_birth, label: "Client's date of birth") #>

Save the template and click “Refresh current template” in DocuMold. You should see a “” icon appears beside the Client's country label. Clicking on it displays the help text above the field. Clicking the “” again or the help text will hide the help text.

9. Choices

If you only work with a few countries, providing a list of choices to pick from would be helpful, saving time and reducing mistakes.

Replace the @TEXT_QUESTION of client_country with @PICK_ONE_QUESTION and add this received value: choices: ["Belgium", "Canada", "France", "United States"]

The template should now look like this:

For <# client_name #>
Country: <# client_country #>
Born on <# client_date_of_birth #>

<# @TEXT_QUESTION(client_name, label: "Client's full name") #>
<# @PICK_ONE_QUESTION(client_country, label: "Client's country", help_text: "This is the country where the client is doing business from.", choices: ["Belgium", "Canada", "France", "United States"]) #>
<# @TEXT_QUESTION(client_date_of_birth, label: "Client's date of birth") #>

Save the template and click “Refresh current template” in DocuMold. The country’s input box should now be a dropdown you can click on to choose the country.

Note: The [ and ] mark the beginning and end of a list, similar to how we use " to mark text. Just like with the values a function receive, we use a comma to separate the elements of the list. So ["Belgium", "Canada", "France", "United States"] is a list of 4 text values.

The choices are displayed in the order you put them in.

10. Try it!

Now fill the form and generate an example to see the result.

11. QUESTION actions

Here are the currently available QUESTION actions :

  • BIG_TEXT_QUESTION: Can write any text even with line changes
  • DATE_QUESTION: Show a date picker
  • NUMBER_QUESTION: Can only write a number
  • PICK_MANY_QUESTION: Show choices and lets you pick multiple ones
  • PICK_ONE_QUESTION: Show choices and lets you pick only one
  • TEXT_QUESTION: Can write any text without line changes
  • YES_NO_QUESTION: Can only choose between “Yes” or “No”, which set the variable to TRUE or FALSE

Many parameters are available to customize the questions. You can find their documentation in the menu bar on the left of this page, under “All actions” then “Questions”.

12. In the sandbox

The sandbox cannot show you a full form with every questions at once. However, it can display the form for one question at a time.

Open the sandbox:

  1. Login on https://documold.com
  2. Click on “Sandbox” in the menu on the left
  3. Click on “Reset” at the top so that you start with the content that this tutorial expects

In the box on the left, add a @PICK_ONE_QUESTION and use its variable. Here is an example:

<# @PICK_ONE_QUESTION(client_country, label: "Client's country",
  help_text: "This is the country where the client is doing business from.",
  choices: ["Belgium", "Canada", "France", "United States"]) #>

Country: <# client_country #>

In the right box, you should see the first choice of the @PICK_ONE_QUESTION. The sandbox picks a value when you first add a question.

At the bottom left, the round box for your variable should also display the first choice. You can click on the choice or the pen icon beside it to view the form for that question and provide a new value.

This is very helpful not only to learn about how each @...QUESTION behaves, but also so that you can have different kinds of values in the sandbox. For example, if you want to try functions that receive dates (such as DAY), you can use the @DATE_QUESTION action which will set the variable to a date (instead of text that contains a date).

Conclusion

Customizing the form is important. Spending some time on it can save a lot of time later when users are using the form. Fewer mistakes, less confusion, less time explaining.