iBoysoft MagicMenu Extensions Developer Reference

Home > iBoysoft MagicMenu > Extensions Developer Reference

iBoysoft MagicMenu implements functional expansion through extensions. With this detailed specification of the extensions architecture of iBoysoft MagicMenu, you can create and install your own extensions.

Extension architecture

An extension of iBoysoft MagicMenu is usually a package folder consisting of a configuration file, an icon file, a directory of internationalized files, an executable file, and a signature file (optional).

Here's an example of the extension package structure, the Snagit extension:

Snagit.magicmenux - Package folder
    |
    —— manifest.json - Configuration file
    —— Snagit.sh (or Snagit.app) - Executable file
    —— icon.png - Icon file
    —— _locales - Internationalized folder
    —— _Signature - Signature file (optional)

extension package architecture

Extension Container

A container for an extension typically refers to the packaged file or directory structure that contains all the necessary components of the extension. This "container" is what gets distributed, installed, and executed by the platform such as an application that supports the extension.

To enable the extension package readable and recognizable in iBoysoft MagicMenu, you should end the folder's name with .magicmenux. For instance, Test.magicmenux.

When you double-click a .magicmenux package in Finder, iBoysoft MagicMenu will automatically load and install it.

Note: An extension directory is recognized as a package in macOS. To check the contents in a package, right-click it in Finder and select Show Package Contents.

For distribution, you should compress the extension package .magicmenux to .magicmenux.zip and then rename it to .magicmenuxz.

Configuration file

An iBoysoft MagicMenu extension should have a configuration file (or called a manifest file) in JavaScript Object Notation (JSON) format and named after manifest.json. It is used to store the required metadata and settings information of the extension, including name, version, icon, identifier, description, scripts, etc.

The manifest.json file usually should cover the general and "actions" properties. The general properties are used to define the basic information of the extension, while the "actions" properties determine what the extension should do when certain conditions are met.

Sometimes, you may also need the "options" properties, a collection of configurable parameters or settings, to define the behavior, appearance, or choices available for a particular action within the extension.

Note: You are suggested to create and edit the manifest.json file using Visual Studio Code.

Configuration file example

Let's view an example config file to dive into the details.

View the example


{
    "name": "WPS",
    "subname":"WPS-1",
    "icon": "icon.png",
    "identifier": "com.custom.wps",
    "description": "Edit a document",
    "os version": "10.13",
    "app version": "4",
    "version": "1",
    "developer":"user",
    "copyright": "",
    "categories":[
        "Utility"
    ],
    "actions": {
        "apps": [
            {
                "name": "WPS",
                "full name": "use WPS",
                "description": "Edit a document",
                "icon": "icon.png",
                "identifier": "com.custom.wps.action",
                "rule": {
                    "type": "basic",
                    "values": [
                        "4"
                    ]
                },
                "run as root": 0,
                "async": 1,
                "default group id": "19B75651-7B42-4265-8235-BB5D2949B972",
                "dependent apps": [
                    {
                        "name": "WPS",
                        "link": "https://www.wps.com/office/mac/",
                        "identifier": "com.kingsoft.wpsoffice.mac",
                        "check installed": 1
                    }
                ],
                "app": {
                    "exec file": "/Applications/wpsoffice 2.app/Contents/PkgInfo",
                    "params": [
                        "{magicmenu selectedURLs 2}",
                        "-v",
                        "{magicmenu osversion}",
                        "{magicmenu appversion}",
                        "{magicmenu developer}",
                        "{magicmenu icon}",
                        "{magicmenu options wps-checkbox-identifier}",
                        "{magicmenu options wps-choice-identifier}",
                        "{magicmenu options wps-password-identifier}",
                        "{magicmenu actions com.custom.wps.action options wps-checkbox-identifier}",
                        "{magicmenu actions com.custom.wps.action options wps-choice-identifier}",
                        "{magicmenu actions com.custom.wps.action options wps-password-identifier}"
                    ]
                },
                "options": [
                    {
                        "identifier": "wps-checkbox-identifier",
                        "type": "checkbox",
                        "name": "Enable WPS",
                        "default values": ["true"],
                        "description": "Choose whether to enable WPS by default"
                    },
                    {
                        "identifier": "wps-choice-identifier",
                        "type": "choice",
                        "name": "Choose icon color",
                        "default values": ["red"],
                        "description": "Set the color of the icon",
                        "candidate options": [
                            "red",
                            "blue",
                            "green"
                        ]
                    },
                    {
                        "identifier": "wps-password-identifier",
                        "type": "password",
                        "name": "Enter password",
                        "default values": ["123456"],
                        "description": "Enter password for verification"
                    }
                ]
            }
        ]
    }
}

General properties (the root-level properties)

The following keys are used at the top level of the configurations to define the properties of the extension itself.

Key	Type	Description	Necessity
name	Localizable String	The display name of this extension is in the main program. If it does not exist, the name of the extension file.	Necessary
subname	Localizable String	A secondary name of the extension.	Necessary
icon	String	The file name of the icon that is used for the extension. An icon is specified by using a text string to describe it. All common picture formats are supported.	Necessary
identifier	String	The identifier of the extension. For non-official extensions of iBoysoft, do not use iboysoft.com. as the prefix.	Necessary
description	Localizable String	A short, human-readable description that is displayed when installing or viewing the extension.	Necessary
os version	String	The minimum operating system version required to run the extension.	Necessary
app version	String	The minimum iBoysoft MagicMenu version required by the extension.	Necessary
version	String	The version of the extension (customizable).	Necessary
developer	String	The developer of the extension. The default value is "user".	Necessary
copyright	String	Copyright information. For personal use of the extension, leave this field blank.	Necessary
categories	Array	The category that the extension belongs to in iBoysoft MagicMenu Extension store.	Necessary
actions	Array	An array with configurations related to actions that the extension can perform.	Necessary
options	Array	An array of dictionaries that define the options available within corresponding actions.	Optional
help url	String	A link to a specific help document	Optional
init	Array	Initialize resources, set up the environment, or perform necessary preparatory tasks during installing the extension.	Optional
uninit	Array	Cleanup and teardown the extension during uninstallation, including deleting temporary files, closing connections, or releasing resources.	Optional

Actions

A generic list of action attributes to define how the extension performs.

Action properties can be placed either in an action dictionary, in an actions array, or at the top level. Properties set at the top level will apply to all actions unless overridden in the individual action.

Since iBoysoft supports app-based and shells cript-based extensions. You can either use the "apps" array or "shells" array to define the "actions" attributes. Thus, choose the corresponding keys based on the type of extension you'll create:

Example of keys in "actions" of an app-based extension:

View the example


"actions": {
    "apps": [
        {
            "name": "WPS",
            "full name": "use WPS",
            "description": "Edit a document",
            "icon": "icon.png",
            "identifier": "com.custom.wps.action",
            "rule": {
                "type": "basic",
                "values": [
                    "4"
                ]
            },
            "run as root": 0,
            "async": 1,
            "default group id": "19B75651-7B42-4265-8235-BB5D2949B972",
            "dependent apps": [
                {
                    "name": "WPS",
                    "link": "https://www.wps.com/office/mac/",
                    "identifier": "com.kingsoft.wpsoffice.mac",
                    "check installed": 1
                }
            ],
            "app": {
                "exec file": "/Applications/wpsoffice 2.app/Contents/PkgInfo",
                "params": [
                    "{magicmenu selectedURLs 2}",
                    "-v",
                    "{magicmenu osversion}",
                    "{magicmenu appversion}",
                    "{magicmenu developer}",
                    "{magicmenu icon}",
                    "{magicmenu options wps-checkbox-identifier}",
                    "{magicmenu options wps-choice-identifier}",
                    "{magicmenu options wps-password-identifier}",
                    "{magicmenu actions com.custom.wps.action options wps-checkbox-identifier}",
                    "{magicmenu actions com.custom.wps.action options wps-choice-identifier}",
                    "{magicmenu actions com.custom.wps.action options wps-password-identifier}"
                ]
            },
            "options": [
                {
                    "identifier": "wps-checkbox-identifier",
                    "type": "checkbox",
                    "name": "Enable WPS",
                    "default values": ["true"],
                    "description": "Choose whether to enable WPS by default"
                },
                {
                    "identifier": "wps-choice-identifier",
                    "type": "choice",
                    "name": "Choose icon color",
                    "default values": ["red"],
                    "description": "Set the color of the icon",
                    "candidate options": [
                        "red",
                        "blue",
                        "green"
                    ]
                },
                {
                    "identifier": "wps-password-identifier",
                    "type": "password",
                    "name": "Enter password",
                    "default values": ["123456"],
                    "description": "Enter password for verification"
                }
            ]
        }
    ]
}

Example of keys in "actions" of an shell script-based extension:

View the example


"actions": {
    "shells": [
        {
            "name": "New Folder",
            "full name": "New Folder",
            "description": "Quickly create a new folder",
            "icon": "icon.png",
            "identifier": "com.custom.newFolder-newfolder",
            "rule": {
                "type": "basic",
                "values": [
                    "1"
                ]
            },
            "run as root": 0,
            "async": 1,
            "dependent apps": [],
            "default group id": "4EEB5A5A-7FA8-4B34-B617-9287E5FACB1F",
            "shell": {
                "shellscript file": "NewFolder.sh",
                "params": [
                    "{magicmenu launchedURL}"
                ],
                "interpreter": "bash"
            }
        }
    ]
},
"options": [
    {
        "identifier": "test-option-1",
        "type": "text",
        "name": "New Folder",
        "default value": "4",
        "description": "Create new a folder",
        "candidate options": [
            "1",
            "2"
        ]
    }
]

Break down the examples:

Key	Type	Description	Necessity
apps	Array	Dictionaries about the action or app-related configuration.	Optional
shells	Array	Define specific settings related to shell execution.	Optional
name	Localizable String	The name of the option on the right-click menu corresponding to the action.	Necessary
full name	Localizable String	The full name of the option on the right-click menu corresponding to the action.	Optional
description	Localizable String	Description for the action.	Optional
icon	String	The icon of the option on the right-click menu corresponding to the action. If you leave it blank, it will show up the icon of the root level.	Optional
identifier	String	The identifier of the action.	Necessary
os version	String	The minimum operating system version required to run the action.	Necessary
app version	String	The minimum iBoysoft MagicMenu version required by the action.	Necessary
rule	Dictionary	The condition for the action to show up on the right-click menu. Look at and choose default values from iBoysoft MagicMenu's rule attribute specification.	Necessary
run as root	Bool	Requirement for the root permission. If the action requires root permission, fill in 1, otherwise 0. The default value is 0.	Necessary
async	Bool	Indicates synchronous (0) or asynchronous (1) execution of the action, the default is 1.	Optional
default group id	String	A UUID (Universally Unique Identifier) is used to associate the action with a specific group in Menu Editor by default. Here are the common UUID we defined: New File: 4EEB5A5A-7FA8-4B34-B617-9287E5FACB1F Move to: 5B6B5E35-54F7-4931-AB4E-F657AB8B4624 Copy to: 4B6B5E25-54F7-4931-AB4E-F657AB8B4625 Quick Access: D39B1581-97D1-4577-9952-2E43616DF6B0 Open with: 19B75651-7B42-4265-8235-BB5D2949B972 General: B6B9583E-1B57-4B3F-9D30-5BC150377B24 Screen Capture: 7CB61989-91CF-4DF1-94CA-936E4F19F37F Delete Directly: 92B88FC2-D707-3873-EA45-83F1252F4A00 AI: CAD691F8-02AE-6E48-68F7-3490A08E0BFA Hide Files: F5F5606F-E474-41E8-8CC6-906DBBB76568	Optional
help url	String	The link of help document to the action.	Optional
permissions	Array	The specific rights or authorizations required to perform the action. The permission inquiry dialogue box only pops up when some apps are running.	Optional
dependent apps	Array	The app that the action depends on.	Optional
app	Array	Details about how the app is executed.	Necessary. Use either the "app" or "shell" array.
shell	Array	Information about the shell script that will be executed for the action.	Necessary. Use either the "app" or "shell" array.
options	Array	A collection of configurable parameters or settings that define the behavior, appearance, or choices available for the action.	Optional

Note:

1. Rule attribute specification

iBoysoft MagicMenu will match the menu items that meet the conditions through the rule attributes and display them in the right-click menu under certain conditions.

Key	Type	Description	Necessity
type	String	Specify the kind or category of rule being defined. It determines the nature of the condition or criteria that needs to be met for an action to be executed. The types of "type" iBoysoft contain: basic: basic info exec: only matching executable files extension: matching file extensions regex: regular expressions mine: MIME (Multipurpose Internet Mail Extensions type)	Necessary
values	String Array	The corresponding value to the "type" key: Basic values: "0": not match "1": blank area "2": a directory (folder) "3": blank area or a directory (folder) "4": a file "5": blank area or a file "6": a directory (folder) or a file "7": blank area, a file or a directory (folder) The executable program: blank area Extension: String array Regular expression: String array MIME: String array	Necessary

2. The permissions field

If the action requires specific rights or authorizations to perform, define the "permissions" with the following.

Key	Type	Description	Necessity
type	String	The default types include: "screen record" "full disk access" "accessibility" "appleEvent" "bluetooth" "microphone" "photo library" "location"	Necessary
description	Localizable String	The brief description for the permission.	Optional
value	String	The checksum corresponding to the permission. For example, appleEvent needs to specify the identifier of the target.	Optional

3. The dependent apps field

If the extension you create is based on an application, you need to add attributes about the dependent app.

Key	Type	Description	Necessity
name	Localizable String	The name of the app.	Necessary
link	String	The download link of the app.	Necessary
identifier	String	The bundle ID of the app. You can find it from the app's info.plist file.	Optional
check installed	Bool	Check whether the app is installed before running the action. Check, enter 1, or else, enter 0.	Optional

4. The app field

Key	Type	Description	Necessity
exec file	String	The path of the dependent app.	Necessary
params	Array	Parameters passed to the executable at runtime.	Necessary

5. The shell field

Key	Type	Description	Necessity
shellscript file	String	The name of the shell script file that will be executed.	Necessary
params	Array	Parameters passed to the executable at runtime.	Necessary
interpreter	String	The interpreter that will run the shell script. The supported interpreters: "bash" "ruby" "python" "python3"	Necessary

Supported variables in parameters

If there is a variable placeholder in the parameter, the variable will be parsed into the corresponding string. The variable placeholder starts with "magicmenu" to obtain the attributes layer by layer and is surrounded by curly braces. If the corresponding type of the attribute is an array, it can be followed by the index value, for example:

{magicmenu launchedURL}: Get the path of the current launch directory
{magicmenu selectedURLs}: Get the path of the currently selected file
{magicmenu selectedURLs 2}: Get the item with index 2 in the currently selected file path, and return null if not found
{magicmenu osversion}: Get the current OS version
{magicmenu version}: Get the current version of iBoysoft MagicMenu
{magicmenu developer}: Get the developer information
{magicmenu copyright}: Get the copyright information
{magicmenu icon}: Get the icon information
{magicmenu identifier}: Get the extension identifier
{magicmenu option option identifier}: Get the identifier of an option under the extension
{magicmenu actions action identifier name}: Get the name of an action under the extension
{magicmenu actions action identifier icon}: Get the icon of an action under the extension
{magicmenu actions action identifier rule type}: Get the rule type of an action under the extension
{magicmenu actions action identifier rule values}: Get the rule value of an action under the extension
{magicmenu actions action identifier option option identifier}: Get the value of an option of an action under the extension
{magicmenu actions action identifier dependentApps 0 link}: Get the link of the dependent app of an action under the extension

Note: You need to replace the action identifier and option identifier with your true ones. All variable placeholder structures are essentially dynamic access to properties. No matter how complex the JSON structure is, you can get the desired variable value by dynamically accessing it layer by layer.

Options

The option properties will be displayed in the extension configuration window (the the right sidebar of iBoysoft MagicMenu's Menu Editor window), and users can self-set the key values.

Key	Type	Description	Necessity
name	Localizable String	The name of the option.	Necessary
description	Localizable String	The description of the option, which will be displayed on the tooltip by default.	Necessary
identifier	String	The identifier of the option.	Necessary
type	String	The type of the option. Here are the default types: text password checkbox datePicker colorPicker choice pathPicker	Necessary
default values	Array	The default value (customizable) of the option.	Optional
candidate options	Array	The selective values (customizable) for the option of choice type.	Optional
required	Bool	Whether the option is a property that the user must set.	Optional

Executable file

The executable file mainly determines the running of the extension's actions. Both the .sh (shell script) file and the .app file are iBoysoft MagicMenu-supported executable files.

.sh file

A .sh (shell script) file is a text file containing a series of commands that are executed by a Unix-like shell. In the context of an application extension, a .sh file might be used to automate tasks, configure settings, or perform specific actions related to the app or extension.

How to create a .sh file with iBoysoft MagicMenu:

Step 1: Right-click the blank area in your extension package folder.

Step 2: Select New File > Shell to create a new shell file and change its name to your extension name.

create a new shell file

Step 3: Use a script editing tool like Visual Studio Code to edit the content you want.

Step 4: Save the .sh file.

Find demo from MagicMenu-Extensions-Tutorial

.app file

A .app file in an extension package is a macOS application bundle that contains the executable code and all associated resources needed for the application to run. It serves as the main application within the extension.

You can use Xcode to create a .app file that can accept launch parameters and execute tasks based on parameters, follow details in this demo: MagicMenu-Extensions-Tutorial

Icon file

The main icon of the extension (similar to the app icon). The icon size should not exceed 100KB and the dimension of the icon should not be larger than 256px * 256px. The icon is displayed when installing, uninstalling, and viewing plugin details.

Internationalized folder (_locales folder)

The _locales folder allows developers to provide translations of the extension's user interface and other text content for different languages, making the application accessible to users in various regions.

Inside the _locales folder, there are subfolders named after language codes (e.g., en, fr, de), each containing a manifest.strings file (and other resources). These JSON files store the translations for that particular language. If no corresponding language is found, "en" resources will be used first. If "en" resources do not exist, strings will be used directly.

The manifest.strings files within each language folder contain key-value pairs, where each key corresponds to a text string in the application, and the value is the translated text in the target language.

The internationalization folder commonly includes: en, de, es, fr, it, ja, ko, pl, pt-BR, ru, sk, tr, zh-Hans, zh-Hant, etc.

en: English (the default language of the extension)
de: German
es: Spanish
fr: French
it: Italian
ja: Japanese
ko: Korean
pl: Polish
pt-BR: Brazilian Portuguese
ru: Russian
sk: Slovak
tr: Turkish
zh-Hans: Simplified Chinese
zh-Hant: Traditional Chinese

locales folder

iBoysoft MagicMenu also supports other languages that are not on the list. If you want to learn their abbreviation, contact the iBoysoft team.

Signature file (_Signature file)

The signature file is exclusively for the extension released by iBoysoft official. It is used to identify the source of the extension, ensure the integrity of the extension, and prevent the installation and abuse of malicious extensions.

Developers can submit their signature files to the iBoysoft official repository. When the extension is officially released to the iBoysoft MagicMenu's Extension store, it will be accompanied by the extension signature file.

Requirements and notes of the _Signature file:

The extension using com.iboysoft. identification code as the prefix indicates that it is an official one. The loss of the official extension's signature file will result in the inability to install and run the extension.
When you customize extensions, you should avoid using identifiers prefixed with com.iboysoft., otherwise the extension won't work.
When you install unofficial extensions, you will be informed of unknown risks and asked whether to install them.
If the official extension is modified after installation, you'll be informed when running it and prompted to reinstall it.
Once the developer mode is enabled, the signature and source won't be verified temporarily by iBoysoft.
There's no need for _Signature file if the extension is for personal use only.
If developers need to distribute self-designed extensions, they need to submit and review the extensions in the GitHub repository.

Extension debugging

If your extension is called during the development, the log file will be displayed in the Console utility on your Mac. Click Settings on the iBoysoft MagicMenu sidebar > View logs to open Console.

view logs

The log name starts from DEBUG🐛. Enter DEBUG🐛into the search box on the upper right corner of the Console and click Start streaming to filter the results and find the target log for debugging.

When the action of the extension is not asynchronous, the execution result error code will appear if the return value of the extension is not 0.