Table of Contents
Overview
The Edit Document Stubs page allows you to map document stubs defined in the Word-based document template against the named ranges that you would like dynamically injected into the placeholder.
What is a Document Stub?
A document stub is a specifically formatted string token that is placed inside of a Word document with the intention of acting as a placeholder for other content, which will likely be output generated by the Excel model or input entered by the user from the web interface.
A stub takes the following form: {{ HelloWorld }}. A stub is distinguished by the double curly brackets enclosing it on either side. The document stub name
is the value inside the double curly brackets - in this example, the stub's name is HelloWorld.
Document stubs can have the following types:
- Text: A string value with the stub format somewhere in your Word-based template document.
- Image: A string value with the stub format placed at the Alt Text property of an image in your Word-based template document.
To create a Text stub, simply add a string value with the stub format somewhere in your Word-based template document. For example, you may have a financial planning tool that should generate a document beginning with the following:
Dear Jim,
Thank you for the opportunity to assist you in assessing your financial plan [...]
However, each individual that uses your financial planning tool will not be named 'Jim'. As a result, your template will need to consider the first name as a piece of dynamic content that will be updated based on the user's first name entry. A document stub should be inserted as such:
Dear {{ FirstName }},
Thank you for the opportunity to assist you in assessing your financial plan [...]
Upon upload to the system as part of a print process, this document stub will be detected with the name FirstName. You can also utilize the same stub numerous
times throughout your document template if you have need of showing the same value repeatedly.
Note: The name of the document stub does not need to match any named ranges in the system since you will be able to map document stubs to corresponding named ranges in the Edit Document Stubs page. However, using stubs with names corresponding to named ranges will make the mapping process easier, since the system will auto-detect corresponding names and automatically associated them.
To create an Image stub, simply add a string value with the stub format placed at the Alt Text property of an image in your Word-based template document. For example, you may have a financial planning report that should generate a document including a bar chart:
When applying formatting to a stub, you must apply the same formatting to the double curly braces for the system to recognize it. For example, this stub will not include the selected formatting of highlight, bold, and italicize:
The total cost of the goods selected is, {{ total_due }}.
This following stub will contain the applied formatting:
The total cost of the goods selected is, {{total_due}} .
Editing Document Stubs
Single Documents
Clicking Edit Document Stubs next to an existing document under the Edit Document page will allow you to configure the mapping between the document stubs and their corresponding named range values.
All valid document stubs from the Word template will be automatically detected by the system, and shown on the Document Stubs grid.
| Column Name | Purpose |
| Active | This toggle indicates whether the corresponding stub will be active, and substituted with the corresponding named range at runtime (i.e. whether this value in the printed document is to be replaced with a named range value). This toggle can be used to de-activate a value if the system picked up a label that you did not intend to be included as a document stub. |
| Key | This is a unique value indicating the stub name. All stubs associated with this name are controlled by the settings in the corresponding row. |
| Stub Type | This is the type of the stub recognized by the system. Text type stubs can be mapped to a named range. Image type stubs can be mapped to a visualization, or a named range which is bound to a File Upload UI control with a maximum file count of 1. |
| Named Range |
This constitutes the named range whose value the stub will be replaced with. This is
effectively the mapping between the workbook and its named ranges to the output document.
A named range can be selected for Text or Image stub Types. Named range should be bound to a File Upload control with a maximum file count of 1 to become available for Image Type stubs. |
| Visualization |
This constitutes the visualiztion whose image the stub will be replaced with. This is
effectively the mapping between the application and its visualizations to the output document.
A visualization can only be selected for Image Type stubs. |
| Type | If you would like the value from this named range to be formatted before it is injected into the document, the Type must be selected from this option. The system will pre-parse the value of the named range, and format it accordingly. If the value of that named range fails to be parsed appropriately during the replacement process, the stub will be replaced with an empty string value. Text data type is different from the others since it will get the formatted value directly from the PSC. PSC will use the format of the named range in the Excel file or overridden value in the Metadata Editor if it exists. |
| Format | If you would like the value from this named range to be formatted before it is injected into the document, you must select a Format option here. The system will pre-parse the value of the named range (based on the Type) and then format it accordingly. If the value of that named range fails to be parsed appropriately during the replacement process, then the stub will be replaced with an empty string value. Available formatting options in the list will show example values that are formatted based on the application Culture. |
| Modification Type |
This option determines which resizing behavior will be used when the replacement image is injected
into the document.
None: Image will be stretched to the size of the placeholder image in the document. CropFill: Image will be resized based on the smaller dimension, keeping the aspect ratio to fill the size of the placeholder image in the document. CropFit: Image will be resized based on the larger dimension, keeping the aspect ratio to fit the size of the placeholder image in the document. Note that this property is only available for Image Type stubs mapped to a named range. |
| Remove Image When Empty |
This option indicates whether the placeholder image in the document will be removed, if
no files were uploaded into the associated File Upload control in the UI, or the uploaded file is not a
valid image.
Note that this property is only available for Image Type stubs mapped to a named range. |
| Quality |
This will determine the quality of rendering for a visualization image. This directly translates to a rendering
scale. Fair quality will render the image at 1x, Good quality will render at 2x, and so on. There is
a point at which increasing the rendering quality will begin to have diminishing returns, since once the rendered
image is embedded into the template, it will have a finite size (i.e., 1x) and therefore be compressed at that size
when the whole document is being rendered during PDF conversion.
Note that this property is only available for Visualization Type stubs mapped to a named range. |
| eSignature |
This indicates whether the corresponding stub will be used as an eSignature field for Docusign Connector,
and what will be the type of the eSignature. If an eSignature type is selected, this stub will not be
substituted at runtime (i.e. this value in the printed document will not be replaced).
Since eSignature stubs will not replaced at runtime, their font color should match their background color to avoid text and signature overlapping in the Docusign Connector output. Since an eSignature field with a pre-defined height will be added to document, font size of the stub should be at least 34pt to provide enough height and avoid text and signature overlapping in the Docusign Connector output. |
Repeating Documents
Clicking Edit Document Stubs next to an existing document under the Edit Document page will allow you to configure the mapping between the document stubs and their corresponding columns from the selected table named range while creating the repeating document.
Each detected document stub from the Word template will occupy a row on the corresponding grid. Repeating documents only support text type stubs.
| Column Name | Purpose |
| Active | This indicates whether or not this stub is active and should be substituted at runtime (i.e. whether this value in the printed document should be replaced with a named range value). This can be de-activated if the system picked up a value that you did not intend to be a document stub. |
| Key | This is a unique value indicating the stub name. All stubs associated with this name are controlled by the settings in the given row. |
| Column | This constitutes the column of the selected table named range whose value the stub will be replaced with. This is effectively the mapping between the workbook and its named ranges to the output document. |
| Type | If you would like the value from this named range to be formatted before it is injected into the document, then the type must be selected here. The system will pre-parse the named range's value and format it accordingly. If the value of that named range fails to be parsed appropriately during the replacement process, then the stub will be replaced with an empty string value. Text data type is different from the others since it will get the formatted value directly from the calculation engine. The calculation engine will use the format of the named range in the underlying Excel file, or overwrite value in the Metadata Editor, if Metadata Formatting is enabled. |
| Format | If you would like the value from this named range to be formatted before it is injected into the document, then the format is defined here. The system will pre-parse the named range's value (according to the Type) and then format using this value. If the value of that named range fails to be parsed appropriately during the replacement process, then the stub will be replaced with an empty string value. Available formatting options in the list will show example values that are formatted based on the application Culture. |
| Required | This column will only be visible if Skip Row Type is selected as Existence of Column Values while creating the repeating document. Each column marked as Required should have a value in order for the document iteration corresponding to that row to be printed. |