Xtrn Menu Mod by mlong

For any issues, contact mlong on IRC, dove-net at mlong@INREALM or innerrealmbbs.us

The Custom External Menu Mod lets you define any number of custom external menus and have those menus link to other custom external menus, external section menus, external programs, or custom commands. You can also choose alpha-numeric inputs for the menu items (except Q), and sort several ways. In addition, you can fully customize the look of each menu and menu item. The mod also supports a “game server mode” in which it can act as its own shell.

1. First (while this is in testing), you'll have to grab the files. Do either I OR II:
   1. If you are familiar with git, checkout the externalmenus branch https://gitlab.synchro.net/main/sbbs/-/tree/externalmenus
   2. Pull down the individual files into your BBS using the following links. On the top right you will see icons to view raw, download, or copy the file into your clipboard.
      • /sbbs/exec/xtrnmenu.js
      • /sbbs/exec/xtrnmenucfg.js
      • /sbbs/exec/load/xtrnmenulib.js
      • /sbbs/webv4/pages/099-xtrnmenu-games.xjs
2. Set the Loadable Module to 'xtrnmenu'
   1. /sbbs/exec/scfg
   2. Choose System
   3. Choose Loadable Modules
   4. Choose Xtrn Section
   5. Enter “xtrnmenu”
   6. NOTE: If you ever want to switch back to stock, switch it to “xtrn_sec”
3. Now you will need to create your menus.
   1. Run “/sbbs/exec/jsexec /sbbs/exec/xtrnmenucfg.js” (if you are in the exec dir, just run ./jsexec xtrnmenucfg)
   2. The first time you run it, it will create the main menu (a custom menu with the id of 'main')
   3. Click on Edit Items and start adding your items to the main menu. Select the target type first (custom menu, standard built-in section menu, or external program) and then you can choose the actual target (where it points to). You can escape back to the start screen to add more custom menus
   4. When you are done, press ESC to exit and save the config. This creates a file called /sbbs/ctrl/xtrnmenu.cfg. This is a JSON file you can make by hand, but using the editor is the preferred way of maintaining it.
4. If you would like to use the web interface, edit /sbbs/webv4/pages/099-xtrnmenu-games.xjs and remove the HIDDEN: from the top line, so that it says:

<!--Games-->

\ \ You also need to modify the stock 003-games.xjs or you will have two Games menus:

<!--HIDDEN:Games-->

This mod will not affect any shells that create their own external menus, most notably lbshell (Deuce's Lightbar Shell). For these shells, they will just see your section menus

By default, this mod will use all of your options as defined in modopts.ini [xtrn_sec], with the exception of multicolumn_fmt and singlecolumn_fmt. This is because those two default to having an unsigned integer in the format, and this mod will require a string. If you don't define them, they will use what is hardcoded in the code.

To setup your global appearance settings, add a section [xtrnmenu] to modopts.ini, and customize as necessary:

[xtrnmenu]
	multicolumn = true
	sort = false
	autoexec = false
; Enable multi-column display (when more than 10 external programs in a section)
	multicolumn = true
; Clear the (remote) terminal screen before displaying the menu
	clear_screen = true     
; Auto-execute the only available program when entering a program section
	autoexec = false

; uncomment and modify any of the below to change the look of the external programs menu
; to remove titles or underline, set to the text ' '
;       multicolumn_separator: " "
;       singlecolumn_margin=7
;       header_fmt: \1n\1c\1h%s \1n\1cExternal Programs:\r\n\r\n
;       titles: \1n\1cKey \1h\xb3\1n\1c Name                             \1n\1c
;       multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-32.32s \1h
;       singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%s \1h
;       which: \r\n\1-\1cWhich or \1h~Q\1n\1cuit: \1h
;       underline: \1c\1h\xc4\xc4\xc4\xc4\xc5\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4\xc4
; to enable cost display, use these instead
;       titles: \1n\1cInput \1h\xb3\1n\1c Name                       Cost \1n\1c
;       multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-26.26s\1h %5u
;       singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-26.26s\1h %5u

To change the look of a custom menu, create it in the format [xtrnmenu:ID], like this:

[xtrnmenu:genre]
    multicolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h
    singlecolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h

The custom menu section can use any of the same options as the global setting.

To change the look of a single item inside of a menu, create it within the [xtrnmenu:ID] section with a key of EXTERNALID-multicolumn_fmt or EXTERNALID-singlecolumn_format (these are the only two settings you can change) like this:

[xtrnmenu:genre]
    multicolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h
    singlecolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h
    lord-multicolumn_fmt: \1n\1g[\1h%2s\1n\1g] \1g%-32.32s \1h
    lord-singlecolumn_fmt: \1n\1g[\1h%2s\1n\1g] \1g%-32.32s \1h

If you want to use custom display files, create them as text/menu/xtrnmenu_(menuid).* where (menuid) is the menu id of the menu.

Example: text/menu/xtrnmenu_genre.msg

You can also include a header file as text/menu/xtrnmenu_head_(menuid).* and a footer file as text/menu/xtrnmenu_tail_(menuid).*, where (menuid) is the menu id of the menu.

You can also include a global header as text/menu/xtrnmenu_head.* and a global footer as text/menu/xtrnmenu_foot.*

The module also supports falling back to the xtrn_sec files of text/menu/xtrn_head.* and text/menu/xtrn_tail.*

• module index