Writing and Executing Scripts

HomeSite and ColdFusion Studio expose an Object Model, enabling developers to manipulate either program from external applications. In addition, power users can create scripts using JavaScript (JScript) or VBScript and execute them from within the HomeSite and Studio 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 by HomeSite or Studio. If you have Microsoft Internet Explorer 4.0 or later on your system, then you have the correct ActiveScripting engine installed. Otherwise, you'll need to download it from http://www.microsoft.com/msdownload/vbscript/scripting.asp.

Writing Scripts

In order for a script to be executable from within HomeSite or Studio, it must contain a Main routine. For example, if you're using JavaScript, create a function Main, and if you're using VBScript, create a Sub Main. This routine is the one that's called when you execute a script within HomeSite or Studio, so without it the script will fail.

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 JavaScript source.

To automate HomeSite or Studio tasks, you'll 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 JavaScript:

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

}

or VBScript:

Sub Main          
    Dim app
    set app = Application 'create application object variable 
    app.WindowState = 3 'maximize the window
End Sub      
Note The Application object is only available from scripts that are executed within HomeSite or Studio. To access the Application object from an external program, use your language's equivalent of CreateObject("AllaireClientApp.TAllaireClientApp").

Executing Scripts

Once you've written a script, you'll need to create a custom toolbutton to execute it from within the program. If you intend to write multiple scripts, you'll want to create a toolbar for them.

Note 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, click the check box on the Toolbars list to display the new toolbar in the Workspace.
Note 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 Keyboard 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.

Note If the scripting engine encounters an error while executing your custom script, the script file will be opened in the editor and the offending line will be selected. In addition, information about the error will be displayed in the status bar, helping you to debug the problem.

A tip on debugging scripts

In the list of keyboard shortcuts on the Customization dialog box you'll find a command called "Execute current document as ActiveScript." Once a shortcut has been assigned to this command, you can pass the current document to the ActiveScripting engine -- turning the program into a powerful tool for debugging your scripts (provided, of course, that they start with the Main routine). As with toolbutton-based scripts, the scripting language is determined by the file extension of the current document.