crichardson/enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Minor document updates

Browse Source
This commit is contained in:
Bryan Ashby
2017-09-29 16:30:05 -06:00
parent e84920e508
commit efee0eafde
3 changed files with 45 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/menu_system.md
View File

@@ -1,17 +1,26 @@
# Menu System
ENiGMA½'s menu system is highly flexible and moddable. The possibilities are almost endless! By modifying your `menu.hjson` you will be able to create a custom look and feel unique to your board.
ENiGMA½'s menu system is highly flexible and moddable. The possibilities are almost endless!
This document and others will refer to `menu.hjson`. This should be seen as an alias to `yourboardname.hjson` (or whatever you reference in `config.hjson` using the `menuFile` property — see below). By modifying your `menu.hjson` you will be able to create a custom experience unique to your board.
The default `menu.hjson` file lives within the `mods` directory. It is **highly recommended** to specify another file by setting the `menuFile` property in your `config.hjson` file:
```hjson
general: {
/* Can also specify a full path */
menuFile: mybbs.hjson
menuFile: yourboardname.hjson
}
```
(You can start by copying the default `menu.hjson` to `mybbs.hjson`)
You can start by copying the default `mods/menu.hjson` to `yourboardname.hjson`.
## The Basics
Like all configuration within ENiGMA½, menu configuration is done via a HJSON file. This file is located in the `mods` directory: `mods/menu.hjson`.
Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format.
Entries in `menu.hjson` are objects defining a menu. A menu in this sense is something the user can see or visit. Examples include but are not limited to:
* Classical Main, Messages, and File menus
* Art file display
* Module driven menus such as door launchers
Each entry in `menu.hjson` defines an object that represents a menu. These objects live within the `menus` parent object. Each object's *key* is a menu name you can reference within other menus in the system.
@@ -26,9 +35,9 @@ telnetConnected: {
}
```
The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the server's config).
The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the Telnet server's config).
An art pattern of `CONNECT` is set telling the system to look for `CONNECT<n>` in the current theme location, then in the common `mods/art` directory where `<n>` represents a optional integer in art files to cause randomness, e.g. `CONNECT1.ANS`, `CONNECT2.ANS`, and so on. You can be explicit here if desired, by specifying a file extension.
An art pattern of `CONNECT` is set telling the system to look for `CONNECT<n>.*` where `<n>` represents a optional integer in art files to cause randomness, e.g. `CONNECT1.ANS`, `CONNECT2.ANS`, and so on. If desired, you can also be explicit by supplying a full filename with an extention such as `CONNECT.ANS`.
The entry `next` sets up the next menu, by name, in the stack (`matrix`) that we'll go to after `telnetConnected`.
@@ -47,20 +56,21 @@ matrix: {
submit: true
focus: true
items: [ "login", "apply", "log off" ]
argName: matrixSubmit
}
}
submit: {
*: [
{
value: { 1: 0 }
value: { matrixSubmit: 0 }
action: @menu:login
}
{
value: { 1: 1 },
value: { matrixSubmit: 1 },
action: @menu:newUserApplication
}
{
value: { 1: 2 },
value: { matrixSubmit: 2 },
action: @menu:logoff
}
]
@@ -71,6 +81,6 @@ matrix: {
}
```
In the above entry, you'll notice `form`. This defines a form(s) object. In this case, a single form by ID of `0`. The system is then told to use a block only when the resulting art provides a `VM` (*VerticalMenuView*) MCI entry. `VM1` is then setup to `submit` and start focused via `focus: true` as well as have some menu entries ("login", "apply", ...) defined.
In the above entry, you'll notice `form`. This defines a form(s) object. In this case, a single form by ID of `0`. The system is then told to use a block only when the resulting art provides a `VM` (*VerticalMenuView*) MCI entry. `VM1` is then setup to `submit` and start focused via `focus: true` as well as have some menu entries ("login", "apply", ...) defined. We provide an `argName` for this action as `matrixSubmit`.
The `submit` object tells the system to attempt to apply provided match entries from any view ID (`*`). Upon submit, the first match will be executed. For example, if the user selects "login", the first entry with a value of `{ 1: 0 }` or view ID 1, value 0 will match causing `action` of `@menu:login` to be executed (go to `login` menu).
The `submit` object tells the system to attempt to apply provided match entries from any view ID (`*`). Upon submit, the first match will be executed. For example, if the user selects "login", the first entry with a value of `{ matrixSubmit: 0 }` will match causing `action` of `@menu:login` to be executed (go to `login` menu).