HomeSite 4.0 and ColdFusion Studio 4.0 introduce a new level of customizability by exposing an Object Model, enabling developers to manipulate either program from external applications. In addition, power users can now create scripts using JavaScript (JScript) or VBScript and execute them from within the HomeSite and Studio environments, automating custom tasks.
Important: the internal scripting feature requires Microsoft's ActiveScripting engine v3.1 or later, which is not installed by HomeSite or Studio. If you have Microsoft Internet Explorer 4.0 or later on your system, then you already have the correct ActiveScripting engine installed. Otherwise, you'll need to download it from Microsoft.
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.
In order to automate various HomeSite or Studio related 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. Using these three objects, you should be able to write scripts to run your most 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").
Once you've written your script, you'll need to create a custom toolbutton in order to execute it from within the program. To do this, select "Customize" from the "Options" menu and switch to the "Toolbar" page. It's a good idea to create a separate toolbar just for your custom scripts, so click the "Add Toolbar" button to create a new toolbar, giving it a name such as "Custom Scripts." Next, click "Add Custom Button," and select the "Execute an ActiveScript file" option. Then just select the external script file, and give the toolbutton a unique caption or image.
Now that you've created both the custom toolbar and toolbutton, make sure that the toolbar will be displayed by placing a checkmark next to it in the list of available toolbars on the Customization dialog. That's it - you now have a toolbutton that will execute a script file.
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.