iRightMenu Pro Plugin Development

Welcome to the iRightMenu Pro plugin development documentation. This guide will help you create custom Finder context menu extensions using Lua.

Quick Start

Create your first plugin in 5 minutes!

1. Create the Plugin Directory

Plugins are installed in the App Group container:

~/Library/Group Containers/group.net.ymlab.iRightMenu.pro/Plugins/

Create a new directory using reverse domain name format:

mkdir -p ~/Library/Group\ Containers/group.net.ymlab.iRightMenu.pro/Plugins/com.yourname.myplugin
cd ~/Library/Group\ Containers/group.net.ymlab.iRightMenu.pro/Plugins/com.yourname.myplugin

2. Create plugin.json

{
  "id": "com.yourname.myplugin",
  "name": "My First Plugin",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A simple Hello World plugin",
  "main": "main.lua",
  "menus": [
    {
      "id": "hello",
      "title": "Say Hello",
      "enabled": true,
      "showOnFiles": true,
      "showOnFolders": true
    }
  ]
}

3. Create main.lua

-- Create plugin class
local MyPlugin = Plugin:extend()

-- Initialization: register menu handlers
function MyPlugin:init()
    self:registerHandler("hello", self.sayHello)
end

-- Menu action handler
function MyPlugin:sayHello(context)
    local files = context.selectedFiles
    local count = #files

    app.notification.show(
        "Hello!",
        "You selected " .. count .. " items"
    )
end

-- Export plugin class (engine auto-instantiates)
return MyPlugin

4. Reload the Plugin

In iRightMenu Pro, go to Preferences > Plugins and click Reload.

Or restart Finder:

killall Finder

5. Test the Plugin

Right-click any file in Finder. You should see a “Say Hello” option in the iRightMenu submenu.

Documentation

Plugin Structure

com.yourname.myplugin/
├── plugin.json          # Plugin manifest (required)
├── main.lua             # Main script (required)
├── icon.png             # Plugin icon (optional, 64x64 recommended)
├── settings.json        # Runtime settings storage (auto-generated)
├── locales/             # Localization files (optional)
│   ├── en.json
│   └── zh-Hans.json
└── resources/           # Other resources (optional)

Core Concepts

Plugin Lifecycle

1. Load: Plugins are loaded when Finder starts or when plugins are reloaded
2. Initialize: init() is called to register menu handlers
3. Execute: Handlers are called when the user clicks a menu item
4. Unload: Plugins are unloaded when Finder quits or when plugins are reloaded

Menu Matching Rules

Control when menus are displayed:

{
  "menus": [{
    "id": "process_images",
    "title": "Process Images",
    "showOnFiles": true,
    "showOnFolders": false,
    "fileMatchType": "extension",
    "fileMatchPatterns": ["jpg", "png", "gif"],
    "minFiles": 1,
    "maxFiles": 100
  }]
}

API Namespaces

All APIs are accessed through the global app namespace:

• app.log - Logging
• app.dialog - Dialogs and forms
• app.file - File operations
• app.path - Path utilities
• app.shell - Shell commands
• app.notification - System notifications
• app.settings - Plugin settings
• And more…

Getting Help

• See the API Reference for detailed documentation
• Check out the Example Plugins to learn common patterns
• View plugin logs: ~/Library/Group Containers/group.net.ymlab.iRightMenu.pro/Logs/

License

Plugins you create belong to you. The plugin API is provided by iRightMenu Pro.