More doc updates of course
This commit is contained in:
Bryan Ashby
parent
ac0f54dc9b
commit
36e1456b47
|
|
@ -2,19 +2,10 @@
|
||||||
layout: page
|
layout: page
|
||||||
title: menu.hjson
|
title: menu.hjson
|
||||||
---
|
---
|
||||||
:warning: ***IMPORTANT!*** Before making any customisations, create your own copy of `/config/menu.hjson`, and specify it in the `general` section of `config.hjson`:
|
## Menu HJSON
|
||||||
|
The core of a ENiGMA½ based BBS is `menu.hjson`. Note that when `menu.hjson` is referenced, we're actually talking about `config/yourboardname-menu.hjson` or similar. This file determines the menus (or screens) a user can see, the order they come in and how they interact with each other, ACS configuration, etc. Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format.
|
||||||
|
|
||||||
````hjson
|
Entries in `menu.hjson` are often referred to as *blocks* or *sections*. Each entry defines a menu. A menu in this sense is something the user can see or visit. Examples include but are not limited to:
|
||||||
general: {
|
|
||||||
menuFile: yourboardname.hjson
|
|
||||||
}
|
|
||||||
````
|
|
||||||
This document and others will refer to `menu.hjson`. This should be seen as an alias to `yourboardname.hjson`
|
|
||||||
|
|
||||||
## The Basics
|
|
||||||
Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format.
|
|
||||||
|
|
||||||
Entries in `menu.hjson` are objects or _sections_ 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
|
* Classical Main, Messages, and File menus
|
||||||
* Art file display
|
* Art file display
|
||||||
|
|
@ -23,21 +14,38 @@ Entries in `menu.hjson` are objects or _sections_ defining a menu. A menu in thi
|
||||||
Menu entries live under the `menus` section of `menu.hjson`. The *key* for a menu is it's name that can be referenced by other menus and areas of the system.
|
Menu entries live under the `menus` section of `menu.hjson`. The *key* for a menu is it's name that can be referenced by other menus and areas of the system.
|
||||||
|
|
||||||
## Common Menu Entry Members
|
## Common Menu Entry Members
|
||||||
* `desc`: A friendly description that can be found in places such as "Who's Online" or the `%MD` MCI code.
|
Below is a table of **common** menu entry members. These members apply to most entries, though entries that are backed by a specialized module (ie: `module: bbs_list`) may differ. See documentation for the module in question for particulars.
|
||||||
* `art`: An art file specification.
|
|
||||||
* `next`: Specifies the next menu to go to next. Can be explicit or an array of possibilites dependent on ACS. See **Flow Control** in the **ACS Checks** section below.
|
| Item | Description |
|
||||||
* `prompt`: Specifies a prompt, by name, to use along with this menu.
|
|--------|--------------|
|
||||||
* `form`: Defines one or more forms available on this menu.
|
| `desc` | A friendly description that can be found in places such as "Who's Online" or wherever the `%MD` MCI code is used. |
|
||||||
* `submit`: Defines a submit handler when using `prompt`.
|
| `art`: | An art file *spec*. See [General Art Information](docs/art/general.md). |
|
||||||
* `config`: May contain any of the following standard configuration members in addition to per-module defined types (see appropriate module for more information):
|
| `next`: Specifies the next menu entry to go to next. Can be explicit or an array of possibilites dependent on ACS. See **Flow Control** in the **ACS Checks** section below. If `next` is not supplied, the next menu is this menus parent. |
|
||||||
* `cls`: If `true` the screen will be cleared before showing this menu.
|
| `prompt` | Specifies a prompt, by name, to use along with this menu. Prompts are configured in `prompt.hjson`. |
|
||||||
* `pause`: If `true` a pause will occur after showing this menu. Useful for simple menus such as displaying art or status screens.
|
| `submit` | Defines a submit handler when using `prompt`.
|
||||||
* `nextTimeout`: Sets the number of **milliseconds** before the system will automatically advanced to the `next` menu.
|
| `form` | An object defining one or more *forms* available on this menu. |
|
||||||
* `baudRate`: See baud rate information in [General Art Information](docs/art/general.md).
|
| `module` | Sets the module name to use for this menu. |
|
||||||
* `font`: See font listing in [General Art Information](docs/art/general.md).
|
| `config` | An object containing additional configuration. See **Config Block** below. |
|
||||||
|
|
||||||
|
### Config Block
|
||||||
|
The `config` block for a menu entry can contain common members as well as a per-module (when `module` is used) settings.
|
||||||
|
|
||||||
|
| Item | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `cls` | If `true` the screen will be cleared before showing this menu. |
|
||||||
|
| `pause` | If `true` a pause will occur after showing this menu. Useful for simple menus such as displaying art or status screens. |
|
||||||
|
| `nextTimeout` | Sets the number of **milliseconds** before the system will automatically advanced to the `next` menu. |
|
||||||
|
| `baudRate` | See baud rate information in [General Art Information](docs/art/general.md). |
|
||||||
|
| `font` | Sets a SyncTERM style font to use when displaying this menus `art`. See font listing in [General Art Information](docs/art/general.md). |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Forms
|
## Forms
|
||||||
TODO
|
ENiGMA½ uses a concept of *forms* in menus. A form is a collection of associated *views*. Consider a New User Application using the `nua` module: The default implementation utilizes a single form with multiple EditTextView views, a submit button, etc. Forms are identified by number starting with `0`. A given menu may have mutiple forms (often associated with different states or screens within the menu).
|
||||||
|
|
||||||
|
Menus may also support more than one layout type by using a *MCI key*. A MCI key is a alpha-numerically sorted key made from 1:n MCI codes. This lets the system choose the appropriate set of form(s) based on theme or random art. An example of this may be a matrix menu: Perhaps one style of your matrix uses a vertical light bar (`VM` key) while another uses a horizontal (`HM` key). The system can discover the correct form to use by matching MCI codes found in the art to that of the available forms defined in `menu.hjson`.
|
||||||
|
|
||||||
|
For more information on views and associated MCI codes, see [MCI Codes](docs/art/mci.md).
|
||||||
|
|
||||||
## Submit Handlers
|
## Submit Handlers
|
||||||
TODO
|
TODO
|
||||||
|
|
@ -49,17 +57,14 @@ Let's look a couple basic menu entries:
|
||||||
telnetConnected: {
|
telnetConnected: {
|
||||||
art: CONNECT
|
art: CONNECT
|
||||||
next: matrix
|
next: matrix
|
||||||
options: { nextTimeout: 1500 }
|
config: { nextTimeout: 1500 }
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the Telnet 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). The entry sets up a few things:
|
||||||
|
* A `art` spec of `CONNECT`. (See [General Art Information](docs/art/general.md)).
|
||||||
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`.
|
* A `next` entry up the next menu, by name, in the stack (`matrix`) that we'll go to after `telnetConnected`.
|
||||||
|
* An `config` block containing a single `nextTimeout` field telling the system to proceed to the `next` (`matrix`) entry automatically after 1500ms.
|
||||||
The entry `next` sets up the next menu, by name, in the stack (`matrix`) that we'll go to after `telnetConnected`.
|
|
||||||
|
|
||||||
Finally, an `options` object may contain various common options for menus. In this case, `nextTimeout` tells the system to proceed to the `next` entry automatically after 1500ms.
|
|
||||||
|
|
||||||
Now let's look at `matrix`, the `next` entry from `telnetConnected`:
|
Now let's look at `matrix`, the `next` entry from `telnetConnected`:
|
||||||
|
|
||||||
|
|
@ -68,34 +73,38 @@ matrix: {
|
||||||
art: matrix
|
art: matrix
|
||||||
desc: Login Matrix
|
desc: Login Matrix
|
||||||
form: {
|
form: {
|
||||||
0: {
|
0: {
|
||||||
VM: {
|
//
|
||||||
mci: {
|
// Here we have a MCI key of "VM". In this case we could
|
||||||
VM1: {
|
// omit this level since no other keys are present.
|
||||||
submit: true
|
//
|
||||||
focus: true
|
VM: {
|
||||||
items: [ "login", "apply", "log off" ]
|
mci: {
|
||||||
argName: matrixSubmit
|
VM1: {
|
||||||
|
submit: true
|
||||||
|
focus: true
|
||||||
|
items: [ "login", "apply", "log off" ]
|
||||||
|
argName: matrixSubmit
|
||||||
|
}
|
||||||
|
}
|
||||||
|
submit: {
|
||||||
|
*: [
|
||||||
|
{
|
||||||
|
value: { matrixSubmit: 0 }
|
||||||
|
action: @menu:login
|
||||||
|
}
|
||||||
|
{
|
||||||
|
value: { matrixSubmit: 1 },
|
||||||
|
action: @menu:newUserApplication
|
||||||
|
}
|
||||||
|
{
|
||||||
|
value: { matrixSubmit: 2 },
|
||||||
|
action: @menu:logoff
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
submit: {
|
|
||||||
*: [
|
|
||||||
{
|
|
||||||
value: { matrixSubmit: 0 }
|
|
||||||
action: @menu:login
|
|
||||||
}
|
|
||||||
{
|
|
||||||
value: { matrixSubmit: 1 },
|
|
||||||
action: @menu:newUserApplication
|
|
||||||
}
|
|
||||||
{
|
|
||||||
value: { matrixSubmit: 2 },
|
|
||||||
action: @menu:logoff
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue