pardus-options-library 2.7.0

package/src/classes/description-element.js

@@ -0,0 +1,80 @@
+import HtmlElement from './html-element.js';
+
+/**
+ * Controls the description for a specific OptionsBox, only one description per OptionsBox permitted
+ * @private
+ */
+export default class DescriptionElement extends HtmlElement {
+    constructor({
+        id,
+        description = '',
+        imageLeft = '',
+        imageRight = '',
+    }) {
+        super(id);
+        this.backContainer = '';
+        this.description = description;
+        this.imageLeft = imageLeft;
+        this.imageRight = imageRight;
+        this.alignment = '';
+        this.frontContainer = {
+            styling: 'style="display: none;"',
+            id: '',
+            setId(idToSet) {
+                this.id = idToSet;
+            },
+            setStyle(style) {
+                this.styling = `style="${style}"`;
+            },
+            toString() {
+                return '';
+            },
+        };
+        this.frontContainer.setId(id);
+    }
+
+    addImageLeft(imageSrc) {
+        this.imageLeft = imageSrc;
+        this.refreshElement();
+    }
+
+    addImageRight(imageSrc) {
+        this.imageRight = imageSrc;
+        this.refreshElement();
+    }
+
+    setDescription(description) {
+        this.description = description;
+        this.refreshElement();
+    }
+
+    setAlignment(alignment) {
+        this.alignment = alignment;
+        this.refreshElement();
+    }
+
+    toString() {
+        let html = `<tr id=${this.id} style=''><td><table><tbody><tr>`;
+
+        if (this.imageLeft && this.imageLeft !== '') {
+            html = `${html}<td><img src="${this.imageLeft}"></td>`;
+        }
+
+        // If there's no specific alignment, work out the most ideal one to use
+        if (this.alignment === '') {
+            if (this.imageLeft === '' && this.imageRight === '') {
+                html = `${html}<td align="left">${this.description}</td>`;
+            } else {
+                html = `${html}<td align="center">${this.description}</td>`;
+            }
+        } else {
+            html = `${html}<td align="${this.alignment}">${this.description}</td>`;
+        }
+
+        if (this.imageRight && this.imageRight !== '') {
+            html = `${html}<td><img src="${this.imageRight}"></td>`;
+        }
+
+        return `${html}</tr></tbody></table></td></tr>`;
+    }
+}

package/src/classes/disableable-html-element.js

@@ -0,0 +1,48 @@
+import HtmlElement from './html-element.js';
+
+/**
+ * @class DisableableHtmlElement
+ * @extends HtmlElement
+ * @abstract
+ */
+export default class DisableableHtmlElement extends HtmlElement {
+    /**
+     * Create an HTML element that can be disabled
+     * @param {object} params Object containing parameters
+     * @param {string} params.id The id of the string. Must be unique.
+     * @param {boolean} params.disabled Whether the element is disabled or not
+     */
+    constructor({
+        id,
+        disabled = false,
+    }) {
+        super(id);
+        this.disabled = disabled;
+    }
+
+    /**
+     * Disables this element and all nested elements
+     * @function DisableableHtmlElement#disable
+     */
+    disable() {
+        this.setDisabled(true);
+        this.refreshElement();
+    }
+
+    /**
+     * Enables this element and all nested elements
+     * @function DisableableHtmlElement#enable
+     */
+    enable() {
+        this.setDisabled(false);
+        this.refreshElement();
+    }
+
+    /**
+     * Allows disabling or enabling ths element and all nested elements without refreshing
+     * @function DisableableHtmlElement#setDisabled
+     */
+    setDisabled(disabled = false) {
+        this.disabled = disabled;
+    }
+}

package/src/classes/html-element.js

@@ -0,0 +1,189 @@
+/**
+ * @class HtmlElement
+ */
+export default class HtmlElement {
+    /**
+     * @constructor HtmlElement
+     * @param {string} id HTML identifier for the element. Must be globally unique.
+     */
+    constructor(id) {
+        // Make sure it is a valid html identifier
+        if (!id || id === '') {
+            throw new Error('Id cannot be empty.');
+        }
+        const validIds = /^[a-zA-Z][\w:.-]*$/;
+        if (!validIds.test(id)) {
+            throw new Error(`Id '${id}' is not a valid HTML identifier.`);
+        }
+
+        this.id = id;
+        this.afterRefreshHooks = [];
+        this.beforeRefreshHooks = [];
+    }
+
+    /**
+     * Add an event listener to the element
+     * @function HtmlElement#addEventListener
+     * @param {string} eventName Name of the event to listen for
+     * @param {function} listener Listener to call when the event fires
+     */
+    addEventListener(eventName, listener, opts = false) {
+        if (this.getElement()) {
+            this.getElement().addEventListener(eventName, listener, opts);
+        }
+
+        if (opts && Object.hasOwn(opts, 'ephemeral') && opts.ephemeral) {
+            return;
+        }
+
+        this.addAfterRefreshHook(() => {
+            if (this.getElement()) {
+                this.getElement().addEventListener(eventName, listener, opts);
+            }
+        });
+    }
+
+    /**
+     * Remove an event listener from the element
+     * @function HtmlElement#removeEventListener
+     * @param {string} eventName Name of the event to listen for
+     * @param {function} listener Listener to call when the event fires
+     */
+    removeEventListener(eventName, listener) {
+        if (this.getElement()) {
+            this.getElement().removeEventListener(eventName, listener);
+        }
+    }
+
+    /**
+     * Return a string representation of the html element
+     * @function HtmlElement#toString
+     * @returns {string} String representation of the html element
+     */
+    toString() {
+        return `<div id='${this.id}'></div>`;
+    }
+
+    /**
+     * Run all hooks that should be called prior to refreshing the element
+     * @function HtmlElement#beforeRefreshElement
+     */
+    beforeRefreshElement() {
+        for (const func of this.beforeRefreshHooks) {
+            func();
+        }
+    }
+
+    /**
+     * Run all hooks that should be called after refreshing the element
+     * @function HtmlElement#afterRefreshElement
+     * @param {object} opts Optional arguments to be passed to the hooks
+     */
+    afterRefreshElement(opts = {}) {
+        for (const func of this.afterRefreshHooks) {
+            func(opts);
+        }
+    }
+
+    /**
+     * Add a hook to run after the element is refreshed
+     * @function HtmlElement#addAfterRefreshElement
+     * @param {function} func Function to call after the element is refreshed
+     */
+    addAfterRefreshHook(func) {
+        this.afterRefreshHooks.push(func);
+    }
+
+    /**
+     * Refresh the element in the dom
+     * @function HtmlElement#refreshElement
+     */
+    refreshElement() {
+        this.beforeRefreshElement();
+        this.getElement().replaceWith(this.toElement());
+        this.afterRefreshElement();
+    }
+
+    /**
+     * Gets how much the element should be offset from the top of the DOM
+     * @function HtmlElement#getOffsetTop
+     * @returns {integer} Pixels the element is offset from the top of the DOM
+     */
+    getOffsetTop() {
+        let currentOffset = this.getElement().offsetTop + this.getElement().offsetHeight;
+        let parent = this.getElement().offsetParent;
+
+        while (parent !== null) {
+            currentOffset += parent.offsetTop;
+            parent = parent.offsetParent;
+        }
+
+        return currentOffset;
+    }
+
+    /**
+     * Gets how much the element should be offset from the left of the DOM
+     * @function HtmlElement#getOffsetLeft
+     * @returns {integer} Pixels the element is offset from the left of the DOM
+     */
+    getOffsetLeft() {
+        let currentOffset = this.getElement().offsetLeft;
+        let parent = this.getElement().offsetParent;
+
+        while (parent !== null) {
+            currentOffset += parent.offsetLeft;
+            parent = parent.offsetParent;
+        }
+
+        return currentOffset;
+    }
+
+    /**
+     * Gets the element
+     * @function HtmlElement#getElement
+     * @returns {element} Element
+     */
+    getElement() {
+        return document.getElementById(this.id);
+    }
+
+    /**
+     * Creates the element within the DOM from the string representation
+     * @function HtmlElement#toElement
+     * @returns {element} Element
+     */
+    toElement() {
+        const template = document.createElement('template');
+        template.innerHTML = this.toString();
+        return template.content.firstChild;
+    }
+
+    /**
+     * Appends a child element to the element within the DOM
+     * @function HtmlElement#appendChild
+     * @param {element} child The child to append
+     * @returns {element} The child element
+     */
+    appendChild(ele) {
+        return document.getElementById(this.id).appendChild(ele);
+    }
+
+    /**
+     * Appends a child element to the element if it was a table within the DOM
+     * @function HtmlElement#appendTableChild
+     * @param {element} child The child to append
+     * @returns {element} The child element
+     */
+    appendTableChild(ele) {
+        return document.getElementById(this.id).firstChild.appendChild(ele);
+    }
+
+    /**
+     * Sets the innerHTML property of the element
+     * @function HtmlElement#setHTML
+     * @param {html} html to set inside the element
+     */
+    setHTML(html) {
+        this.innerHtml = html;
+    }
+}

package/src/classes/info-element.js

@@ -0,0 +1,56 @@
+import HtmlElement from './html-element.js';
+import PardusOptionsUtility from './pardus-options-utility.js';
+import PardusOptions from './pardus-options.js';
+
+/**
+ * @class InfoElement
+ * @extends HtmlElement
+ */
+export default class InfoElement extends HtmlElement {
+    /**
+     * @constructor InfoElement
+     * @param {string} id HTML identifier for the element. Must be globally unique.
+     * @param {string} description Text to display in the InfoElement box
+     * @param {string} title Title to display at the top of the InfoElement box
+     * @param {string} [tipBoxPosition=right] The direction the InfoElement should appear in. Either 'right' or 'left'
+     */
+    constructor({
+        id,
+        description,
+        title,
+        tipBoxPosition = 'right',
+    }) {
+        super(id);
+        this.description = description;
+        this.title = title;
+        this.tipBoxPosition = tipBoxPosition;
+
+        this.addEventListener('mouseover', () => {
+            this.tipBox = PardusOptions.getDefaultTipBox();
+            this.tipBox.setContents({
+                title: this.title,
+                contents: this.description,
+            });
+
+            this.tipBox.setPosition({
+                element: this,
+                position: this.tipBoxPosition,
+            });
+
+            this.tipBox.show();
+        });
+
+        this.addEventListener('mouseout', () => {
+            this.tipBox.hide();
+        });
+    }
+
+    /**
+     * Return a string representation of the InfoElement
+     * @function HtmlElement#toString
+     * @returns {string} String representation of the InfoElement
+     */
+    toString() {
+        return `<a id="${this.id}" href="#" onclick="return false;"><img src="${PardusOptionsUtility.getImagePackUrl()}info.gif" class="infoButton" alt=""></a>`;
+    }
+}

package/src/classes/options/abstract-array-option.js

@@ -0,0 +1,38 @@
+import AbstractOption from './abstract-option.js';
+import PardusOptionsUtility from '../pardus-options-utility.js';
+
+export default class AbstractArrayOption extends AbstractOption {
+    constructor({
+        id,
+        variable,
+        description,
+        defaultValue = [],
+        saveFunction = PardusOptionsUtility.defaultSaveFunction,
+        getFunction = PardusOptionsUtility.defaultGetFunction,
+    }) {
+        super({
+            id,
+            variable,
+            description,
+            defaultValue,
+            saveFunction,
+            getFunction,
+        });
+    }
+
+    toString() {
+        return `<tr id="${this.id}"><td>${this.description}</td><td>${this.getInnerHTML()}</td></tr>`;
+    }
+
+    getInnerHTML() {
+        let html = '<table><tbody>';
+        const currentValues = this.getValue();
+
+        for (const value of currentValues) {
+            html += `<tr><td><input type="text" value="${value}"></td><td><input type="button" value="-"></td></tr>`;
+        }
+        html += '<tr><td><input type="text" value=""></td><td><input type="button" value="+"></td></tr>';
+        html += '</tbody></table>';
+        return html;
+    }
+}

package/src/classes/options/abstract-option.js

@@ -0,0 +1,189 @@
+import DisableableHtmlElement from '../disableable-html-element.js';
+import InfoElement from '../info-element.js';
+import PardusOptionsUtility from '../pardus-options-utility.js';
+
+/**
+ * @class AbstractOption
+ * @extends DisableableHtmlElement
+ * @abstract
+ */
+export default class AbstractOption extends DisableableHtmlElement {
+    constructor({
+        id,
+        variable,
+        description = '',
+        defaultValue = false,
+        saveFunction = PardusOptionsUtility.defaultSaveFunction,
+        getFunction = PardusOptionsUtility.defaultGetFunction,
+        shallow = false,
+        reverse = false,
+        info = null,
+        disabled = false,
+        styleExtra = '',
+        align = 'left',
+    }) {
+        super({
+            id,
+            disabled,
+        });
+        this.variable = variable;
+        this.saveFunction = saveFunction;
+        this.getFunction = getFunction;
+        this.description = description;
+        this.info = info;
+        this.defaultValue = defaultValue;
+        this.inputId = `${this.id}-input`;
+        this.shallow = shallow;
+        this.reverse = reverse;
+        this.styleExtra = styleExtra;
+        this.colour = '#D0D1D9';
+        this.backgroundColour = '#00001C';
+        this.align = align;
+
+        if (this.disabled) {
+            this.colour = '#B5B5B5';
+            this.backgroundColour = '#CCCCCC';
+        }
+
+        this.style = `color: ${this.colour};background-color: ${this.backgroundColour};${this.styleExtra}`;
+
+        if (this.info !== null) {
+            this.infoElement = new InfoElement({
+                id: `${this.id}-info`,
+                description: this.info.description,
+                title: this.info.title,
+            });
+
+            this.addAfterRefreshHook(() => {
+                this.infoElement.afterRefreshElement();
+            });
+        } else {
+            this.infoElement = '';
+        }
+    }
+
+    toString() {
+        if (this.shallow) {
+            return `<td id='${this.id}'>${this.getInnerHTML()}<label>${this.description}</label>${this.infoElement}</td>`;
+        }
+        if (this.reverse) {
+            return `<tr id='${this.id}'><td>${this.getInnerHTML()}</td><td><label for='${this.inputId}'>${this.description}</label>${this.infoElement}</td></tr>`;
+        }
+
+        if (this.description === '') {
+            return `<tr id='${this.id}'><td col='2'>${this.getInnerHTML()}</td></tr>`;
+        }
+
+        return `<tr id='${this.id}'><td><label for='${this.inputId}'>${this.description}:</label>${this.infoElement}</td><td align='${this.align}'>${this.getInnerHTML()}</td></tr>`;
+    }
+
+    /**
+     * Get the inner HTML of the options element
+     * @abstract
+     * @function AbstractOption#getInnerHTML
+     * @returns {string} Inner HTML of the options element
+     */
+    getInnerHTML() {
+        return '';
+    }
+
+    /**
+     * Gets the last-saved value of the options element
+     * @function AbstractOption#getValue
+     * @returns {type} Last-saved value of the options element
+     */
+    getValue(overrideGetFunction = null) {
+        if (overrideGetFunction && typeof overrideGetFunction === 'function') {
+            return overrideGetFunction(`${PardusOptionsUtility.getVariableName(this.variable)}`, this.defaultValue);
+        }
+
+        return this.getFunction(`${PardusOptionsUtility.getVariableName(this.variable)}`, this.defaultValue);
+    }
+
+    /**
+     * Gets the current value of the options element
+     * @abstract
+     * @function AbstractOption#getCurrentValue
+     * @returns {type} Value of the options element
+     */
+    getCurrentValue() {
+        return null;
+    }
+
+    /**
+     * Gets the input element for the option
+     * @function AbstractOption#getInputElement
+     * @returns {object} Input element
+     */
+    getInputElement() {
+        return document.getElementById(this.inputId);
+    }
+
+    /**
+     * Resets the saved value of the options element to its default
+     * @function AbstractOption#resetValue
+     */
+    resetValue() {
+        this.saveFunction(`${PardusOptionsUtility.getVariableName(this.variable)}`, this.defaultValue);
+    }
+
+    /**
+     * Saves the current value of the options element
+     * @function AbstractOption#saveValue
+     */
+    saveValue(overrideSaveFunction = null) {
+        if (overrideSaveFunction && typeof overrideSaveFunction === 'function') {
+            overrideSaveFunction(`${PardusOptionsUtility.getVariableName(this.variable)}`, this.getCurrentValue());
+        } else if (!this.disabled) {
+            this.saveFunction(`${PardusOptionsUtility.getVariableName(this.variable)}`, this.getCurrentValue());
+        }
+    }
+
+    refreshStyle() {
+        this.style = `color: ${this.colour};background-color: ${this.backgroundColour};${this.styleExtra}`;
+        if (this.getInputElement()) {
+            this.getInputElement().setAttribute('style', this.style);
+        }
+    }
+
+    /**
+     * Disables the input element
+     * @function AbstractOption#disable
+     */
+    disable() {
+        this.setDisabled(true);
+        if (this.getInputElement()) {
+            this.getInputElement().setAttribute('disabled', '');
+            this.getInputElement().setAttribute('style', this.style);
+        }
+    }
+
+    /**
+     * Enables the input element
+     * @function AbstractOption#enable
+     */
+    enable() {
+        this.setDisabled(false);
+        if (this.getInputElement()) {
+            this.getInputElement().removeAttribute('disabled');
+            this.getInputElement().setAttribute('style', this.style);
+        }
+    }
+
+    setDisabled(disabled = false) {
+        this.disabled = disabled;
+        if (this.disabled) {
+            this.colour = '#B5B5B5';
+            this.backgroundColour = '#CCCCCC';
+        } else {
+            this.colour = '#D0D1D9';
+            this.backgroundColour = '#00001C';
+        }
+        this.style = `color: ${this.colour};background-color: ${this.backgroundColour};${this.styleExtra}`;
+    }
+
+    loadValue(value) {
+        this.getInputElement().value = value;
+        this.saveValue();
+    }
+}

package/src/classes/options/boolean-option.js

@@ -0,0 +1,24 @@
+import AbstractOption from './abstract-option.js';
+
+/**
+ * @class BooleanOption
+ * @extends AbstractOption
+ */
+export default class BooleanOption extends AbstractOption {
+    getInnerHTML() {
+        let checkedStatus = '';
+        if (this.getValue() === true) {
+            checkedStatus = ' checked';
+        }
+        return `<input id="${this.inputId}" type="checkbox"${checkedStatus} style="${this.style}" ${this.disabled ? 'disabled' : ''}>`;
+    }
+
+    /**
+     * Gets the current value of the boolean options element
+     * @function BooleanOption#getCurrentValue
+     * @returns {boolean} Value of the boolean options element
+     */
+    getCurrentValue() {
+        return this.getInputElement().checked;
+    }
+}

package/src/classes/options/grouped-options.js

@@ -0,0 +1,61 @@
+import HtmlElement from '../html-element.js';
+import BooleanOption from './boolean-option.js';
+import PardusOptionsUtility from '../pardus-options-utility.js';
+
+export default class GroupedOptions extends HtmlElement {
+    constructor({
+        id,
+        description,
+        saveFunction = PardusOptionsUtility.defaultSaveFunction,
+        getFunction = PardusOptionsUtility.defaultGetFunction,
+    }) {
+        super(id);
+        this.description = description;
+        this.saveFunction = saveFunction;
+        this.getFunction = getFunction;
+        this.options = [];
+    }
+
+    toString() {
+        return `<tr id="${this.id}"><td>${this.description}</td><td>${this.getInnerHTML()}</td></tr>`;
+    }
+
+    getInnerHTML() {
+        let html = '<table><tbody><tr>';
+        for (const option of this.options) {
+            html += option;
+        }
+        html += '</tr></tbody></table>';
+        return html;
+    }
+
+    saveValue() {
+        for (const option of this.options) {
+            option.saveValue();
+        }
+    }
+
+    addBooleanOption({
+        variable,
+        description,
+        defaultValue = false,
+        saveFunction = this.saveFunction,
+        getFunction = this.getFunction,
+    }) {
+        const booleanOptions = {
+            id: `${this.id}-option-${this.options.length}`,
+            variable,
+            description,
+            defaultValue,
+            saveFunction,
+            getFunction,
+            shallow: true,
+        };
+
+        const newBooleanOption = new BooleanOption(booleanOptions);
+
+        this.options.push(newBooleanOption);
+        this.refreshElement();
+        return newBooleanOption;
+    }
+}