kbin-mod-options

Description

The purpose of this script is to allow mods to more easily implement settings.

Functionality

Header

kmoAddHeader(<modName>, <{author: 'name', version: 'versionNumber', license: 'licenseType', url: 'modUrl'}>);

  • modName - required
  • info object - optional

Example

const settingHeader = kmoAddHeader(
    'kbin-mod-options examples',
    {
        author: 'Ori',
        version: '0.1',
        license: 'MIT',
        url: 'https://github.com/Oricul'
    }
);

Header Example

Toggle Switch

kmoAddToggle(<headerChildDiv>, <settingLabel>, <settingValue>, <settingDescription>);

  • headerChildDiv - required
  • settingLabel - required
  • settingValue - required
  • settingDescription - optional

Example

// Create toggle switch
const settingEnabled = kmoAddToggle(
    settingHeader,
    'Enabled',
    true,
    'Turns this mod on or off.'
);
// Listen for toggle
settingEnabled.addEventListener("click", () => {
    // Log enabled state to console.
    console.log( kmoGetToggle(settingEnabled) );
});

Toggle Switch Example

Drop-Down

kmoAddDropDown(<headerChildDiv>, <settingLabel>, <[{name: 'friendlyName', value: 'backendValue'},{name: 'friendlyNameTwo', value: 'backendValueTwo'}]>, <currentSetting>, <settingDescription>);

  • headerChildDiv - required
  • settingLabel - required
  • options array - required
  • name/value in options array - required
  • currentSetting - required
  • settingDescription - optional

Example

// Create drop down
const font = kmoAddDropDown(
    settingHeader,
    'Font',
    [
        {
            name: 'Arial',
            value: 'font-arial'
        },{
            name: 'Consolas',
            value: 'font-consolas'
        }
    ],
    'font-consolas',
    'Choose a font for kbin.'
);
// Listen for drop down change
font.addEventListener("change", () => {
    // Log drop down selection to console.
    console.log( kmoGetDropDown(font) );
});

Drop-Down Example

Button

kmoAddButton(<headerChildDiv>, <settingLabel>, <buttonLabel>, <settingDescription>);

  • headerChildDiv - required
  • settingLabel - required
  • buttonLabel - required
  • settingDescription - optional

Example

// Create button const
const resetButton = kmoAddButton(
    settingHeader,
    'Default Settings',
    'Reset',
    'Resets settings to defaults.'
);
// Listen for button press.
resetButton.addEventListener("click", () => {
    // Log press to console.
    console.log( 'button pressed!' );
});

Button Example

Color Dropper

kmoAddColorDropper(<headerChildDiv>, <settingLabel>, <currentColor>, <settingDescription>);

  • headerChildDiv - required
  • settingLabel - required
  • currentColor - required
  • settingDescription - optional

Example

// Create color dropper const
const primaryColor = kmoAddColorDropper(
    settingHeader,
    'Primary Color',
    '#0ff',
    'Select primary theme color'
);
// Listen for new color change
primaryColor.addEventListener("change", () => {
    // Log color selection out to console.
    console.log( primaryColor.value );
});

Color Dropper Example

Usage

Simply add kbin-mod-options to your script’s requires.

// @require    https://github.com/Oricul/kbin-scripts/raw/main/kbin-mod-options.js

Example

// ==UserScript==
// @name         kbin-mod-options-dev
// @namespace    https://github.com/Oricul
// @version      0.1
// @description  Attempt at standardizing mod options.
// @author       0rito
// @license      MIT
// @match        https://kbin.social/*
// @match        https://kbin.sh/*
// @icon         https://kbin.social/favicon.svg
// @grant        none
// @require      file://H:/GoogleDrive/Personal/Documents/GitHub/kbin-scripts/kbin-mod-options.js
// ==/UserScript==

(function() {
    'use strict';

    // Section header - kmoAddHeader(<modName>, {author: 'name', version: 'versionNumber', license: 'licenseType', url: 'modUrl'});
    // modName - required, author - optional, version - optional, license - optional, url - optional
    const settingHeader = kmoAddHeader(
        'kbin-mod-options examples',
        {
            author: 'Ori',
            version: '0.1',
            license: 'MIT',
            url: 'https://github.com/Oricul'
        }
    );
    // Toggle switch - kmoAddToggle(<settingLabel>, <settingValue>, <settingDescription>);
    // settingLabel - required, settingValue - required, settingDescription - optional
    const settingOne = kmoAddToggle(
        settingHeader,
        'Enabled',
        true,
        'Turn this mod on or off.'
    );
    // Listener for toggle switch - kmoGetToggle(<toggleSwitchVar>);
    // toggleSwitchVar - required
    settingOne.addEventListener("click", () => {
            console.log(kmoGetToggle(settingOne));
    });
    // Dropdown Menu - kmoAddDropDown(<settingLabel>, [{name: 'name', value: 'value'},{name: 'name2', value: 'value2'}], <currentSetting>, <settingDescription>);
    // settingLabel - required, name & value - required, currentSetting - required, settingDescription - optional
    const settingTwo = kmoAddDropDown(
        settingHeader,
        'Font',
        [
            {
                name: 'Arial',
                value: 'font-arial'
            },{
                name: 'Consolas',
                value: 'font-consolas'
            }
        ],
        'font-consolas',
        'Choose a site-wide font.');
    // Listener for dropdown menu - kmoGetDropDown(<dropDownVar>);
    // dropDownVar - required
    settingTwo.addEventListener("change", () => {
        console.log(kmoGetDropDown(settingTwo));
    });
    // Button - kmoAddButton(<settingLabel>, <buttonLabel>, <settingDescription>);
    // settingLabel - required, buttonLabel - required, settingDescription - optional
    const settingThree = kmoAddButton(
        settingHeader,
        'Default Settings',
        'Reset',
        'Resets settings to defaults.'
    );
    // Listener example for buttons.
    settingThree.addEventListener("click", () => {
        console.log('button pressed');
    });
    // Color Dropper - kmoAddColorDropper(<settingLabel>, <currentColor>, <settingDescription>);
    // settingLabel - required, currentColor - required, settingDescription - optional
    const settingFour = kmoAddColorDropper(
        settingHeader,
        'Primary Color',
        '#0ff',
        'Select primary color for style.'
    );
    // Listener example for color dropper.
    settingFour.addEventListener("change", () => {
        console.log(settingFour.value);
    });
})();

  • Version 0.2.2 released.

    I noticed that KUP (Kbin Usability Pack) 0.2.1 by @Perry added some settings refactoring that hides the old .settings-list instead of updating in place. This unfortunately has a side-effect of causing script’s settings that are slower, or wait on DOM to load, to be hidden instead of displayed with their new refactor.

    In order to prevent this issue in the future, I’ve updated to create our own DIV and simply append it to the #settings.section DIV instead. Without KUP, you’ll notice no difference in how settings are displayed from version 0.2.1, but if you’re using KUP, it currently puts your options section at the top of the new section created by KUP. I imagine this will change if KUP moves to prepend instead of append. In my view, mod options should have always been last in any settings list solution, so I do hope that change is made at the very least.

    •  Perry   ( @Perry@kbin.social ) 
      link
      fedilink
      2
      edit-2
      1 year ago

      And you’re absolutely right! For some reason that I can’t remember now, that wasn’t included at release, but it should definitely wait for everything to load before mutating the settings. I’ve thrown together a fix that should make it actually wait for the document to load and an additional 100ms before running.

      I’ll probably have a release out later this evening.

      Edit: I’ve also added a Compatibility Mode option to make KUP play nicer with other scripts that customise the settings panel. It will simply append the new settings to the end of the panel. I’ve attached an image of how it looks like.

      Edit: I’ve released KUP 0.2.2 with the aforementioned fixes. https://kbin.social/m/kbinStyles/t/105421/Kbin-Usability-Pack-0-2-2-Now-with-settings. I’ve also made sure to add any enabled KUP setting as a class to the body of the document (e.g. “KUP-setting-settingsCompatibilityMode”) as well as “KUP-injected” when KUP is installed. I’ve also added the object document.KUP that additionally serves as a carrier of future KUP endpoints (or to just check if KUP is installed).

      • Just took a look. With the previous version of kmo, it does in fact work when compatibility mode is enabled. I think that’s probably the best solution to hope for without slowing down your own enhancements to the point of being a visual hindrance. Thanks for taking a look.

        I just need to up my visual appearance game now. Your dropdown appearance and effect is much more visually appealing and while my implementation is meant to make mod options more accessible for would-be devs, it would be ideal to make it visually appealing as well.