REQUIRES prompt_data AS variable_data 
                                [VALUES "value1,value2,value3 ..."]

prompt_data is the text to be presented to the user for each variable required. It must be enclosed in quotes, unlike TEXT and FIELD data. If it is not, the variable line will be ignored.

variable_data is the name that this piece of data will be known by in the script from now onwards. It should be a single word, and must begin with and contain exactly one dollar sign ($). If it does not fit that pattern, it will be ignored. Although the line will not be ignored if more text follows a legitimate variable name, that extra text is ignored and is not part of the variable name. The dollar sign, however, is part of the name and must be used for it to work. See the section Literal Text, Variables & Quotes for details of usage.

REQUIRES commands can appear anywhere in the script, but logically they must appear before you try to use the variable somewhere else, otherwise they will show ???. It would be considered good practice, though, to declare them at the top of the script, or at least before each section that uses them.

There are some reserved variable names:

  • AwaySpeaker
  • Congregation
  • LastWeek
  • LastMonth
  • LastYear
  • LocalCong
  • LocalSpeaker
  • LocalAndAwaySpeaker
  • Today
  • NextWeek
  • NextMonth
  • NextSixMonths
  • NextTwoYears
  • NextYear
  • NextQuarter
  • NumTabStops
  • RangeStart
  • RangeEnd

You can specify a set of options to associate with the variable. These values should be comma separated, and the list of values should be enclosed in speech marks. These values will be displayed in the editor in the drop-down list. You can still override those choices manually if so desired. Note, if you specify only one optional value, then it will be treated as a default value (see below) rather than an option for a drop list.

Default Values

The custom script editor will raise multiple errors whenever uninitialised variables have been used for LOOP and IF criteria. Consider using default variable values to avoid this issue. The first option specified for the VALUES parameter will become the default. The editor will use ??? when nothing has been specified for the VALUES parameter.

Examples:

REQUIRES "Away Speaker:" AS $AwaySpeaker
REQUIRES "Show talk numbers?" AS $bShowTalkNos VALUES "Yes,No"