Your first Marta plugin

Marta functionality can be extended by writing plugins written in Lua. In case if you do not know the language, please refer to its documentation. However, if you can already write code, learning Lua will not be a problem – it is straightforward and logical.

Marta bundles the official Lua 5.4.7 interpreter. There is no need to install anything special in order to develop plugins.

This tutorial will guide you through the process of creation of a trivial Marta plugin.

Plugin Location

All Marta plugins are stored in ~/Library/Application Support/org.yanex.marta/Plugins. Marta creates the directory automatically, so, unless you deleted it explicitly, it should always exist. Marta provides the Open plugin directory action (⌘⇧P, “Open plugin directory”, ↵ Return), use it for quick navigation.

Lua API

There are two kinds of plugins:

  • Single-file plugins are basically .lua files placed directly in the plugin directory. During this tutorial, we will create a single-file plugin.
  • Complex plugins consist of multiple source files placed in a subdirectory. Complex plugins can include dependencies, resources, documentation, or anything else. You are free to define your own plugin structure. The only requirement is that the main plugin file must be named init.lua.

Here is an example of a plugin directory structure with several installed plugins:

Plugins/
    hello.lua
    backup-tool.lua
    share-email/
        init.lua
        utils.lua
        README
        LICENSE
        rocks
            <LuaRocks dependencies>

Create a file hello.lua in the plugin directory and open it with a text editor. I recommend using text editors designed for writing code. Here are some examples: TextMate, Sublime Text, Visual Studio Code and MacVim.

Declare a Plugin

Plugins must declare themselves so Marta recognizes them. The minimal set of metadata is an identifier, a name, and a compatible API version.

Identifier is a unique name of your plugin. I suggest you to use a reverse domain name notation. For example, if you own a bob.com domain, and the plugin name is Send SMS, com.bob.sendsms is a perfect plugin identifier.

Name is a readable plugin name. Although it does not appear a lot, the name is used to tell that your plugin does not work properly (e.g. Plugin 'Hello world' is incompatible with this version of Marta.). Choose a concise but a self-explaining name.

You should also provide a Marta API version your plugin is compatible with. The format is major.minor, e.g. 1.3. Minor version updates contain no breaking changes, so a plugin made for 1.0 will perfectly work with 1.1, 1.2, and with all subsequent 1.* versions. However, major version increment usually means some breaking change happened. By default, Marta ignores plugins built for the previous major versions of the API.

The current API version is 2.2.

Put the plugin declaration to hello.lua:

plugin {
    id = "com.marta.example.helloworld",
    name = "Hello world",
    apiVersion = "2.2"
}

Save the file and restart Marta. You will not notice any difference, though. :) However, if you open the Console application, you will find something like this:

default HH:MM:SS.000000 +XX00   Marta   Loaded Lua plugin Hello world (marta.example.helloworld)

It means Marta loaded your plugin successfully. Great! Now, let’s personalize the plugin, so everyone on Earth will know you created it:

plugin {
    id = "marta.example.helloworld",
    name = "Hello world",
    apiVersion = "2.2",

    author = "Your Name",
    email = "your@email.com",
    url = "https://your.website.com/"
}

🐧 Note that in case if you convert the plugin into the complex one, renaming the script to init.lua is not enough. Read the Using LuaRocks dependencies tutorial to understand why.

Declare an Action

Our plugin will add a “Hello world” action that shows a popup message. To declare an action, you will need an action identifier and a name.

  • Action identifier is local to your plugin. If you wish to register a hotkey for the action, you will need a full name: <plugin id>.<action id>.
  • Action name is displayed in the Actions panel (⌘⇧P).
action {
    id = "action",
    name = "Hello world",
    apply = function()
        martax.alert("Hello, world!")
    end
}

martax.alert is a function from Marta API extensions. It shows a modal alert window.

Declare an action and restart Marta once more. If everything is fine, there will be an additional action called “Hello world” in the Actions panel. Being called, it will show the popup.

Hello world alert

Bingo! You’ve created your first Marta plugin. 😺

Final Version

Here is a complete code of the plugin we made:

plugin {
    id = "marta.example.helloworld",
    name = "Hello world",
    apiVersion = "2.2",
    author = "John Smith",
    email = "john@smith.com",
    url = "https://smith.com/"
}

action {
    id = "action",
    name = "Hello world",
    apply = function()
        martax.alert("Hello, world!")
    end
}