User's Guide - Chapter 4: Introduction to Scripting
Scripting is the art of creating and modifying a sequence of actions that work together to perform a specific task.
Actions are among the most important features in TrueUpdate. They are what you use to control the functionality of your update, with virtually limitless possibilities. Each action is a specific command that tells your TrueUpdate Client to do something, such as downloading a file, showing a screen, or modifying the Registry.
Actions also allow your update to react to different situations in different ways. Does the user have your software installed? Is an Internet connection available? You can use actions to answer these types of questions and have your TrueUpdate Client respond accordingly.
In this chapter, we’ll introduce you to the basics of scripting in TrueUpdate.
A script is a sequence of actions that work together to perform a specific task. It can include a single action, or any number of actions. The simplest scripts comprise a basic series of steps, with one action following another in a direct and straightforward manner. More advanced scripts take advantage of control structures like "if" and "while" to incorporate sophisticated techniques such as decision-making, branching and looping.
Scripts are ultimately just text documents that follow a specific syntax. The actions and control structures in a script are represented by specific keywords, which the TrueUpdate Client ultimately interprets as instructions that tell it what to do.
Note: Scripts are a key component of TrueUpdate. For example, the entire client-server interaction is defined by the script that is entered on the Client Script and Server Script tabs.
Actions are what you use in TrueUpdate when you want to get something done. They are specialized commands that your TrueUpdate Client can perform at run time. Each action is a short text instruction that tells the client to do something--whether it’s to download the server configuration files, show a screen, open a document, or modify a registry key.
Actions are grouped into categories like "File" and "Registry." The category and the name of the command are joined by a period or "dot," like so: File.Run, Registry.GetValue. The text "File.Run" essentially tells TrueUpdate that you want to perform a "Run" command from the "File" category…a.k.a. the "File.Run" action.
Tip: The period in an action name is either pronounced "dot," as in "File-dot-Open," or it isn’t pronounced at all, as in "File Open."
It is worth noting that the many screen types available to you in TrueUpdate actually use actions to accomplish their tasks. In fact, if you want to modify a screen’s built-in functionality, you can do so simply by editing the screen’s actions. Because of TrueUpdate’s scripting engine, the power is in your hands!
The script editor is where you create and edit your scripts in the TrueUpdate design environment. It essentially functions like a text editor, allowing you to type the actions and other scripting elements that you want to use.
However, while it may function like a text editor, the script editor has powerful features that make it a full-fledged programming environment. Some of these features include syntax highlighting, intellisense, quick help and context-sensitive help.
It also has a built-in action wizard, which provides an easy dialog-based way to select, create, and edit actions without having to type a line of script.
In short, the script editor gives you the best of both worlds: pure scripting capabilities for advanced users and programmers, and an easy-to-use action wizard interface for those who’d rather not use free form scripting.
The script editor has two visible interfaces, depending on whether you are adding actions to script tabs or screen events.
The script editor is functionally the same in both places; the only difference is in how you access some of its programming features. The screen event tabs have built-in buttons that allow you to access the most common features of the script editor. The script tabs have no integrated buttons; instead you can access the features via the program menu and toolbars. In both cases, however, you can access the features by using the right-click menu.
The script editor provides many powerful features that make it a useful and accessible tool for programmers and non-programmers alike. Along with the action wizard (covered later under Using the Action Wizard), the four most important features of the script editor are: syntax highlighting, intellisense, quick help, and context-sensitive help.
Syntax highlighting colors text differently depending upon syntax. This allows you to identify script in the script editor as an operator, keyword, or comment with a quick glance.
Note: You can customize the colors used for syntax highlighting via the script editor settings. The script editor settings are accessed on screen event tabs via the advanced button: Advanced > Editor Settings. On script tabs it can be accessed from the program menu by choosing Edit > Advanced > Editor Settings.
Intellisense is a feature of advanced programming environments. It refers to the surrounding script and the position of the cursor at a given moment to provide intelligent, contextual help to the programmer.
Intellisense is a term that has been used with various intended meanings. In TrueUpdate, intellisense manifests itself as two features: autocomplete, and the autocomplete dropdown.
Autocomplete is the editor’s ability to automatically complete keywords for you when you press Tab. As you type the first few letters of a keyword into the script editor, a black tooltip will appear nearby displaying the whole keyword. This is the intellisense feature at work. Whenever you type something that the intellisense recognizes as a keyword, it will display its best guess as to what you are typing in one of those little black tooltips. Whenever one of these tooltips is visible, you can press the Tab key to automatically type the rest of the word.
Another feature of intellisense is the autocomplete dropdown. By pressing Ctrl+Space while your cursor is in the code window, you can make a drop-down list appear containing the names of all the available actions, constants and global variables. Choosing one of the listed items and pressing Tab or Enter will automatically type the item into the script editor for you.
Note: This dropdown cannot be accessed if your cursor is inside a set of quotes (a string).
The autocomplete dropdown is also available for completing action names after the category has been typed. For example, when you type a period after the word File, the intellisense recognizes what you've typed as the beginning of an action name and presents you with a drop-down list of all the actions that begin with "File."
The word will automatically be typed for you if you choose it and then press Tab or Enter. However, you don’t have to make use of the dropdown list; if you prefer, you can continue typing the rest of the action manually.
Once you’ve typed something that the script editor recognizes as the name of an action, quick help is automatically displayed. Quick help is essentially a "blueprint" for the action. It lists the names of the action’s parameters, and indicates what type of value is expected for each one. For example, in the case of a Screen.Jump action, the quick help looks like this:
Screen.Jump(string ScreenName)
This quick help indicates that the Screen.Jump action takes a single parameter called ScreenName, and that this parameter needs to be a string. Strings need to be quoted, so if you wanted to jump to a screen named Finish, the full action would have to be typed exactly like this:
Screen.Jump("Finish");
On screen events, the quick help is located towards the bottom of the properties window. When you’re working on script tabs, it can be found on the status bar at the bottom of the program window, or on the optional Script Help toolbar. (You can enable the Script Help toolbar by choosing View > Toolbars > Script Help.)
Context sensitive help, as its name suggests, provides help for you based upon what you are currently doing. In the script editor, the context sensitive help lets you jump directly to the current action’s topic in the help file.
For instance, if you are typing an action into the script editor and the quick help feature isn’t giving you enough information (perhaps you would like to see an example), press the F1 key and the help file will open directly to that action’s help topic.
Note: The context sensitive feature is only available when the script editor recognizes the action that the cursor is on. It is easy to know when this is the case; when the script editor recognizes an action, the action’s template appears in the quick help.
The Client Script tab is a script editor located on the main development window. It contains the script that runs as soon as the TrueUpdate Client application is started. This script is generally referred to as the client script.
Generally the client script should contain any actions needed to initialize and initiate the update process.
A typical client script will introduce the user to the update and then download the server configuration files. In fact, the main function of the client script is to download and run the server script, which is contained in the server configuration files.
Tip: While you’re working on the script tabs, you can access all of the script editor features under the Edit and Script program menus.
The Server Script tab is another script editor located on the main development window. It contains the script that is hosted at the TrueUpdate Server locations. This script is generally referred to as a server script.
The purpose of a server script is to determine whether an update is available, and to actually perform the update--either by running a series of actions, or by launching a separate installer or patch file.
TrueUpdate actually supports multiple server scripts, each represented by a separate tab on the program window. Every project begins with a single "main" server script, represented by the Server Script tab.
For larger projects, you may want to divide your actions into multiple server scripts in order to make the project easier to maintain. TrueUpdate allows you to add as many additional server scripts as you need in order to facilitate organizing your code.
The server scripts that you add are treated just like the main server script. In fact, the contents of all the server scripts are stored in the same server configuration file, and they are all downloaded together by the TrueUpdate.GetServerFile action. Just as you would run the main server script, you can run any individual server script using the TrueUpdate.RunScript action.
Tip: Use multiple server scripts to implement "branching" in different situations. For example, if your TrueUpdate Client needs to perform different steps in order to update different versions of your software, you could create a separate server script for each version, and then use the TrueUpdate.RunScript action to call the appropriate script tab from your main server script once the installed version is detected.
The server scripts are stored together in one of the server configuration files, which is downloaded by an action in the client script. Because they are downloaded each time your TrueUpdate Client connects to a TrueUpdate Server, you are free to modify the server scripts at any time--even after the TrueUpdate Client has been distributed.
This separation between the client and the server scripts is an important feature of TrueUpdate. It allows you to adjust the update process for your software at any time, without any modifications to the client at all. In other words, it allows you to modify your update process without having to redistribute new clients to your users.
Note: The server scripts are normally what you will modify each time a new version of your software is released (or whenever you need to update your software).
Every screen has a number of events associated with it. These events are "triggered" when something happens to the screen. For example, every screen has an On Preload event that is triggered just before the screen is displayed.
For every event that a screen supports, there is a separate tab on the screen’s properties dialog. Each tab contains a script editor, where you can edit the script that will be executed when the corresponding event occurs.
When you add an action to a screen’s event tab, you are in effect adding the action to that event. At run time, when the event is triggered, all of the actions on the event tab are performed in sequence from top to bottom. In other words, TrueUpdate "runs through" the script for that event. This happens each time the event is triggered.
For example, to make something happen immediately before a screen is displayed, you would add an action to the screen’s On Preload event. To make something happen when a screen’s Next button is clicked, you would add an action to the screen’s On Next event.
Screen events are triggered either by the controls on the screen or by the screen itself. They can be used for navigation (e.g. moving to the next screen), to change what is displayed on the screen (e.g. updating progress text), or to perform the task required of the screen (e.g. downloading a file).
Note: A control is an "object" on a screen that serves a specific purpose, such as receiving mouse clicks, displaying text, or providing a checkbox. Most screens contain several controls. You can think of the controls as the different screen "parts" that allow the screen to do what it does. For more information on controls and which controls exist on the various screen types, please consult the help file.
The action wizard is a dialog-based way for you to add actions in the script editor. It is designed to guide you through the process of selecting your action and configuring its parameters.
Tip: Even if you prefer typing actions directly into the script editor, don’t disregard the usefulness of the action wizard. It is an excellent way to add an action when you aren’t familiar with its parameters and the range of values it accepts.
While in a script editor, you can launch the action wizard by pressing Ctrl+W, or by right-clicking and choosing Action Wizard from the context menu.
Note: The action will be added at the current location of the cursor, so take care where you click or right-click before launching the action wizard.
Here is a brief example that shows how easy it is to add an action. It illustrates how to display a popup dialog with a message on it by adding a Dialog.Message action to the Client Script tab.
To start a new project, either start TrueUpdate and click "Create a new project" on the welcome dialog, or choose File > New Project from the program menu. When the project wizard appears, click Cancel to skip the wizard and go straight to the design environment.
Note: Normally you will want to use the project wizard in order to base your project on a completed structure; however for this example it is easier to start with an almost blank project.
Make sure you have the Client Script tab selected and not the Server Script tab. (You can select the Client Script tab by clicking on it.)
Before we continue, let’s disable the default client script’s Screen.Show action so it won’t interfere with this example.
Any line in a script that begins with two dashes is treated as a comment. Comments aren’t executed; they are typically used to add helpful notes and explanations to your code. For example, you’ll notice that the first four lines of the Client Script already have comments describing what the Client Script does.
When you add two dashes to the start of the line that has the Screen.Show action on it, the line turns green, the default color for comments in the script editor. Adding the two dashes turned the line into a comment. This effectively causes TrueUpdate to ignore that line completely.
You can add two dashes to the start of any line of code to "turn it off" temporarily. Turning a line of code into a comment is known as "commenting out" the code.
Tip: You can "uncomment" a line that is currently commented out by simply deleting the two dashes. Removing the dashes reverts the line to its former "active" status; it is no longer a comment.
For the purposes of this example, we don’t want the client script to display any screens; instead, we will be displaying a message in a popup dialog.
The action wizard will walk you through the process of adding an action to the client script. The first step is to choose a category using the drop-down list.
When you choose the Dialog category from the drop-down list, all of the actions in that category will appear in the list below.
To select an action from the list, just click on it. When you select an action in the list, a short description appears in the area below the list. In this description, the name of the action will appear in blue. You can click on this blue text to get more information about the action from the help file.
Parameters are just values that get "passed" to an action. They tell the action what to do. For instance, in the case of our Dialog.Message action, the action needs to know what the dialog’s window title and message should be. You provide this information to the action in its first two parameters.
The first parameter lets you specify the title of the dialog. This it the text that will appear in the dialog window’s title bar.
The second parameter lets you specify the message that will be displayed on the dialog itself.
For now the other parameters are not important, but you should take some time to look at them and their options. (TrueUpdate will automatically fill the other parameters with appropriate default values.)
For now, change the title to:
"TrueUpdate"
and the text to:
"Message from Chapter 4!"
Note: Be sure to include the quotes on either side of both parameters. These are string parameters and the quotes are needed for TrueUpdate to properly interpret them.
Once you’ve set the action’s parameters, click the Finish button to close the action wizard. The Dialog.Message action will appear on the Client Script tab.
Note that the parameters you provided are listed between parentheses after the action’s name. The parameters are in the same order as they appeared in the action wizard, separated by commas.
Start the publish wizard by choosing Publish > Build from the program menu. The default settings should suffice, so click the Next button to show the list of upload locations (which can be ignored for this example) and then click the Build button to start the build process.
Once the build has completed successfully, make sure the "Open output folder" checkbox is selected, and click the Finish button.
Once the output folder appears, double-click on the client executable to launch it.
You should see a dialog message box.
This popup "message box" is the result of the Dialog.Message action.
Click OK to close the message box and allow the TrueUpdate Client to exit.
There are two ways that you can modify an existing action: you can either edit the action’s text directly in the script editor, just like you would edit text in a word processor; or you can use the Action Properties dialog.
The Action Properties dialog is similar to the action wizard, but instead of walking you through choosing a category, it takes you straight to the part where you modify the action’s parameters.
The easiest way to bring up the Action Properties dialog is by double-clicking on the action. Or, if you prefer, you can place the cursor within the action and either press Ctrl+E, or right-click and choose Edit Action from the context menu.
Tip: You can tell that the cursor is within an action when the action’s function prototype appears in the quick help.
Here is a quick example illustrating how to edit the Dialog.Message action that we created in the previous section.
First, make sure the Client Script tab is selected. You should see the Dialog.Message action created in the previous topic.
To edit the action, just double-click it. Double-clicking on the action opens the Action Properties dialog, where you can modify the action’s current parameters.
To change the Type parameter, first click on the parameter field, then click the select button at the right edge of the parameter field and choose MB_OKCANCEL from the drop-down list.
For the Icon parameter, click the parameter field, click the select button, and choose MB_ICONNONE from the drop-down list.
These changes will add a cancel button to the dialog (MB_OKCANCEL) and get rid of the icon (MB_ICONNONE).
Finally, click OK to finish editing the action. Notice that the changes you made now appear in the script editor.
When you run the TrueUpdate Client, a dialog will pop up. This dialog is created by the Dialog.Message action on the Client Script tab.
Notice that there is no longer an "information" icon on the dialog, and there is now a Cancel button next to the OK button. This is a direct result of the changes that you made to the action’s parameters.
You can get help on actions in a variety of different ways in TrueUpdate. For example, when you’re using the action wizard, text is displayed at the bottom of the dialog describing the current action or parameter that you have selected. Additionally, quick access to the help file is provided in the form of a blue text link that you can click on to receive context sensitive help for the action.
In the script editor, the current action’s function prototype is displayed in the quick help field--either on the Script Help toolbar, in the status bar, or directly on a screen’s event tab. In the case of the Script Help toolbar and the event tabs, there is even a help button next to the quick help field that will open the help file directly to that action’s help topic.
You can press the F1 key at any time while working in the script editor to open the TrueUpdate help file. The help file is especially useful when you’re working with actions. It contains a wealth of information on each action, including an overview topic with detailed information about each parameter, and a topic providing one or more working examples for that action.
The overview topic for an action will provide you with the function prototype, which serves as a definition of the action showing what (if anything) the action returns, along with the action’s parameters and their types.
A function prototype defines the types of all of the parameters, the type of the return value (if any), and whether or not any of the parameters have default values.
You can click on any part of the function prototype in the help file to learn more about that part and its particular purpose.
An include is any external script that can be "included" in your project. Also known as a script file, an include is simply an external text file that contains a valid TrueUpdate script. By convention, these text files usually have a .lua file extension.
You can add script files to your project on the Includes tab of the Resources dialog, which can be accessed by choosing Project > Includes.
All of the files listed on the Includes tab are stored in the client data file when you build your project. Note that this means adding or removing script files will result in a change to your TrueUpdate Client application.
Script files are very similar to script tabs in TrueUpdate except that instead of the script being kept in the project, it is stored in an external text file.
Note: All of the script editors in TrueUpdate have the ability to export their script to an external file. To save a script from the script editor, simply right-click and choose Advanced > Export from the context menu.
Script files are very useful if you need to share important and complex code between a variety of different projects. By keeping the common code in a single location, your projects will be easier to maintain.
This is more advantageous than simply copying and pasting scripts between projects. Having duplicated script in multiple projects can mean duplicated effort if you want to make changes to the script in all of the projects (e.g. if you discover a bug). For instance, when two projects contain copies of a script, you have to edit both projects in order to make the same changes to both scripts.
Using an external script file gets around this issue, by allowing multiple projects to share the same script. When using an external script file, each project does not contain a copy of the script; rather, each project references the same script. If you find an error or want to change any of the code, you do not have to edit the script in each project; you simply have to edit the script in the external file. Since each project references the same file, you know that the next time you build a project, it will be using the new script.
Using external script files allows you to maintain your script in a single location: the script file. For this reason, it’s a good idea to use includes whenever you want to share scripts between projects.
Plugins are actions that are "added on" to the TrueUpdate program. They are independently developed and distributed and can be integrated into your projects to extend their functionality. You can obtain plugins developed by Indigo Rose as well as those developed by third parties.
Any available plugin can be enabled or disabled in your project on the Plugins tab, which you can access by choosing Project > Plugins.
Note: Only plugins that are installed in the Includes\Plugins folder within the TrueUpdate program directory will be available on the Plugins tab.
To enable a plugin in your project, simply place a check mark in the checkbox next to its name on the Plugins tab. Only plugins that are enabled on the Plugins tab will be available in your project.
Once you have enabled a plugin in your project, all of its actions become available to you in the script editor and action wizard. You can even access the plugin’s help file in the same way that you would access the help for built-in actions.
Note: Since there is some overhead in terms of file size, it is recommended that you only include plugins that are needed by your update. If you do not place a check mark beside a plugin, it will not be included in the TrueUpdate Client and will not take up any extra space.
For information about a particular plugin’s features and how to use them, refer to the plugin’s documentation. You can access a plugin’s documentation from the Plugins dialog by selecting the plugin, clicking the About Plugin button, and then clicking the Plugin Help button on the About Plugin dialog.
Tip: The More Plugins button on the About Plugin dialog is an easy way to see what plugins are currently available on the Indigo Rose website. Clicking this button will take you directly to the TrueUpdate plugins area of the Indigo Rose website.
Now that you’ve been introduced to the basics of scripting, you’ll probably want to learn more about this important feature of TrueUpdate. Fortunately, there are several resources available to you.
Chapter 11 of this user’s guide is a crash course on the scripting language. It covers the basic syntax of the scripting language, and more advanced topics such as looping and functions.
The scripts that are generated by the project wizard are excellent real-world examples for you to follow. They were designed to serve as best-practice examples, and include full comments making them easy to follow despite their sophistication. Try choosing different settings in the project wizard, and see how it changes the script as a result.
When you reach the "Update Method" step of the project wizard, you are given the option to use a single installer/patch file, or a custom method. If you choose the custom option and click Next, you will be presented with a list of project templates to choose from. These project templates also contain excellent real-world examples of scripting. Like the other project wizard scripts, they are also fully commented.
TrueUpdate comes with a number of sample projects that demonstrate very specific update situations. In addition to being good starting points for your own projects, these sample projects contain customized scripts and screens that you will not find in the generic scripts that the project wizard generates.
The sample projects are located in a "Samples" subfolder within the Program Files folder where TrueUpdate was installed.