More docs on MCI/views/theming
This commit is contained in:
Bryan Ashby
parent
8e8016d0fd
commit
e7cb804ada
|
|
@ -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: {
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
<font color="red">%BN1</font><font color="bright red">%BN1</font>
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue