Icons

An icon is asked for by a name. Which drawing answers depends on the set in force: the one your application declared, or the one Whakerexa carries when yours says nothing of that name.

A set holds line drawings, images, or grounds — the textures laid on a plain background. It carries part of the names, or all of them, and it says which ones it carries.

What this is for, what it deliberately does not do, and why: icons-design.html.

What it looks like

These are asked for by name, on this page, from the set Whakerexa carries. Each button says what it stands for, and holds nothing else.

<button type="button" data-icon="back" aria-label="Back"></button>

Larger, by giving the room another value. The drawing does not change:

#that-button {
    --icon-width:  calc(var(--font-size) * 3);
    --icon-height: calc(var(--font-size) * 3);
}

And a name no set carries: the room stays empty, the console says the name, and the page holds.

<button type="button" data-icon="nothing-like-a-name">…</button>

The drawings of the framework

The reference set, the one a name falls back to when no other carries it. The page writes this panel itself, from Wexa.icons.carried(): it says what the set carries when the page is read, and not what it carried when this documentation was written.

Grounds

A ground covers a surface. It is asked for by name, in the same sets, and it designates nothing: nothing is said of it to whoever does not see it.

<section data-ground="diagonals">…</section>

This page shows itself with the set grounds, which carries these three and nothing else: the icons above it are answered by the reference set, name by name. A ground declared in a set that is not in force is never looked at — only the set in force and the reference one are.

These three are drawn in a grey that holds on a light page as on a dark one. A ground cannot take the color of what surrounds it: it is laid as an image, and an image is a document of its own, where currentColor means nothing. A set that draws for one mode only draws two grounds, and the page names the one it wants.

Declare a set

A set is declared where a page already says what it loads, on the tag of the loader. Each set is a name, a path, a form, and the names it carries:

<script src="wexa_statics/js/wexa.loader.js"
        data-base="wexa_statics/"
        data-icons="refine:icons/refine/:home.png,back.png,next.png
                    colored:icons/colored/:home.png"
        data-icons-fallback="refine"
        data-icons-default="colored"></script>

Where the set stands. The path 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: a set a page brings has no reason to stand under wexa_statics/, nor to be written as if it did. The same holds for data-themes, data-themes-base and data-extras.

Why the files are written. They are what lets a missing name fall back to the set of Whakerexa with no request at all. On a document opened from a disk a request is never answered, and on a served one it would cost a round trip for every name your set does not carry.

One set, several formats. A set is not held to one of them: you bring the files you have. An .svg is drawn as a line and takes the color of what surrounds it; anything else — .webp, .png, .jpg, .ico — is an image and keeps its own colors. Nothing else is read in the file, and nothing is converted.

data-icons-default names the set to show when the address names none. Without it, the set of Whakerexa is the one in force.

Which set answers for the others. Your sets are rarely all complete: one of them is, and the others draw a few names differently. data-icons-fallback names the complete one, and a name that the shown set does not carry is taken from it. Above, a page shown with colored draws home in colors and takes back and next from refine.

A name goes down a chain of two, and no more: the set shown, the set that answers for the others, then the set of Whakerexa. What none of the three carries is not drawn.

Ask for an icon

The attribute goes on the element that already carries the meaning — a button, a link, a heading — and never on an element written for the icon alone. What the icon stands for is said by that element, and the drawing is put inside it:

<button type="button" data-icon="house" aria-label="Home"></button>

<a href="index.html" data-icon="back">Back to the index</a>

A surface asks for a ground the same way, on the section it covers:

<section data-ground="paper">…</section>

The room the icon takes is declared once, and holds for every set: were it to come from the drawing, changing the set in force would move what surrounds it. An icon is not always square — a set of flags is not a set of arrows — so the room is declared in both dimensions. They are variables, written in a stylesheet and not on the element; their default suits a text:

#menu-button {
    --icon-width:  calc(var(--font-size) * 1.6);
    --icon-height: calc(var(--font-size) * 1.6);
}

A drawing whose proportions are not those of the room is held inside it, and never stretched to it. And an image is given that room as its width and its height, so that nothing waits for the file to know how much space it will take — which is what the RGESN asks, and what keeps the page from moving under the reader.

Accessibility. An icon says nothing to a screen reader: what it stands for is written on what holds it — the text of a link, the aria-label of a button that holds nothing else. The attribute goes on that element. A ground stands for nothing and is never announced.

A line drawing holds in dark mode and in high contrast, since it takes the color of what surrounds it. An image keeps the colors it was drawn with: read it in the three themes before you bring it.

Change the set

The set in force is read in the address, as the theme is, so a choice holds from one page of a document to the next:

index.html?wexa_icons=child

From a page, the reader changes it without the page being loaded again. Only what is on the screen is asked for again:

<button type="button" onclick="Wexa.icons.show('child')">Child</button>

The JavaScript API

A name no set carries draws nothing, keeps the room, says the name in the console, and breaks no page.

A document read from a disk

A document opened without a server cannot go and get a file: a browser refuses to read one there. The drawings of Whakerexa are gathered into the bundle when it is built; the drawings of your sets are gathered the same way, into one file you write beside your page. Add it anywhere in the page, and the loader pours it in before answering the first demand:

<script src="wexa_icons.js"></script>

What that file holds. One list on the namespace of the framework, one entry per drawing: the name of the set, the name the drawing answers to — its file without its extension — and the drawing itself. Nothing else is read in it. The file may be loaded before Whakerexa, so it makes the namespace if it is not there yet. Written by hand or by a tool of your own, it is answered the same way, so a page that never runs the script says as much as one that does. A file written by an older build, which left the list under a name of its own, is read all the same:

window.Wexa = window.Wexa || {};
window.Wexa.gatheredIcons = [
    ["child", "home", "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 32 32\" …>…</svg>"],
    ["child", "back", "<svg …>…</svg>"],
    ["adult", "home", "<svg …>…</svg>"]
];

The name of the set is the one declared on the loader, and the name of the drawing the one a page asks for. A set gathered this way still declares its files on the loader: the list says what exists, the gathering says what it looks like.

Only line drawings are gathered, and only they need it: they are written into the page. An image is never read — its address is what answers, and a document read from a disk finds it beside itself. Grounds are in that case too.

Without that step, your line drawings answer on a served document and the set of Whakerexa answers on a local one.