                             List All Users
                              Verison 1.13
                        Release date: 2023-02-22

                                  by

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



This file describes the Digital Distortion user lister.

Contents
========
1. Introduction
2. Installation & Setup
3. Configuration file
4. Revision History

1. Introduction
===============
The Digital Distortion user lister is a JavaScript door application written for
Synchronet that lists the users on the BBS.  The output is nicely formatted with
colors that can be changed by the sysop, if desired, by editing the JavaScript
source file.

Settings can be configured via a configuration file, called
DigitalDistortionListUsers.cfg.

The script can be used in a telnet/SSH context (text mode) as well as with
Synchronet's SSJS web scripts.  For the web, the script can produce the user
list in an HTML table, to be used in a web page.  The HTML table is colored
similarly to the ANSI text table, and the username field contains a hyperlink
to view the user's profile, similar to Synchronet's web user list.


2. Installation & Setup
=======================
The Digital Distortion user lister is a JavaScript application contained in the
file DigitalDistortionListUsers.js.  No additional configuration is required;
this is designed as a drop-in replacement for Synchronet's default user list
functionality.

In a JavaScript script, you can run the user lister as follows:
   bbs.exec("?DigitalDistortionListUsers.js");
Or if you have it in a different directory (i.e., ../xtrn/ddlu):
   bbs.exec("?../xtrn/ddlu/DigitalDistortionListUsers.js");

In a Baja script, you can run it as follows:
   exec "?DigitalDistortionListUsers.js"
Or in a different directory:
   exec "?../xtrn/ddlu/DigitalDistortionListUsers.js"
The script can also be set up as an external door in SCFG.  Simply use the
following command:
   ?DigitalDistortionListUsers.js
The multi-user option should be set to Yes.

Starting with Synchronet 3.20 (around 2023-02-20), Synchronet now supports a
loadable module for listing users - You can specify a script rather than using
Synchronet's built-in user list.  This user lister can be set up as such.  In
SCFG > System > Loadable Modules > List Users, you can specify
DigitalDistortionListUsers.js. If you have the script in a different directory,
you will need to include the path to the script (for instance,
../xtrn/ddlu/DigitalDistortionListUsers.js). With the script set up as the List
Users loadable module, then your command shell can remain the same, but
Synchronet will use this user lister script when listing users.

Web server setup
----------------
To use this user lister in your Synchronet web site, follow these steps:
1) In the web directory, there is a file called userlist-DigDist.ssjs.  Copy
   this file to your Synchronet web root directory.
2) Open this file with a text editor.  Toward the top of the file, there
   is this line:
   load("../xtrn/DigDist/ListUsers/DigitalDistortionListUsers.js", false);
   That line loads the DigitalDistortionListUsers.js script.  The first parameter
   is a string that contains the full path and filename - You will need to
   edit the path so it points to the right place for your system.
3) Place a link to userlist-DigDist.ssjs in one of your BBS web pages.


3. Configuration file
=====================
If you want to change the default beavior and colors, you can edit the configuration
file, DigitalDistortionListUsers.cfg, which is a plain text file.  The configuration
file has 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.  The
colors don't apply to the web - the colors are only used in text mode (i.e.,
telnet).

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

Behavior section
----------------
Setting                               Description
-------                               -----------
ExcludeSysop                          Whether or not to exclude the sysop from
                                      the list.  Valid values are true and false.

SortList                              Whether or not to sort the list.  Valid
                                      valuse are true, false, and ask (to ask the
                                      the user).

DisplayQWKAccts                       Whether or not to display QWK accounts.
                                      Valid values are true and false.

Colors section
--------------
Color setting                        Description
-------------                        -----------
veryTopHeader                        The title text that appears above the user list
border                               The table border lines
colLabelText                         The column labels
userNum                              User number
userName                             User name
location                             User's location
lastCallDate                         User's last call date
connectionType                       User's connection type
numCalls                             User's number of calls


4. Revision History
===================
Version     Date         Description
-------     ----         -----------
1.12        2023-02-21   Now makes use of command-line arguments so it can be
                         used as a loadable module and supports listing all
                         users, only users with access to the current file
                         directory, and only users with access to the current
                         sub-board.
1.11        2018-09-22   Fixed an issue where a user object property was being
                         set after the object was set to undefined, which was
                         causing an error
1.10        2018-08-03   Updated to delete instances of User objects that are
                         created, due to an optimization in Synchronet 3.17
                         that leaves user.dat open
1.09        2013-11-17   Fixed a bug in the HTML generation: Now it uses the
                         correct user numbers for the user information links
                         when the list is sorted.
1.08        2011-11-25   Fixed a bug in the HTML generation where it wouldn't
                         get the last user, using Synchronet 3.11 and higher.
                         Thanks to Slinky for reporting this and the fix.
1.07        2011-11-23   Bug fixes: Fixed a typo in a variable name.  Also
                         fixed the error text displayed when the Synchronet
                         version is not current enough.  Thanks to Slinky
                         for catching these.
1.06        2011-02-13   Added the getHTML function for use in a web page.
1.05        2010-02-17   Bug fix: Now skips inactive user records.
1.04        2009-08-19   Fixed a bug where it might not have displayed
                         all users, because of the way it was going
                         through the user records.
1.03        2009-08-17   Updated to read configuration options from a
                         configuration file.  Added options there for
                         excluding the sysop, sorting the list, whether
                         or not to display QWK accounts, and colors.
1.02        2009-07-23   Minor update: Commented out VERSION and VER_DATE
                         to avoid re-declaration problems.  These weren't
                         being displayed to the user anyway.  Also,
                         changed the special character variables to be
                         declared with "var" rather than "const" to avoid
                         re-declaration errors.
1.01        2009-05-11   No change; released alongside other scripts.
1.01        2009-05-10   First public release
