User's Guide - Chapter 7: Session Variables
Session Variables
When designing an update, it is often desirable to make parts of it dynamic. For example, the user might input a value on one screen that you’d like to display on the next. Or you might want to display a path on a screen (as the default value in an edit field, perhaps), but the path includes a folder like "My Documents" that is likely to have a different location on each user’s system.
Although you could use regular script variables along with actions to manipulate the screen text at run time, session variables allow you to accomplish the same result in a more direct way: by simply including "placeholders" in your screen text that will automatically be replaced by specific values before the screen is shown.
In this chapter you will learn everything there is to know about session variables in TrueUpdate.
Session variables are designed to handle dynamic data during the update process. Essentially "placeholders" for changeable text, session variables give you an easy way to insert dynamic values into the text that appears on your screens.
They also give you an easy way to compose paths to locations that cannot be known in advance, such as the path to the user’s My Documents folder. For example, you can use a session variable like %MyDocumentsFolder% in a path to be replaced by the appropriate full path at run time.
Like regular variables, session variables allow you to "store" information in them, acting like named "containers" that you can assign values to. The main difference between session variables and the "regular" variables you use in scripts is simply that session variables in a screen’s text are automatically expanded before the screen is shown. This makes them especially useful for displaying dynamic text on screens.
Even though all session variables are functionally identical, there are two distinct categories of session variables that can be used in TrueUpdate: built-in session variables, and custom session variables.
For convenience, TrueUpdate contains a variety of built-in session variables for values that are commonly used in projects. These variables are automatically assigned appropriate values when the TrueUpdate Client application is started.
Most 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 which automatically contains the correct path.
Note: Many of these values are also available in the form of global variables that you can use directly in your scripts, e.g. _WindowsFolder and _ProgramFilesFolder. There are also actions like Shell.GetFolder that you can use to get additional system paths. The built-in session variables are provided primarily for use in paths and default values that are displayed on screens.
Here is the list of built-in session variables, in alphabetical order:
%ApplicationDataFolder%
The path to the Application Data folder on the user's system. This folder serves as a common repository for application-specific data. Typically, this path is something like "C:\Documents and Settings\YourName\Application Data." On Windows Vista or later, it would return something like "C:\Users\YourName\AppData\Roaming."
%ApplicationDataFolderCommon%
The path to the all-user Application Data folder on the user's system. This folder servers as a common repository for application-specific data. Typically this is something like "C:\Documents and Settings\All Users\Application Data." On Windows Vista or later, this returns "C:\ProgramData."
%CommonFilesFolder%
The user’s Common Files folder. Typically, this is something like "C:\Program Files\Common Files."
%CompanyName%
Your company’s name. The value of this variable is set on the Session Variables tab of the Project Settings dialog.
%Copyright%
The copyright message for your product. The value of this variable is set on the Session Variables tab of the Project Settings dialog.
%DAOPath%
The path to the user’s DAO (Data Access Objects) directory.
%DesktopFolder%
The path to the user’s Desktop folder. On Windows NT/2000/X/VistaP, this is the path from the per-user profile.
%DesktopFolderCommon%
The path to the user’s Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %DesktopFolder%.
%FontsFolder%
The path to the user’s font directory (e.g. "C:\Windows\Fonts").
%MyDocumentsFolder%
The user's personal (My Documents) folder on their system. Usually this is something like "C:\Documents and Settings\YourName\My Documents" on Windows 2000/XP and "C:\My Documents" on Windows 98/ME, and "C:\Users\YourName\Documents" on Windows Vista or later.
%ProductName%
The name of the product that you are updating. The value of this variable is set on the Session Variables tab of the Project Settings dialog.
%ProgramFilesFolder%
The user’s Program Files folder (e.g. "C:\Program Files").
%RegOwner%
The name of the registered user of the system.
%RegOrganization%
The organization of the registered user of the system.
%SourceDrive%
The drive that the TrueUpdate Client executable was run from (e.g. "C:" or "D:").
%SourceFolder%
The full path to the folder that the update executable was run from (e.g. "C:\Downloads" or "D:\").
%SourceFilename%
The full path, including the filename, for the current update executable. For example, if the user was running "update.exe" from "C:\Downloads," %SourceFilename% would be expanded to "C:\Downloads\update.exe."
%StartFolder%
The path to the user’s Start menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.
%StartFolderCommon%
The path to the user’s Start menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %StartFolder%.
%StartProgramsFolder%
The path to the Programs folder in the user’s Start menu. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.
%StartProgramsFolderCommon%
The path to the Programs folder in the user’s Start menu. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %StartProgramsFolder%.
%StartupFolder%
The path to the user’s Startup folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.
%StartupFolderCommon%
The path to the user’s Startup folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %StartupFolder%.
%SystemFolder%
The path to the user’s Windows System folder (e.g. "C:\Windows\System").
%SystemDrive%
The drive that the user’s Windows System directory is located on (usually "C:").
%TempFolder%
The path to the user’s Temp folder.
%WindowsFolder%
The path to the user’s Windows folder (e.g. "C:\Windows").
You can define your own session variables to supplement the built-in session variables that are automatically provided in TrueUpdate. The session variables that you define are known as "custom" session variables.
Custom session variables can be used everywhere that built-in session variables can be used; in fact, they are functionally identical. The only difference is that the built-in session variables are automatically created for you in each project, whereas custom session variables don’t exist until you assign a value to them.
Each session variable consists of a name, e.g. "%ProductName%," and a value that you assign to it, e.g. "Widget Master 2.0." When a session variable is expanded at run time, its name is replaced by the value that is currently assigned to it. (For example, "Thank you for using %ProductName%" would become "Thank you for using Widget Master 2.0.")
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 project.
The Session Variables tab provides a convenient location for setting the initial value of session variables at startup. It is primarily used for values that need to be displayed on the client screens and that don’t need to be determined dynamically at run time using actions. In other words, it is where you can specify values that you know in advance and that you want to display on the earliest screens in your project.
You can access the Session Variables tab by choosing Project > Session Variables from the program menu.
All session variables defined on the Session Variables tab are stored in the client data file. This means that any changes to the list of session variables will in turn change the client data file. TrueUpdate handles changes to the client data file automatically--in fact, a copy of the latest client data file is stored at each TrueUpdate Server location so the TrueUpdate Client applications can make sure they are always using the latest version. In order for a TrueUpdate Client to update its data file, however, it needs to restart itself. If you foresee needing to change the values of these session variables often, you should consider whether they could be defined in your Server Script using actions instead. Since changes to the Server Script aren’t stored in the client data file, they don’t cause the TrueUpdate Client application to restart.
Tip: Generally, session variables that aren’t displayed on the client screens should be created from your Server Script so they can be changed without affecting the client data file.
The Session Variables dialog contains two categories: Product Information and Custom.
The Product Information category contains three built-in session variables for values that are commonly displayed on screens, such as the product name and the name of the company that produced it. To set the value of one of these variables, simply edit the appropriate field in the right-hand column.
The Custom category is where you can add, remove and edit your own session variables to supplement the ones in the Product Information category. To add a custom session variable, click on the Add button at the bottom of the dialog.
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. It allows you to set the value of an existing session variable that was defined on the Session Variables tab, or to create a brand new one.
The SessionVar.Set action can be used with any event (i.e. in any script) 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, including built-in session variables like %MyDocumentsFolder%. 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 remove a session variable from your project, TrueUpdate 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 in 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 update 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.
The main use of session variables is for the dynamic expansion of text strings on screens. 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 where 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 on one screen that needs to be displayed on another screen. In this case, the values are not known until some point during the update, and therefore could not be directly entered at design time.
Tip: Session variables can also be useful in multilingual updates for custom messages that you wish to display depending on the language detected or chosen.
Session variables are automatically expanded before each screen is shown--specifically, before each screen’s On Preload event. Any session variable that is used on a screen will automatically display the value it contained before that screen was shown.
This means that if you change the value of a session variable in a screen’s On Preload event, in most cases the old value will still appear. There are a few exceptions, such as some static text controls which will automatically be "refreshed" after the On Preload event and will therefore display their new values. As a general rule, however, the On Preload event is already "too late" for any changes to a session variable to be made if you want the new value to automatically appear on the screen.
One way to get the current value from a session variable is to expand it "manually" using the SessionVar.Expand action. SessionVar.Expand allows you to retrieve the current value of a session variable at any point in your project. In fact, you can use SessionVar.Expand on a screen’s On Preload event to retrieve a session variable’s value, and then use actions to replace the screen text with new text that includes the current value.
Session variables are often used on screens that gather information from the user. For example, the Edit Fields screen stores the user’s input in separate session variables--one session variable for each edit field on the screen. This is fine if you simply want to display the user’s input on another screen; in that case, all you need to do is include the appropriate session variables in that other screen’s text. If you want to use the inputted values in your scripts, however, you need a way to expand the session variables in your script. This can easily be accomplished using the SessionVar.Expand action.
The function prototype for this action is:
string SessionVar.Expand(string Text);
Basically, the SessionVar.Expand action takes a string of text and gives you back the same text, but with all of the session variables in the string expanded. In other words, it returns a copy of the text in which all of the session variables have been replaced by their current values.
For example, if a session variable called %MyName% contains the string "They call me nobody," you can access the string using the following action script:
strContents = SessionVar.Expand("%MyName%");
In the above line of script, the variable strContents would receive an expanded version of "%MyName%." The end result is that the value stored in %MyName% ("They call me nobody") would be assigned to strContents.
However, SessionVar.Expand isn’t limited to retrieving the contents of a single session variable. It will happily expand a string containing several session variables--or even one containing no session variables at all. (In the latter case, the string it returns will be an exact copy of the original string.)
For example, using SessionVar.Expand on the string "When asked for his name, all he said was: %MyName%" would return the entire string with the expanded contents of the session variable %MyName%:
When asked for his name, all he said was: They call me Nobody
In addition, when the SessionVar.Expand action expands a string, it performs a recursive expansion. Session variables within session variables are expanded as well. This means that if the value in a session variable is a string that has a session variable in it, the "internal" session variable will also be expanded. You can think of the expansion as being a "loop" that continues until there are no more session variables left to expand.
For example, consider the following two session variables:
%verb% - whose value is "flying"
%message% - whose value is "Look at me, I’m %verb%!"
After the following action script is executed:
strContents = SessionVar.Expand("%message%");
…the contents of the variable strContents would be:
Look at me, I’m flying!
As you can see, %message% was replaced by "Look at me, I’m %verb%!" and then %verb% was replaced by "flying."
TrueUpdate 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 is:
string SessionVar.Get(string Text);
Using the previous example, let’s say we only wanted to expand the contents of %message%, without expanding %verb%. In that case, the following action script could be used:
strContents = SessionVar.Get("%message%");
…and the contents of the variable strContents would be:
Look at me, I’m %verb%!
As you can see, the SessionVar.Get action would expand the %message% session variable, but wouldn’t go any further; the %verb% variable would remain unexpanded.
Session variables are automatically expanded before each screen is shown. This automatic expansion happens before any of the screen’s events are triggered--even before the earliest screen event, On Preload. This means that if you use the SessionVar.Set action to change the value of a session variable from On Preload, the new value will not appear on the screen, because at that point the session variables have already been expanded. (There are exceptions to this rule, such as the static text controls on some screens, but it is safer to assume that it is true in all cases.)
In order to change the text on a screen from within that screen’s events, you must use a different method. Luckily, there are two ways in which you can expand session variables on the current screen.
The first and most straightforward method is to formulate a new text string with the session variable in it, expand that string using SessionVar.Expand, and then assign the expanded string to the desired screen control.
For example, the following script would expand a string that contains two session variables and then replace the text on a scrolling text screen with the new text:
NewText = SessionVar.Expand("First: %FirstName%\r\nLast:
%LastName%");
DlgScrollingText.SetProperties(CTRL_SCROLLTEXT_BODY, {Text=NewText});
Although this method works well, it requires you to write and edit the text within your script, instead of composing the text directly on the Settings tab for that screen. This isn’t too difficult if your project only supports one language. However, if you’re creating a multilingual project, you’ll need to use control structures to assign different text to the screen that is appropriate for the user’s system language. This would make your scripts much longer and more difficult to maintain.
An alternative method is to use an action to retrieve the original text for the screen, which still contains the session variables in their unexpanded form. This allows your script to essentially "re-expand" the text that you entered on the Settings tab.
Here is a version of the previous script that uses the Screen.GetLocalizedString action to retrieve the original unexpanded text for the scrolling text control:
OriginalText = Screen.GetLocalizedString(IDS_CTRL_SCROLLTEXT_BODY);
NewText = SessionVar.Expand(OriginalText);
DlgScrollingText.SetProperties(CTRL_SCROLLTEXT_BODY, {Text=NewText});
The key to this second approach is the Screen.GetLocalizedString action, which retrieves the text for a specific screen control as it was entered on the Settings tab, automatically choosing the appropriate text for the language on the user's system.
When your project supports multiple languages, it is much easier to edit the screen text directly on the Settings tab, where you can use the language selector to switch between all of the languages that your project supports.
Tip: If you would like to see an advanced example of session variables in use, examine some of TrueUpdate’s built-in screens. For example, the Select Drive screen uses actions to set, update, and display the session variable %SpaceAvailable%.