                               Holiday Screens
                                 Version 1.01
                           Release date: 2025-07-22

                                     by

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



This file describes the Digital Distortion Holiday Screens mod.

Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup



1. Disclaimer
=============
I cannot guarantee that this script is 100% free of bugs.  However, I have
tested it, and I used it often during development, so I have some confidence
that there are no serious issues with it (at least, none that I have seen).


2. Introduction
===============
This is a script for displaying holiday screens for particular dates of the
year. it is meant to be run during logon, as a logon event, but could be run
any time.

Screens (as ANSI, .asc, or potentially RIP) can be configured to display for
certain dates in ctrl/modopts.ini.

For the configuration, you can specify dates (month & day, or just a month)
and a filename or comma-separated list of filenames (one to be chosen at random)
to display for that day/month. For the dates, you can optionally include an
abbreviated country code (such as US for the united states) to display the
screen only for users in that country. To determine a user's country, this
script uses a service at http://www.geoplugin.net and sends the user's IP
address in order to get the user's country. That doesn't work when you're logged
into your BBS locally though, so one of the settings (described below) is
BBSCountry, where you can specify the abbreviated country code where your BBS
is located.


3. Installation & Setup
=======================
Inside this package, the holidays directory contains some sample screens for
some holidays (some which are US-centric). Copyright goes to the creators of
these screens. If there are other holidays that you would like to have screens
for, you will need to make some or search for some to use with this script.

Create a subdirectory in your sbbs/text directory for storing holiday screens.
You can name it anything you like, but for the documentation & examples here,
I have called it holidays.  You can then copy any holiday ans/asc/rip files you
want into that subdirectory.

holidayScreens.js is the holiday screens script. You can copy this to your
sbbs/mods directory.

Then, open your ctrl/modopts.ini file in a text editor and add a section for
dd_holiday_screens. In that section, you can specify dates (of formats described
below) and filenames, which are relative to sbbs/text/menu. The filename can be
a single filename or a comma-separated list of filenames, and one will be chosen
at random. The setting formats are as follows:

Format                            Description
#-#=filename[,filename,...]       A date in MM-DD format, and the filename of
                                  a holiday screen, relative to sbbs/text/menu.
                                  The filename can also be a comma-separated
                                  list of filenames, and one will be chosen
                                  at random.

#-#_CountryCode=filename[,...]    A date in MM-DD format, with a country code
                                  (such as US for the united states), and a
                                  filename (or comma-separated list)

#-DayName#=filename[,...]         A month (1-12)-day of week name, and number,
                                  and a filename (or comma-separated list). The
                                  date here specifies the Nth weekday of a
                                  month. For example, 11-Thu4 would be the 4th
                                  Thursday in November (for instance, this is
                                  Thanksgiving in the US).

#_rand#=filename[,filename,...]   A month (1-12) with a filename or comma-
                                  separated list of filenames, one which will be
                                  chosen randomly. There can be a number at
                                  the end of the "rand", so that if desired,
                                  you can include multiple of these lines in
                                  modopts.ini to specify more filenames to be
                                  chosen at random for a particular month.

There is also a setting called BBSCountry, which specifies a country code for
your BBS machine. The location matching mechanism used by this script doesn't
work when logged on locally, so the BBSCountry setting is useful for when you're
logged onto your BBS locally to match any configuration entries that specify a
country code.

This is an example section for modopts.ini:

[dd_holiday_screens]
	BBSCountry=US
	7-4_US=../holidays/July4
	10-31_US=../holidays/Halloween
	11-Thu4_US=../holidays/Thanksgiving
	12_rand1=../holidays/ChristmasTree,../holidays/holidays-bestwishes
	12_rand2=../holidays/xmas0004,../holidays/xmas0013,../holidays/ChristmasTree

In the above example, the following dates are configured:
- July 4th (for the US)
- October 31st (for the US) - Halloween
- The 4th Thursday in November (for the US) - Thanksgiving in the US
- For December, a collection of random holiday screens


After you have the files copied and configuration options set in modopts.ini,
run scfg, and go to External Programs > Online Programs (Doors), and open a
section in there. Add an entry to run holidayScreens, and for "Execute on
Event", choose Logon:
+[ ][?]====================================================+
|                   Logon Holiday Screens                  |
+==========================================================+
| |Name                       Logon Holiday Screens        |
| |Internal Code              LOGONHOLIDAYSCRS             |
| |Start-up Directory                                      |
| |Command Line               ?holidayScreens.js           |
| |Clean-up Command Line                                   |
| |Execution Cost             None                         |
| |Access Requirements                                     |
| |Execution Requirements                                  |
| |Multiple Concurrent Users  Yes                          |
| |I/O Method                 Standard                     |
| |Native Executable/Script   No                           |
| |Use Shell or New Context   No                           |
| |Modify User Data           No                           |
| |Execute on Event           Logon, Only                  |
| |Pause After Execution      No                           |
| |Disable Local Display      No                           |
| |BBS Drop File Type         None                         |
+==========================================================+
