Rename Scripts

This is by far the most powerful, but also most complicated, feature of the Advanced Rename dialog. Using VBScript, JScript or other ActiveX scripting languages, you can write a rename function that gives you complete control over the outcome of the rename operation.

Here's an extremely simple example (we're keeping it simple for two reasons; one, this document is not about to try to teach you how to write VBScript, and two, the screen shot would be too big!) of a scripted rename. You can see the Script mode option has been turned on, which revealed the script editor. This is pre-populated with a do-nothing VBScript that you can edit, however you could change this to using JScript by editing the @script line at the top and making the appropriate changes to the function definition.

The parameters passed to the Rename_GetNewName function are as follows:

• strFileName is the original name of the file.
• strFilePath is the full path of the file.
• fIsFolder will be True if the item is a folder, or False if it's a file.
• strOldName provides the value that the user entered in the Old name field of the Advanced Rename dialog. In this example, we entered * for both old and new names, which means the filename is passed through unaltered to the script, but we could easily have used the Standard Rename or Regular Expressions wildcard system to perform pre-processing of the filenames.
• strNewName on input, provides the new name that Opus has generated based on the settings of the Rename dialog (which means you can combine the in-built functionality of the Rename dialog with a script that runs after the normal rename options have been processed). Because strNewName is passed by reference, you can also return a value to Opus using this field, and indeed, this is how the script can alter the final name that will be given to the file.

The Rename_GetNewName function is called once for each file selected for renaming. If you don't want to make any changes to the name of a particular file, set strNewName to the value of strFileName, and Opus will silently skip it.

In the above example, we're simply using the VBScript LCase() function to convert the new name to lower case, but your script can do just about anything it wants to produce the new name.

There is an alternative interface, Rename_GetNewName2,  which is provided for scripting languages that don't support "by-reference" variables. The only difference is that strNewName is not passed by-reference, and you use the return value of the function to specify the new name. The above example using Rename_GetNewName2 would look something like this:

Function Rename_GetNewName2 ( strFileName, strFilePath, fIsFolder, strOldName, strNewName )
        Rename_GetNewName2 = LCase(strNewName)
End Function

Any error messages or other text output from a script can be viewed in the Other Logs log window, which is accessed from the Utility Panel (or the Logs / Other Logs command in the Help menu). If you find a script isn't behaving as expected, you should check this log to see if any error messages are being generated. You can also output your own text to this log using the DOpus.OutputString script method, which can help with debugging.

The default File Operations toolbar has a Number Files script provided in the Rename drop-down menu, which is implemented using VBScript, so please feel free to examine this for a more complex example. This also provides an example of embedding a script directly in a button. Finally, please see the Rename Scripting section on the Opus Resource Centre for example rename scripts you can download and use, and feel free to ask on the forum for help with writing rename scripts.