Chapter 5: Session Variables
Session Variables
When designing an installer, it's often desirable to make parts of it dynamic. During the development and maintenance stages, there is usually some information that will need to change, such as your product's version number. Being able to quickly propagate such changes throughout the project can greatly decrease development time and costs. If you can predict such changes ahead of time, you can minimize their impact by using session variables as "placeholders" for the data that is likely to change.
There are also some things that are almost guaranteed to be different from one system to the next, such as the path to the user's My Documents folder, or what drive they installed Windows on. Your installer must be flexible enough to handle all the ways a user can customize a system.
Having a dynamic installation at run time is equally important. For example, if you want to allow the user to choose the destination folder, this means that all files must be dynamically installed to the chosen location.
Session variables are designed to handle such dynamic data during the installation. In this chapter you will learn everything there is to know about session variables in Setup Factory.
In this chapter, you'll learn about:
Built-in and custom session variables
Setting session variables
Adding session variables
Removing session variables
Using session variables on screens
Expanding session variables
Session variables are special named "containers" for values that may change during the installation process. At run time these variables are automatically replaced with the string of text that is assigned to them. These variables are used when displaying dynamic text on screens or within the paths of files you are installing.
Even though all session variables behave the same, there are two categories of session variables that can be used in Setup Factory: built-in session variables, and custom session variables.
For convenience, Setup Factory contains a series of built-in session variables that are commonly used in projects. These variables are automatically expanded every time they're used.
Many of the built-in session variables hold information that has been gathered from the user's system. For example, since the path to the Windows folder can differ between systems, a session variable named %WindowsFolder% is provided, and it automatically contains the correct path. The list of built-in variables is too long to outline here, but some other examples include %ProgramFilesFolder% and %MyDocumentsFolder%.
While many of the built-in variables gather information from the target system, there are other built-in session variables that are available for managing information about the product you are installing. A few examples of these product-related variables are:
%ProductName% - The name of the product you are installing.
%CompanyName% - The name of the company that developed the product.
%ProductVer% - The version of the product you are installing.
%AppFolder% - The default directory that the product will be installed to.
Since the built-in session variables were designed to be generic, there may be situations where the available built-in session variables do not accomplish all of your design needs. For these occasions, you can still take advantage of session variable technology by defining custom session variables in your install. These can be named anything you wish and can contain any textual data you require.
Each session variable consists of a name, e.g. "%NickName%," and a value that you assign to it, e.g. "Pookie." When a session variable is expanded at run time, its name is replaced by the value that is currently assigned to it. (For example, "I love you, %NickName%" would become "I love you, Pookie.")
There are two ways you can assign a value to a session variable: you can set its initial value on the Session Variables tab, or you can use an action to set its value anywhere in your installation.
Generally the Session Variables tab is used for setting the initial value of session variables at startup and for values that won't be changing at run time using actions.
The Session Variables tab can be found on the Project Settings dialog. To display this tab, choose Project > Session Variables from the program menu. An image of this dialog can be seen below:
As seen in the image above, the Session Variables dialog contains three categories: Product Information, Folder Defaults, and Custom.
The Product Information category contains a series of built-in session variables whose values can be set. They consist of informational values that pertain to the product you are installing. To set the value of one of these variables, click on the value in the right-hand column that is beside the session variable whose value you want to set. The session variable will become highlighted and the cursor will flash in the variable's value field. This means it is ready for editing. Once you have finished editing its value, you can press the Enter key, or click on the next variable you wish to edit.
The Folder Defaults category contains two built-in variables that are used as defaults, both relating to the files you are installing. For example, the variable %AppFolder% contains the default path that will be used as the destination for your files (if they are being installed to that location).
The Custom category contains any custom session variables that have been created. Variables of this type will appear in the same way as variables in the other two categories.
Tip: As the session variable list grows, it may help to hide portions of the list. Each category can be expanded or collapsed by clicking the "+" icon on the left hand side of the category text.
An action is also available to set the value of a session variable. This action is called SessionVar.Set and can be found in the "SessionVar" action category. It allows you to set the value of an existing session variable that was defined on the Session Variables tab, or to create a new one.
The SessionVar.Set action can be used with any event (i.e. on any Actions tab) throughout the project. The function prototype for this action is:
SessionVar.Set(string VariableName, string Value)
For example, if you want to assign the value "My Value" to a session variable named %MyVar%, the action would look like this:
SessionVar.Set("%MyVar%", "My Value");
After the above action is performed, all occurrences of the text %MyVar% on future screens will be replaced with the text "My Value."
Note: The SessionVar.Set action works with all session variables, i.e. both custom and built-in session variables. It is possible to overwrite a built-in session variable's value using the SessionVar.Set action, so be very careful when setting session variables with actions. Under normal circumstances, there should be no reason to modify the values of built-in variables.
When you add a new session variable to your project and assign it a value, it is ready to be used on any screen or file path in your project.
Adding a new session variable to your project means that its name is now a special placeholder for the string that was assigned to it. As with built-in variables, custom session variables can be used on any install screen or within the path of any file in your project's file list.
There are two methods you can use to add custom session variables to your project: using the Session Variables tab, or using an action.
To add a new session variable to your project, choose Project > Session Variables from the program menu. This will display the Session Variables tab on the Project Settings dialog.
When setting a session variable from this tab, its value is available as soon as the install starts and throughout the install. The only difference between a custom session variable and a built-in one is that you can remove custom session variables from the Session Variables tab, but you cannot remove built-in ones.
To add a new session variable to your project, you can also click the Add button. This will display the New Session Variable dialog where you can define its name and assign it a value. When you click the OK button on the dialog, the newly defined session variable will appear in the Custom category of the list.
An action can also be used to create new session variables. As mentioned earlier in the chapter, this action is called SessionVar.Set and can be found in the "SessionVar" action category. This allows you to create a new session variable at any point during the install. The function prototype for this action can be found below:
SessionVar.Set(string VariableName, string Value)
For example, if you want to create a new session variable called %MyVar% and assign it the value "My Value," the action script would look like the following:
SessionVar.Set("%MyVar%", "My Value");
Note: Generally it is good practice to create new session variables on the Session Variables tab rather than using an action. Following these guidelines helps keep track of which variables exist in the install.
When you remove a session variable from your project, Setup Factory will no longer recognize the variable's name as special placeholder text. For example, removing the session variable %ProductName% causes the name to revert back to its actual characters. In other words, the text "%ProductName%" ceases to be anything other than the letters %, P, r, o, d, u, c and so on. After the session variable is "removed," there is no longer a value associated with the name, and no expansion occurs.
There are two methods for removing session variables from your project: using the Session Variables tab, or using actions.
Similar to adding session variables, removal of session variables can also be accomplished from the Session Variables tab. However, only those within the Custom category can be removed from your project. To remove a custom session variable, click on the desired session variable name in the list to highlight it, and then click on the Remove button. The session variable will be removed from the list.
Session variables can also be removed at any point during your install with an action. The action used to remove a session variable is called SessionVar.Remove and can be found in the "SessionVar" action category. The function prototype for this action can be seen below:
SessionVar.Remove(string VariableName)
For example, if you want to remove a session variable called %MyVar%, the action script would look like the following:
SessionVar.Remove("%MyVar%");
Note: Since both custom and built-in session variables behave the same, it is possible to remove a built-in session variable using the SessionVar.Remove action. For this reason, extra care should be taken when removing session variables with actions.
One of the main uses of session variables is for the dynamic expansion of text strings on screens in the install. One example of a valuable use of session variables is when you need to use a value on multiple screens, such as a product version number. While you can certainly enter the text directly for each screen, if that string changes in the future, it would require finding every location it is used in order to change its value. Using a session variable in place of that text would only require the modification of the session variable's value in one location.
Another valuable use of session variables is for gathering data that needs to be displayed on other install screens. In this case, values are often not known until some point during the install, and therefore could not be directly entered at design time.
Tip: Session variables can also be useful in multilingual installs for custom messages that you wish to display depending on the language detected or chosen.
When an installation starts, the session variables that are defined on the Session Variables tab are recognized and ready to be expanded. Any session variable that is used on a screen will automatically be expanded before that screen is shown and before the screen's On Preload event.
If a session variable is set to a different value, it will reflect that change the next time it is used on a screen, or if it is explicitly expanded using the SessionVar.Expand action.
As discussed in earlier sections, session variables are automatically replaced with their contents on screens. However, since these variables are often used to gather information from the user, the resulting values stored in these variables may need to be accessed and worked with in action script. In order to retrieve the contents of a session variable while in action script, the SessionVar.Expand action must be used. The function prototype for this action can be seen below:
string SessionVar.Expand(string Text);
For example, if there is an existing session variable called %MyVar% containing the string "These are the contents of my variable," you can access this string using the following action script:
strContents = SessionVar.Expand("%MyVar%");
In the above line of script, the Lua variable strContents would contain the value within the session variable, "These are the contents of my variable".
However, SessionVar.Expand does not restrict its Text parameter to only a session variable. It can also be used to expand a string that contains a session variable. For example, passing the string "The contents of my variable are: %MyVar%" as the parameter of SessionVar.Expand would return the entire string with the expanded contents of the session variable %MyVar%.
This action not only expands the session variable, but performs a recursive expansion. This means that if the session variable being passed to the action has an assigned value that contains a session variable, that session variable will be expanded as well. This type of recursion can be any number of levels deep. Yes, this sounds confusing, but an example should help:
Given the following two existing session variables:
%Inside% - whose value is "this is the inside string"
%Outside% - whose value is "The value of inside is: %Inside%"
If the following action script was executed:
strContents = SessionVar.Expand("%Outside%");
The contents of the Lua variable "strContent" would be:
"The value of inside is: this is the inside string"
Setup Factory also contains an action that will prevent the recursive expansion of session variables. This action is called SessionVar.Get and can also be found in the "SessionVar" actions category. The function prototype can be seen below:
string SessionVar.Get(string Text);
Using the previous example, let's say we only wanted the expanded contents of %Outside%, without expanding %Inside%. In that case, the following action script could be executed:
strContents SessionVar.Get("%Outside%");
and the contents of the Lua variable strContents would be:
"The value of inside is: %Inside%"
Tip: If you would like to see an advanced example of session variables in use, examine some of Setup Factory's built-in screens. For example, the Select Install Folder screen uses actions to set, update, and display a pair of session variables named %SpaceAvailable% and %SpaceRequired%.