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(sln) { }

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

Hello, World!

Let's take a look at a simple Hello World scriptlet. Ameko injects a logger in with the name logger, so you have full logging access.

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

function execute(sln) {
  logger.Info("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(sln) {
  const activeEvent = sln.WorkingSpace.Selectionmanager.ActiveEvent;
  if (!activeEvent) return false;

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

  sln.WorkingSpace.Commit(activeEvent, CommitType.EventText);
  return true;
}

Some things to note:

• Once you leave the realm of Ameko's functions, you use native JavaScript methods. As seen in the example, the event's text is modified using the JavaScript method string.toUpperCase() rather than the C# method string.ToUpper(). This is an important thing to keep in mind as you write scriptlets.
• The CommitType enum is implicitly exposed to scriptlets, so you are able to directly use them when committing.

That's all for now! Happy scripting!