Configure a template

The XL Docs Configurator screen (the "master" screen) sets up one template: which workbook sheet the master record's data goes on, which fields go in which cells, how big images are, and which data tables the template includes. Everything is saved on the template's Document Templates record. For the fields themselves, see Document Templates table reference.

Before you start

Design your Excel workbook (.xls, .xlsx, or .xlsm) with the layout, labels, formulas, and charts you want. Note the cells where Quickbase data should go. See Build a document template.
In your app, open the Document Templates table and add a record.
Enter a Name for the template, attach the workbook in the template file field, and save the record.
Open the saved record and select the XL Docs Configurator button. The Configurator opens in a pop-up.

If the button is missing, see Configurator overview and installation.

Fields tab

The Fields tab opens first. It has three sections.

Template Settings

Control	What it does	Saved to
Template Name (required, red asterisk)	The template's name. Saving with it blank shows Name is required.	Name
Excel Sheet #	The sheet that the master record's fields are written to, counted by position from the left: 1 is the first sheet, whatever its tab is named. Whole numbers from 1. Leave it blank to use the first sheet.	Excel Sheet #
PDF Pages	For PDF output, which sheets to include, by position—for example 1,3-5. Sheets are printed as consecutive PDF pages. Leave it blank to include every sheet.	PDF Pages

Master Table Selection

Control	What it does	Saved to
Table	The master (parent) table to take data from. The list starts with -- Select a Table --, followed by every table in your app. Choose a table even if you only plan to use data tables; you don't have to map any of its fields.	Master table dbid (the table ID) and Master table name (its name)

Note
When you pick a different table, the Configurator shows Table changed. Save to confirm selection, or reload to refresh fields. The field grid still shows the old table's fields. Select Save, close the pop-up, and open the Configurator again to map the new table's fields.

Field Mapping

The grid lists every field in the master table. Select a column heading to sort by it; fields that have a cell position are listed first, sorted by column and then row.

Column	What it shows or does
Field ID	The field's ID in Quickbase.
Field Name	The field's name.
Reference Type	Lookup or Summary for lookup and summary fields; blank for other fields.
Type	How XL Docs writes the value into the cell. Click the cell to choose: Text—the value as it is. Numeric—as a number, so Excel formulas and number formats work. A leading $ is removed; if the cell is formatted as a percentage, the value is converted. Date—as an Excel date. HTML Text—rich text from an HTML field. An HTML table is written as a grid of cells starting at that cell. See Rich text and HTML. Image—the picture from a file attachment or image URL field. See Images tab. A field with no mapping yet gets a type to match its Quickbase type: numeric, currency, percent, and rating fields are Numeric; date and date/time fields are Date; file attachments are Image; rich text is HTML Text; everything else is Text.
Cell Position	The cell to write the field to—for example B6. To write the same field to several cells, separate them with commas and no spaces: B6,E10. Leave it blank to leave the field out.

Cell positions are optional. If the master record's data shouldn't appear in the workbook—for example, the template only has data tables—leave them all blank.

When you save, the grid is written to the template's clist field as a list of cell:field ID entries separated by periods. The type adds a suffix to the cell: -N Numeric, -D Date, -H HTML Text, -I Image (Text has no suffix). An image size is added at the end as height|width. For example:

B6:6.B7:7.B8:8.K6:104.K7:105.M12-I:275:200|200.A38-H:276.RK:3.AA:7.BB:10

Here field 6 goes in B6, field 275 is a 200 × 200 pixel image in M12, and field 276 is HTML in A38. Entries without a row number, such as RK:3 or AA:7, aren't written to a cell: they make master-field values available to data table queries (see Parent fields in queries). The Configurator keeps these entries when it saves.

If a cell position isn't valid, saving shows Invalid cell notation for: followed by the field names. Use a column letter and a row number, like A1, or a comma-separated list like A1,B3.

Images tab

The Images tab sets the size of image fields. It lists only the fields whose Type is Image and that have a Cell Position on the Fields tab, and it updates as you change the Fields tab. If there are none, it shows No images were selected for the template.

For example, to include a QR code: on the Fields tab, find the field that holds the QR code (for example, a formula URL field that returns a QR code image), set its Type to Image and its Cell Position to M12. On the Images tab, set the size.

Column	What it does
Field ID, Field Name, Cell Position	The image field and its cell, from the Fields tab (read-only here).
Width (px or Auto)	Width in pixels. Leave blank or enter Auto to keep the image's proportions.
Height (px or Auto)	Height in pixels. Leave blank or enter Auto to keep the image's proportions.

The size is saved in the clist entry for the field—for example M12-I:275:200|200. If an image can't be loaded when a document is created, the cell shows Image Error. For more about images in XL Docs templates, see Images in Build a document template.

Data Tables tab

The Data Tables tab lists the template's data tables—sets of rows from other tables, such as an invoice's line items or a project's expenses. Each is a record in the Document Subtable Excel table, related to this template. A template can have as many as you need, on the same sheet or on different sheets. See Data tables (subtables).

The grid is sorted by sheet and has these columns:

Column	Shows
Edit (link)	Opens the data table in the XL Docs Subtable Configurator.
Copy (link)	Copies the data table (see below).
Sheet #	The sheet the data table is written to (Sheet).
Table Name	The table it reads (dbid).
Description	Its description (Description).
Cell List	Its cell mapping (clist).
Query	Its filter (qry).
Is Data Grid?	Yes or No.
Max Lines Type, Max Line Items, Skip Rows, Tab Sub Order	Its grid settings.
Has Images	Yes if any of its fields is an image.

On this tab, the Save and Cancel buttons are replaced by Add New Data Table.

Add New Data Table

Select Add New Data Table to open an empty XL Docs Subtable Configurator in a new pop-up, then set it up as described in Configure a data table. When you close that pop-up (or an Edit pop-up), the Data Tables grid refreshes on its own.

Copy Data Table

To start a new data table from an existing one—for example, the same layout on another sheet—select Copy on its row. The Copy Data Table dialog asks for a New Description:; enter one and select Copy (or Cancel).

The copy is a new Document Subtable Excel record for the same template with every setting of the original—table, cell mapping, query, sorting, sheet, grid settings, subtotals, grouping, and averages—and the new description.
It appears in the grid with Data table copied successfully. Select Edit on it to change it.
A blank description shows Please enter a description for the copied record.

Save and Cancel

Save writes the Fields and Images tabs to the Document Templates record and shows Settings saved successfully.
Cancel undoes your changes since you opened the screen or last saved.
If you switch tabs with unsaved changes, the Configurator shows Please save or cancel changes before proceeding.

For other messages, see XL Docs Configurator messages and troubleshooting.