API for other addons

YUKI "Piro" Hiroshi edited this page Oct 12, 2017 · 9 revisions

This describes about Multiple Tab Handler 2.x API for other WebExtensions-based addons. See also old documentation about Legacy MTH 0.x (Japanese translation)

Table of contents generated with markdown-toc

Abstract

To communicate with MTH, your addon can send messages to MTH via browser.runtime.sendMessage(). You need to specify MTH's internal ID multipletab@piro.sakura.ne.jp as the first argument of the method.

Any API message for MTH is an object with a string property named type, which indicates the type of the message. For example:

const kMTH_ID = 'multipletab@piro.sakura.ne.jp';
var success = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'clear-tab-selection'
});

You'll receive returned value from MTH APIs as a promise.

Control Selection of Tabs

Set Selection

set-tab-selection message changes selection status of tabs in a window. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type:     'set-tab-selection',
  unselect: '*',
  select:   [1, 2, 3]
});

Here is the list of parameters:

  • select(Optional): A constant string "*" (means "all tabs in the window"), an integer tabs.Tab.id, or an array of tabs.Tab.ids. This specifies which tabs should be newly selected. Already selected tabs will stay selected. This parameter is processed after unselect is successfully processed.
  • unselect(Optional): A constant string "*" (means "all tabs in the window"), an integer tabs.Tab.id, or an array of tabs.Tab.ids. This specifies which tabs should be unselected. This parameter is processed before select.
  • window(Optional): An integer windows.Window.id. If you omit this parameter, tabs in the active window will be processed by default. Tabs specified via select or unselect in other windows are simply ignored.

Here are more valid examples:

  • Select all tabs in the active window: { select: '*' }
  • Unselect two tabs and select other three tabs in the active window: { unselect: [1, 2], select [5, 6, 8] }

Get Selection

get-tab-selection message requests last selection status of tabs. For example:

var selection = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'get-tab-selection'
});
console.log(selection.selected); // [{id: 1, ...}, {id: 2, ...}, ...]
console.log(selection.unselected); // [{id: 5, ...}, {id: 6, ...}, ...]

The returned response will have these two properties:

  • selected: An array of tabs.Tabs which are selected.
  • unselected: An array of tabs.Tabs which are not selected.

Note that this doesn't return selection in the active window, just returns last selection. In other words, if you select some tabs in a window and you open a new window, this API still returns the selection in previous window until selection status is updated.

Clear Selection

clear-tab-selection message clears last selection status of tabs completely. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'clear-tab-selection'
});

This message doesn't accept any optional parameter.

Extra selection menu items

Your addon can provide custom menu item for the selection menu of MTH.

Add selection menu item

add-tab-selection-command message registers an extra command to the selection menu. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type:  'add-tab-selection-command',
  id:    'save-as-pdf',
  title: 'Save as PDF'
});

Here is the list of parameters:

  • id(Required): A string to indicate unique ID of the command.
  • title(Required): The name of the command which should appear as the label of its menu item.
  • always(Optional): A boolean to indicate the command should appear even if there is no selection.

Remove selection menu item

remove-tab-selection-command message unregisters an extra command from the selection menu. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'remove-tab-selection-command',
  id:   'save-as-pdf'
});

Here is the list of parameters:

  • id(Required): A string to indicate unique ID of the command.

Note that you need to remove items manually when your addon is going to be disabled or uninstalled. Otherwise ghost menu item will stay there even if your addon is unavailable.

Invoke the command

After you add your custom command, a tab-selection-command message will be delivered to your addon via browser.runtime.onMessageExternal. Here is an example to invoke command by the message:

browser.runtime.onMessageExternal.addListener(async (aMessage, aSender) => {
  switch (aSender.id) {
    case kMTH_ID:
      switch (aMessage.type) {
        case 'tab-selection-command':
          ... // do something
          return Promise.resolve(true);
      }
      break;
  }
});

Here is the list of properties the delivered message will have:

  • id: A string which is the ID of the command.
  • selection: An object which have selected and unselected. Same to the result of get-tab-selection.

How to know when MTH become getting ready

Adding selection menu item will fail if your addon starts before MTH is completely initialized.

However, MTH caches the ID of the addon which successfully registers any selection menu item. MTH sends ready message to those addons on its startup process, so you'll re-register your selection menu item by the message. For example:

browser.runtime.onMessageExternal.addListener(async (aMessage, aSender) => {
  switch (aSender.id) {
    case kMTH_ID:
      switch (aMessage.type) {
        case 'ready':
          addMTHSelectionMenuItems(); // for second time and later
          return Promise.resolve(true);
      }
      break;
  }
});
addMTHSelectionMenuItems(); // for initial installation

Sadly MTH cannot broadcast such a ready message for unknown addons, so your addon's custom selection menu items won't be available until your addon is reloaded, if MTH is installed after your addon.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.