Auto/Embedded Fields
Automatic fields are form fields that automatically supply a field value, such as the current date or current document number. These fields are distinguished by a "$" (dollar sign) as the first character of the field name. So for example, a field named $DocNum would automatically display the current document number. Since these fields are filled in at data merging time, values that are known only after pagination is completed are not available as $-automatic fields, but they are available as [!embedded] field references.
Embedded fields are metatags within a text label where data is automatically inserted. The embedded metatag can be either an existing field name on the form (such as [customerName] or a "!" (exclamation mark) character followed by one of the Automatic Fields specified below:
For example:
- "Today is [!Date MMMM dd, yyyy]." becomes "Today is March 05, 2016."
- "The current page is [!PN] of [!PC]." becomes "The current page is 3 of 5."
- "Dear [customerName]:" becomes "Dear Fred:"
| Automatic Field | Embedded Field | Description |
|---|---|---|
| [FieldName] | Value of the form field or label (label added in 3.1.002.12) called FieldName. | |
| [!PageNum] | Current page# within the document. | |
| [!PN] | Same as [!PageNum]. | |
| [!PageNumForm] | Current page# within the form. (Added in 3.1.002.02) | |
| [!PNF] | Same as [!PageNumForm]. | |
| [!PageCount] | Total # of pages within this document. | |
| [!PC] | Same as [!PageCount]. | |
| [!PageCountForm] | Total # of pages within this form. (Added in 3.1.002.02) | |
| [!PCF] | Same as [!PageCountForm]. | |
| $DocNum | [!DocNum] | Current document# being generated (starts at 1). |
| $DN | [!DN] | Same as $DocNum or [!DocNum]. |
| $Date | [!Date fmt] | Today's date. $Date uses that field's Picture formatting, !Date uses picture format fmt or defaults to yyyyMMdd format. |
| $Time | [!Time fmt] | Current time. $Time uses that field's Picture formatting, !Time uses picture format fmt or defaults to hhmmss. |
| $DateTime | [!DateTime fmt] | Today's date and time. $DateTime uses that field's Picture formatting, !DateTime uses picture format fmt or defaults to yyyyMMddhhmmss format. |
| $FormFile | [!FormFile] | Fully qualified form file name. |
| $FormPath | [!FormPath] | Path of the form file name (without the form file name). |
| $FormName | [!FormName] | Form file name (without the path or extension). |
| $FormNameExt | [!FormNameExt] | Form file name and extension (if provided). |
| $DataFile | [!DataFile] | Fully qualified data file name. |
| $DataPath | [!DataPath] | Path of the data file name (without the data file name). |
| $DataName | [!DataName] | Data file name (without the path or extension). |
| $DataNameExt | [!DataNameExt] | Data file name and extension (if provided). |
| [!Base64 name] | Converts the value of a named Field or Label to an encoded base64 string. (Added in 3.1.002.10) | |
| $Cachekeyword | [!Cache keyword] | Value from the -cache keyword:value command line option. |
| [!Data name] | Fetch data directly from the Data file. 'name' can be either a simple node name, or a compound name in dotted notation. If name is '*' the name of the current object (Field or Label) will be used. (Added in 3.2.001.01) | |
| [!Profile key] | The value from an external profile file. For values under an profile file section, use section.key to reference. See Profile Files. | |
| [!Session name] | Fetch data from the current Session. If name is '*' the name of the current object (Field or Label) will be used. See Session. (Added in 3.2.001.01) | |
| [!Env name] | The value from environment variables. If name is '*' the name of the current object (Field or Label) will be used. (Added in 3.2.001.01) | |
| [!Field name] | Synonym to [FieldName]. (Added in 3.2.001.01) | |
| [!Auto name] | Synonym to autofields. Added just for consistency. Example: [!Auto DocNum]. (Added in 3.2.001.02) |
- All calls to date and time functions use a common date stamp, which is the time and date when the Merge began running. A call to $Time 20 seconds into the run will return the same time as a call at the beginning.
- The $Date, $Time and $DateTime fields can be formatted using the available field format options for these types of fields. (As of 3.0.001.02)
- To have a formatted date embedded in a text label, create a (possibly hidden) $Date field that correctly formats the date, then references it in the text label as in "Today is [$Date]".
- File names will not include a file extension unless one was passed on the Merge command line.
- The -cache command line option allows
keyword:valuepairs to be passed from the calling application to the form. An automatic or embedded reference to "keyword" returns the corresponding value. - For a table of possible symbols in the ICU documentation
https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax
-embeddedDefault
If an embedded field could be excluded from the data such as title or address2, use the merge option -embeddedDefault to prevent the embedded field syntax from presenting in the output.
For example, if the field title is optional, then use the merge option -embeddedDefault ""
Form Design
Dear [title] [firstName] [lastName],
Output
Dear Sam Smith,
See Also
Object Tags (Direct Data Binding)
-embeddedDefault
