enigma-bbs/docs/menu_system.md

Menu System

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:

general: {
  /* Can also specify a full path */
  menuFile: yourboardname.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 in HJSON 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.

Example

Let's look a couple basic menu entries:

telnetConnected: {
  art: CONNECT
  next: matrix
  options: { 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<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.

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:

matrix: {
  art: matrix
  desc: Login Matrix
  form: {
    0: {
      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
              }
          ]
        }
      }
    }
  }
}

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 { matrixSubmit: 0 } will match causing action of @menu:login to be executed (go to login menu).