                           List Today's Callers
                               Version 1.02
                        Release date: 2009-06-16

                                  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 today's callers lister.

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

1. Introduction
===============
The Digital Distortion today's callers lister is a JavaScript script written
for Synchronet that lists the day's callers.  The output is formatted in a
table with colors, similar to Renegade's caller lister.  The colors can be
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.

The script can be used in a telnet/SSH context (text mode) as well as for
Synchronet's web server, replacing the default output which uses logon.lst.

2. Installation & Setup
=======================
DigitalDistortionListTodaysCallers.js is the script file.  No additional
configuration is required; this is designed as a drop-in replacement for
Synchronet's default callers list functionality.  The script file can be
placed anywhere.

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) Open up your lastcallers.ssjs script.  There are actually two of these files, in
   Synchronet's web\root\members directory and web\html\members.
2) Place the following line near the top of the file:
   load("../exec/DigitalDistortionListTodaysCallers.js", false, null, false);
3) 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:
    // List the day's last several callers
    var callerLister = new DDTodaysCallerLister();
    template.lastcallers = html_encode(callerLister.listTodaysCallers(true), true, false, true, true);
For an example, see the included lastcallers.ssjs in web\root\members or
web\html\members directories, included 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. Colors
=========
In DigitalDistortionListUsers.js, the DDTodaysCallerLister class has a member array
called colors.  The colors array is indexed using strings that signify the text the
color is used for.  The values are Synchronet color codes.  The following are the
color array indexes and what they're used for:

Array index                          Use
------------                         ---
"veryTopHeader"                      The title text that appears above the user list
                                     ("User List")
"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.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