Specify icon for each artifact.


We need a way to indicate an icon for each artifact. There are many uses for icons, but particularly they are needed in generated menu items for artifacts.

A page will indicate its icon using the icon property in page metadata. The value will be in the form group/name, e.g. "fas/fa-home" or "material-icons/home" or "ion/home". Initially mummy:regenerate will have hard-coded recognition of Font Awesome and Material Icons (the first two examples). If no "group" is present, e.g. "⌂", the value itself is used.

A template can include an include an icon in a menu using mummy:regenerate by including <i></i> in the template text. This will be replaced with <span></span> using the page icon in the correct form. Initially mummy:regenerate will have hard-coded recognition of Font Awesome and Material Icons, and for literal font text.

(Note that it is debatable whether <i></i> or <span></span> is best for icons, but most seem to agree if not reluctantly that <i></i> is not correct. However it provides a good template replacement rather than inventing a new element. Note also that some tools like Blue Griffon break icons using <i></i>, so a workaround may be needed for editing the template with such an editor.)




Garret Wilson
January 9, 2020, 3:40 PM

So on the face of it, we may need to:

  • Distinguish between some icon identifier (e.g. "home") and a path/href to an icon (e.g. "fa-solid.svg#home").

  • Distinguish between an icon identifier (e.g. "home") and some actual Unicode code point serving as the icon, e.g. ⌂ (U+2302).

In the first case, however, might it still be better to indicate some name (e.g. fas/fa-home) and map that to the SVG (or to the webfont) based upon the configuration?

In the second case, perhaps the "name" could also indicate the actual Unicode code point if no icon type was specified.

So here is a tentative proposal:

  • The property icon is used to indicate the icon.

  • The value will be in the form group/name, e.g. "fas/fa-home" or "material-icons/home" or "ion/home". Initially mummy:regenerate will have hard-coded recognition of Font Awesome and Material Icons (the first two examples).

  • If no "group" is present, e.g. "⌂", the value itself is used.

  • Lastly if a path is wanted, an IRI can be provided; that is in XHTML <link> instead of <meta> can be used. (This would probably require some extra tricks to relocate the links from the source path to the target location, and then also to relativize to the referrer.)

That is the tentative path forward. The actual short term implementation is simply recognizing "fas/fa-home" or "material-icons/home", which should be pretty easy.

Garret Wilson
January 9, 2020, 3:19 PM

As CSS Tricks explained, using SVG "sprites" for icons will look something like this after including them in the page:

The FlatIcon site recommends something similar.

(Note that CSS Tricks now recommends just including the SVG.)

For Font Awesome SVG sprites, you link to part of a single SVG sprite file:

Garret Wilson
January 9, 2020, 2:08 PM

It should be pointed out that this approach for mummy:regenerate will only work with webfont icons. Here is a few approaches used by a few of the webfont libraries:

However there are arguments for using SVG instead of webfonts (see also this comparison and one person's reasons for switching). We may need to have Guise Mummy generate more complicated icon representations at some point. For future-proofing, we need to:

  • Find a way to concisely and semantically identify an icon, so that in the future we can render it as a webfont character reference or e.g. as an SVG sprite. Thus we need to concentrate on semantic identification and allow later mapping.

  • Implement some simple way in the near term to map the icon to web fonts, supporting Font Awesome and Material Icons for now using mummy:regenerate.

Garret Wilson
January 8, 2020, 5:18 PM

There is also the risk of over-engineering the mummy:regenerate facility. This was meant to make a lot of its own decisions about which text (the page label) to use, etc. It wasn't meant to be full-fledged templating system with expression replacement.

When we have expressions and iteration, we can forgo use of mummy:regenerate and do everything using expressions. But for mummy:regenerate, we can probably let it make most of the decision. We need merely to indicate that we want an icon. It may be stretching the semantics a bit, but we could use <i></i> as an icon placeholder:

Garret Wilson
January 8, 2020, 2:53 PM

The other question is how to define these. We could make the jump to an initial expression language implementation (although the replacement would be hard-coded), using something like this in the .template.xhtml file:

The first problem is that this is very speculative: we have little idea how the expression language will work, or more importantly what variables will be exposed. (It also raises the question of why we didn't use something like ^{nav-target.link} in the second case. Maybe we will in the future.)

Another idea would be to follow the current approach and create more of a template.

But how would the replacement engine know in advance that the <span> represents an icon to be replaced? We could use some icon class perhaps:

But if we are being consistent with our current template navigation regeneration approach, icon seems like a normal CSS class that should be left in as part of whatever CSS framework we are using.

Maye we need something higher-level and more semantic—something to indicate an actual icon. There is in fact already a <link rel="icon" href="favicon.ico"> used to indicate the favicon for the entire site. This probably can't be used in the body, but it's an example of the type of placeholder that might be used.

This requires more thought. So far the most consistent and of these, and the one more consistent with long-term expression language goals, would be to use some expression as indicated above, but that would require even more thought on the actual expression variables to use.



Garret Wilson


Garret Wilson




Fix versions