ChooseFromFile is in some ways similar to ChooseFromDataSource, except that the data are defined either in a simple text file, or an XML file, and the file does not have to be configured into the Data Sources configuration:
The first line of the text file will contain a list of data element names. These names are delimited by any character that is not a valid character in a data element name. For example, a comma, or a pipe |, or a tab character, etc.
The second and subsequent lines have data element values which correspond to the names in the first line. The values are delimited by the same character as was used in the first line.
An example of a text file containing details of partners would be:
The ChooseFromFile command presents the user with a drop-down list which includes in it the first data element value of each of the second and subsequent lines of the text file. When the user chooses a particular value in the drop-down list, then all the data elements corresponding to that line in the text file are included in the data set for the template being run.
The full syntax of the command is demonstrated by this example:
<<ChooseFromFile(lookups:Partners.xdtxt,Choose the Partner,Refresh,PartnerSurname,Primary)>>
The second parameter is the caption which will appear on the interview. The third parameter, ‘Refresh’, is discussed in more detail here. The fourth parameter (in this example PartnerSurname) is the name of the data element whose values must be displayed in the drop down list in the UI. If it is omitted, then the first data element in the file is used.
The last parameter (in this example Primary) is a prefix which is pre-pended to the names of the data elements retrieved from the file. For example, if the first line of the text file contained
PartnerSurname,PartnerFirstNames,PartnerEmail, then the above example would provide data elements called PrimaryPartnerSurname, PrimaryPartnerFirstNames and PrimaryPartnerEmail. In this way, the same text file can be used for providing different lookups.
Note in the first example above that the file extension is ‘.xdtxt’. Use of this extension is recommended but not obligatory, as it is used within XpressDox to assist the template author in their tasks.
This is similar to the Text file but in this case the delimiter between data element names in the first line and between values in the second and subsequent lines is a comma.
Choosing data from an XML file is done with the same command and the functioning is identical, taking into account that the information in file is in XML format. The file extension for an XML file must be ‘.xml’. Other advanced features includes a discussion on the
ChooseFromFile supports the use of “special” characters used in non-English languages, such as ä, Å, è, etc . However, when saving the file using Notepad (or even Save As Text in Word), care must be taken to specify the Encoding as UTF-8.
In Notepad when you save the file for the first time the encoding is available in a drop down box at the bottom of the Save As dialog.
With Word if you choose Save As Plain text then when Word notices the special characters it will either by default save as UTF-8, or will give you the chance to choose the encoding.