Toolbox Module Structure

This document aims to give a global overview of the toolbox module structure. Refer to the JSDoc code documentation for the most recent and more detailed information.

Example empty module

function exampleModule () {
    const self = new TB.Module('Developer Tools');
    self.shortname = 'DevTools';

    //Default settings
    self.settings['enabled']['default'] = true;

    // True if not specifically set to false here. 
    self.config['betamode'] = false;

    // Example setting
    self.register_setting('thisIsAboolean', { // setting name
        type: 'boolean', // Setting type
        default: false, // The default setting value.
        advanced: false, // If set to true the setting will not show up for the user unless the specifically enabled settings.
        title: 'The title the setting will have for the user',
    });

    self.register_setting('ThisIsASelector', { // setting name
        type: 'selector', // Setting type
        values: ['value', 'Other value', 'Third value'],
        default: 'value', // The default setting value.
        title: 'This is a selector setting',
    });

    // Module init
    self.init = function () {
        // Module functionality
    }

    // Register the module
    TB.register_module(self);
}

window.addEventListener('TBModuleLoaded', () => {
    exampleModule();
});

Execution Flow

const TB in tbmodule.js is the core extension object. It contains all methods (or at least references to them) and data needed to run the extension. It gets initialized right after const TBUtils, and includes a reference to TBUtils (TB.utils).

Module Creation

An extension is created by creating a new instance of the TB.Module object. You must pass in a full proper name, in Title Caps, e.g. const modButton = new TB.Module('Mod Button'); (and you must use the new keyword). By default, this full name is used to derive a short name (Module.shortname) with whitespace stripped, which is used in numerous places to identify the module, including as the module key in calls for settings and storage. This short name can be manually set to something different, simply set `Module.shortname = 'NewShortName'.

You then create all of that extension's functions, data attributes, etc. as properties of the new TB.Module object instance. The execution entry point into the module is called init(); this is what gets called if the module is enabled.

Once you're done (at the end of the module's file), you call TB.register_module(<moduleName>) to add that module object to the extension, e.g. TB.register_module(modButton);. Module init order is stored in TB.moduleList, which is updated in order of registration.

Settings

A module's settings allows us to specify a single default value, which is then picked up by the Module.setting() convenience method. You can also specify that a given setting should only be shown in beta mode (and/or developer mode, whatever that means), that a setting should be hidden altogether, what the text that goes next to the setting input should say, and what type of data it contains (which impacts how it's parsed and what <input> type is generated. At a minimum, every module has at least a setting called "enabled", example:

        self.settings['enabled']['default'] = true;

You don't need to specify this setting, and you probably shouldn't change any of its values, except to set the module enabled by default.

By default, a TB.Module instance is configured with the beta flag, which means it won't show up at all unless beta mode is enabled. You can change this simply by setting Module.config["betamode"] = false; as it's just a safety feature to prevent unfinished modules from somehow ending up in the regular user's vicinity.

To let a module know about a setting, simply call Module.register_setting(); the first argument is the name, the second argument is an object as shown in the module example code.

Module Structure, Conventions

A module's main code, to be called on page load, should be placed in Module.init(). Other helper methods specific to that module can be created as properties of the module alongside Module.init(). There are a few reserved names here: Module.name, Module.shortname, Module.settings, Module.settingsList (which contains the order for a module's settings), Module.config, and Module.setting.

Module.settings is an array of settings keyed on the setting name. The setting name should match the key used in localstorage. See above for a description of each setting.

Module.setting() is a convenience method which uses the module's shortname and setting default values to make it easier to write settings calls; it just wraps TB.utils.getSetting() and setSetting() (which alias to TBUtils) so you don't have to write the module name and the setting's default value every time.

Module.name and Module.shortname are pretty self-explanatory.

Module.init() gets called on page load if the module should be run (if it's enabled and beta settings are correct). Stick your main code in here.