Using expressions
variaDoc features a powerful language that uses expressions. Expressions can be used to assign values to a wide variety of properties such as output file names, form field values, e-mail message subjects and SQL statements.
Expressions
Almost all settings in a merge project can be entered as an expression.
An expression can be literal text, but it may also contain data references or VB.NET expressions.
- Literal text can be used only in certain contexts. For instance, if you added a section node to your document, then literal text can be converted into text paragraphs.
- A data reference is a dynamic part of an expression. It is typically used to fill the value from a database in a field. During a merge it will be replaced by the value that it refers to at that time.
For example, if we have a list of customers in our database, we could refer to the company name of the customer like this:
$[Customers:CompanyName]In this expression Customers is the name of a data source that connects to the database of the list of customers. CompanyName is the name of a column in the table that holds the list of customers.
The data reference will result in a different value for each row in the data source.
- VB.NET expressions can perform tasks such as calculations and formatting. Here you can think of adding a calculated value or a date to your form.
Other examples of expressions are SQL queries and XPath expressions.
The use of expressions is not limited to form fields. They are used through out the project as well. For example, they can also be used to set file names and other document information.
The use of expressions gives unlimited possibilities for combining data into forms.
Entering expressions
Most text boxes in variaDoc allow you to enter expressions.
Every entry box in variaDoc that lets you enter an expression has a preview button, 
. Clicking this button will evaluate the expression and show the results. If the expression is located in the merge project below one or more data sources, all possible instances of the evaluated expression are shown. This allows you to test expressions without having to run the entire project.
. Clicking this button will evaluate the expression and show the results. If the expression is located in the merge project below one or more data sources, all possible instances of the evaluated expression are shown. This allows you to test expressions without having to run the entire project. Anatomy of an expression
As previously mentioned, an expression can contain three kinds of sub-expressions:
- Literal text
- Data references
- Embedded VB.NET expressions.
To distinguish between these parts, some special characters are used.
Characters | Description | Example |
$[ ] | A data reference. | $[customers:first] |
: | If inside a data reference, separates the data source name from the data query. | $[customers:first] |
| | If inside a data reference, separates the query from the inline format specifier. | $[customers:first|Upper] |
{ } | { DateTime.Now } |
Every character that is not part of a data reference or an embedded expression is literal text.
You can combine all kinds of sub-expressions in a single expression.
For example:
This is piece of literal text combined with data $[Users:Name] from the Users data source and a VB.NET for the current date { DateTime.Now }.What happens during a merge
Expressions are evaluated during a merge. Evaluation of an expression always results in a single value for either a setting or a form field. If an expression is specified on a page that is repeated many times, the expression is evaluated just as many times.
Evaluation of an expression happens in two steps.
- Data references are replaced with actual data. If inline formatting is used, the formatted data is used instead of the actual data.
- Any embedded VB.NET expressions are evaluated and replaced with their result.
The resulting value is used by variaDoc to fill form fields or set properties.
Syntax coloring
While typing expressions, syntax coloring will help you identify how the different parts of the expression are interpreted by variaDoc. The following shows the color scheme.
Color sample | Description |
“static text” | Static text in SQL expressions ( red ) |
SELECT | SQL keyword ( blue ), VB keyword |
{ String.Format() } | Embedded VB.NET expression ( accolades marked yellow ) |
$[mydata:field] | Data reference ( dark red / dark yellow with light yellow back ) |
Type assist
variaDoc provides type assist. For example if you type in the $ character, variaDoc knows you are trying to reference a data source or merge parameter and will display a list of available options. This will help you to type expressions quickly and reduce the number of typing errors. See figure below.
If you select a data source from the suggested list and type the : (colon) character, variaDoc knows you are trying to select a field from the selected data source and will display a list of available options.
variaDoc provides type assist for:
- Data sources
- Database fields
- Merge Parameters
- XML/XPath entities
Preview expressions
Every entry box in variaDoc that lets you enter an expression has a preview button, . Clicking this button will evaluate the expression and show the results. If the expression is located in the merge project below one or more data sources, all possible instances of the evaluated expression are shown. This allows you to test expressions without having to run the entire project.
. Clicking this button will evaluate the expression and show the results. If the expression is located in the merge project below one or more data sources, all possible instances of the evaluated expression are shown. This allows you to test expressions without having to run the entire project.