IDM PowerTips
Integrated scripting engine tutorial
Scripting in UltraEdit is enabled through embedding of the JavaScript engine, this allows users to enjoy the power and flexibility of the JavaScript language while using the UltraEdit Application Object commands to interact with the editor – or documents open in the editor (Document Object commands).
The scripting engine supports the core functionality of JavaScript 1.7. Further information on JavaScript 1.7 may be found on the associated Mozilla site.
Using the Integrated Scripting Engine
Step 1: Create the Script
Create your (JavaScript) script using UltraEdit. As mentioned above, you may use JavaScript 1.7 and the UltraEdit Application Object commands and Document Object Commands.
There is extensive information in the Help regarding the commands available, however we have a few sample scripts below.
There is extensive information in the Help regarding the commands available, however we have a few sample scripts below.
Step 2: Add the Script
Once you’ve created (and saved) your script you will need to add it in the Scripting : Scripts dialog.
Click on the “Add” button to add the script to the list. You will need to browse to the location of the script and, if you would like, type a description of the script. The description will display in the Description field in the scripting dialog.
Once the script has been added, you can define a Hotkey/Chord for a quick and easy execution of the script.
When you are done, you may click OK.
Step 3: Execute the Script
To execute the script go to the Scripting menu. You will see your script name at the bottom of the “Scripts” menu. Click on the script name to execute it. You can also use the Hotkey/Chord if you have defined them.
After executing the above script, you should see the following results:
Note: As the scripting does take advantage of the JavaScript language, you may also write this as a function:
Edit and save!
Once you are done editing your file, simply press Ctrl + S or click the Save icon to save it back to the FTP server through Nautilus.
// Hello World Example Script
function hello() {UltraEdit.activeDocument.write("Hello World!")
}
hello();
Example Script – Retrieving String User Input
The scripting support allows you to prompt the user for String or Integer data, capture that data in a variable, then use the variable accordingly. The methods used to retrieve the data are “UltraEdit.getValue” and “UltraEdit.getString”.
Prompt for String Input
To prompt for String input use the “UltraEdit.getString” command. An example of prompting for input and capturing the input as a variable is as follows:
var str = UltraEdit.getString(“Please Enter a String:”,1);
Capture Input:
In order to capture the data, and NOT write it immediately to the document, you must use the ‘1’ parameter in the getString method.
Write Input:
If you would like to write the user input immediately to the file use ‘0’ as the parameter value.
Sample Capture String Input Script
The example below prompts the user for a String and captures it in the variable “str”. It will then write “You Entered user input (str)” to the active document. It will write a different response depending on whether “UltraEdit” or “UEStudio” was entered.
If you would like, you may copy the script below and expand upon it.
//Get user input
var str = UltraEdit.getString("Please Enter a String:",1);
//Output what was entered
UltraEdit.activeDocument.write("You Entered " + str + "\r\n");
//Conditional responses
if (str == "UltraEdit") {
UltraEdit.activeDocument.write(str + " has an integrated scripting engine.\r\n");
UltraEdit.activeDocument.write(str + " is a very powerful editor.\r\n");
UltraEdit.activeDocument.write("\r\n");
} else if (str == "UEStudio") {
UltraEdit.activeDocument.write(str + " also has integrated scripting\r\n");
UltraEdit.activeDocument.write(str + " includes all the functionality of UltraEdit and more.\r\n");
UltraEdit.activeDocument.write("\r\n");
} else {
UltraEdit.activeDocument.write("Sorry, there is no defined output for " + str + "\r\n");
UltraEdit.activeDocument.write("\r\n");
}
} //end strInput
strInput();
Note: The command used to write to the active document is “UltraEdit.activeDocument.write”
The results after entering “Data”, “UltraEdit“, and “UEStudio” is as follows
Example Script – Retrieving Integer User Input
Prompt for Integer Input
To prompt for Integer input use the “UltraEdit.getValue” command. An example of prompting for integer input and capturing the input as a variable is as follows:
var num = UltraEdit.getValue(“Please enter an integer”,1);
Capture Input:
In order to capture the data, and NOT write it immediately to the document, you must use the ‘1’ parameter in the getValue method.
Write Input:
If you would like to write the user input immediately to the file use ‘0’ as the parameter value.
Sample Capture Integer Input Script
The example below prompts the user for an integer value and captures it in the variable “num”. It will write “You Entered user input (str)” to the active document. It will then enter a loop in which it will write “i” number of lines, and number each line.
If you would like, you may copy the script below and expand upon it.
//Get user input
var num = UltraEdit.getValue("How Many Lines:",1);
//Output what was entered
UltraEdit.activeDocument.write("You Entered " + num + "\r\n\r\n");
//Loop
var i = 1;
while (i <= num) {
UltraEdit.activeDocument.write(i + " \r\n");
i = ++i;
}
} //end strInput
intInput();
Note: The command used to write to the active document is “UltraEdit.activeDocument.write”
The result after entering “5” is as follows:
Example Script – Enumerate Through All Open Files
Using the Document Object commands, you may access/reference the files that currently open in the editor. If you would like to perform an action/run a script against all open files you would need to retrieve the number of open files, and then loop through each file.
As an example, if you need to find out how many files are open in the editor, you could use the following:
var num_of_docs = UltraEdit.document.length;
If you need to reference a specific file, based on what it was opened, you can do so using UltraEdit.document[x]; where x is the number of the document.
Sample Enumerate Through All Open Files
The script below will Enumerate through each open file and write a simple header to each file.
If you would like, you may copy the script below and expand upon it.
// put a header comment at the top of a javascript file to be used in UltraEdit
// in order to indicate the version of the UltraEdit scripting API like so:
// Version = 1.00
// However, this is currently not necessary since the API will default to 1.00.
// ----------------------------------------------------------------------------
// header.js
// This script creates a header for all open documents
// ----------------------------------------------------------------------------
// UltraEdit is our application object. All UltraEdit operations will use this
// object.
// Get the num of open documents.
var num_of_docs = UltraEdit.document.length;
var dashes = "// ------------------------------------------------------------";
dashes += "----------------\r\n";
// Enumerate through all open documents and add the header.
var index;
for (index = 0; index < num_of_docs; index++) {
UltraEdit.document[index].top();
UltraEdit.document[index].write(dashes);
UltraEdit.document[index].write("// Script Name: \r\n");
UltraEdit.document[index].write("// Creation Date: \r\n");
UltraEdit.document[index].write("// Last Modified: \r\n");
UltraEdit.document[index].write("// Copyright (c)20XX\r\n");
UltraEdit.document[index].write("// Purpose: \r\n");
UltraEdit.document[index].write(dashes);
} //end for loop
After running the above script, every open file now has the following header:
Enjoy the power of the integrated scripting engine!