Rename Scripting


How would you like to get started with rename scripts?

I was intrigued by some of the new features in DO12 rename scripting, so I threw together a simple example to see how they work. In coding, not being able to see a full working example is often the only hindrance to getting started, so I thought I'd share the result for anyone who might be on the same track. I'll tell you upfront that I'm no Opus rename scripting expert! There are far more complex things you can do with rename scripts.

Some features on this page are specific to DO12 and above.


Please note that this page is not a programming primer. It assumes you have some familiarity with any C-style language such as Java, C# or PHP. If you know JavaScript, so much the better, but you don't need to. I know almost nothing about JavaScript (apart from the intricacies of its crippled regex flavor) but I was able to throw these scripts together in a few minutes just by looking up the functions I needed for case conversion.

Ten minutes to code, six hours to write this page!


Our Goal: Convert File Names to Camel Case

We'll work with a simple example: converting file names to camel case (i.e., from something-like-this to somethingLikeThis). We'll start with a simple version that accepts four kinds of word delimiters in the file names: dashes, underscores, dots and spaces. Then we'll tweak the script so the user can check boxes in the rename interface to enable or disable these delimiters.

This is the end goal:

camel script goal


Simplest Version: No Options

In our first version, we don't give the user any options for the delimiters—we'll convert to camel case whenever we find dashes, underscores, dots and spaces. To convert file names to camel case, we'll use a simple but slightly incorrect strategy:
✱ We'll use the built-in "modify capitalization" option to convert all file names to title case before passing them on to the script. For instance, star-wars will become Star-Wars
✱ We'll write a simple script that takes that title case name and strips dashes, underscores, dots and spaces. Therefore, Star-Wars becomes StarWars

The reason I say this stragegy is slightly incorrect is that starWars would be a correct camel case name, but StarWars isn't (the first letter shouldn't be capitalized). We'll fix this in the expanded version, where we'll give the user the option of whether to capitalize the first letter.

Okay, let's get started. Create three files with these names:

return.of.the.jedi.txt
star_wars.txt
the-empire-strikes-back.txt

Select the files, then click the Rename button on the standard toolbars (or my toolbar, Ren or Shift + F2).

Now to execute the first step of our rename strategy, check the Modify capitalization box and select Capitalize All Words from the pull-down menu.

script rename capitalize


Step two is to strip dashes, underscores, dots and spaces. We'll do this with a script. Next to "No script is defined", click Edit.

script edit


Under script type, make sure JScript is selected. This opens a brand new script. Press Ctrl + L to show the line numbers, or select Edit / Show line numbers. You should see this:

new script


Now delete the comments. At some stage you should read them, because they give you some important properties you can use for your scripts. But it might be easier if you first get the hang of how to write a simple script, and read the docs later. After deleting the comments, you should see this.

empty script


This is the bare minimum for a rename script. OnGetNewName is the name expected by Opus for the rename function. That function will return the new file name. The parameter getNewNameData is an object (supplied by Opus based on the selected files) that contains details about the file names.

At this stage, you could just write return "My All-Encompassing File Name" into the function, and it would work. But I'll give you an example with a bit more meat.

Paste this into the body of the function:

var stem = getNewNameData.newname_stem var ext = getNewNameData.newname_ext delimiterRegex = /[-_. ]/g var newstem = stem.replace(delimiterRegex, '') return newstem + ext


Type in two lines of comments, and you should have this:

simple camel case script


You have the complete script! I'll explain how it works in a second, but first hit Ctrl + S and call the script CamelCase simple. The script's name now shows in the Preset pane on the left. You can right-click the preset's name and assign it to a group, for instance a new group called Script Tests. Soon you should see something like this:

empty script


How does the script work?
The first two lines just assign the name stem and extension (passed to the function in the getNewNameData object) to some variables with short names. They are just there for comfort.

Next, we define a basic regular expression. If you're not fluent in those you could use string functions to achieve the same.

/[-_. ]/g

✱ The two forward slashes are delimiters (the actual pattern is inside the slashes).
✱ At the end of the pattern definition, the g modifier makes the engine find all matches.
✱ The [-_. ] character class matches one character that is either a dash, an underscore, a dot or a space.

We can now proceed with the replacement:
var newstem = stem.replace(delimiterRegex, '') replaces all the matches found in stem by the delimiterRegex pattern with an empty string.

This gives us the name we want because the script works operates on getNewNameData.newname_stem, which is the name after the mods applied directly in the interface, i.e., the name after Title Case has been applied. If instead we were using getNewNameData.name_stem, we would operate on the original name.

This is all we needed, so we can now return the new name:

return newstem + ext


Press Ctrl + S to save the script, then try it by pressing Apply.
Then revert to the original file names by pressing Undo.

script rename undo


Full version: options to turn delimiters on or off

In the next version, we want to tweak the script to allow users to enable or disable the dash, underscore and dot delimiter.

Setting the Parameters
To define these parameters, at the top of the script, paste this new function:

// This optional function handles parameter input // the fields are added to the rename interface function OnGetCustomFields(getFieldData) { // define checkboxes with an initial state getFieldData.fields.capitalizeFirstLetter = false getFieldData.fields.splitOnDashes = true getFieldData.fields.splitOnUnderscores = true getFieldData.fields.splitOnDots = true getFieldData.fields.splitOnSpaces = false // set the labels for the checkboxes getFieldData.field_labels("capitalizeFirstLetter") = "CapitalizeFirstLetter" getFieldData.field_labels("splitOnDashes") = "split-on-dashes" getFieldData.field_labels("splitOnUnderscores") = "split_on_underscores" getFieldData.field_labels("splitOnDots") = "split.on.dots" getFieldData.field_labels("splitOnSpaces") = "split on spaces" }


Next, select Save As to save the script with a new name. Call it CamelCase. Right-click the preset and move it to the right family.

script rename save as


Hit the Refresh Preview button.

rename refresh


Look closely at the interface: five new checkboxes have appeared! Of course, so far they don't have any effect on the rename action.

How does the new function work?
OnGetCustomFields is the name expected by Opus to set the rename parameters. The first five lines create five checkboxes called capitalizeFirstLetter, splitOnDashes and so on. Three of the boxes are initially set to the checked state ( i.e. true), the other two are left unchecked ( i.e. false).

The next five lines creates the text labels for the checkboxes in the interface: split-on-dashes, split_on_underscores and so on.

Checkboxes are one of several kinds of rename configuration options offered by Opus, but they're the only one we'll be using today.

Using the Parameters
Next, replace the whole body of the rename function with this:

// these two fields inherit any renames already done by other // means (e.g. capitalization) var stem = getNewNameData.newname_stem var ext = getNewNameData.newname_ext // build a delimiter string reflecting the state of the checkboxes var delimiters = (getNewNameData.custom.splitOnDashes ? "-" : "") + (getNewNameData.custom.splitOnUnderscores ? "_" : "") + (getNewNameData.custom.splitOnDots ? "." : "") + (getNewNameData.custom.splitOnSpaces ? " " : "") if (delimiters == '') return false var delimiterRegex = new RegExp("[" + delimiters + "]", 'g') var newstem = stem.replace(delimiterRegex, '') if (! getNewNameData.custom.capitalizeFirstLetter) { newstem = newstem.slice(0,1).toLowerCase() + newstem.slice(1) } return newstem + ext

The entire script should look like this:

camel case rename script


There are actually very few changes from the original script.

✱ the assignments to stem and ext are unchanged.
✱ we build a string called delimiters which is a simple concatenation of the delimiters for which the boxes are checked.
✱ if delimiters is empty (no boxes checked) we exit the script.
✱ this time the regex delimiterRegex is almost identical to the one in the first version, except instead of always matching all delimiters with [-_. ], we build the regex by inserting the actual delimiters string. To build the regex dynamically, we use the RegExp constructor instead of an inline definition.
✱ the replacement statement is unchanged.
✱ if the capitalizeFirstLetter box is unchecked, since we have converted the whole name to Title Case, we bring the first letter back to lower case.
✱ the return statement is unchanged.

That's it! This procedure is rather basic: you'll probably be able to think up a number of improvements and enhancements.

I hope you found this stimulating and that you'll be encouraged to whip out your own rename scripts.


Where to go from here?

I'm no Opus rename script expert, so from here I'll probably be spending more time looking at:

✱ The documentation (press F1 and search for rename scripts)
✱ The Rename Presets section of the forum.


next
 What's New in Directory Opus 12





Be the First to Leave a Comment






All comments are moderated.
Link spammers, this won't work for you.

Kindly note that I will not reply to general Opus tech support questions (but feel free to ask about issues directly related to my toolbars).


To prevent automatic spam, we require that you type the two words below before you submit your comment.