diff --git a/docs/art/general.md b/docs/art/general.md
index 365326df..7b2a5917 100644
--- a/docs/art/general.md
+++ b/docs/art/general.md
@@ -5,15 +5,20 @@ title: General Art Information
## General Art Information
One of the most basic elements of BBS customization is through it's artwork. ENiGMA½ supports a variety of ways to select, display, and manage art.
+### Art File Locations
As a general rule, art files live in one of two places:
1. The `art/general` directory. This is where you place common/non-themed art files.
2. Within a _theme_ such as `art/themes/super_fancy_theme`.
-### Art in Menus
-While art can be displayed programmatically such as from a custom module, the most basic and common form is via `menu.hjson` entries. This usually falls into one of two forms.
+### MCI Codes
+All art can contain [MCI Codes](mci.md).
-**Form 1**: A "standard" entry where a single `art` spec is utilized:
+### Art in Menus
+While art can be displayed programmatically such as from a custom module, the most basic and common form is via `menu.hjson` entries. This usually falls into one of two forms:
+
+#### Standard
+A "standard" entry where a single `art` spec is utilized:
```hjson
{
mainMenu: {
@@ -22,7 +27,8 @@ While art can be displayed programmatically such as from a custom module, the mo
}
```
-**Form 2**: An entry for a custom module where multiple pieces are declared and used. The second style usually takes the form of a `config.art` block with two or more entries:
+#### Module Specific / Multiple Art
+An entry for a custom module where multiple pieces are declared and used. The second style usually takes the form of a `config.art` block with two or more entries:
```hjson
{
nodeMessage: {
diff --git a/docs/art/mci.md b/docs/art/mci.md
index 32c60e4a..5fde7bbd 100644
--- a/docs/art/mci.md
+++ b/docs/art/mci.md
@@ -2,16 +2,26 @@
layout: page
title: MCI Codes
---
-ENiGMA½ supports a variety of MCI codes. Some **predefined** codes produce information about the current user, system,
-or other statistics while others are used to instantiate a **View**. MCI codes are two characters in length and are
-prefixed with a percent (%) symbol. Some MCI codes have additional options that may be set directly from the code itself
-while others -- and more advanced options -- are controlled via the current theme. Standard (non-focus) and focus colors
-are set by placing duplicate codes back to back in art files.
+## MCI Codes
+ENiGMA½ supports a variety of MCI codes. Some **predefined** codes produce information about the current user, system, or other statistics while others are used to instantiate a **View**.
-## Predefined MCI Codes
-There are many predefined MCI codes that can be used anywhere on the system (placed in any art file). More are added all
-the time so also check out [core/predefined_mci.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js)
-for a full listing. Many codes attempt to pay homage to Oblivion/2, iNiQUiTY, etc.
+## General Information
+MCI codes are composed of two characters and are prefixed with a percent (%) symbol.
+
+:information_source: To explicitly tie a MCI to a specific View ID, suffix the MCI code with a number. For example: `%BN1`.
+
+:information_source: Standard (non-focus) and focus colors are set by placing duplicate codes back to back in art files:
+%BN1%BN1
+
+Some MCI codes have additional options that may be set directly from the code itself while others -- and more advanced options -- are controlled via the current theme.
+
+## Relationship with Menus, Art, and Themes
+A MCI code that appears in a `menu.hjson` entry corresponds to that found in it's associated art file. This same MCI code can be referenced in the `theme.hjson` in order to apply a theme.
+
+See [Menus](../docs/configuration/menu-hjson.md) and [Themes](themes.md) for more information.
+
+## Predefined Codes
+There are many predefined MCI codes that can be used anywhere on the system (placed in any art file).
| Code | Description |
|------|--------------|
@@ -92,6 +102,13 @@ Some additional special case codes also exist:
| `XY` | A special code that may be utilized for placement identification when creating menus or to extend an otherwise empty space in an art file down the screen. |
+:information_source: More are added all
+the time so also check out [core/predefined_mci.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js)
+for a full listing.
+
+:note: Many codes attempt to pay homage to Oblivion/2, iNiQUiTY, etc.
+
+
## Views
A **View** is a control placed on a **form** that can display variable data or collect input. One example of a View is
a Vertical Menu (`%VM`): Old-school BBSers may recognize this as a lightbar menu.
@@ -109,10 +126,11 @@ a Vertical Menu (`%VM`): Old-school BBSers may recognize this as a lightbar menu
| `TM` | Toggle Menu | A toggle menu commonly used for Yes/No style input |
| `KE` | Key Entry | A *single* key input control |
-
-Peek at [/core/mci_view_factory.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) to
+:information_source: Peek at [/core/mci_view_factory.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) to
see additional information.
+### View Identifiers
+As mentioned above, MCI codes can (and often should) be explicitly tied to a *View Identifier*. Simply speaking this is a number representing the particular view. These can be useful to reference in code, apply themes, etc.
## Properties & Theming
Predefined MCI codes and other Views can have properties set via `menu.hjson` and further *themed* via `theme.hjson`. See [Themes](themes.md) for more information on this subject.
@@ -132,8 +150,7 @@ Predefined MCI codes and other Views can have properties set via `menu.hjson` an
| `itemFormat` | Sets the format for a list entry. See **Entry Formatting** below |
| `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** below |
-These are just a few of the properties set on various views. *Use the source Luke*, as well as taking a look at the default
-`menu.hjson` and `theme.hjson` files!
+These are just a few of the properties set on various views. *Use the source Luke*, as well as taking a look at the default `menu.hjson` and `theme.hjson` files!
### Custom Properties
Often a module will provide custom properties that receive format objects (See **Entry Formatting** below). Custom property formatting can be declared in the `config` block. For example, `browseInfoFormat10`..._N_ (where _N_ is up to 99) in the `file_area_list` module received a fairly extensive format object that contains `{fileName}`, `{estReleaseYear}`, etc.
diff --git a/docs/art/themes.md b/docs/art/themes.md
index 9c9087e1..f7b234de 100644
--- a/docs/art/themes.md
+++ b/docs/art/themes.md
@@ -6,10 +6,12 @@ title: 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](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) called Mystery Skull. This theme is in `art/themes/luciano_blocktronics`, and thus it's *theme ID* is `luciano_blocktronics`.
+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](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) 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](general.md). TL;DR: In general, to theme a piece of art, create a version of it in your themes directory.
+For information on art files, see [General Art Information](general.md). In general, to theme a piece of art, create a version of it in your themes directory.
:memo: 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.!
@@ -67,8 +69,20 @@ Major areas to override/theme:
* `mci`: Set per-MCI code properties such as `height`, `width`, text styles, etc. See [MCI Codes](mci.md) for a more information.
Two formats for `mci` blocks are allowed:
-* Verbose where a form ID(s) are supplied.
* 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:
+```hjson
+matrix: {
+ mci: {
+ VM1: {
+ itemFormat: "|03{text}"
+ focusItemFormat: "|11{text!styleFirstLower}"
+ }
+ }
+}
+```
Example: Verbose `mci` with form IDs:
```hjson
@@ -88,18 +102,6 @@ newUserFeedbackToSysOp: {
}
```
-Example: Shorthand `mci` format:
-```hjson
-matrix: {
- mci: {
- VM1: {
- itemFormat: "|03{text}"
- focusItemFormat: "|11{text!styleFirstLower}"
- }
- }
-}
-```
-
##### 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`:
@@ -112,7 +114,7 @@ messageAreaChangeCurrentArea: {
```
## Creating Your Own
-:warning: ***IMPORTANT!*** It is recommended you don't make any customisations to the included `luciano_blocktronics' theme. Instead, create your own and make changes to that instead:
+:warning: ***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:
@@ -125,10 +127,41 @@ info: {
}
```
-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 radomly pick.
+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.
``` hjson
theme: {
default: your_board_theme
preLogin: *
}
```
+
+## Theming Example
+Let's run through an example!
+
+Consider the following `menu.hjson` entry:
+```hjson
+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:
+```hjson
+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
+ }
+ }
+}
+```
\ No newline at end of file