Writing and Executing Scripts in Visual Tools

The Visual Tools expose an Object Model, enabling developers to manipulate program functionality from external applications. In addition, power users can create scripts to automate tasks using JScript or VBScript and run the scripts from the Visual Tools environments.

The Visual Tools internal scripting feature requires the Microsoft ActiveScripting engine version 3.1 or later, also known as Windows Script. The engine is not installed with the Visual Tools. If you installed Microsoft Internet Explorer 4.0 or later on your computer, then you have the correct ActiveScripting engine. Otherwise, you need to download it from http://www.microsoft.com/msdownload/vbscript/scripting.asp.

The VTOM hierarchy

The object hierarchy is very simple; the Application object is the parent of all the other objects and none of the other objects is a parent.

The VTOM hierarchy can be illustrated as follows:

Application

ActiveDocument

DocumentCache

Project

ProjectManager

DeploymentManager

HTTPProvider

ZIPProvider

Notation

The simplicity of the object model makes syntax notation very straightforward. To call a property or method, begin at the object root, append the child object name (if any), the property or method name, separated by a period, and then the parameters.

For example,

Application.ActiveDocument.SaveAs(CurrentFolder + '\\' + sFile);

Writing scripts

For a script to be executable from within the Visual Tools, it must contain a Main routine. In JScript, create a function Main; in VBScript, create a Sub Main routine. Without this routine, the script fails.

The program determines which language engine to use based on the extension of the script file. If the file extension is BAS, VB, or VBS, the VBScript engine executes the script. Otherwise, the program uses the JScript engine.

To automate Visual Tools tasks, you must familiarize yourself with the Visual Tools Object Model (VTOM). The main object is the Application object. The Application object contains two important child objects, the ActiveDocument object and the DocumentCache object. You can use these objects to write scripts for common tasks.

In addition, the Application object contains a number of toolbar-related functions, which enable you to create toolbars dynamically.

For best performance, you should create an Application object variable and use it throughout the script rather than continually referencing the Application object directly.

For example, the following code creates an Application object variable in JScript:

function Main() {        
        var app = Application; //create application object variable 
        app.WindowState = 2; //maximize the window

The following code creates an Application object variable in VBScript:

Sub Main        
  Dim app
  set app = Application 'create application object variable 
  app.WindowState = 2 'maximize the window
End Sub      

The Application object is only available from scripts that are executed within the Visual Tools.

To access the Application object from an external program, use the language's equivalent of CreateObject("AllaireClientApp.TAllaireClientApp").


Note

When writing and editing VTOM scripts and when porting code from VBScript, remember that JScript is case-sensitive.


Executing scripts

If the scripting engine encounters an error while executing your custom script, the script file opens in the editor with the error line highlighted. In addition, information about the error displays in the status bar, which helps you debug the problem.

In the Customization dialog box, theKeyboard Shortcuts tab includes a shortcut (Shift + Ctrl + Q) for the Execute current document as ActiveScript command.You can use this command to pass the current document to the ActiveScripting engine, which provides you with a tool for debugging your scripts. As with toolbutton-based scripts, the scripting language is determined by the file extension of the current document.

Creating a custom toolbutton and toolbar

After you write a script, you can create a custom toolbutton to execute the script from within the program. If you intend to write multiple scripts, you can create a toolbar for them. You can rearrange the buttons and add separators in the toolbar.

To create a custom toolbutton:

  1. On the Toolbars tab, select your custom script toolbar from the Toolbars list.

    The toolbar displays at the top of the tab.

  2. Click Add Custom Button.
  3. In the Custom Toolbutton dialog box, select the Execute an ActiveScript file option.
  4. Enter a path and file name in the Script File box.
  5. Make selections in the Button Image, Button Caption, and Button Hint boxes.

    You can optionally create script hot keys on the Script Shortcuts tab and then click the Show keyboard shortcuts in toolbutton hints box on the Toolbars tab.

  6. Click OK.

To create a toolbar for custom scripts:

  1. Select Options > Customize from the menu.
  2. Click the Add Toolbar button on the Toolbars tab.
  3. Enter a name for the toolbar and click OK.
  4. On the Toolbars tab, select the check box on the Toolbars list to display the new toolbar in the workspace.

Comments