Scripting the Visual Tools Object Model
Scripting the Visual Tools Object Model

Writing and Executing Scripts in Allaire Visual Tools

The Allaire visual tools -- HomeSite, ColdFusion Studio, and JRun Studio -- expose an Object Model, enabling developers to manipulate program functionality from external applications. In addition, power users can create scripts using JScript or VBScript and execute them from within the visual tools environments to automate tasks.

The internal scripting feature requires Microsoft's ActiveScripting engine v3.1 or later, also known as Windows Script. The engine is not installed with the Allaire visual tools. If you have Microsoft Internet Explorer 4.0 or later on your system, then you have the correct ActiveScripting engine installed. Otherwise, you need to download it from http://www.microsoft.com/msdownload/vbscript/scripting.asp.

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. 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, then the VBScript engine is used to execute the script. Otherwise, it is assumed that the file contains JScript source.

To automate visual tools tasks, you will need to familiarize yourself with the Visual Tools Object Model. 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 to write scripts for common tasks.

In addition, the Application object contains a number of toolbar-related functions, enabling 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, using JScript:

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

}

or VBScript:

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

Executing scripts

Once you have written a script, you can create a custom toolbutton to execute it from within the program. If you intend to write multiple scripts, you will want to create a toolbar for them.

To create a toolbar for custom scripts:

1. Select the Options > Customize menu item.
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.

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.

You can rearrange the buttons and add separators as needed.

In the of Keyboard Shortcuts tab of the Customization dialog, you will find a shortcut (Shift + Ctrl + Q) for the Execute current document as ActiveScript command. Executing this command passes the current document to the ActiveScripting engine, turning the program into a powerful tool for debugging your scripts. As with toolbutton-based scripts, the scripting language is determined by the file extension of the current document.

Copyright © 2000, Allaire Corporation. All rights reserved.