readme.txt 12.9 KB
Newer Older
1
                        Digital Distortion File Lister
2 3
                                 Version 2.05a
                           Release date: 2022-03-13
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

                                     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 File Lister.

Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup
   - Command shell setup
   - Background: Running JavaScript scripts in Synchronet
4. Configuration file & color/text theme configuration file
25
5. Strings used from text.dat
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52


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 release is version 2.00 because I had previously released a message lister
mod for Synchronet which was just a list header and a command bar to display
under the list, and it still used Synchronet's stock file list.  Now that
Synchronet provides a JavaScript interface to its filebases (as of version
3.19), more customization is possible with JavaScript.

Digital Distortion File Lister is a script for Synchronet that provides an
enhanced user interface (for ANSI terminals) for listing files in the user's
current file directory.  This file lister uses a lightbar interface to list the
files, a 'command bar' at the bottom of the screen allowing the user to use the
left & right arrow keys or the first character of the action to select an
action.  The file lister also uses message boxes to display information.

If the user's terminal does not support ANSI, the file lister will run the
stock Synchronet file lister interface instead.

53 54 55 56 57 58 59 60
Digital Distortion File Lister makes use of the user's extended description
setting.  If the user's extended description setting is enabled, the lister
will use a split interface, with the lightbar file list on the left side and
the extended file description for the highlighted file displayed on the right
side.  If the user's extended file description setting is disabled, the
lightbar file menu will use the entire width of the screen, with the short
file descriptions being displayed in a single row with each file.

61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
When adding files to the user's batch download queue or (for the sysop)
selecting files to move or delete, multi-select mode can be used, allowing
the user to select multiple files using the spacebar.  If the spacebar is not
used, the file at the current highlighted lightbar location will be used.

For viewing file information or viewining file contents, only the current file
where the lightbar location will be used.

For the lightbar file list, basic descriptions and short filenames are used in
order for the information for each file to fit on a single line in the list.
The user can view extended information for each file, in which case a window
will be displayed with the filename, size, timestamp, and extended description.
The file lister also provides the ability to view files (according to
Synchronet's viewable files configuration), and adding files to the user's
batch download queue.  Additionally, sysops can delete files and move files to
another file directory.

78 79 80 81 82 83 84
In addition to listing files in the user's current directory, this lister can
perform a file search (via filespec, description, or new file search since last
search).  The default is to list files in the current directory, but a search
mode can be specified with the command-line option -MODE.  search_filename,
search_description, or new_file_search will perform the searching; list_curdir
lists files in the user's current directory, which is the default.

85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116

3. Installation & Setup
=======================
Aside from readme.txt revision_history.txt, Digital Distortion File Lister is
comprised of the following files:

1. ddfilelister.js        The Digital Distortion File Lister script

2. ddfilelister.cfg       The file lister configuration file

3. defaultTheme.cfg       The default theme file containing colors used in the
                          file lister

The configuration files are plain text files, so they can be edited using any
editor.

The .js script and .cfg files can be placed together in any directory.  When
the lister reads the configuration file & theme file, the lister will first
look in your sbbs/mods directory, then sbbs/ctrl, then in the same directory
where the .js script is located.  So, if you desire, you could place
ddfilelister.js in sbbs/exec and the .cfg file sin your sbbs/ctrl directory,
for example.

Command shell setup
-------------------
Running the file lister involves simply having the BBS run a command to run
ddfilelister.js.  No command-line parameters are required.  The command to run
ddfilelister.js can be placed in a command shell for a command key, or in
SCFG > External Programs > Online Programs (Doors) in one of your program
groups, and then you could have your command shell run the lister via the
internal program code you configured in SCFG.

117 118
Installing into a command shell is described in section 3, "Installation &
Setup".
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133

Background: Running JavaScript scripts in Synchronet
----------------------------------------------------
The command line to run this script would be as follows (if the script is in
your sbbs/xtrn/ddfilelister directory):
?../xtrn/ddfilelister/ddfilelister.js

In a Baja script, you can use the 'exec' command to run a JavaScript script, as
in the following example:
exec "?../xtrn/ddfilelister/ddfilelister.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/ddfilelister/ddfilelister.js");

134 135 136 137 138 139 140 141 142 143 144 145
To perform searching, you can add the -MODE option on the command line.
To do a filename search:
?../xtrn/DigDist/ddfilelister/ddfilelister.js -MODE=search_filename
To do a description search:
?../xtrn/DigDist/ddfilelister/ddfilelister.js -MODE=search_description
To search for new files since the last search:
?../xtrn/DigDist/ddfilelister/ddfilelister.js -MODE=new_file_search
You can also specify a mode to list the user's current directory, which is
already the default action:
?../xtrn/DigDist/ddfilelister/ddfilelister.js -MODE=list_curdir


146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
To install the file lister as an external program (in SCFG in External
Programs > Online Programs (Doors)), see the following document for more
information:
http://wiki.synchro.net/howto:door:index?s[]=doors


4. Configuration file & color/text theme configuration file
===========================================================
Digital Distortion File Lister allows changing some settings and colors via
configuration files.  The configuration files are plain text and can be edited
with any text editor.  These are the configuration files used by Digital
Distortion File Lister:
- ddfilelister.cfg: The main configuration file
- defaultTheme.cfg: The default theme configuration file which defines colors
  for items displayed in the file lister.  The name of this file can be
  specified in ddfilelister.cfg, so that alternate "theme" configuration files
  can be used if desired.

Each setting in the configuration files has the format setting=value, where
"setting" is the name of the setting or color, and "value" is the corresponding
value to use.  The colors specified in the theme configuration file are
Synchronet color/attribute codes.  Comments are allowed in the configuration
files - Commented lines begin with a semicolon (;).

Digital Distortion File Lister will look for the configuration files in the
following directories, in the following order:
1. sbbs/mods
2. sbbs/ctrl
3. The same directory as ddfilelister.js
If you customize your configuration files, you can copy them to your sbbs/mods
or sbbs/ctrl directory so that they'll be more difficutl to accidentally
override if you update your xtrn/DDMsgReader from the Synchronet CVS
repository, where this reader's files are checked in.

The configuration settings are described in the sections below:

Main configuration file (DDMsgReader.cfg)
-----------------------------------------
Setting                               Description
-------                               -----------
sortOrder                             String: The file sort order to use.
                                      Valid values are:
                                      NATURAL: Natural sort order (same as DATE_A)
                                      NAME_AI: Filename ascending, case insensitive sort order
                                      NAME_DI: Filename descending, case insensitive sort order
                                      NAME_AS: Filename ascending, case sensitive sort order
                                      NAME_DS: Filename descending, case sensitive sort order
                                      DATE_A: Import date/time ascending sort order
                                      DATE_D: Import date/time descending sort order

196 197 198 199

pauseAfterViewingFile                 Whether or not to pause after viewing a
                                      file

200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278
themeFilename                         The name of the configuration file to
                                      use for colors & string settings

Theme configuration file
------------------------
The convention for the setting names in the theme configuration file is that
setting names ending in 'Text' are for whole text strings, and the setting
names that don't end in 'Text' are for colors.

Setting                              Element in the file lister
-------                              --------------------------
filename                             Filename in the file list

fileSize                             File size in the file list

desc                                 Description in the file list

bkgHighlight                         Background color for the highlighted
                                     (selected) file menu itme

filenameHighlight                    Highlight filename color for the file list

fileSizeHighlight                    Highlight file size color for the file
                                     list

descHighlight                        Highlight description color for the file
                                     list

fileTimestamp                        File timestamp color for showing an
                                     extended file description

fileInfoWindowBorder                 For the extended file information box
                                     border

fileInfoWindowTitle                  For the title of the extended file
                                     information box

errorBoxBorder                       Error box border

errorMessage                         Error message color

successMessage                       Success message color

batchDLInfoWindowBorder              Batch download confirm/info window border
                                     color

batchDLInfoWindowTitle               Batch download info window title color

confirmFileActionWindowBorder        Multi-file action confirm window border
                                     color

confirmFileActionWindowWindowTitle   Multi-file action confirm window title
                                     color

fileAreaMenuBorder                   The color of the file area menu border (for
                                     moving a file)

fileNormalBkg                        The file area entry background color for
                                     'normal' colors (for moving a file)

fileAreaNum                          The file library/directory number for
                                     'normal' colors (for moving a file)

fileAreaDesc                         The file library/directory description for
                                     'normal' colors (for moving a file)

fileAreaNumItems                     The number of directories/files for
                                     'normal' colors (for moving a file)

fileAreaMenuHighlightBkg              The file area entry background color for
                                      'highlight' colors (for moving a file)

fileAreaNumHighlight                  The file library/directory number for
                                      'highlight' colors (for moving a file)

fileAreaDescHighlight                 The file library/directory description for
                                      'highlight' colors (for moving a file)

fileAreaNumItemsHighlight            The number of directories/files for
279 280 281 282 283 284 285 286 287 288 289
                                     'highlight' colors (for moving a file)


5. Strings used from text.dat
=============================
Digital Distortion File Lister uses the following strings from text.dat (in
Synchronet's ctrl directory):

- DirLibOrAll (622)
- FileSpecStarDotStar (199)
- SearchStringPrompt (76)