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