Table of Contents
We generally need a way to control the dynamic behavior of the program by setting the values of various parameters. The dynamic parameters are specified while setting the properties of a program at design time and the value is assigned during the execution of the program.
A parameter is "declared" when you type ${something} within a text field. A field may include multiple declarations, mixed with normal text, e.g. "My name is ${first} ${last}". A parameter is "defined" when you supply a value.
Each dynamic parameter can have up to three elements, name, type and default value. These parts are separated by # characters, which can be omitted when there are no subsequent elements. Here are some examples:
${name} - This syntax is used to specify a parameter name.
${name#type} - This syntax is used to specify the name and type of the dynamic parameter
${name#type#value} - This syntax is used to specify the name, type and value.
${name##value} - If the type has to be excluded and just the default value has to be specified the syntax is given as above.
Dynamic parameter names can include any characters, including spaces and be as descriptive as you like. For example ${Name} or ${Please enter your name}. Reserved characters such as # { and } should be escaped by prefixing with a backslash \. For example ${Enter your \#Id}.
## - A plain text field (the default)
#password# - A password field so the typed characters are masked.
#choice(A,B,C)# - A combo box with choices A, B and C.
#integer# - An integer field, which accepts non-negative integer values.
#number# - A field for numeric values, which may be positive or negative and may include decimals.
#date()# - A date field with a popup calendar.
The date type provides a number of variants to control how the date is presented to the user. Within the tool, the string representation of dates always follows the international standard format yyyy-MM-dd. Here are some examples of date syntax and their meaning (the // indicates a comment and is not part of the syntax):
date // system locale, long format
date() // system locale, long format
date(fr) // french locale, long format
date(fr_CA) // french-canadian locale, long format
date(,"long") // system locale, long format
date(,"medium") // system locale, medium format
date(,"short") // system locale, short format
date(,"(yyyy) dd/MM") // system locale, custom format
date(fr,"short") // french locale, short format
As you can see, date can take up to two parameters (locale,format). Both parameters are optional. The locale is defined using the appropriate language, country and variant codes, separated by underscores: LA_CO_VA. Again you can omit values from the end to accept the default, LA_CO, or just LA. The language codes are defined at: http://www.loc.gov/standards/iso639-2/englangn.html, while the country codes are defined at: http://www.iso.org/iso/country_codes/iso-3166-1_decoding_table.htm. The format should either be "long","medium" or "short" or else a custom pattern. Remember the format only affects how the date is presented to the user, not the internal string representation of the date.
Dynamic parameters are always strings. This means the result substituted for a date type will not be a date object, only a string representation (in ISO format, as mentioned earlier). If such a string is substituted in JavaScript, you will be performing subtraction instead: 2005-01-01 = 2003! In order to convert the string to a date, you need the following form of JavaScript (showing a french date, here):
asDate("${Enter French date#date(fr,"long")}");There are two important parts to this example. Firstly, notice that the ${} substitution is enclosed within quotes. This ensures the result is substituted as a string, not as a series of number subtractions. Secondly, the string is passed to the asDate() function, which is pre-defined within the tool for converting strings in ISO date format into actual Date objects.
#lookup(...)# - Lookup choices from a datasource.
It is good to give users a choice of valid values, but the options are often dynamic. Using the lookup type, you can fetch values from a datasource to populate a combo box on the parameter UI. Here's an example:
${Company Name#lookup(Fruit,CompanyName)#B}This will create a parameter on the UI with label Company Name with a combo box that reads its values from the data source called Fruit using the field called "CompanyName". The default selection will be company B.
Further, the datasource "Fruit" can be either:
Also, further parameters can be passed in if the datasource requires parameters:
${Company Name#lookup(Fruit,CompanyName,User=Jon,Password=XXX)#B}By default, parameters are presented in alphabetical order. This means, if you have parameters defined for ${Name} and ${Address} then the Address will appear first. Often we want to control the order of presentation - it is more common to request Name before Address. To achieve this, we declare a dependency between the parameters. If the name of the parameter includes a string embedded in angle brackets <string> then this indicates that the parameter is dependent on that named parameter and should be shown after it. To ensure Address appears after Name we can therefore define ${Name} ${Address<Name>} - this declares Address depends on Name and should therefore be shown after it. Note the text in angle brackets is not shown on the UI. If we need to give type and/or default values, we include the # separator as usual: ${Address<Name>#choice(Singapore,UK)#UK}, for example.