The template author will use this command to provide a way for the user of a template to choose data from a Data Source and those data can then be inserted into the template.
Watch a quick demo on the ChooseFromDataSource command:
Simple Form
The simplest form of the command is shown in this example:
«ChooseFromDataSource(Contacts,Select the contact or type in the Contact ID if you know it)»
The first parameter is the data source name, and the second is the caption that will be displayed next to the control in the interview.
The control in the interview has a text area and also a button. If the user presses the button, then the data source search form is presented, and they then can search for the data that they require.
If the user knows the value of the Id for that data source (usually a code like an account number or in this example a contact Id), then they can type that into the text area, and the data will be retrieved as soon as the focus moves out of that text area – for example if the user presses the Tab key.
Refresh, Save and AllowInsert Options
Another form of the command is
«ChooseFromDataSource(Contacts,Select the contact or type in the Contact ID if you know it,RefreshSave)»
The “RefreshSave” option means that if the user changes any of the data which was retrieved from the data source, then those changes will be written back to the data source. A full explanation of the RefreshSave parameter is given in Control how the user can change data source data.
Restrict the range of the search
Suppose you want the user to be able to select only Customers from the Contacts data source. Assuming the data source has a column called “ContactType”, the command would look something like:
«ChooseFromDataSource(Contacts,Select the contact or type in the Contact ID if you know it,RefreshSave,Range=ContactType='CUST')»
Use variable information in the Range
It might be that the contact type is actually in a data element which has already been populated (it might have been captured by the user in the interview, or included using an IncludeDataSourceData command, or one of many different ways of including data in the data set). Suppose the contact type is in a data element called ContactType – then it can be used in the Range as follows:
«ChooseFromDataSource(Contacts,Select the contact or type in the Contact ID if you know it,RefreshSave,Range=ContactType='<ContactType>')»
Manage the button
The last parameter to the command enables the template author to either:
- Insist that the user use the search button, in other words they can’t type in any arbitrary ID and have the data source retrieve it:
«ChooseFromDataSource(Contacts,Select the contact or type in the Contact ID if you know it,RefreshSave,Range=ContactType='CUST',RequireSearch)» - Disallow the user from using the search button – i.e. they must know the ID of the data that they want:
«ChooseFromDataSource(Contacts,Select the contact or type in the Contact ID if you know it,RefreshSave,,DisallowSearch)»
In effect, this is the same as using the LinkToDataSource command with a normal text box for the control, e.g.
«CaptureDataElement(ContactId)»«LinkToDataSource(ContactId,Contacts)» - The third option is “AllowSearch”, but that is the default and so can be left out.
Choose Multiple Entries
With effect from Version 5 of XpressDox, there is a 6th parameter which can be passed to the command, this being the name of a repeating data element. This has the effect of permitting the user to choose more than one entry from the search dialog. The entries thus selected are used to create and populate a set of repeating data elements. An example would look like:
«ChooseFromDataSource(Clients,Select the Client,,Range=DateOfBirth <= '1999-12-31',RequireSearch,Client)»
Once the user has chosen the entries from the search dialog, Xpressdox will create one containing data element with name ‘Client’ for each of those entries, and those data elements will then appear in the treeview as a repeater (or, if the «CaptureInGrid(Client)» command has been used, in a grid) on the interview.
The entries chosen in the above example can then be referenced in commands like «ForEach(Client)».
