When Opus opens a Standalone publication (i.e. an EXE file), it checks to see if any parameters have been sent (passed) to it – see Passing Parameters – Introduction for more information. If Opus finds parameters, it creates new COMMAND_PARAM variables that stores the parameter information. You can then use this information to change the behaviour of your publication.
This section description describes how to set up a publication so that it can use information that is sent to it when the publication is launched.
Note:
Before you read this topic, please read the How to Pass Parameters using the Launch File action topic first.
As described above, Opus checks to see if parameters are passed when a Standalone publication is run. Parameters can be passed when one Opus publication opens another Opus publication using the Launch File action.
If a Launch File action contains parameters, the following process will happen. Opus will open the new publication and create a COMMAND_PARAM variable for each parameter contained in the with option/parameter box of the Launch File action. For example, if the box contains /Page2 /On the following variables will be created in the new publication:
COMMAND_PARAM_1 will contain the value Page2
COMMAND_PARAM_2 will contain the value On
Your new publication now has two new COMMAND_PARAM variables, which you can use as and when you like – Please note point 4 below!
Note:
You must remember the order in which you passed the parameters so you know which one to use in your new publication. For example, if the first parameter you sent contains a page name and the second a value to turn music on or off, you must remember that COMMAND_PARAM_1 is used when you want to go to a specific page.
In the new publication (i.e. the one using the parameters), you MUST create the new COMMAND_PARAM variables when you create your publication. This is important! The COMMAND_PARAM variables do not already exist in your publication, that is, you cannot pick them off the list of variables available.
Note:
The reason the COMMAND_PARAM variables do not exist is because we do not know how many parameters you may pass from one publication to another. The variables are created ‘dynamically’, which simply means that when you use the Launch File action in one publication to open a new publication, Opus counts the number of parameters you are passing and then creates the exact same number of COMMAND_PARAM variables in the new publication.
To add COMMAND_PARAM variables to your new publication, simply create one variable for each parameter. For example, if you are sending three parameters to your new publication, then create three variables with the following names:
COMMAND_PARAM_1
COMMAND_PARAM_2
COMMAND_PARAM_3
Note:
To create a variable in Opus – see Creating Variables for more information.
The COMMAND_PARAM variables do not have an initial value because that information will come from the Launch File action in the publication that opens your new publication.
Often, parameters are passed because you want to change the behaviour of your publication when it is first opened. For example, publications always open on the first page by default, but by passing a parameter, you can make a different page appear when the publication is first opened.
Note:
Although parameters are most commonly used when you first enter a publication, they can be used at any time in your publication. For example, you could have a parameter that specifies whether a voiceover should be On or Off. Any page that contains a voiceover could first check the parameter to see if it should play or mute the voiceover.
To use a parameter when the new publication is first opened, use the Pre-Show trigger on the first page of your publication. For example, if a parameter passed to the new publication specifies the first page to display in the publication, you must use a Pre-Show trigger to ensure the first page does not appear briefly before you go to the specified page – see Example 1 below for more information.
Use the Select and Case actions when the parameter contains one option from a variety of options. For example, if the fist parameter contains a page name, do the following. Set up a Select action that uses the PARAM_COUNT_1 variable; create a Case action for each page name the parameter can contain; add a Go to Page action to each Case action that will open the page you want to open.
Note:
Remember to add the Select and Case action to a Pre-Show trigger on your first page of the new publication. This will ensure that the first page the user sees in the new publication is the specified page and not the first page in the publication.
Use the IF action when the parameter contains one of two possible options. For example, if the second parameter contains a value that turns a voiceover On or Off, do the following. On the page or pages in your publication that this applies: add an If action that uses the variable COMMAND_PARAM_2; use a Set Variable action to test if the parameter contains the value On; add a Play Sound action to the If action to play the voiceover. In this example, the voiceover will only play when the second parameter is set to On, if it is set to Off (or anything else), the voiceover will not play.
Use the Insert Variable or Expression option in a Text object if you want to display the contents of a parameter on the page. For example, if the third parameter contains the value of the variable UserName, do the following. Click inside the text box you want to add the user name to; right-click in the text box to open the right-click menu and select the Insert Variable or Expression option; in the Insert Variable or Expression dialog add the variable COMMAND_PARAM_3. In this example, the user name will be displayed in the new publication. See Displaying Variables on a Page for more information.
Note:
Notice you enter COMMAND_PARAM_3 and not the variable UserName. This is because the Launch File action can pass the contents of a variable as a parameter, however, it is the value contained in the variable and not the variable name that is sent. Therefore, if the third parameter was set up to use the contents of the variable UserName, and the name was John, then COMMAND_PARAM_3 will contain the value John.
Example 1 in the How to Pass Parameters using the Launch File action topic showed you how to set up a menu system in one publication that opened a new publication on different pages depending on which menu option was selected. This example shows you how to set up the new publication to show the different pages.
In the new publication, create a variable named COMMAND_PARAM_1. This will contain the value of the parameter /<PageName>.
On the first page in the new publication, add a Pre-Show trigger to the page.
Add a Select action to the Pre-Show trigger and set the variable to COMMAND_PARAM_1.
Add a Case action for each page in your new publication. For example, to show the second page in your publication, set the Value field in the Case action to Page2.
Note:
The entry in Value should be the same as the value of the entry of the parameter in the with option/parameter option of the Launch File action. For example, when the variable PageName is set to the second page, the value entered in PageName is Page2 – this is the value passed as the parameter value and so must be set in the Case action.
Add a Go to Page action to each Case action. The Go to Page should specify the name of the page you want to open for each Case action.
Do NOT add an action to the Default action that is created with the Select action. This will ensure that if none of the Case actions match the value of COMMAND_PARAM_1 then the first page in the new publication is opened.
When a menu option is selected in the menu publication and the Launch File is triggered, the new publication will open. The new publication will then check for any parameters and finds there is one parameter, which it saves into a variable named COMMAND_PARAM_1. Before the first page in the publication is displayed, the Pre-Show trigger is activated and this in turn activates the Select action to see if any of the Case actions match. Once a Case or Default action is matched, the specified page is then displayed.
Note:
Although, this seems like a long process, the specified page should appear more or less instantly. You could use the If action to perform the same task but it is less efficient when you have more than two options to choose from and would take longer to set up and process – therefore, the Select Case action is recommended.