From 35a52adb75a065007142cd1124dbcecd5957b031 Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Fri, 20 Nov 2020 18:50:12 -0700 Subject: [PATCH] Some docs --- docs/configuration/hjson.md | 2 + docs/configuration/menu-hjson.md | 72 +++++++++++++++++++++++++++++++- docs/modding/menu-modules.md | 2 +- 3 files changed, 73 insertions(+), 3 deletions(-) diff --git a/docs/configuration/hjson.md b/docs/configuration/hjson.md index e812479f..7bfb8ddf 100644 --- a/docs/configuration/hjson.md +++ b/docs/configuration/hjson.md @@ -40,6 +40,8 @@ See https://hjson.org/users.html for more more editors & plugins. ### Hot-Reload A.K.A. Live Editing ENiGMA½'s configuration, menu, and theme files can edited while your BBS is running. When a file is saved, it is hot-reloaded into the running system. If users are currently connected and you change a menu for example, the next reload of that menu will show the changes. +:information_source: See also [Configuration Files](/docs/configuration/config-files.md) + ### CaSe SeNsiTiVE Configuration keys are **case sensitive**. That means if a configuration key is `boardName` for example, `boardname`, or `BOARDNAME` **will not work**. diff --git a/docs/configuration/menu-hjson.md b/docs/configuration/menu-hjson.md index 886fba7f..b23c0ef4 100644 --- a/docs/configuration/menu-hjson.md +++ b/docs/configuration/menu-hjson.md @@ -3,7 +3,7 @@ layout: page title: Menu HSJON --- ## 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/menus/yourboardname-*.hjson`. These files 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. See [HJSON General Information](hjson.md) for more information. +The core of a ENiGMA½ based BBS is `menu.hjson`. Note that when `menu.hjson` is referenced, we're actually talking about `config/menus/yourboardname-*.hjson`. These files determines the menus (or screens) a user can see, the order they come in, how they interact with each other, ACS configuration, and so on. Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format. See [HJSON General Information](hjson.md) for more information. 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: @@ -22,7 +22,7 @@ Below is a table of **common** menu entry members. These members apply to most e |--------|--------------| | `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 possibilities dependent on ACS. See **Flow Control** in the **ACS Checks** section below. If `next` is not supplied, the next menu is this menus parent. | +| `next` | Specifies the next menu entry to go to next. Can be explicit or an array of possibilities dependent on ACS. See **Flow Control** in the **ACS Checks** section below. If `next` is not supplied, the next menu is this menus parent. Note that special built in methods such as `@systemMethod:logoff` can also be utilized here. | | `prompt` | Specifies a prompt, by name, to use along with this menu. Prompts are configured in the `prompts` section. See **Prompts** for more information. | | `submit` | Defines a submit handler when using `prompt`. | `form` | An object defining one or more *forms* available on this menu. | @@ -257,3 +257,71 @@ someMenu: { ] } ``` + +### Case Study: Adding a New User Password (NUP) +You've got a super 31337 board and want to prevent lamerz! Let's run through adding a NUP to your application flow. + +Given the default menu system, two "pre" new user application menus exist due to the way Telnet vs SSH logins occur. We'll focus only on Telnet here. This menu is `newUserApplicationPre`. Let's say you want to display this preamble, but then ask for the NUP. If the user gets the password wrong, show them a `LAMER.ANS` and boot 'em. + +First, let's create a new menu for the NUP: +```hjson +newUserPassword: { + art: nup.ans + next: newUserApplication + desc: NUP! + + form: { + 0: { + mci: { + ET1: { + // here we create an argument/variable of "nup" + argName: nup + focus: true + submit: true + } + } + submit: { + *: [ + { + // if the user submits "nup" with the correct + // value of "nolamerz" action will send + // them to the next menu defined above -- + // in our case: newUserApplication + value: { nup: "nolamerz" } + action: @systemMethod:nextMenu + } + { + // anything else will result in going to the badNewUserPassword menu + value: { nup: null } + action: @systemMethod:badNewUserPassword + } + ] + } + } + } +} +``` + +Looks like we'll need a `badNewUserPassword` menu as well! Let's create a very basic menu to show art then disconnect the user. + +```hjson +badNewUserPassword: { + art: badnup.ans + // here we use a built in system method to boot them. + next: @systemMethod:logoff + config: { + // wait 2s after showing the art before kicking them + nextTimeout: 2000 + } +} +``` + +Great, we have a couple new menus. Now let's just point to them. Remember the existing `newUserApplicationPre` menu? All that is left to do is point it's `next` to our `newUserPassword` menu: + +```hjson +newUserApplicationPre: { + // easy! Just tell the system where to go next + next: newUserPassword + // note that the rest of this menu is omitted for clarity +} +``` \ No newline at end of file diff --git a/docs/modding/menu-modules.md b/docs/modding/menu-modules.md index ea3ea4a7..1a2a9133 100644 --- a/docs/modding/menu-modules.md +++ b/docs/modding/menu-modules.md @@ -3,7 +3,7 @@ layout: page title: Local Doors --- ## Menu Modules -Menu entries found within `menu.hjson` are backed by *menu modules*. +Menu entries found within `menu.hjson` are backed by *menu modules*. ## Creating a New Module TODO