JavaScript

Overview

The JavaScript of Whakerexa is a set of ES6 modules, one class per file, with no dependency and no build step. A single module gathers them: wexa.js imports the classes of the framework, exports them, and puts them under the global Wexa. A page loads that one file and has the whole API.

Each component has its own page in this documentation, with a living demonstration. This page describes what holds them together: how the API is loaded, what it contains, when the code runs, and the conventions a new module follows.

One entry, two ways to load it

ES6 modules are refused by a browser on file://. Whakerexa therefore ships the same code twice: the modules, and wexa.bundle.js, a single file that defines window.Wexa without any import. Both give the same names to a page.

<script type="module" src="wexa_statics/js/wexa.js"></script>

<script src="wexa_statics/js/wexa.bundle.js"></script>

<script src="wexa_statics/js/wexa.loader.js"
        data-base="wexa_statics/"></script>

<script src="wexa_statics/js/wexa.loader.js"
        data-base="wexa_statics/"
        data-default="wexa_theme"
        data-links="btn-back,nav-menu"></script>

A path a page writes — a theme, a set of icons, an extra — is read from data-base only when it is written bare, as the files of the framework are. One written ./ or ../ is read from the page, one written / from the root of the site, one carrying a scheme from its host.

<script>
    window.Wexa = window.Wexa || {};
    window.Wexa.logLevel = 'warning';
</script>

<script src="wexa_statics/js/wexa.loader.js" data-base="wexa_statics/"></script>

Once the page is open, Wexa.logger.setLogLevel('debug') changes it, for an author looking at what he is writing.

A page that has something of its own to start declares a function named bootPage: it is called once everything is loaded, and receives the namespace of the framework and the extras it asked for.

Two ways, and only two. Either the loader is asked for everything — it reads the protocol, registers the themes and the sets, and hands the namespace to bootPage —, or the page does the wiring itself: it names wexa.js or wexa.bundle.js, builds its ThemeManager, registers what it wants and declares its sets of icons. What must not be done is half of each: a theme registered after the loader has read the address is a name the manager has already refused.

What this is for, what it deliberately does not do, and why: logger-design.html for what the framework says, javascript-design.html for the rest.

What Wexa holds

The namespace makes a difference the framework maintains everywhere: a service that must exist exactly once is already built and answers under a lowercase name; a component a page may own several of is exposed as a class, under its own name.

Services, already built

Wexa.accessibility.switchColorScheme();
Wexa.dialog.open('dlg-about', true);
Wexa.logger.info('Page ready.');

Components, to be built

The classes behind the services are exported too, under their own name. A page that owns several navigation bars builds them itself, and a page that needs a second dialog manager is not forbidden one.

Code that waits for the page

A component looking for an element it decorates cannot run before that element exists. Wexa.onload holds the functions that wait, and runs them in the order they were given, once the document is loaded. The framework uses it for itself: wexa.js registers there what makes every data-href element reachable with the Tab key.

Wexa.onload.addLoadFunction(() => {
    const menu = new Wexa.MenuManager();
    menu.registerSubmenu('appmenu-framework', 'submenu-toggle-framework');
    menu.initMobileToggle();
});

Saying what happened

A module never writes into the console directly: it says it to the logger, which prefixes the message and drops it if it is below the level of the page. A level is a name as Python writes it, or the number that goes with it, and the default is 20 — information, warnings and errors are shown, debug messages are not. A page says its own before the loader, as above.

Wexa.logger.setLogLevel('debug');
Wexa.logger.debug('Slides: 57 pages laid out.');

Extras

The extras are not in Wexa: a page that does not display a bibliography has no reason to download the parser of one. They live in js/extras/ and are imported by the page that needs them. The bundle carries them all, so on file:// they are found under Wexa as well.

<script type="module">
    import { Book } from '../wexa_statics/js/extras/book.js';
    import { SortaTable } from '../wexa_statics/js/extras/sortatable.js';
    import { ThemeManager } from '../wexa_statics/js/customize/theme_manager.js';

    const themes = new ThemeManager();
    themes.register('wexa_theme', '../wexa_statics/css/themes/wexa_theme.css');
    themes.register('aurora',     '../wexa_statics/css/themes/wexa_theme_aurora.css');
</script>

Components speak through events

A component that has something to announce dispatches a CustomEvent on the document. The name carries its domain first, then what happened — slides:navigate, slides:viewmode, wexa:slides:ready. This is also what a keyboard shortcut may be given instead of a function.

const keyboard = new Wexa.KeyboardController();
keyboard.register({keys: ['ArrowRight'], action: 'page:next',
                   label: 'Next page', preventsDefault: true});
keyboard.init();

document.addEventListener('page:next', () => book.nextPage());

Conventions of a module

A new file of the framework is written like the ones already there. What follows is what they all do.

• One class per file, and the file is named after it. The class is exported by name; only a class a page owns a single one of is a default export.
• The banner of the license opens the file, then a JSDoc block describes the class, what it is for, and an @example of its use. Every public method is documented with its parameters and what it returns.
• The state of an instance is held in private fields, written with #. A member written with a leading underscore is internal too, but a class inheriting it may use it.
• What a class knows before existing is a static constant in capitals, at the top of the class: the tags it treats as interactive, the selector it looks for, the identifier it defaults to.
• Nothing is kept in localStorage. What has to survive a page carries itself in the URL, the way the color and contrast modes do with wexa_color and wexa_contrast.
• A threshold decided in JavaScript counts in font sizes, not in pixels: the text grows in contrast mode, and a number of pixels does not follow it.
• A class name is unique in the whole framework. The bundle concatenates every file into one scope, where two classes of the same name are one bug.