Themes

ENiGMA½ comes with an advanced theming system allowing system operators to highly customize the look and feel of their boards. A given installation can have as many themes as you like for your users to choose from.

General Information

Themes live in art/themes/. Each theme (and thus it’s theme ID) is a directory within the themes directory. The theme itself is simply a collection of art files, and a theme.hjson file that further defines layout, colors & formatting, etc.

ENiGMA½ comes with a default theme by Luciano Ayres of Blocktronics called Mystery Skull. This theme is in art/themes/luciano_blocktronics, and thus it’s theme ID is luciano_blocktronics.

Art

For information on art files, see General Art Information. In general, to theme a piece of art, create a version of it in your themes directory.

Note

Remember that by default, the system will allow for randomly selecting art (in one of the directories mentioned above) by numbering it: FOO1.ANS, FOO2.ANS, etc.!

Theme Sections

Themes are some important sections to be aware of:

Config Item	Description
info	This section describes the theme.
customization	The beef!

Info Block

The info configuration block describes the theme itself.

Item	Required	Description
name	Yes	Name of the theme. Be creative!
author	Yes	Author of the theme/artwork.
group	No	Group/affils of author.
enabled	No	Boolean of enabled state. If set to false, this theme will not be available to your users. If a user currently has this theme selected, the system default will be selected for them at next login.
emulation	No	Terminal emulation the theme is drawn for. Defaults to ansi. See Terminal Emulation below.

Terminal Emulation

Every theme is drawn for one terminal emulation, named by info.emulation. A theme without it is an ansi theme, which is what every theme so far is, so existing themes need no change.

info: {
    name: Commodore Calling
    author: Cool Artist
    emulation: petscii
}

A caller is only ever given a theme for the emulation their session uses:

• Before login, the pre-login theme for that emulation (see theme.emulations under Creating Your Own). A * picks among that emulation’s themes only.
• After login, the user’s own theme if it is for that emulation. If it is not, the session uses that emulation’s default theme instead, and the user’s saved choice is left alone for their next call on a terminal it suits.
• The theme list in user configuration shows only themes for the session’s emulation.

If no theme exists for an emulation, its callers get the system default theme and a warning is logged once.

Note

ENiGMA½ has three emulations today: ansi, petscii and atascii. A theme for any other emulation loads but is never offered to anyone until that emulation exists.

A petscii or atascii theme in your themes directory is given to every caller of that kind, with or without a theme.emulations entry, and art for such a caller is then looked up in that theme and art/general only, never in an ANSI theme. Add one together with menus made for it: see PETSCII (Commodore) Callers.

Customization Block

The customization block in is itself broken up into major parts:

Item	Description
defaults	Default values to use when this theme is active. These values override system defaults, but can still be overridden themselves in specific areas of your theme.
menus	The bulk of what you theme in the system will be here. Any menu (that is, anything you find in menu.hjson) can be tweaked.
prompts	Similar to menus, this section themes prompts.

Defaults

Override system defaults.

Item	Description
passwordChar	Character to display in password fields. Defaults to *
dateFormat	Sets the moment.js style short and/or long format for dates.
timeFormat	Sets the moment.js style short and/or long format for times.
dateTimeFormat	Sets the moment.js style short and/or long format for date/time combinations.
getStatusAvailIndicators	An array[2] of availability status indicators. Defaults to [ 'Y', 'N' ].
getStatusVisibleIndicators	An array[2] of visibility status indicators. Defaults to [ 'Y', 'N' ].

Example:

defaults: {
    dateTimeFormat: {
        short:  MMM Do h:mm a
    }
}

Menus Block

Each key in the menus block matches up with a key found in your menu.hjson. For example, consider a matrix menu defined in menu.hjson. In addition to perhaps providing a MATRIX.ANS in your themes directory, you can also theme other parts of the menu via a matrix entry in theme.hjson.

Major areas to override/theme:

• config: Override and/or provide additional theme information over that found in the menu.hjson’s entry. Common entries here are for further overriding date/time formats, and custom range info formats (<someFormName>InfoFormat<num>). See Entry Formatting in MCI Codes and Custom Range Info Formatting below.
• mci: Set per-MCI code properties such as height, width, text styles, etc. See MCI Codes for a more information.

Two formats for mci blocks are allowed:

• Shorthand if only a single/first form is needed.
• Verbose where a form ID(s) are supplied (required if multiple forms are used)

Example: Shorthand mci format:

matrix: {
    mci: {
        VM1: {
            itemFormat: "|03{text}"
            focusItemFormat: "|11{text!styleFirstLower}"
        }
    }
}

Example: Verbose mci with form IDs:

newUserFeedbackToSysOp: {
    0: {
        mci: {
            TL1: { width: 19, textOverflow: "..." }
            ET2: { width: 19, textOverflow: "..." }
            ET3: { width: 19, textOverflow: "..." }
        }
    }
    1: {
        mci: {
            MT1: { height: 14 }
        }
    }
}

Custom Range Info Formatting

Many modules support “custom range” MCI items. These are MCI codes that are left to the user to define using a format object specific to the module. For example, consider the msg_area_list module: This module sets MCI codes 10+ (%TL10, %TL11, etc.) as “custom range”. When theming you can place these MCI codes in your artwork then define the format in theme.hjson:

messageAreaChangeCurrentArea: {
    config: {
        areaListInfoFormat10: "|15{name}|07: |03{desc}"
    }
}

Creating Your Own

Caution

IMPORTANT! Do not make any customizations to the included luciano_blocktronics theme. Instead, create your own and make changes to that instead:

1. Copy /art/themes/luciano_blocktronics to art/themes/your_board_theme

2. Update the info block at the top of the theme.hjson file:

   info: {
       name: Awesome Theme
       author: Cool Artist
       group: Sick Group
       enabled: true // default
   }

3. If desired, you may make this the default system theme in config.hjson via theme.default. theme.preLogin may be set if you want this theme used for pre-authenticated users. Both of these values also accept * if you want the system to randomly pick.

   theme: {
       default: your_board_theme
       preLogin: *
   }

   Both settings apply to every terminal emulation unless overridden for one under theme.emulations, keyed by emulation name. Each entry may set default, preLogin or both, with the same meaning and the same *, limited to that emulation’s themes. A setting that names a theme for another emulation is passed over in favour of that emulation’s default, or failing that its first theme.

   theme: {
       default: your_board_theme
       preLogin: your_board_theme
       emulations: {
           petscii: {
               default: your_c64_theme
               preLogin: your_c64_theme
           }
       }
   }

Theming Example

Let’s run through an example!

Consider the following menu.hjson entry:

superFancyMenu: {
    art: FANCY.ANS
    // ...some other stuff...
}

With a file of FANCY.ANS in art/themes/fancy_theme containing the following MCI codes:

• TL1 (Generic text label)
• BN2 (Predefined: Board Name)

An entry in your theme.hjson could look like this:

superFancyMenu: {
    mci: {
        TL1: {
            //  supply the full format of the TL1 View
            text: |02ENiGMA|10½ |08v|03|VN
        }
        BN2: {
            //  Make Board Name l33t style
            style: l33t
        }
    }
}