Panel API: JS

[taufik-nurrohman]

This article is a draft and will be moved to the official web site when the API is matured.

To prevent conflicts with third-party libraries, all JavaScript features related to Panel need to be contained in global variable _.

Dialog

_.dialog(content: string|Array|Node|NodeList, then?: Function): Promise

Spawn a basic dialog box with overlay.

_.dialog('<p>This is a dialog box.</p>').then(function (value) {
    console.log('Current value: ' + JSON.stringify(value));
    console.log(this);
}).catch(console.info);

const content = document.createElement('p');
content.textContent = 'This is a dialog box.';

function onClick() { … }

function then(open) {
    if (open) {
        content.addEventListener('click', onClick);
    } else {
        content.removeEventListener('click', onClick);
    }
}

_.dialog(content, then).then( … ).catch( … );

_.dialog.alert(description: string): Promise

Spawn an alert dialog box with overlay.

_.dialog.alert('Hey!').then(value => {
    console.info('OK button was clicked.');
    console.info('Current value: ' + JSON.stringify(value));
}).catch(console.info);

_.dialog.confirm(description: string): Promise

Spawn a confirmation dialog box with overlay.

_.dialog.confirm('Are you sure?').then(value => {
    if (true === value) {
        console.info('OK button was clicked.');
    } else if (false === value) {
        console.info('Cancel button was clicked.');
    } else if (null === value) {
        console.info('Escaped.');
    }
    console.info('Current value: ' + JSON.stringify(value));
}).catch(console.info);

_.dialog.prompt(key: string, value?: string): Promise

Spawn a prompt dialog box with overlay.

_.dialog.prompt('Type in your name below:', "").then(value => {
    if (false === value) {
        console.info('Cancel button was clicked.');
    } else if (null === value) {
        console.info('Escaped.');
    } else {
        console.info('Your name is: ' + JSON.stringify(value));
    }
}).catch(console.info);

Hook

_.fire(hook: string, data?: Array): Window

_.fire('change.tab', ['the value', 'the key']);

_.off(hook: string, context?: Function): Window

// Remove all hook(s) from `change.tab`
_.off('change.tab');

// Remove hook `onChangeTab` from `change.tab`
_.off('change.tab', onChangeTab);

_.on(hook: string, then: Function): Window

_.on('change.tab', function (value, key) {
    console.log([this, value, key]);
});

function onChangeTab(value, key) {
    console.log([this, value, key]);
}

_.on('change.tab', onChangeTab);

Name	Description
change	Will be triggered every time the page changes. This event is not available by default in the panel but developers planning to implement AJAX feature may need to execute this event to ensure that other components that depend on JavaScript events such as x\panel\type\menu(), x\panel\type\stacks() and x\panel\type\tabs() can work properly when those components are rendered by AJAX call.
change.stack	Will be triggered every time a stack’s trigger is clicked.
change.tab	Will be triggered every time a tab’s trigger is clicked.

Once the component is loaded by AJAX call, make sure to trigger the change event:

const desk = document.querySelector('.lot\\:desk');
const template = document.createElement('template');
fetch('/panel/get/page/1?query=foo+bar').then(response => response.text()).then(text => {
    template.innerHTML = text;
    desk.innerHTML = template.content.querySelector('.lot\\:desk').innerHTML;
    _.fire('change'); // Trigger the `change` event!
});

Event consumers can then re-execute their DOM manipulation tasks via this change event:

function onChange() {
    const titles = document.querySelectorAll('.title');
    titles.forEach(title => (title.style.color = 'red'));
}

onChange(); // Execute on the first page visit

_.on('change', onChange); // Re-execute on every AJAX complete event

Keys

Global keyboard’s key maps.

_.keys['Control-s'] = function () {
    console.log('Save');
    return false;
};

// NOTE: `S` needs to be in upper-case because `Shift` key is currently active
_.keys['Control-Shift-S'] = function () {
    console.log('Save as…');
    return false;
};

Commands

Global reusable commands. Usually will be used by the _.keys implementation.

_.commands.save = function () {
    // …
    return false;
};

_.commands.saveAs = function (name) {
    _.dialog.prompt('Save as…', name).then( … ).catch( … );
    // …
    return false;
};

_.keys['Control-s'] = 'save';
_.keys['Control-Shift-S'] = ['saveAs', ['file-name.txt']];