Differences

This shows you the differences between two versions of the page.

--- projects:mystic_cal [2026/02/16 16:32] – [Script Usage] freedomotter
+++ projects:mystic_cal [2026/02/17 12:35] (current) – freedomotter
@@ Line 1: / Line 1: @@
 ====== Mystic Calendar ======
-This is a port of the CNet Calendar AREXX script for CNet Pro BBS. This generates a calendar for display at login or as a PFile/Door on the BBS, creating an on screen text calander as well as reading from a file with a list of dates and events to show. It will also generate a birthday file for user birthdays to be dispayed at the option of the SysOp, or can be added as a menu option for the user if they run it from the DOORS menu on the BBS.
+This is a port of the classic **CNet Calendar** AREXX script (CNet Pro BBS) to **Mystic BBS (Python scripts)**.
+It displays a monthly calendar and a right-side “upcoming events” list from a simple data file, and can also generate a separate **birthday events file** from Mystic user records.
+This script is intended to be run:
+  * at login (ex: a `welcome`/auto-run spot), or
+  * as a PFile/Door from a menu.
+----
+===== What This Version Does =====
+  * **80-column layout** (uses 79 to be safe)
+  * Left column: **month grid**
+  * Right column: **upcoming events list**, grouped by month
+  * Reads events from: `cal.YYYY`
+  * Reads birthdays from: `cal.bdays.YYYY` (when run with `bd`)
+  * Preserves indentation in event lines (multi-line events work)
+  * **ANSI colors** (safe approach; no box-drawing due to encoding issues in Mystic Python output path)
+  * Can roll forward into next year for the “upcoming” list and show `January YYYY+1` only when needed
+----
 ===== Directory Layout =====
@@ Line 8: / Line 30: @@
 /mystic/
 ├── scripts/
-│   ├── calendar.py
+│   ├── calendar.mpy
 │   ├── generate_birthdays.py
 │   └── generate_holidays.py
 └── calendar_data/
+    ├── cal.2026
+    ├── cal.2027
+    ├── cal.bdays.2026
+    └── cal.bdays.2027
 </code>
+Notes:
+  * Mystic scripts are typically placed under your theme scripts directory, for example:
+    * `/home/pi/mystic/themes/default/scripts/`
+  * Data lives under:
+    * `/home/pi/mystic/themes/default/scripts/calendar_data/`
+----
+===== Data File Format =====
+Each event line begins with **MMDD**, followed by display text.
+Example:
+<code>
+1st  - New Year's Day
+4th  - Independence Day!
+20th - Renaissance Faire at Burbank CA
+        E-mail Jim Shaffer for more info
+</code>
+Rules:
+  * The first 4 characters **must** be digits (`MMDD`)
+  * Everything after `MMDD` is displayed on the right (the script preserves leading spaces)
+  * You can use multiple lines for the same date by repeating the same `MMDD`
+Birthday files (`cal.bdays.YYYY`) use the same format.
+----
 ===== Setup =====
+Create the data directory:
 <code>
-mkdir -p ~/mystic/calendar_data
+mkdir -p /home/pi/mystic/themes/default/scripts/calendar_data
 </code>
+Confirm your script points to the correct location:
+<code>
+DATA_PATH = "/home/pi/mystic/themes/default/scripts/calendar_data/"
+</code>
+----
 ===== Script Usage =====
-This version:
-  * Uses Mystic’s Python API
+Normal events calendar:
-  * Reads cal.YYYY
-  * Optionally regenerates birthday file automatically
-  * ANSI framed (retro style)
-  * Today highlighted
-  * Event days marked
-Supports:
 <code>
-calendar.py
+calendar.mpy
-calendar.py bd
 </code>
-See full code [[mystic_cal:mystic_cal_code|here]]
+Birthday calendar (reads `cal.bdays.YYYY`):
+<code>
+calendar.mpy bd
+</code>
+Important Mystic note:
+  * Mystic does not reliably pass arguments via `sys.argv` inside scripts.
+  * This script uses Mystic parameter calls (example: `param_count()` / `param_str()`).
+----
+===== Birthdays =====
+Birthdays are generated into yearly files:
+  * `cal.bdays.YYYY`
+The generator:
+  * reads Mystic user records via Mystic’s Python API (`getuser(<id>)`)
+  * skips deleted/invalid users
+  * formats entries like:
+    * `0405 5th  - MobbyG's birthday!`
+If you run both `cal.bdays.<year>` and `cal.bdays.<year+1>`, the main calendar script can show upcoming birthdays across the year boundary.
+----
+===== Why The Fancy Box/Grid Was Dropped =====
+We attempted two traditional approaches for a “CNet-style” boxed calendar:
+  * **DEC line drawing mode** (VT100 `ESC ( 0` / `ESC ( B`)
+  * **CP437 box drawing characters**
+  * **Unicode box drawing characters**
+In Mystic’s Python output path, those characters were either sanitized or re-encoded (mojibake like `0xB...`, `├ä...`, or `ΓöÇ...`) depending on the terminal/client path.
+So this release uses **plain ASCII layout + ANSI colors** for maximum compatibility and reliability.
+----
+===== Future Enhancement: ANSI Template Overlay (Recommended) =====
+If we want the exact “classic boxed calendar” look later without encoding problems, the best approach is:
+  - Build a static **.ANS template** containing the full calendar grid and border art
+  - Display the template using Mystic’s normal ANSI rendering (where CP437/ANSI art is handled correctly)
+  - Use Python only to print the dynamic parts (dates and events) at fixed positions
+This avoids encoding problems entirely because the box art is handled by Mystic’s ANSI file renderer, not Python output.
+----
+===== Install / Menu Integration =====
+Add as a PFile/Door (example paths will vary by install):
+  * Create a menu entry that runs:
+    * `python3 calendar.mpy`
+  * For birthday view:
+    * `python3 calendar.mpy bd`
+You can also call it at login by running it from the appropriate Mystic login event/menu hook.
+----
+===== Source / Code =====
+See full code here:
+[[mystic_cal:mystic_cal_code|Mystic Calendar Code]]