                           Door Stats Web Page
                         From Digital Distortion
                              Version 1.03
                        Release date: 2024-07-25

                                  by

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



This file describes my Door Stats web page for Synchronet.

Contents
========
1. Introduction
2. Installation & Setup
3. Configuration settings (in ctrl/modopts.ini)


1. Introduction
===============
DoorStats.xjs (in the included web directory) is a web page for Synchronet's
web server, which displays stats for top-used doors on your BBS using graphical
web-based charts. As an XJS file, it has server-side JavaScript as well as HTML.

The included screenshot (screenshot.png) shows an example of the statistics
shown by this page.

For the charts, it uses chart.js, which is an open-source JavaScript chart
library for web sites.  DoorStats.xjs loads chart.js from the following external
URL:
https://cdn.jsdelivr.net/npm/chart.js@3.9.0/dist/chart.min.js

You can read more information about chart.js here:
https://www.chartjs.org

This gathers statistics about the doors by analyzing Synchronet's log files
in your Synchronet logs directory. The statistics will be based on all the logs
in the logs directory - so, the stats will go back only as far as the oldest log
file. syncLogDoorStats.js (in the included mods/load directory) has JavaScript
code that reads and parses the logs for any doors that have been run, and
returns the statistics (which doors were run, who ran them, how many times they
have been run, etc.).


2. Installation & Setup
========================
To install, do the following:
1. Copy DoorStats.xjs from the included web directory to your Synchronet web
   root directory (or a subdirectory within). For example, if you're using the
   ecwebv4 web interface, the default root directory is sbbs/webv4/root .
2. Copy syncLogDoorStats.js from the included mods/load directory to your
   sbbs/mods/load directory (if you don't have a 'load' directory in your mods
   directory, or don't have a sbbs/mods directory, then create it)
3. Edit your ctrl/modopts.ini and add a [dd_web_door_stats] section, and
   configure the settings as described in section 3, Configuration settings.
4. Optionally, the genDoorStats.js in the included mods directory can be used to
   periodically generate a JSON file which will cache the stats up to that point
   so that the DoorStats web page loads more quickly. Log data after the cached
   data will still be read so that the stats are always up-to-date. To make use
   of this:
   - Copy genDoorStats.js from the included mods directory to your sbbs/mods
     directory
   - Run scfg and go to External Programs > Timed Events, and add an entry there
     to run genDoorStats.js periodically (perhaps once a day). An example is
     below, running it once per day at midnight (you might choose to run it
     more or less frequently if you want):
     ╔═══════════════════════════════════════════════════════════════[< >]╗
     ║                     GEN_DOOR_STATS Timed Event                     ║
     ╠════════════════════════════════════════════════════════════════════╣
     ║ │Internal Code                   GEN_DOOR_STATS                    ║
     ║ │Start-up Directory              ../mods                           ║
     ║ │Command Line                    ?genDoorStats.js                  ║
     ║ │Enabled                         Yes                               ║
     ║ │Execution Node                  Any                               ║
     ║ │Execution Months                Any                               ║
     ║ │Execution Days of Month         Any                               ║
     ║ │Execution Days of Week          All                               ║
     ║ │Execution Time                  00:00                             ║
     ║ │Requires Exclusive Exec         No                                ║
     ║ │Force Users Off-line            No                                ║
     ║ │Native Executable/Script        Yes                               ║
     ║ │Use Shell or New Context        No                                ║
     ║ │Background Execution            No                                ║
     ║ │Always Run After Init/Re-init   Yes                               ║
     ║ │Always Run After (re)Init       No                                ║
     ╚════════════════════════════════════════════════════════════════════╝
   The JSON file it generates is DDDoorStats.json in the sbbs/mods directory.
5. Optionally, you can create some CSS files to style the charts, as well as the
   web page in general, and specify those CSS filenames in the configuration as
   described below. CSS files should go in your web root directory, usually
   in a css subdirectory. The general CSS files can have any styling information
   for the web page. For an example of what parts of the charts you can style,
   see DigitalDistortionChartStatsMobile.css or DigitalDistortionChartStats.css
   in the exampleCSS directory.

When you've done the above, users can then load DoorStats.xjs from your BBS web
site, and the door stats with charts should be displayed.

To make the door stats easy to find, you can place a link to it by editing one
of the pages normally loaded with your Synchronet web site. For instance, if
you're using the ecwebv4 web interface, you can customize what is shown on the
right sidebar by adding or editing files in the sbbs/webv4/sidebar directory.
For example, you could make a .xjs file in there called 001-Links.xjs and place
a link to DoorStats.xjs in there (and the "001" part of the filename would make
it display first - though there may already be another .xjs file in there
starting with 001).

The following page on the Synchronet wiki describes ecwebv4 customization,
including sidebar modules:
https://wiki.synchro.net/custom:webv4

Also, the following page on the Synchronet wiki describes ecwebv4 configuration:
https://wiki.synchro.net/config:webv4


3. Configuration settings (in ctrl/modopts.ini)
===============================================
ctrl/modopts.ini is a file that can hold settings for various mods for
Synchronet.  Add a [dd_web_door_stats] section, as in the following example:

; Digital Distortion's Door Stats web page
[dd_web_door_stats]
	mobileGeneralStylesCSSFilename=
	mobileChartStylesCSSFilename=
	nonMobileGeneralStylesCSSFilename=
	nonMobileChartStylesCSSFilename=
	useTableForTopDoorText=true
	useTableForUserDoorCountText=true
	doorsToSkip=BullsEye! Bulletins,Synchronet BBS List
	usersToSkip=


The settings are described below:

Setting name                                Description
------------                                -----------
mobileGeneralStylesCSSFilename              A fully-pathed filename for a file
                                            to use for general CSS styling
                                            for mobile devices. For intsance,
                                            /css/DoorStatsMobileGeneral.css

mobileChartStylesCSSFilename                A fully-pathed filename for a file
                                            to use for chart styling for mobile
                                            devices. For an example of what
                                            things can be styled for charts, see
                                            DigitalDistortionChartStatsMobile.css
                                            in the exampleCSS directory.

nonMobileGeneralStylesCSSFilename           A fully-pathed filename for a file
                                            to use for general CSS styling for
                                            non-mobile devices

nonMobileChartStylesCSSFilename             A fully-pathed filename for a file
                                            to use for chart styling for non-
                                            mobile devices.  For an example of what
                                            things can be styled for charts, see
                                            DigitalDistortionChartStats.css
                                            in the exampleCSS directory.

useTableForTopDoorText                      Whether or not to use an HTML table
                                            to display the text-based door run
                                            counts. Valid values are true or
                                            false.

useTableForUserDoorCountText                Whether or not to use an HTML table
                                            to display the text-based run counts
                                            for the doors for each user. Valid
                                            values are true or false.

doorsToSkip                                 A comma-separated list of names of
                                            doors to skip (as specified in SCFG)

usersToSkip                                 A comma-separated list of usernames
                                            to skip in the stats. For instance,
                                            you may want to skip yourself (the
                                            sysop).
