                     Digital Distortion Area Choosers
                              Version 1.41
                        Release date: 2024-03-13

                                  by

                             Eric Oulashin
                     Sysop of Digital Distortion BBS
                 BBS internet address: digdist.bbsindex.com
                     Email: eric.oulashin@gmail.com



This file describes the Digital Distortion area chooser scripts.

Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup
4. Configuration files
5. Sub-board & directory name collapsing
6. DDMsgAreaChooser class: Properties & methods
7. DDFileAreaChooser class: Properties & methods


1. Disclaimer
=============
The only guarantee that I can make about these scripts is that they will take
up space on your computer.  I have tested these with the Windows verison of
Synchronet 3.15 and 3.16 in Windows 2000 and Windows XP, and Synchronet 3.17 in
Windows 7.
I created these scripts to customize the message & file area selection on my
BBS and am providing them to the Synchronet BBS community in case other
Synchronet sysops might find them useful.


2. Introduction
===============
The Digital Distortion message & file area chooser scripts provide a lightbar
or traditional user interface to let the user choose their message and file
area.  The colors are customizable via a configuration file.

By default, the scripts will let the user choose both the message group and
sub-board, and file library and directory - There is also a command-line
parameter that will only allow the user to choose a message sub-board within
their current message group, or file directory only within their current file
library, if desired.    Additionally, the message area
chooser will show the date & time of the latest post for each of the
sub-boards.

The file & message area chooser scripts can be run in several ways:
- Executed from a JavaScript/Baja script
- Loaded in a JavaScript script, then use the DDMsgAreaChooser or
  DDFileAreaChooser object to let the user choose their message/file area
- Set up as a door

These scripts require Synchronet version 3.14 or higher.


3. Installation & Setup
=======================
Step 1: Copy the following files to a directory of your choice (i.e., sbbs/exec
or sbbs/mods):
DDFileAreaChooser.js
DDMsgAreaChooser.js
DDMsgAreaChooser.cfg
DDFileAreaChooser.cfg

Step 2: Set up the scripts to run on your BBS.  To do so, you will need to
update your command shell to execute the included script instead of
Synchronet's built-in area chooser functionality.  Synchronet does not use a
traditional menu system like some other BBS packages do; rather, Synchronet
uses a "command shell", which is a script that handles user input, performs
actions based on the user's input, displays menu files, etc.  If you have not
modified your Synchronet installation much, you may be using the default
command shell, which (at the time of this writing) is default.src and its
compiled version, default.bin, which is written in Baja (Synchronet's own
scripting language).  It's also possible to use a command shell written in
JavaScript - Synchronet includes a few examples, such as classic_shell.js.

For these examples, I will use DDMsgAreaChooser.js.

To use these scripts in a Baja script (such as the 'default' script mentioned
above), you can run the area chooser as follows:
exec "?DDMsgAreaChooser.js"

If you're using a JavaScript command shell, you can run it this way:
bbs.exec("?DDMsgAreaChooser.js");

To use the message area chooser in the 'default' command shell, search for the
text "msg_select_area" (without the double-quotes).  It should be underneath a
line that says "cmdkey J" (meaning the J key is used to jump to another message
area).  Replace msg_select_area with this line:
exec "?DDMsgAreaChooser.js"

The process is similar for the file area chooser - Search for file_select_area
and replace that with the following:
exec "?DDFileAreaChooser.js"

For example: If you are using the JavaScript command shell classic_shell.js, do
the following for message area selection (some knowledge of the JavaScript
language will be helpful):
- Search for the text "case 'J':" (without the double-quotes)
- Comment out the text from the next line until (and not including) the next
  case statement
- Underneath the "case 'J':" line, put the following two lines:
bbs.exec("?DDMsgAreaChooser.js");
break;

In classic_shell.js, the process will be similar for file area selection.

Command-line parameters
-----------------------
The first command-line parameter specifies whether or not to allow the user to
choose a message group (for the message area chooser) or file library (for the
file area chooser).  These parameters are true by default.  If you want to
allow the user to choose a message sub-board only within their current message
group, or file directory only within their current file library, add the word
"false" (without the double-quotes) as a command-line parameter after the .js
script filename.  For example:
For JavaScript:
bbs.exec("?DDMsgAreaChooser.js false");
bbs.exec("?DDFileAreaChooser.js false");
For Baja:
exec "?DDMsgAreaChooser.js false"
exec "?DDFileAreaChooser.js false"

The second command-line parameter specifies whether or not to execute the
script - This is for use when loading the script with the load() function
instead of bbs.exec() in JavaScript.  See the next section for more details.


Advanced installation notes (optional)
--------------------------------------
The area chooser functionality is encapsulated into JavaScript objects so
that you can customize the settings & colors within your script if you like.
To do this, follow these steps:
 1. Include the following line in your JavaScript script (preferably near the
    top):
 load("DDMsgAreaChooser.js", true, false);
 2. Where you want to have area choosing functionality, instantiate the object
    and call its SelectMsgArea() function (for the message area chooser) or its
    SelectFileArea() function (for the file area chooser).  An example:
    var msgAreaChooser = new DDMsgAreaChooser();
	 msgAreaChooser.SelectMsgArea();
You can also list message groups (using the same colors as the chooser) as
follows:
  msgAreaChooser.ListMsgGrps();
You can also use the message lister object to list the sub-boards in the
current message group (using the same colors as the chooser) as follows:
  msgAreaChooser.ListSubBoardsInMsgGroup();
For listing file libraries and file directories inside of a library, you can
do the following:
  var fileAreaChooser = new DDFileAreaChooser();
  fileAreaChooser.ListFileLibs(); // List file libraries
  fileAreaChooser.ListDirsInFileLib(); // List directories inside the current library


If you would like to set up these scripts as doors, the following is an example
setup of the message area chooser (assuming it is placed in sbbs/exec or
sbbs/mods):
+[¦][?]----------------------------------------------------+
¦                   Message Area Chooser                   ¦
¦----------------------------------------------------------¦
¦ ¦Name                       Message Area Chooser         ¦
¦ ¦Internal Code              MSGARCHO                     ¦
¦ ¦Start-up Directory                                      ¦
¦ ¦Command Line               ?DDMsgAreaChooser.js         ¦
¦ ¦Clean-up Command Line                                   ¦
¦ ¦Execution Cost             None                         ¦
¦ ¦Access Requirements                                     ¦
¦ ¦Execution Requirements                                  ¦
¦ ¦Multiple Concurrent Users  Yes                          ¦
¦ ¦Intercept Standard I/O     No                           ¦
¦ ¦Native (32-bit) Executable No                           ¦
¦ ¦Use Shell to Execute       No                           ¦
¦ ¦Modify User Data           No                           ¦
¦ ¦Execute on Event           No                           ¦
¦ ¦Pause After Execution      No                           ¦
¦ ¦BBS Drop File Type         None                         ¦
¦ ¦Place Drop File In         Node Directory               ¦
+----------------------------------------------------------+
To run that from a JavaScript, include this line:
bbs.exec_xtrn("MSGARCHO");
To run that from a Baja script, include this line:
exec_xtrn MSGARCHO


4. Configuration files
======================
If you want to change the default beavior and colors for one of these scripts,
you can edit its configuration file, which is a plain text file.  The
configuration files have two sections: A behavior section (denoted by
[BEHAVIOR]) and a colors section (denoted by [COLORS]).  For each setting or
color, the syntax is as folows:

setting=value

where "setting" is the behavior setting or color, and "value" is the corresponding
value for the setting/color.  The colors are Synchronet color codes.

Also, comments are allowed in the configuration file.  Comments begin with a
semicolon (;).

For the color settings, the colors specified for each setting can simply be a
list of the color attribute characters.  For instance, for normal white: nw
Or, for high cyan: ch

Behavior section: Message area chooser
--------------------------------------
Setting                               Description
-------                               -----------
useLightbarInterface                  true/false: Whether or not to use a
                                      lightbar user interface.

showImportDates                       true/false: Whether or not to show the
                                      import dates (rather than message dates)
                                      in the latest date & time column in the
                                      sub-board lists.

areaChooserHdrFilenameBase            The filename to use (without the
                                      extension) for a header to display above
                                      the message area chooser list.  For
                                      example, if areaChgHeader is specified,
                                      then the chooser will look for
                                      areaChgHeader.ans if it exists, and if
                                      not, the chooser will look for
                                      areaChgHeader.asc.  Additionally, you
                                      can have multiple header files for
                                      different terminal widths; fpr example,
                                      areaChgHeader-80.ans for an 80-column
                                      terminal, areaChgHeader-140.ans for a
                                      140-column terminal, etc.

areaChooserHdrMaxLines                The maximum number of lines to use from
                                      the message area chooser header file

showDatesInSubBoardList               Specifies whether or not to show the date
                                      & time of the latest message in the
                                      sub-boards.  Valid values are true and
                                      false.

useSubCollapsing                      Whether or not to enable sub-board name
                                      collapsing.  For example, for sub-boards
                                      in a group starting with common text and
                                      a separator (specified by
                                      subCollapseSeparator), the common text
                                      will be the only one displayed, and when
                                      the user selects it, a 3rd tier with the
                                      sub-boards after the separator will be
                                      shown.

subCollapseSeparator                  The separator to use for sub-board name
                                      collapsing

Colors section: Message area chooser
------------------------------------
Color setting                        Description
-------------                        -----------
areaNum                              The color to use for area numbers

desc                                 The color to use for descriptions

numItems                             The color to use for the item counts

header                               The color to use for list headers

subBoardHeader                       The color to use for the header in the
                                     sub-board list showing "Sub-boards of"
                                     with the group description and page number
                                     (note that the group description will have
                                     he bright attribute applied)

areaMark                             The color to use for the marker character
                                     used to show the area that is currently
                                     selected

latestDate                           The color to use for the latest post date

latestTime                           The color to use for the latest post time

bkgHighlight                         The background highlight color for
                                     lightbar mode

areaNumHighlight                     The color to use for an area number for
                                     a selected item in lightbar mode

descHighlight                        The color to use for a description for
                                     a selected item in lightbar mode

dateHighlight                        The color to use for the date for a
                                     selected item in lightbar mode

timeHighlight                        The color to use for the time for a
                                     selected item in lightbar mode

numItemsHighlight                    The color to use for the number of items
                                     for a selected item in lightbar mode

lightbarHelpLineBkg                  The background color to use for the help
                                     text line displayed at the bottom of the
                                     screen in lightbar mode

lightbarHelpLineGeneral              The color to use for general text in the
                                     help text line displayed at the bottom of
                                     the screen in lightbar mode

lightbarHelpLineHotkey               The color to use for hotkeys in the help
                                     text line displayed at the bottom of the
                                     screen in lightbar mode

lightbarHelpLineParen                The color to use for the ) characters in
                                     the help text line displayed at the bottom
                                     of the screen in lightbar mode

Behavior section: File area chooser
-----------------------------------
Setting                               Description
-------                               -----------
useLightbarInterface                  true/false: Whether or not to use a
                                      lightbar user interface.

areaChooserHdrFilenameBase            The filename to use (without the
                                      extension) for a header to display above
                                      the file area chooser list.  For example,
                                      if areaChgHeader is specified, then the
                                      chooser will look for areaChgHeader.ans
                                      if it exists, and if not, the chooser
                                      will look for areaChgHeader.asc.
                                      Additionally, you can have multiple
                                      header files for different terminal
                                      widths; fpr example, areaChgHeader-80.ans
                                      for an 80-column terminal,
                                      areaChgHeader-140.ans for a 140-column
                                      terminal, etc.

areaChooserHdrMaxLines                The maximum number of lines to use from
                                      the message area chooser header file


useDirCollapsing                      Whether or not to enable directory name
                                      collapsing.  For example, for directories
                                      in a library starting with common text and
                                      a separator (specified by
                                      dirCollapseSeparator), the common text
                                      will be the only one displayed, and when
                                      the user selects it, a 3rd tier with the
                                      directories after the separator will be
                                      shown.

dirCollapseSeparator                  The separator to use for directory name
                                      collapsing

Colors section: File area chooser
------------------------------------
Color setting                        Description
-------------                        -----------
areaNum                              The color to use for area numbers

desc                                 The color to use for descriptions

numItems                             The color to use for the item counts

header                               The color to use for list headers

fileAreaHdr                          The color to use for the header in the
                                     directory list showing "Directories of"
                                     with the group description and page number
                                     (note that the group description will have
                                     the bright attribute applied)

areaMark                             The color to use for the marker character
                                     used to show the area that is currently
                                     selected

bkgHighlight                         The background highlight color for
                                     lightbar mode

areaNumHighlight                     The color to use for an area number for
                                     a selected item in lightbar mode

descHighlight                        The color to use for a description for
                                     a selected item in lightbar mode

numItemsHighlight                    The color to use for the number of items
                                     for a selected item in lightbar mode

lightbarHelpLineBkg                  The background color to use for the help
                                     text line displayed at the bottom of the
                                     screen in lightbar mode

lightbarHelpLineGeneral              The color to use for general text in the
                                     help text line displayed at the bottom of
                                     the screen in lightbar mode

lightbarHelpLineHotkey               The color to use for hotkeys in the help
                                     text line displayed at the bottom of the
                                     screen in lightbar mode

lightbarHelpLineParen                The color to use for the ) characters in
                                     the help text line displayed at the bottom
                                     of the screen in lightbar mode

5. Sub-board & directory name collapsing
========================================
Sub-board name collapsing (for message areas) and directory name collapsing (for
file areas) is a way to simplify long lists of sub-boards and file directories
that share a common theme.  A 3rd tier of options will be created for those with
a common theme.  For example, within a file library, if you have multiple
directories relating to Windows, the file area chooser can just include one
directory entry for Windows, and when the user chooses Windows, another list
of options will be shown for the Windows directories.  Similarly, for message
sub-boards, if you have multiple sub-boards in a message group that share a
common theme, the message area chooser can show just one sub-board entry for
that, and when the user selects it, the chooser will show a 3rd tier of options
for the sub-boards in that group.

For example, if you have the following file directory structure:
BBS files
  DOS: BBS software
  DOS: BBS doors
  DOS: BBS utilities
  Windows: BBS software
  Windows: BBS doors
  Windows: BBS utilities

With directory name collapsing, the selection will be come 3 tiers, as follows:
BBS files
  DOS
    BBS software
    BBS doors
    BBS utilities
  Windows
    BBS software
    BBS doors
    BBS utilities

The message area chooser has similar functionality for sub-boards.  You can
configure what text to split the names on (i.e, by default, it splits on a
colon, :).  This only happens at the file directory/message sub-board level, not
at the file library/message group level.

Name collapsing for message areas can be configured with the useSubCollapsing
and subCollapseSeparator options in DDMsgAreaChooser.cfg, and for files, with
the useDirCollapsing and dirCollapseSeparator options in DDFileAreaChooser.cfg.

If all of the sub-boards in a message group or all directories in a file library
have the same separator, then those will not be collapsed, since that would
result in only a single 2nd-tier selection, which would not be useful.


6. DDMsgAreaChooser class: Properties & methods
===============================================
The following are the properties and methods of the DDMsgAreaChooser class, which
is the class used for letting the user choose a message area:
Property name                         Description
-------------                         -----------
showImportDates                       Boolean: Whether or not to show the
                                      import dates (rather than message dates)
                                      in the latest date & time column in the
                                      sub-board lists.

useLightbarInterface                  Boolean: Whether or not to use a
                                      lightbar user interface.

Methods
-------
Method name                           Description
-----------                           -----------
DDMsgAreaChooser()                    Constructor

SelectMsgArea()                       Lets the user choose a message sub-board.
                                      If the useLightbarInterface property is
                                      true and the user's terminal supports
                                      ANSI, it will use the lightbar interface;
                                      otherwise, it will use traditional
                                      interface.

SelectMsgArea_Lightbar()              Lets the user choose a message sub-board,
                                      with a lightbar user interface.

SelectMsgArea_Traditional()           Lets the user choose a message sub-board,
                                      with a traditional user interface.

ListMsgGrps()                         Lists the message groups

ListSubBoardsInMsgGroup(pGrpIndex,    Lists the sub-boards in the user's
                        pMarkIndex,   currently-selected message group.
                        pSortType)    The parameters are all optional.  They
                                      specify the index of the message group,
                                      the index of the sub-board to mark with
                                      the "chosen" character, and a sort type,
                                      which can be "none" (default sorting),
                                      "dateAsc" for date ascending,
                                      "dateDesc" for date descending, or
                                      "description" for description.

7. DDFileAreaChooser class: Properties & methods
===============================================
The following are the properties and methods of the DDMsgAreaChooser class, which
is the class used for letting the user choose a message area:
Property name                         Description
-------------                         -----------
useLightbarInterface                  Boolean: Whether or not to use a
                                      lightbar user interface.

Methods
-------
Method name                           Description
-----------                           -----------
DDFileAreaChooser()                   Constructor

SelectFileArea()                      Lets the user choose a file directory.
                                      If the useLightbarInterface property is
                                      true and the user's terminal supports
                                      ANSI, it will use the lightbar interface;
                                      otherwise, it will use traditional
                                      interface.

SelectFileArea_Lightbar()             Lets the user choose a file directory,
                                      with a lightbar user interface.

SelectFileArea_Traditional()          Lets the user choose a file directory,
                                      with a traditional user interface.

ListFileLibs()                        Lists the file libraries

ListDirsInFileLib(pLibIndex,          Lists the directories in the user's
                  pMarkIndex)         currently-selected file library.
                                      The parameters are optional.  They
                                      specify the index of the file library
                                      and the index of the directory to mark
                                      with the "chosen" character.
