All types of variables work in the same way, that is, they store information and you can use or show the contents of the variable as you like. However, there are five types of variables: System, Page, Publication, Arrays and OpusScript variables – these are described below.
Note:
If you are unsure what a variable is or why you would want to use one – see What are variables? for more information.
Opus provides System variables; these are ready-to-use variables that already contain information. For example, the PUBLICATION_TIME variable contains the current time the user has been running the publication.
The name of System variables is always in uppercase and each word is separated by an underscore character (i.e. the _ symbol), for example, SYSTEM_PUBLICATION_DIR.
Note:
We recommend that when you create a variable, you do not use the same convention for typing names as the System variables – this will help you to identify your own variables quickly.
Some System variables provide information about your publication and current machine. For example, you can check if the user has a sound card installed on their machine with the SYSTEM_HAS_SOUND variable or the SYSTEM_TIME_AMPM variable so your publication can say ‘Good Morning’ or ‘Good Afternoon’.
Note:
The current machine while you are developing is your machine. When the user runs your publication, the current machine is their machine. Therefore, the value of these variables will change depending on which machine is running the publication.
Other System variables provide information about the location of directories on the machine, for example, SYSTEM_PROGRAMS_DIR shows the pathname to the Program Files folder e.g. C:\Program Files – these location System variables are often used in the Publish, Distribution and Upload wizards and the Storage actions, to name a few.
Whenever the Insert Variable or Expression dialog appears, the System variables are listed.
The System variables are listed in the Variables tab of the Publication Properties dialog.
A glossary of the System variables is also available – see System Variables – a Glossary for more information.
Publication variables are user-defined variables and can be created using the New Variable dialog – see Creating Variables for more information.
Note:
When creating Publication variables use a different naming convention than for System variables – this will help you to identify your variables quicker (see point 2 in System variables above).
A Publication variable is available on every page in your publication – hence the name. The value (i.e. the contents) of the variable is persistent, which simply means the contents of the variable remain in it if you move from one page to another. For example, if you create a Publication variable named UserName and it contains the value John, it will always contain that value unless you change it. Therefore, you can display the variable UserName in a Text object on another page of your publication.
To change the value (i.e. the contents) of a variable, use the Set Variable or Set Variable to Expression action in the Variables menu of the Programming tab.
A Publication variable can be displayed on a page in your publication using a Text object – see Displaying Variables on a Page for more information.
The Publication variables are listed in the Variables tab of the Publication Properties dialog – you can also add new Publication variables in the Variables tab.
When the user first opens a publication, the value of the Publication variable is set to the initial value (i.e. the value it contained when it was first created). In other words, it does not contain the value of the last time the publication was run.
When the user closes a publication, the current value of the Publication variable is lost – see points 8 and 9 below.
If you want to keep the information of a Publication variable when the publication is closed, use the Write to disk file action to store the information to a file.
Note:
You may want to keep the information for administrative reasons, such as, if the variable contained the score the user gained after a test. The next time the user opens the publication you will want to use the variables initial value – see point 6 above.
If you want to reset the Publication variable to the same value as the last time the publication was run, use the Read from disk file action to read the value back into the variable.
Note:
Sometimes you want to keep the last value of a variable over several sessions. For example, a variable may contain a user preference, such as ‘don’t play ambient music’. If their preference is NOT the initial value you set when creating the variable, you will need to write the information to a file before the publication is closed and then read the file when the publication is opened.
Publication variables are NOT copied when you copy pages (or an object containing a Publication variable) from one publication to another. In other words, if you copy a page with a Text object containing a variable (point 4 above) the variable is NOT added to the Variables tab in the Publication Properties dialog of the new publication.
Note:
You will have to re-create the Publication variable in the new publication using the New Variable dialog. Once you have created the Publication variable, the copied Text object (or other object containing the name of the variable) will work.
Page variables are user-defined variables and can be created using the New Variable dialog – see Creating Variables for more information.
Note:
When creating Page variables use a different naming convention than for System variables – this will help you to identify your variables quicker (see point 2 in System variables above).
Many of the descriptions in the Publication variable section also apply for Page variables – these are points 3, 4, 6, 7, 8 and 9 above. The descriptions below apply to Page variables only.
A Page variable can ONLY be used on the page in which it was created. The value (i.e. the contents) of the variable can be reset to its initial value or made persistent when the user opens a new page – see points 4 and 5 below.
A Page variable will reset to its initial value (i.e. the value it contained when it was first created) if the Persistent option is NOT ticked in the New Variable dialog when the object was created. For example, if a Page variable named Age has an initial value of 0 and the user changes it to 30 and then opens a new page, the Age variable will be reset to 0 – when the user returns to the page, the Age is 0.
A Page variable will NOT reset to its initial value if the Persistent option IS ticked in the New Variable dialog when the object was created. For example, if a Page variable named Age has an initial value of 0 and the user changes it to 30 and then opens a new page, the Age variable will remain at 30 – when the user returns to the page, the Age is 30.
Points 4 and 5 above explain one reason for having Page variables, that is, a variable with the same name can have different values on different pages. This means if you create a question page for example, you can duplicate the page and the Page variable (although the same name on each page) can have a different value.
The Page variables are listed in the Variables tab of the Page Properties dialog – you can also add new Page variables in the Variables tab.
Note:
The Page variables are NOT listed in the Variables tab of the Publication Properties dialog.
Page variables ARE copied when you copy a page from one publication to another. However, if you only copy a Text object containing a variable, the Page variable is not added to the Variables tab of the page in the new publication.
Array variables are like super variables because they contain more than one value at the same time, unlike Page and Publication variables that only ever contain one value.
Each individual value is stored in an element of the Array variable. You can insert a value into an element of an Array by findings its Index position, which always remains the same – see Array definition for example.
To change the value (i.e. the contents) of an element of an Array, use the Set Variable Array action in the Variables menu of the Programming tab.
Array variables are useful when you want to save information of the same type and you don’t want to create an individual Publication variable for each new bit of information. For example, if you create a quiz in your publication with 10 questions and you wanted to store the answer given for each question, an Array variable would be the best type of variable to use. The Array variable name could be Answer made up of 10 elements Answer[0] to Answer[9].
The Create Table option in the QuickBuild menu allows you to insert one element of an Array variable in each new cell created by the table. Using the example in the previous point, you could display the user’s answers on the page using the table.
Note:
Adding elements to cells of a table is only available when using a Text object to create the table.
In every other way, the Array variable is the same as a Publication variable – see Publication Variable section above for more information.
OpusScript is the Opus Pro programming language – variables are often used in a script to store information that you want to use later on in the script.
You can use the values of System, Page and Publication variables in a script. Simply type the name of the variable, for example, the following line of code (commonly known as an expression):
cdDrive = SYSTEM_CD_DRIVE
means that the OpusScript variable cdDrive will equal the value of the System variable SYSTEM_CD_DRIVE.
OpusScript variables can only be displayed on a page in your publication if you do one of the following:
Use the New Variable dialog to enter the name of the OpusScript variable as a Page or Publication variable – it can then be displayed in a Text object on the page.
Use the Insert New Variable or Expression dialog and enter the OpusScript variable in the Constant Expression box.
Use the OpusScript function ReplaceSelection() in a script to add the contents of an OpusScript variable into a text box displayed on the page.
OpusScript variables that are declared in a script cannot be displayed on a page in your publication other than by using the ReplaceSelection() function. For example:
var userName = "John Smith"
welcomeBox.SetSelection(0,-1)
welcomeBox.ReplaceSelection(userName)
In this example the OpusScript variable named userName is declared (i.e. it has the word var before it, meaning that it is declared). The next line selects the current text in a Text object named welcomeBox and the last line replaces the selected text with the variables value John Smith.
Note:
Variables that are declared in a script are only recognised by the function in which they were created – think of them as a little like a Page variable, outside of its own function a declared OpusScript variable does not exist.
Note:
The most commonly created type of variable is the Publication variable.
Displaying Variables on a Page