Digital Distortion Message Reader (DDMsgReader)

Digital Distortion Message Reader is a JavaScript mod for Synchronet for reading messages in Synchronet's messagebases (sub-boards) and personal email. It is designed to be a drop-in replacement for Synchronet's stock message reader. The initial motivation for creating Digital Distortion Message Reader was to provide a reader interface where the message is scrollable; this was before Digital Man's message list module was created with a similar reader interface. The purpose of this page is to provide an overview of Digital Distortion Message Reader & its features, and to explain how to install it. If you want to know how to get & install it, you may skip to the Getting Digital Distortion Message Reader section.

Digital Distortion Message Reader supports reading messages in sub-boards and personal email and navigating through the messages, much like Synchronet's stock message reader, but with some differences:

• For ANSI-capable terminals, this reader uses a scrollable interface, allowing the user to scroll the message up & down, along with a scrollbar on the side that shows the position/progress of the message. If desired, the reader can use a traditional (non-scrollable) interface instead, via a setting in its configuration file. If the user's terminal is not ANSI-capable, the reader will fall back to a traditional non-scrollable interface.
• The user can toggle between message read mode and the message list. The message list can use a lightbar interface for ANSI-capable terminals (default), or can use a traditional non-lightbar interface, specified via a setting in the configuration file. If the user's terminal is not ANSI-capable, the reader will fall back to a traditional non-lightbar interface for the message list.
• Message voting is supported, including upvoting & downvoting, and voting on polls
• Message searching & scanning is supported
• Features an optional “indexed” mode for newscans: Rather than reading each sub-board as new messages are found, it can show a menu of the sub-boards with counts of the total number of messages and new messages. This works only with newscans (not new-to-you scans, etc.)
• Personal twit lists: Individual users can have their own twit lists to filter out messages from/to particular users
• User settings allow individual users to toggle options such as indexed newscan mode, listing messages in reverse in the message list, editing their personal twit list, etc.)

Some misc. notes:

• User settings can be brought up with the Ctrl-U hotkey.
• From the “indexed” newscan menu, pressing the Enter key will select a sub-board and go into reader mode to read the first new message. Alternately, pressing M on a sub-board in the indexed newscan menu will show the message list for that sub-board, which then allows the user to select a message to read.
• If the user's terminal doesn't support ANSI, Digital Distortion Message Reader will fall back to a traditional (non-lightbar/non-scrolling) user interface

Some example screenshots (scrolling interface):

Reading a message	Message list

“Indexed” newscan mode	User settings

Digital Distortion Message Reader requires Synchronet 3.18 or newer and makes use of the following JavaScript scripts (in the exec/load directory). In general, it is good to have the latest versions of these loadable JavaScript scripts. If you see an error that looks like it might be from one of these, a good first step is to update these from the Synchronet Git repository.

• 822header.js
• ansiterm_lib.js
• attr_conv.js
• avatar_lib.js
• cnflib.js
• dd_lightbar_menu.js (ddlightbarmenu.js)
• graphic.js
• html2asc.js
• sbbsdefs.js
• smbdefs.js
• text.js
• userdefs.js
• utf8_cp437.js

Digital Distortion Message Reader is comprised of the following files:

• DDMsgReader.js: The Digital Distortion Message Reader script
• DDMsgReader.cfg: The reader configuration file
• DefaultTheme.cfg: The default theme file containing colors & some configurable text strings used in the reader
• ddmr_lm.js: Loadable module script for setup in SCFG (only needed for Synchronet 3.19 and earlier, or Synchronet built before 2023-02-20)

Digital Distortion Message Reader is in the Git and can be downloaded from the its directory within xtrn (Git repository link)

The easiest way to get Digital Distortion Message Reader set up is via the Loadable Module options in SCFG > System > Loadable Modules.

As of Synchronet 3.20, Synchronet allows up to 63 characters with a full command-line for a loadable module, allowing DDMsgReader.js to be specified directly as the loadable module for the 4 entries mentioned above. I've noticed that it must include the .js filename extension. For example, if you have DDMsgReader.js in ../xtrn/DDMsgReader, you would specify the following for all 4 of the above loadable module settings:

Read Mail ../xtrn/DDMsgReader/DDMsgReader.js

Scan Msgs        ../xtrn/DDMsgReader/DDMsgReader.js
Scan Subs        ../xtrn/DDMsgReader/DDMsgReader.js
List Msgs        ../xtrn/DDMsgReader/DDMsgReader.js

As of Synchronet 3.16, the Loadable Modules options let you specify scripts to run for various events in Synchronet. As of Synchronet 3.19, the following Loadable Modules options are available in SCFG for message reading/scanning events:

• Read Mail (added in Synchronet 3.16)
• Scan Msgs (added in Synchronet 3.16)
• Scan Subs (added in Synchronet 3.16)
• List Msgs (added in Synchronet 3.18)

The Loadable Modules options take the filename of the script (sometimes without the filename extension). Up to Synchronet 3.19, you will need to use the ddmr_lm.js script, and it's probably best to copy that to your sbbs/mods directory.

Depending on your Synchronet version and where you have DDMsgReader.js, you may be able to specify DDMsgReader.js directly as the loadable module for the above settings. However, if you're using an earlier verison of Synchronet (before 3.20) and you have DDMsgReader.js in ../xtrn/DDMsgReader or another path, you will need to use ddmr_lm.js. Refer to one of the below sections, depending on which version of Synchronet you're using.

Example:

Read Mail        ddmr_lm.js
Scan Msgs        ddmr_lm.js
Scan Subs        ddmr_lm.js
List Msgs        ddmr_lm.js

Also, if you will be running the script from a directory other than xtrn/DDMsgReader, edit ddmr_lm.js and look for the text “SYSOPS:” (without the double-quotes). One or two lines below that, there is a variable called msgReaderPath - Change that so that it contains the path where you copied DDMsgReader.js.

Alternately, you can copy DDMsgReader.js to your sbbs/exec or sbbs/mods directory and specify DDMsgReader in your Loadable Modules for the above modules in SCFG. For that to work, you would also need to copy DDMsgReader.cfg to your sbbs/ctrl directory or to sbbs/mods along with DDMsgReader.js.

There are a few search modes that Synchronet provides that Digital Distortion Message Reader doesn't support yet (such as continuous newscan and browse new scan), and for those situations, the Loadable Modules scripts will fall back to the stock Synchronet behavior.

Digital Distortion Message Reader can be set up by adding options to your command shell to run DDMsgReader.js for any or all of the desired functionality (reading, searching, message scanning, etc). The command-line parameters are described in the subsection “Command-line parameters”. Installing into a command shell is described in the subsection “Installing into a command shell”.

The general syntax for a command to run a JavaScript script in Synchronet is with a question mark before the .js file. For example:

?../xtrn/DDMsgReader/DDMsgReader.js

In a Baja script, you can use the 'exec' command to run a JavaScript script, as in the following example:

exec "?../xtrn/DDMsgReader/DDMsgReader.js"

In a JavaScript script, you can use the bbs.exec() function to run a JavaScript script, as in the following example:

bbs.exec("?../xtrn/DDMsgReader/DDMsgReader.js");

Alternately, the reader can be installed as an external program (in SCFG in External Programs > Online Programs (Doors)). See the Install Doors page for more information.

The Digital Distortion Message Reader supports command-line parameters to specify some behavior options. The command-line parameters are used in the command string after DDMsgReader.js.

Most of the command-line arguments are in -arg=val format, where arg is the argument (parameter) name, and val is the value for that argument. Some of the command-line parameters are simply in -arg format, to enable an option. For example, -search=new_msg_scan will start the reader to do a new message scan. Another example is -personalEmail which lets the user read their personal email.

The following are the command-line parameters supported by DDMsgReader.js:
-indexedMode: Starts DDMsgreader in “indexed” reader mode, which lists all sub-boards configured for newscan by the user, with total number of messages, number of new messages, and last post date, allowing the user to select a sub-board to read. This is intended to work if it is the only command-line option.

-search: A search type. Available options:
keyword_search: Do a keyword search in message subject/body text (current message area)
from_name_search: 'From' name search (current message area)
to_name_search: 'To' name search (current message area)
to_user_search: To user search (current message area)
new_msg_scan: New message scan (prompt for current sub-board, current group, or all)
new_msg_scan_all: New message scan (all sub-boards)
new_msg_scan_cur_grp: New message scan (current message group only)
new_msg_scan_cur_sub: New message scan (current sub-board only)
This can (optionally) be used with the -subBoard command-line parameter, which specifies an internal code for a sub-board, which may be different from the user's currently selected sub-board.
to_user_new_scan: Scan for new (unread) messages to the user (prompt for current sub-board, current group, or all)
to_user_new_scan_all: Scan for new (unread) messages to the user (all sub-boards)
to_user_new_scan_cur_grp: Scan for new (unread) messages to the user (current group)
to_user_new_scan_cur_sub: Scan for new (unread) messages to the user (current sub-board)
to_user_all_scan: Scan for all messages to the user (prompt for current sub-board, current group, or all)
prompt: Prompt the user for one of several search/scan options to choose from
Note that if the -personalEmail option is specified (to read personal email), the only valid search types are keyword_search and from_name_search.

-suppressSearchTypeText: Disable the search type text that would appear above searches or scans (such as “New To You Message Scan”, etc.)
-startMode: Startup mode. This overrides the startMode option in the confiruation file. Available options are read (or reader) for reader mode and list (or lister) for message list mode.
-configFilename: Specifies the name of the configuration file to use. Defaults to DDMsgReader.cfg.
-subBoard: The sub-board (internal code or number) to read, other than the user's current sub-board. This is optional; if this is specified, the sub-board specified by this option will be used instead of the user's current sub-board. If this option is specified, the -chooseAreaFirst option will be ignored.
-personalEmail: Read personal email to the user. This is a true/false value. It doesn't need to explicitly have a =true or =false afterward; simply including -personalEmail will enable it. If this option is specified, the -chooseAreaFirst and -subBoard options will be ignored.
-personalEmailSent: Read personal email to the user. This is a true/false value. It doesn't need to explicitly have a =true or =false afterward; simply including -personalEmailSent will enable it.
-chooseAreaFirst: Display the message area chooser before reading/listing messages. This is a true/false value. It doesn't need to explicitly have a =true or =false afterward; simply including chooseAreaFirst will enable it. If -personalEmail or -subBoard is specified, then this option won't have any effect.

The following parameters generally shouldn't be used unless you know what you're doing. These were added for use by the Loadable Modules scripts, which Synchronet will load for various scenarios:

-userNum: Specify a user number for reading personal email. This parameter is there because although usually the current user will be reading their own personal mail, there are situations where a sysop can read other users' personal mail.
-allPersonalEmail: Read all personal email (to/from all). There are instances where Synchronet supports this, but more than likely only for sysops.

If you are already familiar with Synchronet's command shell concepts, you can skip to the subsection “Installing into a command shell” below. If you are not yet familiar with how Synchronet's menus are controlled, the key is that Synchronet doesn't have a menu editor like some other BBS packages do. Instead, Synchronet uses a “command shell”, which is a script that runs when a user logs in and controls the flow of activity as it responds to the user's commands. Synchronet supports two languages for its scripts: Baja and JavaScript. Baja is Synchronet's own scripting language; JavaScript is an industry standard scripting language that Synchronet has provided extensions for to allow scripting while also being able to take advantage of some of JavaScript's other features. Baja scripts need to be compiled before running, whereas JavaScript scripts don't. For more information on Synchronet command shells & scripting, see the following documentation:

• Command Shell
• Modules
• Baja language reference
• Synchronet's JavaScript object reference (it's best to become familiar with JavaScript before referring to this document)

Examples for running the reader will assume that it's installed in the directory sbbs/xtrn/DDMsgReader.

If you are unsure which command shell you are using, you are likely using Synchronet's “default” command shell, which is contained in the files default.src and default.bin in the synchronet/exec directory. To modify the default command shell, you'll need to open default.src with a text editor. These are the key things to modify in default.src:

• Search for msg_read and replace that with the following: exec “?../xtrn/DDMsgReader/DDMsgReader.js -startMode=read”
• Where msg_your_scan appears, run DDMsgReader.js with the following: exec “?../xtrn/DDMsgReader/DDMsgReader.js -search=to_user_new_scan -startMode=read”
• Where msg_your_scan_all appears, run DDMsgReader.js with the command-line: exec “?../xtrn/DDMsgReader/DDMsgReader.js -search=to_user_new_scan_all -startMode=read”

If you are using a JavaScript command shell, the process would be similar. You will need to determine where the current message operations are done in the shell and replace them with the appropriate commands for running DDMsgReader.js.

The following are example command line strings for running the reader to perform some common message operations. These command lines can be used with the exec command in Baja, bbs.exec() method in JavaScript, or as set up as an external door in SCFG. This list is not complete but provides examples of some common message operations.

- Read messages in the current sub-board:

?../xtrn/DDMsgReader/DDMsgReader.js -startMode=read

- List messages in the current sub-board:

?../xtrn/DDMsgReader/DDMsgReader.js -startMode=list

- New message scan:

?../xtrn/DDMsgReader/DDMsgReader.js -startMode=read -search=new_msg_scan

- New-to-user message scan (scan for new messages to the user):

?../xtrn/DDMsgReader/DDMsgReader.js -startMode=read -search=to_user_new_scan

- Scan for all messages to the user:

?../xtrn/DDMsgReader/DDMsgReader.js -startMode=read -search=to_user_all_scan

- Start in indexed reader mode:

?../xtrn/DDMsgReader/DDMsgReader.js -indexedMode

- Text (keyword) search in the current sub-board, and list the messages found:

?../xtrn/DDMsgReader/DDMsgReader.js -search=keyword_search -startMode=list

- 'From' name message search in the current sub-board, and list messages found:

?../xtrn/DDMsgReader/DDMsgReader.js -search=from_name_search -startMode=list

- 'To' name message search in the current sub-board, and list messages found:

?../xtrn/DDMsgReader/DDMsgReader.js -search=to_name_search -startMode=list

- Search for all messages to the logged-in user in the current sub-board, and list the messages found:

?../xtrn/DDMsgReader/DDMsgReader.js -search=to_user_search -startMode=list

- Read personal email:

?../xtrn/DDMsgReader/DDMsgReader.js -personalEmail -startMode=read

- List personal email:

?../xtrn/DDMsgReader/DDMsgReader.js -personalEmail -startMode=list

- Read sent personal email:

?../xtrn/DDMsgReader/DDMsgReader.js -personalEmailSent -startMode=read

- Search personal email with a keyword, and start with the message list:

?../xtrn/DDMsgReader/DDMsgReader.js -search=keyword_search -personalEmail -startMode=list

Alternately, for searching personal email with a keyword, you can specify -subBoard=mail instead of -personalEmail:

?../xtrn/DDMsgReader/DDMsgReader.js -search=keyword_search -subBoard=mail -startMode=list

For more information on the configuration file options, theme configuration, etc., see the readme file.

• howto:door index