The ChooseFromFile command
This command is in some ways similar to ChooseFromDataSource, except that the data are defined either in a simple text file, csv file, or an XML file, and the file does not have to be configured into the Data Sources configuration:
Command structure:
«ChooseFromFile(lookups:Correspondents.txt)»
«ChooseFromFile(shared:Partners.csv)»
Text file
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:
PartnerSurname,PartnerFirstNames,PartnerEmail
Jones,John Henry,johnjones@email.com
Smith,Marge,margesmith@email.com
Basset,Fred,fredbasset@email.com
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.txt,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.
CSV file
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.
XML file
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 IncludeFileData command.
Special Characters
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.
