Synchronet v3.19b-Win32 (install) has been released (Jan-2022).

You can donate to the Synchronet project using PayPal.

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
module:xtrnmenu [2020/11/30 18:28] – [Enhanced External Custom Menu Mod by mlong (BETA!)] mlongmodule:xtrnmenu [2021/02/13 13:08] (current) – [External Program Menu] Pluralize digital man
Line 1: Line 1:
-====== Xtrn Menu Mod by mlong (BETA!) ======+====== External Programs Menu ======
  
-BETA BETA BETA BETA +For any issues, contact mlong on IRC, dove-net at mlong@INREALM or innerrealmbbs.us
- +
-Things may be broken or not work right. Contact mlong on IRC, dove-net at mlong@INREALM or innerrealmbbs.us+
  
 ===== Introduction ===== ===== Introduction =====
  
-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, or +The XtrnMenu Mod is a loadable module replacement for xtrn_sec.js which lets you: 
-external programs. 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. +  * 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 
 +  * choose alpha-numeric inputs for the menu items (except Q), and sort several ways 
 +  * fully customize the look of each menu and menu item 
 +  * use keyboard arrow nav, mouse, esc, etc. with lightbar 
 +  * track launches and time and use this to power web stats as well as special menus 
 +  * search for any for door 
 +  * have a favorites menu that the user manages 
 +  * provide a game-only shell if you desire (gamesrv) 
 +  * use built in commands for feedback, mail, chat, text files, file area, etc. 
  
 ===== Installation ===== ===== Installation =====
  
-  - First (while this is in testing), you'll have to grab the files. Do either I **OR** II: +1. Get the latest files from the git repo 
-    - If you are familiar with git, checkout the externalmenus branch https://gitlab.synchro.net/main/sbbs/-/tree/externalmenus + 
-    - 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. +2. Set the Loadable Module to 'xtrnmenu'
-      * [[https://gitlab.synchro.net/main/sbbs/-/blob/a2777216707b140cafb9826762210f4521a6d17b/exec/xtrnmenu.js|/sbbs/exec/xtrnmenu.js]] +
-      * [[https://gitlab.synchro.net/main/sbbs/-/blob/a2777216707b140cafb9826762210f4521a6d17b/exec/xtrnmenucfg.js|/sbbs/exec/xtrnmenucfg.js]] +
-      * [[https://gitlab.synchro.net/main/sbbs/-/blob/a2777216707b140cafb9826762210f4521a6d17b/exec/load/xtrnmenulib.js|/sbbs/exec/load/xtrnmenulib.js]] +
-      * [[https://gitlab.synchro.net/main/sbbs/-/blob/a2777216707b140cafb9826762210f4521a6d17b/webv4/pages/099-xtrnmenu-games.xjs|/sbbs/webv4/pages/099-xtrnmenu-games.xjs]] +
-  - Set the Loadable Module to 'xtrnmenu'+
     -/sbbs/exec/scfg     -/sbbs/exec/scfg
     -Choose System     -Choose System
Line 26: Line 28:
     -Enter "xtrnmenu"     -Enter "xtrnmenu"
     -NOTE: If you ever want to switch back to stock, switch it to "xtrn_sec"     -NOTE: If you ever want to switch back to stock, switch it to "xtrn_sec"
-  - Now you will need to create your menus. +3. Now you will need to create your menus. 
     - Run "/sbbs/exec/jsexec /sbbs/exec/xtrnmenucfg.js" (if you are in the exec dir, just run ./jsexec xtrnmenucfg)     - Run "/sbbs/exec/jsexec /sbbs/exec/xtrnmenucfg.js" (if you are in the exec dir, just run ./jsexec xtrnmenucfg)
     - The first time you run it, it will create the main menu (a custom menu with the id of 'main')     - The first time you run it, it will create the main menu (a custom menu with the id of 'main')
-    - 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+    - 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, external program, special menu, or custom command) 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
     - 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.     - 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.
-  - 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:+4. To use game stats, special menus, and favorites, you will need to enable JSON service. Add this to our ctrl/json-service.ini and restart services:
 <code> <code>
-<!--Games--> +[xtrnmenu] 
-</code> \ \+dir=../data/ 
 +</code> 
 +Then add this to modopts.ini under [xtrn_sec]: 
 +<code> 
 +eval_before_exec=js.exec("xtrnmenu.js",{},"pre",prog.code); 
 +eval_after_exec=js.exec("xtrnmenu.js",{},"post",prog.code); 
 +</code> 
 +5. If you would like to use the web interface, copy the files from xtrn/xtrnmenu into your webv4/pages directory
 You also need to modify the stock 003-games.xjs or you will have two Games menus: You also need to modify the stock 003-games.xjs or you will have two Games menus:
 <code> <code>
Line 44: Line 53:
 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 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
  
-===== Customizing the Look =====+The mod does not handle scrolling. You need to ensure that you do not have more menu items or external programs in a section than can be displayed in one screen (with header/footer/prompt) 
 +===== xtrnmenucfg.js ===== 
 + 
 +You can configure the external menus by running "jsexec xtrnmenucfg.js". 
 + 
 +The main menu is a special menu called "main" and everything else can be linked to it. 
 + 
 +You can create custom menus containing other menus, programs, sections, commands, etc. These can then be linked to other menus or to your main menu. 
 + 
 +The types of items are: 
 + 
 +  * Custom Menu: Another custom menu item 
 +  * External Section: Displays the external section menu for the specified section 
 +  * External Program: Launches the specified external program 
 +  * Special Menu: For most viewed, most recent, longest run (requires json services) 
 +  * Favorites: User-maintained menu (requires json services) 
 +  * Search: Search menu for games 
 +  * Command: Runs any synchronet command line. This is intended mainly for adding menu options for the Game Server. 
 + 
 +===== Customizing the Look and Behavior =====
  
 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. 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.
  
-=== Global Appearance Options ===+However, you will mainly be maintaining the settings under [xtrnmenu] in modopts.d/xtrnmenu.ini 
 + 
 +=== Global Options ===
  
-To setup your global appearance settings, add a section [xtrn_custommenu] to modopts.ini, and customize as necessary:+To setup your global  settings, add a section [xtrnmenu] to modopts.ini, and customize as necessary:
  
 <code> <code>
-[xtrn_custommenu] +[xtrnmenu] 
- multicolumn = true + 
- sort = false +; Uncomment if you wish to have the mod hand over section menus to xtrn_sec.js 
- autoexec = false+;use_xtrn_sec = true 
 + 
 +; Default sort, can be "name", "key", or false (no sort) 
 +sort = false 
 ; Enable multi-column display (when more than 10 external programs in a section) ; Enable multi-column display (when more than 10 external programs in a section)
- multicolumn = true +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+
  
 +; Clear the (remote) terminal screen before displaying the menu
 +clear_screen = true    
 + 
 ; uncomment and modify any of the below to change the look of the external programs menu ; 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 ' ' ; to remove titles or underline, set to the text ' '
-;       multicolumn_separator: " " +;multicolumn_separator: " " 
-;       singlecolumn_margin=7 +;singlecolumn_margin=7 
-;       header_fmt: \1n\1c\1h%s \1n\1cExternal Programs:\r\n\r\n +;header_fmt: \1n\1c\1h%s \1n\1cExternal Programs:\r\n\r\n 
-;       titles: \1n\1cKey \1h\xb3\1n\1c Name                             \1n\1c +;titles: \1n\1cKey \1h\xb3\1n\1c Name                             \1n\1c 
-;       multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-32.32s \1h +multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-32.32s \1h 
-;       singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%s \1h +singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%s \1h 
-;       which: \r\n\1-\1cWhich or \1h~Q\1n\1cuit: \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+;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 
 +; used by the lightbar 
 +multicolumn_fmt_inverse: \1n\1w[\1y\1h%2s\1n\1w] \1n\1w\1h\x015%-32.32s \1n\1h 
 +singlecolumn_fmt_inverse: \1n\1w[\1y\1h%2s\1n\1w] \1n\1w\1h\x015%s \1n\1h 
 ; to enable cost display, use these instead ; to enable cost display, use these instead
-;       titles: \1n\1cInput \1h\xb3\1n\1c Name                       Cost \1n\1c +; Note: cost not supported in special menus 
-;       multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-26.26s\1h %5u +;titles: \1n\1cInput \1h\xb3\1n\1c Name                       Cost \1n\1c 
-;       singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-26.26s\1h %5u+;multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-26.26s\1h %5u 
 +;singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-26.26s\1h %5u 
 +;multicolumn_fmt_inverse: \1h\1c%3s \xb3 \1n\x016\1w\1h%-26.26s\1n \1c%5u 
 +;singlecolumn_fmt_inverse: \1h\1c%3s \xb3 \1n\x016\1w\1h%-26.26s\1n \1c%5u 
 + 
 +; These are used for the special menus (most launched, etc.) 
 +; It adds the "stats" field which is the number of launches, amount of time, etc. 
 +multicolumn_fmt_special: \1h\1c%3s \xb3 \1m%-21.21s\1h \1m%-10s 
 +singlecolumn_fmt_special: \1h\1c%3s \xb3 \1m%-21.21s\1h \1m%-10s 
 +multicolumn_fmt_special: \1h\1c%3s \xb3 \1m%-21.21s\1h \1m%-10s 
 +singlecolumn_fmt_special: \1h\1c%3s \xb3 \1m%-21.21s\1h \1m%-10s 
 + 
 +; Override the message when there are no programs available 
 +; (defaults to text.dat NoXtrnPrograms) 
 +;no_programs_msg: 
 + 
 +; Override the restricted user msg 
 +; (defaults to text.dat R_ExternalPrograms) 
 +;restricted_user_msg: 
 + 
 +; JSON service powers special menus (most popular, recent, etc.) 
 +; Add appropriate entry to json-service.ini and set host/port here 
 +;json_enabled = true 
 +;json_host = localhost 
 +;json_port = 10088 
 + 
 +; Exclude external codes or external sections from being tracked 
 +; and showing up in special menus (most popular, recent, etc.)     
 +blacklist_tracking_xtrncodes: bullshit,sbbslist,avatchoo 
 +blacklist_tracking_xtrnsec: operator 
 + 
 +; Formatting for the "return to previous menu" option 
 +return_msg: "\xae Return to Previous Menu" 
 +logoff_msg: "Logoff" 
 +quit_msg: "Quit" 
 +; Formatting for the "return to previous menu" option 
 +return_msg: "\xae Return to Previous Menu" 
 +logoff_msg: "Logoff" 
 +quit_msg: "Quit" 
 +return_multicolumn_fmt: \1h\1c%3s \xb3 \1n\1c%-32.32s \1h 
 +return_singlecolumn_fmt: \1h\1c%3s \xb3 \1n\1c%s \1h 
 +return_multicolumn_fmt_inverse: \1h\1c%3s \xb3 \1n\x016\1w\1h%-32.32s \1n\1h 
 +return_singlecolumn_fmt_inverse: \1h\1c%3s \xb3 \1n\x016\1w\1h%s \1n\1h 
 +return_multicolumn_special_fmt: \1h\1c%3s \xb3 \1m%-32.32s\1h 
 +return_singlecolumn_special_fmt: \1h\1c%3s \xb3 \1m%s\1h 
 +return_multicolumn_special_fmt_inverse: \1h\1c%3s \xb3 \x015\1w\1h%-32.32s\1n 
 +return_singlecolumn_special_fmt_inverse: \1h\1c%3s \xb3 \x015\1w\1h%s\1n 
 + 
 +; Change display of filearea command menu 
 +;xfer_prompt: "\x01n\x01c\xfe \x01b\x01hFile \x01n\x01c\xfe \x01h" 
 +;xfer_prompt2: " \x01n\x01c@DIR@: \x01n" 
 +;command_prompt: "\r\n\x01gCommand: " 
 +;view_prompt: "\r\n\x01c\x01hView File(s)\r\n" 
 +;searchfname_prompt: "\r\n\x01c\x01hSearch for Filename(s)\r\n" 
 +;remove_prompt: "\r\n\x01c\x01hRemove/Edit File(s)\r\n" 
 +;finddesc_prompt: "\r\n\x01c\x01hFind Text in File Descriptions (no wildcards)\r\n" 
 +;download:prompt:  "\r\n\x01c\x01hDownload File(s)\r\n" 
 + 
 +; Change display of search menu 
 +entersearchterm: "\x01y\x01hEnter search term: " 
 +searchresultheader: "\x01n\x01cSearch Results for \x01h%s" 
 +searchagainmsg: "\x01n\x01mPress S to Search Again." 
 + 
 +; Feedback Module 
 +;feedback_subject: "Game Server Feedback\r\n" 
 +;feedback_msg: Thank you for your Feedback, @SYSOP@ will get back to you ASAP!\r\n\r\n 
 + 
 +; Favorites Module 
 +;favorite_add_item: "Add Item" 
 +;favorte_remove_item: "Remove Item" 
 +;add_favorites_msg: "\x01c\x01hAdd Favorite" 
 +;remove_favorites_msg: "\x01c\x01hRemove Favorite" 
 +;favorites_inst: "\x01n\x01w\x01h\x012 [Up/Down/Home/End] to Navigate, [Enter] to Select, [Q] to Quit, [S] to Search " 
 +;favorites_inst_rem: "\x01n\x01w\x01h\x012 [Up/Down/Home/End] to Navigate, [Enter] to Select, [Q] to Quit " 
 +;favorite_add_search_prompt: "\x01c\x01hSearch (ESC to Cancel): \x01n" 
 + 
 +; autocomplete (search) box on add favorite 
 +; see cga_defs.js for color codes 
 +; autocomplete input box 
 +;favorite_add_search_fg=LIGHTGRAY 
 +;favorite_add_search_bg=BG_BLACK 
 +; autocomplete result box 
 +;favorite_add_search_sfg=LIGHTGRAY 
 +;favorite_add_search_sbg=BG_BLACK 
 +; autocomplete highlighted row 
 +;favorite_add_search_hsfg=WHITE 
 +;favorite_add_search_hsbg=BG_MAGENTA 
 + 
 +; scrolling menu on add favorite 
 +; lightbar non-current item 
 +;favorite_add_fg=LIGHTGRAY 
 +;favorite_add_bg=BG_BLACK 
 +; lightbar current item 
 +;favorite_add_lfg=WHITE 
 +;favorite_add_lbg=BG_MAGENTA 
 +; tree heading  
 +;favorite_add_cfg=WHITE 
 +;favorite_add_cbg=BG_BLACK 
 </code> </code>
  
 === Custom Menu Appearance Options === === Custom Menu Appearance Options ===
  
-To change the look of a custom menu, create it in the format [xtrn_custommenu:ID], like this:+To change the look of a custom menu, create it in the format [xtrnmenu:ID], like this:
  
 <code> <code>
-[xtrn_custommenu:genre]+[xtrnmenu:genre]
     multicolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h     multicolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h
     singlecolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h     singlecolumn_fmt: \1n\1y[\1h%2s\1n\1y] \1y%-32.32s \1h
Line 94: Line 229:
 === Single Item Appearance Options === === Single Item Appearance Options ===
  
-To change the look of a single item inside of a menu, create it within the [xtrn_custommenu:ID] section with a key of EXTERNALID-multicolumn_fmt or EXTERNALID-singlecolumn_format (these are the only two settings you can change) like this:+To change the look of a single item inside of a menu, create it within the [xtrnmenu:ID] section with a key of EXTERNALID-OPTION, like this: 
 +<code> 
 +[xtrnmenu:wordgame] 
 +boggle-multicolumn_fmt: \1n\1w[\1r\1h%2s\1n\1w] [test] \1m%-25.25s \1h 
 +boggle-singlecolumn_fmt: \1n\1w[\1r\1h%2s\1n\1w] [test] \1m%-25.25s \1h 
 +boggle-multicolumn_fmt_inverse: \1n\1w[\1r\1h%2s\1n\1w] [test] \x015\1w%-25.25s \1h 
 +boggle-singlecolumn_fmt_inverse: \1n\1w[\1r\1h%2s\1n\1w] [test] \x015\1w%-25.25s \1h 
 +</code> 
 + 
 +=== Custom Display Files === 
 + 
 +If you want to use custom display files, create them as ''[[dir:text]]/[[custom:menu_files|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 ''[[dir:text]]/[[custom:menu_files|menu]]/xtrnmenu_head_**(menuid)**.*'' and a footer file as  
 +''[[dir:text]]/[[custom:menu_files|menu]]/xtrnmenu_tail_**(menuid)**.*'', where (menuid) is the menu id of the menu. 
 + 
 +You can also include a global header as ''[[dir:text]]/[[custom:menu_files|menu]]/xtrnmenu_head.*'' and a global footer as 
 +''[[dir:text]]/[[custom:menu_files|menu]]/xtrnmenu_foot.*'' 
 + 
 +The module also supports falling back to the xtrn_sec files of ''[[dir:text]]/[[custom:menu_files|menu]]/xtrn_head.*'' and ''[[dir:text]]/[[custom:menu_files|menu]]/xtrn_tail.*'' 
 + 
 + 
 +===== Game Server ===== 
 + 
 +You can use the mod to provide functionality for a game server. You will probably still need to make other changes to your system such as to logon.js, etc. 
 + 
 +==== Shell ==== 
 + 
 +You can make a shell which just runs the menumod. Create your shell source such as ''game.src'' in ''[[dir:exec]]'' which contains:
  
 <code> <code>
-[xtrn_custommenu:genre] +exec "?xtrnmenu.js gamesrv"
-    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+
 </code> </code>
  
-=== ANSI/MSG Screens ===+Then compile it with baja: ''baja game''
  
-If you want to use custom ANSI files, put them in the text/menu dir as xtrn_custom_MENUID.[rip|ans|mon|msg|asc]+==== Commands ====
  
-Example: text/menu/xtrn_custom_genre.ans+You can add custom commands to your menu by using ''xtrnmenucfg'' and adding a Command item. These can be any synchronet commands. Some built-in ones have been provided: 
 + 
 +^ Command Name ^ Value to Use ^ Note ^ 
 +| Chat Section | ''?xtrnmenu command chat'' | - | 
 +| Check Mail | ''?xtrnmenu command checkmail'' | - | 
 +| Download Area | ''?xtrnmenu command filearea SECTION DIR'' | Ex: ''?xtrnmenu filearea main gamedocs'' | 
 +| Last Callers | ''?logonlist -l'' | - | 
 +| Prefs | ''?xtrnmenu command prefs'' | - | 
 +| Send Feedback | ''?xtrnmenu command feedback'' | - | 
 +| Text Files | ''?xtrnmenu command textsec'' | - | 
 +| Sysop Command | ''?xtrnmenu command sysop'' | Be sure to set access_string to SYSOP | 
 + 
 + 
 +===== Display Files ===== 
 + 
 +You can create a footer that only shows when the menu is running in game server mode: 
 + 
 +''[[dir:text]]/[[custom:menu_files|menu]]/xtrngamesrv_tail_**(menuid)**.*''
  
 ===== See Also ===== ===== See Also =====
   * [[:module:|module index]]   * [[:module:|module index]]
 +
 +===== 
  
 {{tag>}} {{tag>}}
  

Trace: