                           List Today's Callers
                               Version 1.08
                        Release date: 2023-03-20

                                  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 Today's Callers lister script from Digital
Distortion.

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

1. Introduction
===============
Digital Distortion List Today's Callers is a script, written in JavaScript,
for Synchronet that lists the day's callers in a colored, formatted table
similar to Renegade's caller list format.  The colors can be easily changed
by the sysop, if desired, by editing the JavaScript source file.

The caller list is read from the logon.lst file in Synchronet's data directory.
This file is written by Synchronet and displayed for Synchronet's built-in today's
callers list.  If for some reason this day's caller lister can't open logon.lst,
the caller lister will read through all user records looking for users who have
called today.  However, in the latter case, only one entry per user will be listed,
even if they have called more than once in the day, rather than listing all of
a user's callers that day, as is the case with logon.lst.

This script also reads its settings from a configuration file, called
DigitalDistortionListTodaysCallers.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 caller list
in an HTML table, which is more flexible than using plain text.  The HTML
table is colored similarly to the ANSI text table, and the username field
contains a hyperlink to the user's profile, similar to Synchronet's web user
list.  The HTML table is the recommended method for outputting the day's
callers list for the web.

2. Installation & Setup
=======================
You will need to place the following two files together in a directory of your
choice:
 DigitalDistortionListTodaysCallers.js
 DigitalDistortionListTodaysCallers.cfg
To change the behavior settings or colors, edit the .cfg file with a text editor
(refer to section 3: Configuration File).

The following instructions assume that DigitalDistortionListTodaysCallers.js
is placed in Synchronet's exec directory.

In a Baja script, you can include the following line to run the message lister:
   exec "?DigitalDistortionListTodaysCallers.js"
Running the script from JavaScript can be done in several ways; one is the load()
function, as in the following:
   load("DigitalDistortionListTodaysCallers.js");
If you don't want the script to pause at the end (for example, if you run it in your
logon script), you can pass false as an argument using the load() function, as
follows:
   load("DigitalDistortionListTodaysCallers.js", false);
(Note: Using load() this way is a way to pass arguments to a JavaScript source file,
in the argv array.  In DigitalDistortionListTodaysCallers.js, the false is recognized
as argv[0].)
The script can also be set up as an external door in the Synchronet configuration program
(SCFG).  Simply use the following command:
   ?DigitalDistortionListTodaysCallers.js
The multi-user option should be set to Yes.

Web server setup
----------------
In Synchronet's default web site setup, where it lists the last callers, it displays
the logon.lst file.  DigitalDistortionListTodaysCallers.js can used in the web interface,
if desired, to replace Synchronet's default functionality.  These are the following
steps to do so:
1) Update your lastcallers.ssjs file.  There are actually two of these files, in
   Synchronet's web\root\members directory and web\html\members.
   A) Place the following line near the top of the file:
      load("../exec/DigitalDistortionListTodaysCallers.js", false, null, false);
   B) There is a block of code in that file that starts with "if(user.number!=0)".
      Replace the code between the curly braces with this code:
        // Create an HTML table containing the day's last few callers.
        var callerLister = new DDTodaysCallerLister();
        template.lastcallers = callerLister.getHTML("lastcallers");
      For an example, see the included lastcallers.ssjs in web\root\members
      in this archive.
2) Update your lastcallers.inc file.  This file is located in each of your
   template directories (i.e., templates/default, templates/nightshade, and
   any other templates you have set up).  Replace the last callers output
   with the following text:
      <h3 align="center">Last Few Callers on @@system:name@@</h3>
      <center>
      @@lastcallers@@
      </center>
   For an example, see the included lastcallers.inc in web\templates\DigDist
   in this archive.


For those who are familiar with JavaScript, the code for listing the day's
callers is in a class.  The constructor method is DDTodaysCallerLister();
the member method that performs the caller listing is
listTodaysCallers(pReturnInString).  The parameter, pReturnInString, is an
optional boolean parameter that specifies whether or not to return the
caller listing as a string rather than outputting it directly.  By default,
the method outputs the caller listing directly.


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.

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

Behavior section
----------------
Setting                               Description
-------                               -----------

IncludeSysop                          Whether or not to include the sysop in the
                                      list.  If the sysop appears in logon.lst and
                                      this setting is false, the sysop will not be
                                      shown.  Valid values are true and false.

PauseAtEnd                            Whether or not to pause at the end of the
                                      listing.  This could be useful in scripts where
                                      you might not want it to pause at the end of the
                                      list.

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

Colors section
--------------
Color setting                        Description
-------------                        -----------
veryTopHeader                        The title text that appears above the user list
                                     ("Last Several Callers")

border                               The table border lines

colLabelText                         The column labels

timeOn                               The time that the user logged on

userName                             User name

location                             User's location

nodeNumber                           The node that the user used

connectionType                       User's connection type

numCalls                             User's number of calls


4. Revision History
===================
Version   Date         Description
-------   ----         -----------
1.07      2022-06-08   Now skips lines from the login file that are not
                       strings, to avoid errors with fileLine being undefined.
1.06      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.05      2011-11-24   Updated to more accurately display the number of calls
                       from each user.  The last version would add 1, and
                       this version does not.  Thanks to Slinky for reporting
                       this issue.
1.04      2009-08-19   Updated the getHTML() function to center the column
                       header text in the HTML table.
                       Added the feature of reading configuration
                       settings from a configuration file.
                       Added an option for whether or not to display
                       QWK account logins.
1.03      2009-07-18   Improved output for the web: Added the ability to
                       output the caller list in an HTML table.  Also,
                       updated to add 1 to the call # field, because that
                       field is 0-based in data/logon.lst.  Also, made the
                       node # and # calls right-justified, since they are
                       numeric fields.
1.02      2009-06-16   Updated so that the caller list can also be used in the
                       web interface:
                       - Put the caller listing code into a class so that
                         the caller list can either be executed in this
                         script (default), or this script can be loaded
                         into another script, and the user may use the
                         class as desired.
                       - Added parameters to the user listing functions
                         to specify whether to return the caller list as
                         as a string rather than outputting it to the
                         screen.
1.01      2009-05-13   Released separately as a stand-alone script.
1.00      2009-05-11   No change; released alongside other scripts.
1.00      2009-05-10   First public release
