Request (User)

Ribbon Request (User)


Press the Request (User) button on the ribbon bar.
Command Syntax
Request (User) dialogue
This is actually more of a pre-processor than an actual script command. It tells the scripter that some data is needed from the user. Once that data has been assigned to the variable, that variable can be used through the script to substitute what the user chose for some literal text.

The usefulness of this will become apparent if you try to create a script to print out, say, all away talks being given by a certain brother. You could write one script per brother, changing the name to look for in the database each time. But hey, that wouldn't be very efficient! Instead, use a variable to represent the brother's name, and thus you only have one script. Every time the user runs it with a different brother's name, it's the same script executing each time, but it prints out different data.

Use the variable prompt edit box to specify the text to be presented to the user for each variable required (this will happen when you actually generate a custom report itself). Use the variable name edit box to specify the name that this piece of data will be known by in the script from now onwards. It should be a single word.

You can use the droplist to select some predefined variable names - AwaySpeaker, Congregation, LocalSpeaker and LocalAndAwaySpeaker. These are special because they will provide you droplists to select the values to assign to the variables.

If you know ahead of time the preferred choices that you want to choose from then you should fill in the Optional set of values to use edit box. Each value should be separated with a comma (,). These options will then automatically show in the drop list for you to select from (similar to AwaySpeaker and Congregation variables etc.). 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.

Variables can also be set as dynamic. Such variables do not have a prompt and are only used internally within the script. However, declaring dynamic variables in this way has been superceded by the Set New Value script command. (see note below).

The custom script editor will raise multiple errors whenever unititialised 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.
 
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. But you are not forced to. It just makes it easier to maintain.

You won't be allowed to duplicate an existing variable name. In order to actually use your variable within the editor, you must update the value that the variable refers to. This is covered in the Script Editor help topic.

Please be aware that you can now use the new Set New Value feature and in many instances this does away with the need to use a REQUIRES command. But you must still use REQUIRE commands whenever you need the user to make a selection or enter a value.
Insert 
You must press Insert (or Update if editing an existing command) for your changes to be applied to the current script in the editor.