From 36e1456b47510d97109a9205dea4b625f5e79c48 Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Sat, 17 Nov 2018 18:03:54 -0700 Subject: [PATCH] More doc updates of course --- docs/configuration/menu-hjson.md | 127 +++++++++++++++++-------------- 1 file changed, 68 insertions(+), 59 deletions(-) diff --git a/docs/configuration/menu-hjson.md b/docs/configuration/menu-hjson.md index 336c9878..34114573 100644 --- a/docs/configuration/menu-hjson.md +++ b/docs/configuration/menu-hjson.md @@ -2,19 +2,10 @@ layout: page 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 -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: +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: * Classical Main, Messages, and File menus * 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. ## Common Menu Entry Members -* `desc`: A friendly description that can be found in places such as "Who's Online" or the `%MD` MCI code. -* `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. -* `prompt`: Specifies a prompt, by name, to use along with this menu. -* `form`: Defines one or more forms available on this menu. -* `submit`: Defines a submit handler when using `prompt`. -* `config`: May contain any of the following standard configuration members in addition to per-module defined types (see appropriate module for more information): - * `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`: See font listing in [General Art Information](docs/art/general.md). +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. + +| Item | Description | +|--------|--------------| +| `desc` | A friendly description that can be found in places such as "Who's Online" or wherever the `%MD` MCI code is used. | +| `art`: | An art file *spec*. See [General Art Information](docs/art/general.md). | +| `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. | +| `prompt` | Specifies a prompt, by name, to use along with this menu. Prompts are configured in `prompt.hjson`. | +| `submit` | Defines a submit handler when using `prompt`. +| `form` | An object defining one or more *forms* available on this menu. | +| `module` | Sets the module name to use for this menu. | +| `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 -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 TODO @@ -49,17 +57,14 @@ Let's look a couple basic menu entries: telnetConnected: { art: CONNECT 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). - -An art pattern of `CONNECT` is set telling the system to look for `CONNECT.*` where `` 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`. - -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. +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)). +* 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. Now let's look at `matrix`, the `next` entry from `telnetConnected`: @@ -68,34 +73,38 @@ matrix: { art: matrix desc: Login Matrix form: { - 0: { - VM: { - mci: { - VM1: { - submit: true - focus: true - items: [ "login", "apply", "log off" ] - argName: matrixSubmit + 0: { + // + // Here we have a MCI key of "VM". In this case we could + // omit this level since no other keys are present. + // + VM: { + mci: { + 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 - } - ] - } - } - } } } ```