Scriptlets

Scriptlets are a second-class user script, written in JavaScript.

Unlike C# Scripts, Scriptlets cannot use libraries and are quite limited in scope.

What's in a Scriptlet?

All scriptlets have two components used by Ameko. First, identification:

const scriptInfo = {
  displayName: string,
  qualifiedName: string
};

• Display Name is the name users of the script will see in the Package Manager and in the scripts menu.
• Qualified Name is a unique namespaced identifier for the script. The most common format is authorName.scriptName, but this is by no means required.

And second, there's the entry point:

function execute(prj) { }

Ameko will call the execute function when your script is invoked, passing in the current Project as a parameter. The execute function can return a boolean. Returning false will result in a failing ExecutionResult.

Note

The prj parameter will be removed in release 1.3.0. Use the project global instead.

What do I have access to?

What can I access in the Playground?

The following methods and fields are available for you to use:

Methods

• log(message): Log an Info message
• err(message) Log an Error message
• commitOne(event, ChangeType): Commit changes to a single event to history
• commitMany(event[], ChangeType): Commit changes to multiple events to history
• selectOne(event): Select an event
• selectMany(event, event[]): Select multiple events

Fields

• project: The currently-open Project
• workspace: The currently-selected Workspace, may be null
• events: All events in the current Document
• activeEvent: The currently-active Event
• selectedEvents: All currently-selected events
• eventManager: The current Document's EventManager
• The ChangeType enum

Caveats

• Lists are JavaScript arrays, meaning you use .filter() and .forEach(), not LINQ methods like .Where()
• Primitives are JavaScript primitives, meaning it's activeEvent.Text.toUpperCase(), not activeEvent.Text.ToUpperCase()

Hello, World!

Let's take a look at a simple Hello World scriptlet. Ameko injects log and err methods for logging.

const scriptInfo = {
  displayName: "Hello World",
  qualifiedName: "example.helloWorld",
};

function execute(prj) {
  log("Hello, World!");
  return true;
}

A Script that Does Something

We'll make a script that edits the selected event's text to be UPPERCASE, then we'll commit that change to history.

const scriptInfo = {
  displayName = "Uppercase Machine",
  qualifiedName = "example.uppercaseMachine",
};

function execute(prj) {
  if (!activeEvent)
    return false;

  activeEvent.Text = activeEvent.Text.toUpperCase();

  commitOne(activeEvent, ChangeType.ModifyEventText);
  return true;
}

That's all for now! Happy scripting!