webext-options-sync-multi v0.0.1

webext-options-sync-multi

Helps you manage and autosave your extension's options, separately for each additional permission.

Prerequisites

• Your WebExtension’s options are managed by webext-options-sync
• Your WebExtension can be enabled on multiple optional domains, maybe via webext-dynamic-content-scripts
• Your users want to customize your extension’s options for each domain, indipendently.

In that case, webext-options-sync-multi as a wrapper for webext-options-sync with these feature:

• Automatically detects new origin permissions
• Prepares a fresh set of options for each new origin
• Transparently serves the right set of options based on the current domain
• Adds a domain switcher on the options page — only if the user adds multiple origins

Install

You can just download the standalone bundle (it might take a minute to download) and include the file in your manifest.json, or:

npm install webext-options-sync-multi
npm remove  webext-options-sync # This is now included

import OptionsSyncMulti from 'webext-options-sync-multi';

Usage

If you're following the suggested setup for webext-options-sync, here are the changes you should make:

  // options-storage.js
- export default new OptionsSync({defaults, migrations});
+ export const multiOptions = new OptionsSyncMulti({defaults, migrations});
+ export default multiOptions.getOptionsForOrigin();

Now options-storage.js will the same old OptionsSync instance, except it varies depending on the current domain.

  // options.js in options.html
-	import optionsStorage from './options-storage';
+ import {multiOptions} from './options-storage';

  async function init() {
- 	await optionsStorage.syncForm('form');
+ 	await multiOptions.syncForm('form');
  }

That's all! A domain switcher will only appear if the user adds new additional domains via chrome.permissions.request() or webext-domain-permission-toggle.

Concepts

Origins

Origins are what the browser calls each "website" permission; they look like https://example.com or https://*.example.com/*

Domains

Domains are the same as origins, except it's a less ambiguous word and it's generally shown protocol-less: example.com or *.example.com

Default

webext-options-sync-multi differentiates between origins that are part of manifest.json and origins added later via chrome.permission.request(). All manifest.json origins share the same options and these are considered the "default".

API

const multiOptions = new OptionsSyncMulti(setup?)

setup

This is identical to the setup in webext-options-sync

multiOptions.syncForm(form)

This is identical to syncForm() in webext-options-sync, but it will also:

• add a domain selector dropdown if the user enabled the extension on more origins
• switch the data of the form depending on the selected domain

If you want to customize the switcher or listen to its change, await this call and perform the changes after it runs. Example:

// options.js
import {multiOptions} from './options-storage';

async initOptions() {
	await multiOptions.syncForm('form');

	// Update domain-dependent page content when the domain is changed
	const dropdown = select('.js-options-sync-selector');
	if (dropdown) {
		dropdown.addEventListener('change', event => {
			select('#personal-token-link')!.host = event.currentTarget.value;
		});
	}
}

initOptions();

multiOptions.getOptionsForOrigin(origin?)

Returns an origin-specific instance of OptionsSync. If called from an extension page (background.js, options.html, etc) and without the parameter, it will use the default origin.

origin

Type: string Default: location.origin Example: http://example.com

multiOptions.getAllOrigins()

Returns a Map of the OptionsSync instances, one for each origin. The default origins are on the key default and the other ones are on keys that look like domain.ext

const instances = multiOptions.getAllOrigins();

// Print the options of these 2 instances
console.log(await instances.get('default').getAll());
console.log(await instances.get('example.com').getAll());

Related

Permissions

• webext-additional-permissions - Get any optional permissions that users have granted you.
• webext-dynamic-content-scripts - Automatically registers your content_scripts on domains added via permission.request
• webext-permissions-events-polyfill - Polyfill for onAdded and onRemoved permission events for Firefox.

Others

• webext-options-sync - Helps you manage and autosave your extension's options. Chrome and Firefox.
• webext-storage-cache - Map-like promised cache storage with expiration. Chrome and Firefox
• webext-detect-page - Detects where the current browser extension code is being run. Chrome and Firefox.
• Awesome-WebExtensions - A curated list of awesome resources for WebExtensions development.

License

MIT © Federico Brigante