ScriptLoader is an Eclipse Monkey Domain Object Model (DOM) [rationale for while it's called a DOM] that can be used to run other scripts from an Eclipse Monkey script.
Why do you want this? Eclipse Monkey scripts (.em files) are monolithic. They can call out to DOMs, they can access Java code that Eclipse Monkey exposes in it's own plugin classloader, but they can't call out to other JavaScript files. ScriptLoader can.
Bonus feature: break through the Eclipse plugin classloader handcuffs and access Java code from any plugin you want!
With ScriptLoader, you can basically do what you would have ordinarily have to do in a DOM written in Java, with all the overhead that entails; building plugins, publishing update sites, etc. Only, you don't have to do all that crap. You can do it all in JavaScript!
Install ScriptLoader through the Eclipse UpdateMangler. The update site is:
http://muellerware.org/projects/em-sl/update
The Eclipse Monkey install page (see the link to the Dash site below) has a quick walkthrough on using UpdateMangler to install Eclipse Monkey. Given that, you should be able to figure out how to install ScriptLoader.
OK, now some good stuff. Let's write a script. Create a new project to house your Eclipse Monkey scripts if you don't already have one. In that project, create a monkey folder (required for Eclipse Monkey), and underneath that folder create a folder called lib (a ScriptLoader convention). Create a new file in the lib folder named alert.js. Here are the contents:
What we got here is a function that does the same thing the horrific alert() function we use in browsers does; puts up a dialog with a message in it. Thanks to Bjorn/Ward for figuring out this snippet; I'm an eclipse API n00b, would have taken me a while to find this.
So what's going on here. We are creating a function called alert, that takes a parameter called message (should be a string). Calls the big honking method name, passing some interesting goodies. The Packages bit is a Rhino JavaScript 'thing' that allows you to access Java classes from Rhino. (Mozilla Rhino JavaScript is the implementation of JavaScript that Eclipse Monkey uses). window is a global variable that Eclipse Monkey exposes to all it's .em scripts, and these are visible from your ScriptLoader scripts as well. I assume window is the top-level 'window' you are running the script from. The last thing we do, at the bottom of the file, is reference the function. Kinda confusing, but what's going to happen is that you are going to reference this script from an Eclipse Monkey script (.em file) and get something returned when you reference it. What you get is the last value referenced from the JavaScript file. You will always be placing the name of the variable with the value of the object you want from your .em script at the bottom of file. I assume other things would work like object literals, but I haven't tried yet.
Hopefully that wasn't too confusing. Now let's use our script.
In the folder with your Eclipse Monkey macros, in it's monkey directory, create a new file called test_alert.em. Here are the contents of the file:
In this .em file, we are using (required!) Eclipse Monkey meta-data to specify the menu the macro will be available from and the DOM that's required (ScriptLoader). In the actual code, we load our script, using loadProjectFile, which expects the first parameter is the name of a project the script is stored in, and the second parameter is the project-relative name of the script. Change those values as appropriate for your environment (the project you put alert.js in, and it's location in the project). The script is loaded, and the 'result' (the alert function, remember?) is assigned to a variable called alert. The two usages of the name 'alert' are purely coincidental; you could assign it to a different variable name; the name used in the alert.js script is not remembered. Only the object returned matters. Finally, we implement a main() function (again, required by Eclipse Monkey), and use our function to display Hello World. Try it!
Console.js
test_Console.em
Besides the more elaborate code, the new bit here is some ScriptLoader meta-data in the Console.js file, in the line
This meta-data makes the code in the specified bundle available for the script to use.
To use the ScriptLoader DOM, you MUST put a DOM meta-data tag in the .em files where you want to use it. The line is specifically this:
The reason for the full URL there is that it's pointing to an update site. You can actually create the alert or Console samples, and run them without having ScriptLoader installed. Eclipse Monkey will recognize the DOM plugin is not available and use the URL to prime an UpdateMangler session to download it for you.
Referencing the ScriptLoader DOM in your .em file will cause the variable ScriptLoader to become available to your script. It supports two methods:
loadFile(String fileName)
Run the script with the specified file name. You probably want to use an absolute file
name here, otherwise it will be considered relative to whatever the current directory
Eclipse is running in.
loadProjectFile(String projectName, String fileName)
Run the script from the specified project with the specified project-relative file name.
Both functions return the last object referenced in the JavaScript file.
ScriptLoader scripts loaded with the ScriptLoader DOM may include a comment with meta-data in it. The comment should be a /* .. */ style comment, and should be the first thing in the file besides whitespace. The following meta-data tags are supported:
@requires-bundle
The 'word' following this tag is taken to be an eclipse bundle that should be
made visible while the script is running. This tag may be used multiple times to
make multiple bundles visible.
While the ScriptLoader script is running, it has access to the variables currently available in the calling script. I think this means you could use ScriptLoader from a ScriptLoader script, but I haven't tried that yet.
Check the Eclipse error log for errors. The easiest way to do this is to go to
Window /Show View /Other... / PDE Runtime / Error Log
and a view will be added for the Error Log.
If the Error Log shows a message about not finding the JavaScript Context class, you probably need to perform surgery on your org.eclipse.eclipsemonkey plugin per the directions above.
If you have errors in your ScriptLoader scripts, you may need to 'touch' your .em files that are using them to once you get the problems fixed. .em files seem to remember their scope, until you change them. Add and delete a space somewhere, then save.
0.1.5 - 2006/12/10
Fixes as identified by Peter Dolberg; thanks Peter! Add new dependency for org.mozilla.rhino, since rhino was split out from the monkey. Tested with Eclipse Monkey 0.1.8.
0.1.4 - 2006/03/15
Tweakage
0.1.3 - 2006/03/15
Add doc
0.1.2 - 2006/03/15
Tweakage
0.1.1 - 2006/03/15
Tweakage
0.1.0 - 2006/03/15
Initial version