autooptions v1.3.3

AutoOptions - Chrome Storage API Helper

AutoOptions is a JavaScript/TypeScript library that simplifies the process of saving and managing extension preferences automatically using the Chrome Storage API. It is designed to be used in Chrome extensions to handle user configurations and persist them across sessions. It can handle categories, exceptions, default values and more. Also, it's really fast.

Table of Contents

• Installation
• Usage
• Features
• Contributing
• License

Installation

You can install AutoOptions using npm:

npm install autooptions

To use AutoOptions in your project, import the AutoOptions module.

<script type="module" src="options.js"></script>

import { AutoOptions } from "../node_modules/autooptions/AutoOptions.mjs";

Usage

background.js

chrome.runtime.onInstalled.addListener((details) => {
    if (details.reason === "install") setDefaultConfig();
    
    // to apply changes made in options using session storage later,  include this here:
    chrome.storage.session.setAccessLevel({accessLevel: "TRUSTED_AND_UNTRUSTED_CONTEXTS"});
});

chrome.runtime.onMessage.addListener((message)=> {
    if (message === "openOptions") setDefaultConfig();
});

function setDefaultConfig() {
    // --- IMPORTANT: ONLY OPEN THE PAGE / POPUP HERE IF YOU USE AUTOOPTIONS IN IT! ---

    // get URL of the options HTML from the manifest file
    const page = chrome.runtime.getManifest().options_page; // full page
    const embedded = chrome.runtime.getManifest().options_ui.page; // embedded
    const popup = chrome.runtime.getManifest().action.default_popup; // popup

    // open and close the tab to create the default config
    createTab(popup);

    // OR use this if you have a welcome message (except for popups)
    chrome.runtime.openOptionsPage();
}

function createTab(tab) {
    chrome.tabs.create({
        url: tab
    });

    // the rest is handled in the JS file of the tab
}

options.js

The init method of AutoOptions returns a Promise. This allows you to perform actions after the initialization is complete. The Promise will resolve if the initialization is successful and reject if there is an error.

AutoOptions.init(options)
  .then(() => {
    // Initialization successful
  })
  .catch((error) => {
    // Error occurred during initialization
  });

The options parameter is an object containing the developer-defined options for AutoOptions.

To reset your inputs to the default configuration, you can use the resetToDefault method:

AutoOptions.resetToDefault();

To see if user just installed your extension, use AutoOptions.isFirstTime:

if (AutoOptions.isFirstTime) {
  // ...
}

script.js

This is an example on how to handle the configuration changes live.

const configName = 'page';
let configuration = {};

  chrome.storage.sync.get([configName]).then(storedConfiguration => {
    if (configName in storedConfiguration) {
      configuration = storedConfiguration[configName];
    } else {
      // fallback if configuration somehow wasn't created on extension install
      chrome.runtime.sendMessage("openOptions");
    };
  });

  // message listener
    chrome.storage.onChanged.addListener((storedConfiguration, storageType) => {
        const newConfig = storedConfiguration[configName].newValue;

        switch (storageType) {
            case 'sync':
                this.configuration = newConfig;
                break;
            case 'session':
                this.onConfigChange(newConfig);
                break;
        }
    });

    onConfigChange(updatedConfig) {
        const { category, setting } = updatedConfig;

        switch (category) {
            case 'ui':
                // your script
                break;
            case 'buttons':
                // your script
                break;
            case 'misc':
                // your script
                break;
            default:
                H.error.throwException(`${category} is an unknown configuration category!`);
                break;
        }
    }

HTML Inputs

AutoOptions automatically handles HTML inputs and validates them.

• Inputs that should be included must have an ID set.
• Radio inputs should also have a name set.

Supported input types and properties can be defined using the autooptions-* (or ao-) attribute. It provides a way to customize the behavior of input elements in the configuration process. It allows you to specify additional properties for each input, influencing how the configuration is handled.

1. autooptions-default: This attribute marks an input element as checked by default, applicable to radio buttons and checkboxes. Use this instead of "checked".

2. autooptions-value="": If an input requires a default value, you can specify it using this attribute. Use this instead of "value".

3. autooptions-category="": To group similar inputs under a category, add this attribute to the input.

4. autooptions-exclude: This attribute can be used to exclude specific inputs from the configuration process, ensuring they are not considered when saving the configuration.

Developer Options

The following developer options can be provided when initializing AutoOptions:

• configName: Specifies the type of options (accepted values: 'page', 'popup', 'site'). (Required)
• closeOptionsOnInstall: Specifies whether to close the options page after opening it in a new tab on install to save the configuration for the first time. Should be always true if options is popup, should be false if options page has a welcome message on first install. (Default value: true, Accepted values: true, false)
• applyChangesInstantly: Specifies whether changes made in options should take effect immediately. (Default value: true, Accepted values: true, false)

License

AutoOptions is licensed under the CC BY 4.0 license. You are free to use, modify, and distribute this library as long as you provide appropriate attribution to the original author (skyfighteer).