Document templates

A document template is a Microsoft Word file that shows how the documents Exact Forms Plus creates should look. You write the fixed text and layout in Word, and type a field name or field ID between tildes (~) wherever a value from Quickbase should go. When a user creates a document, Exact Forms Plus replaces each of these with the value from the record, and saves the result as a Word document or a PDF.

This page explains how to build a template and add it to Quickbase. For dates, images, functions, and everything else you can put in a template, see Template fields and functions. For tables of related records, see Insert embedded reports (subtable). For the terms used here (master record, related data, embedded report), see Exact Forms Plus terms and concepts.

The template file

The template must be a Word file whose name ends in .docx or .doc, in lowercase. Other files, including a name ending in .DOCX, are rejected with the message This version of Exact Forms Plus only supports .doc or .docx template files. To fix it, open the file in Word, save it as .docx or .doc, and upload it again.
You don't need macros or add-ins. Any version of Word that saves .docx or .doc files works, including Word for Mac.
Word documents created from the template have the same format as the template: a .docx template creates .docx files, a .doc template creates .doc files. To create a PDF instead, set docfmt=pdf in the button formula (see Output file).
You can put field values anywhere in the document, including Word headers and footers and inside Word tables.

Insert field values

Put a field name or field ID between tildes (~). When the document is created, Exact Forms Plus replaces it, tildes included, with the field's value from the master record.

For example, if a Customer Name field (field ID 5) holds John Smith, either of these lines:

Dear ~Customer Name~,
Dear ~5~,

creates Dear John Smith, in the document. If the name is stored in two fields, First Name (6) and Last Name (7), use Dear ~First Name~ ~Last Name~, or Dear ~6~ ~7~,.

Field names aren't case-sensitive. ~customer name~ works too. Field IDs keep working if someone renames the field, so they're the safer choice.
Every field the template uses must be in the template's clist. Exact Forms Plus reads only the fields listed in the clist field of the template record (or in the clist parameter of the button formula, if there is one). The EFP Configurator fills the clist for you; see Add a new document template.
If the field isn't in the clist, or doesn't exist, the text is left in the document exactly as typed, for example ~Customer Name~. No error is shown, so check a test document for leftover tildes.
A field with no value is replaced with nothing.

Example: a purchase order template

A purchase order template on a Purchase Orders table could contain the following. The fixed labels are typed in Word; everything between tildes comes from the record. This example uses field IDs, which keep working if a field is renamed. Field names work the same way, for example ~PO Date~ instead of ~6~.

PURCHASE ORDER
PO Date: ~6~                      PO #: ~7~

Vendor:                           Ship To:
~8~                               ~14~
~9~                               ~15~
~10~, ~11~ ~12~                   ~16~, ~17~ ~18~

Shipping Method     Delivery Date     Approved     Photo
~19~                ~20~              ~21~         ~i:75:30~

~strid=1~                         (the line items table)

                     Subtotal   ~22~
                     Sales Tax  ~23~
                     Total      ~13~
                     ~=FormatN(f[13],$)~   (the total in words)

The field IDs in this example belong to these fields on the Purchase Orders table:

Field ID	Field	Field ID	Field
6	PO Date	15	Client Address
7	PO Number	16	Client City
8	Vendor Name	17	Client State
9	Vendor Address	18	Client Zip
10	Vendor City	19	Shipping Method
11	Vendor State	20	Delivery Date
12	Vendor Zip	21	Approved
13	Total	22	Subtotal
14	Client Name	23	Sales Tax
75	Photo (file attachment)

Here, ~i:75:30~ inserts the image in field 75 (see Images), ~strid=1~ inserts an embedded report (see Embedded reports), and ~=FormatN(f[13],$)~ writes the value of field 13 in words (see Numbers in words).

All of these fields must be in the template's clist, so for this template it would be 6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.75. The EFP Configurator builds it when you select the fields (see Step 2).

Formatting, images, and functions

Besides plain field values, a template can format values and add images, barcodes, and other content. Each option is described, with examples, in Template fields and functions:

How field types appear: dates, percentages, checkboxes, user fields, HTML, and images.
Dates: date formats and the current date.
Images: how to insert an image and set its size.
Functions: numbers in words, ordinal numbers, currency symbols, barcodes and QR codes, and charts.

Embedded reports (related data)

To show a table of records, such as the line items of an order, add an embedded report. You set it up with the EFP Configurator as a Document Subtables record, then copy the record's Template Reference value, for example ~strid=1~, onto its own line in the template. For the steps and every option, see Insert embedded reports (subtable).

Add a new document template

Templates are stored in the Document Templates table, which the setup wizard adds to your app. Each record is one template, and its Record ID# is the template ID that the button formula uses (tpid). Once you've designed the template in Word, add it to Quickbase in two steps: create the template record, then choose the fields with the EFP Configurator. If the template has embedded reports, add them afterward (see Create an embedded report).

Step 1: Create the template record

Open the Document Templates table in your app and add a new record.
The new record form shows these fields:
- Name (required): enter a name for the template, for example Purchase Order.
- clist: leave it blank. The EFP Configurator fills it in (step 2).
- Template File (in older apps, MS Word Template file): select Choose File and pick the Word file on your computer.
- MSG_DetailsNotFound (optional): the text to show when an embedded report has no records.
Select Save.

The saved record shows the template's details and the tools for the next steps:

Name, a blank clist, Template File with a link to the Word file and a Revisions button for earlier versions, MSG_DetailsNotFound, and a blank Master table dbid.
The EFP Configurator button (used in step 2).
The Add New Exact Forms Plus Subtable button and a list of the template's embedded reports, empty for now.

Step 2: Choose the fields with the EFP Configurator

These are the basic steps. For everything on the configurator's Master tab, including how to change the master table later, see Choose the master table fields.

On the saved template record, select EFP Configurator. The Exact Forms Plus Configurator opens in a new window. It has two tabs, Master and Configurations, and opens on Master, under the heading Master Table Settings.
In Select the table from your application, choose the master table, for example Purchase Orders. Until you choose one, the list shows No Table is Selected..
The fields of that table are listed with three columns: Field ID#, Field Name (with the field ID in parentheses, for example Client Name(7)), and Is Selected. Select a column heading to sort the list.
Select the check box in Is Selected for every field the template uses, including fields used inside functions and in the file name. Clear the check box for fields you don't need. As you go, Master Table Clist: below the list shows the selected field IDs separated by periods, for example 2.3.7.9.11.12.
Select Apply Changes to save the selection to Quickbase. A success message confirms that the master table settings were saved. If you haven't chosen a table or any fields, you see Please Select a table or Please add some fields before saving instead.
Select Close. If you leave without selecting Apply Changes, your browser warns you that changes may not be saved.
Back on the template record, clist now holds the field IDs you selected, for example 9.18.10.12.13.14, and Master table dbid holds the master table's ID. If they're still blank, refresh the page.

When you add a field to the template later, open the EFP Configurator again, select the field in Is Selected, and select Apply Changes. You can also add the ID to clist yourself: field IDs separated by periods, starting and ending with a number.

Change a template

Edit the Word file and attach it to Template File again. Earlier versions are kept, so you can go back to one. To start a new template from an existing one, use Copy this Document Template, which copies the record together with its embedded reports.

To try a change without saving documents to your records, add test=y to the button formula. See Other parameters.

If the document isn't created or looks wrong

What you see	What to do
This version of Exact Forms Plus only supports .doc or .docx template files.	Save the template as .docx or .doc (lowercase extension) and attach it again.
The template record was not found.	The template ID (`tpid`) in the button formula doesn't match a record in the Document Templates table.
The template table was not found.	The `tpdbid` in the button formula is wrong. Use the table alias `[_DBID_DOCUMENT_TEMPLATES]`.
The template record exists but there is no file associated to it.	Attach the Word file to the template record.
Document could not be downloaded at this time.	Exact Forms Plus couldn't read the template file. Try again in a moment.
Text such as ~Customer Name~ appears in the document as typed	The field isn't in the template's clist, or the name or ID is wrong. Add it with the EFP Configurator.

For errors from embedded reports (~strid=N~), see If the embedded report doesn't appear or looks wrong. The exact wording of these messages differs slightly between buttons. If you still need help, open a technical support case.