Using the data source commands on your XpressDox template (..cont)
If you have not yet configured a data source, you need to do before proceeding. You will find instructions on how to configure a data source here.
Whereas the ChooseFromDataSource relies on interaction from the user in the interview, the IncludeDataSourceData includes data from a pre-configured data source before the interview is even loaded.
Example:
«IncludeDataSourceData(Clients)»
or
«IncludeDataSourceData(Clients,,,Matters)»
The second example shows how the data from the data source is to be merged into the Data Set in a Collection called ‘Matters’.
Return a range:
When using a data source to produce a mail-merge type of document, then the IncludeDataSourceData command can include a ‘Range Restriction’, which in the data base sense is a ‘where’ clause (excluding the word “where”):
«Comment(The following assumes that the data source 'Clients' has a data field, or column, called 'IncludeInMailshot'
and that all the rows which are required in the template contain the word 'yes' in that column.)»
«IncludeDataSourceData(Clients,,range=IncludeInMailshot = ‘yes’)»
Return only 1 row:
It is also possible to include a single row from a Data Source, using the ‘id=’ syntax, as in this command:
«Comment(This assumes that the Data Source has an 'id' configured for it which is numeric in type
The below command will select the row which has an 'id' value of 1 thereby returning only one row.)»
«IncludeDataSourceData(FirmAddressAndDetails,Refresh,id=1)»
Note that if the ‘id’ column in the Data Source is not numeric, then the value must nevertheless not be in quotes. However, the syntax for the “range=” option requires that non-numeric values be in quotes and numerics not in quotes (as in the above example range=IncludeInMailshot = ‘yes’). Note also that when the value is a date, it must also be enclosed in quotes, except that for Excel and Access the delimiter is not a quote but the # symbol – hence range=DateOfBirth > #2001-01-31#.
Summary of all parameters in the IncludeDataSourceData command:
| Data source name | The name of the data source as per the configuration |
| Refresh/Save | Refresh and save options as described below |
| “Where’ clause | The id or range. |
| Parent element name | Optional. |
| Condition for Save | Optional. Used in conjunction with the Save parameter. |
| Apply DataSource condition | Optional. Apply a condition to prevent the IncludeDataSourceData from executing |
Conditional:
To make the IncludeDataSourceData conditional, use the 6th parameter listed above i.e. supply a condition in the command itself. The IncludeDataSourceData will not be subject to an If statement. Remember that IncludeDataSourceData runs before the interview has even loaded, and an If statement runs inside the interview.
The Refresh and Save options
When running templates within the MS Word environment, the user has the option to run a template and then select ‘Use Other Data’ – which means use the Data Set saved from running this or another template on a previous occasion. This is a very useful feature, but has complications relating to data from Data Sources (and File Data).
The question arises about whether or not the data elements saved on the previous occasion should be used exactly as they were when the previous template was run. This is on the face of it what we would like. But, suppose some data elements were originally included from a data source, for example an Excel spreadsheet or a database, and the data elements in the data source have subsequently changed, should the new, changed data be used, or the data as saved when the last template was run?
In general, there is no hard and fast answer to this question, but in particular circumstances, the expectation would be that when data in a data source changes, it should affect not only new templates which reference that data source, but also templates using older data.
For this reason the IncludeDataSourceData, ChooseFromDataSource, IncludeFileData and ChooseFromFile commands all have a ‘refresh’ option. This indicates that when the user selects ‘Use Older Data’, then the data elements from the relevant data source must be refreshed from the data source and not copied directly from the originally saved data set.
Examples of usage are:
«IncludeDataSourceData(Clients,Refresh)»
«ChooseFromDataSource(Directors,Select the Director,Refresh)»
Related to this is the ‘Save’ option, which governs what happens when the user changes a value which originated from a data source. The template author can decide whether those changed items should be changed in the data source or not, or whether the user should be prompted to confirm that the data source should be changed.
The ‘Save’ option is connected to the ‘Refresh’ option in that if ‘Refresh’ is not chosen, then ‘Save’ cannot be chosen.
The full set of refresh and save options are, then:
– Refresh
– RefreshNoSave (which is the same as Refresh)
– RefreshOptionalSave: The user is prompted to save any changes.
– RefreshSave: Changes made by the user are saved without prompting the user.
The default for IncludeDataSourceData and ChooseFromDataSource is ‘Refresh’. The default for IncludeFileData and ChooseFromFile is also ‘Refresh’.
