Minor updates to file area list to use proper date/time theme formatting + initial docs

art/themes/luciano_blocktronics/theme.hjson

@@ -548,9 +548,6 @@
 					detailsGeneralInfoFormat21: "{uploadTimestamp}"
 					detailsGeneralInfoFormat22: "{archiveTypeDesc}"
 
-					fileListEntryFormat: "|00|03{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} |11{byteSize!sizeAbbr}"
-					focusFileListEntryFormat: "|00|19|15{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} {byteSize!sizeAbbr}"
-
 					notAnArchiveFormat: "|00|08( |07{fileName} is not an archive |08)"
 				}
 
@@ -609,6 +606,8 @@
 						VM1: {
 							height: 17
 							width: 79
+							itemFormat: "|00|03{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} |11{byteSize!sizeAbbr}"
+							focusItemFormat: "|00|19|15{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} {byteSize!sizeAbbr}"
 						}
 					}
 				}
@@ -649,9 +648,6 @@
 					detailsGeneralInfoFormat21: "{uploadTimestamp}"
 					detailsGeneralInfoFormat22: "{archiveTypeDesc}"
 
-					fileListEntryFormat: "|00|03{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} |11{byteSize!sizeAbbr}"
-					focusFileListEntryFormat: "|00|19|15{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} {byteSize!sizeAbbr}"
-
 					notAnArchiveFormat: "|00|08( |07{fileName} is not an archive |08)"
 				}
 
@@ -710,6 +706,8 @@
 						VM1: {
 							height: 17
 							width: 79
+							itemFormat: "|00|03{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} |11{byteSize!sizeAbbr}"
+							focusItemFormat: "|00|19|15{fileName:<67.66} {byteSize!sizeWithoutAbbr:>7.6} {byteSize!sizeAbbr}"
 						}
 					}
 				}

core/file_area_list.js

@@ -218,7 +218,7 @@ exports.getModule = class FileAreaList extends MenuModule {
         const config        = this.menuConfig.config;
         const currEntry     = this.currentFileEntry;
 
-        const uploadTimestampFormat = config.browseUploadTimestampFormat || config.uploadTimestampFormat || 'YYYY-MMM-DD';
+        const uploadTimestampFormat = config.browseUploadTimestampFormat || this.client.currentTheme.helpers.getDateFormat('short');
         const area                  = FileArea.getFileAreaByTag(currEntry.areaTag);
         const hashTagsSep           = config.hashTagsSep || ', ';
         const isQueuedIndicator     = config.isQueuedIndicator || 'Y';
@@ -268,7 +268,7 @@ exports.getModule = class FileAreaList extends MenuModule {
             entryInfo.archiveTypeDesc = 'N/A';
         }
 
-        entryInfo.uploadByUsername  = entryInfo.uploadByUsername || 'N/A';  //  may be imported
+        entryInfo.uploadByUsername  = entryInfo.uploadByUserName = entryInfo.uploadByUsername || 'N/A';  //  may be imported
         entryInfo.hashTags          = entryInfo.hashTags || '(none)';
 
         //  create a rating string, e.g. "**---"
@@ -289,7 +289,7 @@ exports.getModule = class FileAreaList extends MenuModule {
                     entryInfo.webDlLink     = config.webDlLinkNeedsGenerated || 'Not yet generated';
                 }
             } else {
-                const webDlExpireTimeFormat = config.webDlExpireTimeFormat || 'YYYY-MMM-DD @ h:mm';
+                const webDlExpireTimeFormat = config.webDlExpireTimeFormat || this.client.currentTheme.helpers.getDateTimeFormat('short');
 
                 entryInfo.webDlLink     = ansi.vtxHyperlink(this.client, serveItem.url) + serveItem.url;
                 entryInfo.webDlExpire   = moment(serveItem.expireTimestamp).format(webDlExpireTimeFormat);
@@ -583,7 +583,8 @@ exports.getModule = class FileAreaList extends MenuModule {
                 return cb(err);
             }
 
-            this.currentFileEntry.archiveEntries = entries;
+            //  assign and add standard "text" member for itemFormat
+            this.currentFileEntry.archiveEntries = entries.map(e => Object.assign(e, { text : `${e.fileName} (${e.byteSize})` } ));
             return cb(null, 're-cached');
         });
     }
@@ -600,12 +601,7 @@ exports.getModule = class FileAreaList extends MenuModule {
                 }
 
                 if('re-cached' === cacheStatus) {
-                    const fileListEntryFormat       = this.menuConfig.config.fileListEntryFormat || '{fileName} {fileSize}';    //  :TODO: use byteSize here?
+                    fileListView.setItems(this.currentFileEntry.archiveEntries);
-                    const focusFileListEntryFormat  = this.menuConfig.config.focusFileListEntryFormat || fileListEntryFormat;
-
-                    fileListView.setItems( this.currentFileEntry.archiveEntries.map( entry => stringFormat(fileListEntryFormat, entry) ) );
-                    fileListView.setFocusItems( this.currentFileEntry.archiveEntries.map( entry => stringFormat(focusFileListEntryFormat, entry) ) );
-
                     fileListView.redraw();
                 }
             });

docs/_includes/nav.md

@@ -64,6 +64,7 @@
         - Combatnet
         - Exodus
     - [Existing Mods]({{ site.baseurl }}{% link modding/existing-mods.md %})
+    - [File Area List]({{ site.baseurl }}{% link modding/file-area-list.md %})
     - [Last Callers]({{ site.baseurl }}{% link modding/last-callers.md %})
     - [Who's Online]({{ site.baseurl }}{% link modding/whos-online.md %})
     - [User List]({{ site.baseurl }}{% link modding/user-list.md %})

docs/modding/file-area-list.md

@@ -0,0 +1,86 @@
+---
+layout: page
+title: File Area List
+---
+## The File Area List Module
+The built in `file_area_list` module provides a very flexible file listing UI.
+
+## Configuration
+### Config Block
+Available `config` block entries:
+* `art`: Sup configuration block used to establish art files used for file browsing:
+    * `browse`: The main browse screen.
+    * `details`: The main file details screen.
+    * `detailsGeneral`: The "general" tab of the details page.
+    * `detailsNfo`: The "NFO" viewer tab of the detials page.
+    * `detailsFileList`: The file listing tab of the details page (ie: used for listing archive contents).
+    * `help`: The help page.
+* `hashTagsSep`: Separator for hash entries. Defaults to ", ".
+* `isQueuedIndicator`: Indicator for items that are in the users download queue. Defaults to "Y".
+* `isNotQueuedIndicator`: Indicator for items that are _not_ in the users download queue. Defaults to "N".
+* `userRatingTicked`: Indicator for a items current _n_/5 "star" rating. Defaults to "*". `userRatingTicked` and `userRatingUnticked` are combined to build strings such as "***--" for 3/5 rating.
+* `userRatingUnticked`: Indicator for missing "stars" in a items _n_/5 rating. Defaults to "-". `userRatingTicked` and `userRatingUnticked` are combined to build strings such as "***--" for 3/5 rating.
+* `webDlExpireTimeFormat`: Presents the expiration time of a web download URL. Defaults to current theme → system `short` date/time format.
+* `webDlLinkNeedsGenerated`: Text to present when no web download link is yet generated. Defaults to "Not yet generated".
+* `webDlLinkNoWebserver`: Text to present when no web download is available (ie: webserver not enabled). Defaults to "Web server is not enabled".
+* `notAnArchiveFormat`: Presents text for the "archive type" field for non-archives. Defaults to "Not an archive".
+* `browseUploadTimestampFormat`: Timestamp format for `browseInfoFormatXXX`. Defaults to current theme → system `short` date format. See also **Browse Info Format** below.
+
+Remember that entries such as `isQueuedIndicator` and `userRatingTicked` may contain pipe color codes!
+
+### Browse Info Format
+Additional `config` block entries used for the `browse` page are as follows:
+* `browseInfoFormatXXX`: Where XXX is 10..._N_ such as `browseInfoFormat10`. See **Browse Page** below for format members.
+
+### Theming
+#### Browse Page
+* MCI 1 (ie: `%MT1`): File's short description (user entered, FILE_ID.DIZ, etc.).
+* MCI 2 (ie: `%HM2`): Navigation menu.
+* MCI 10..._N_: Custom entires with the following format members:
+    * `{fileId}`: File identifier.
+    * `{fileName}`: File name (long).
+    * `{desc}`: File short description (user entered, FILE_ID.DIZ, etc.).
+    * `{descLong}`: File's long description (README.TXT, SOMEGROUP.NFO, etc.).
+    * `{uploadByUserName}`: User name of user that uploaded this file, or "N/A".
+    * `{uploadByUserId}`: User ID of user that uploaded this file, or "N/A".
+    * `{userRating}`: User rating of file as a number.
+    * `{userRatingString}`: User rating of this file as a string formatted with `userRatingTicked` and `userRatingUnticked` described above.
+    * `{areaTag}`: Area tag.
+    * `{areaName}`: Area name or "N/A".
+    * `{areaDesc}`: Area description or "N/A".
+    * `{fileSha256}`: File's SHA-256 value in hex.
+    * `{fileMd5}`: File's MD5 value in hex.
+    * `{fileSha1}`: File's SHA1 value in hex.
+    * `{fileCrc32}`: File's CRC-32 value in hex.
+    * `{estReleaseYear}`: Estimated release year of this file.
+    * `{dlCount}`: Number of times this file has been downloaded.
+    * `{byteSize}`: Size of this file in bytes.
+    * `{archiveType}`: Archive type of this file determined by system mappings, or "N/A".
+    * `{archiveTypeDesc}`: A more descriptive archive type based on system mappings, file extention, etc. or "N/A" if it cannot be determined.
+    * `{shortFileName}`: Short DOS style 8.3 name available for some scenarios such as TIC import, or "N/A".
+    * `{ticOrigin}`: Origin from TIC imported files "Origin" field, or "N/A".
+    * `{ticDesc}`: Description from TIC imported files "Desc" field, or "N/A".
+    * `{ticLDesc}`: Long description from TIC imported files "LDesc" field joined by a line feed, or "N/A".
+    * `{uploadTimestamp}`: Upload timestamp formatted with `browseUploadTimestampFormat`.
+    * `{hashTags}`: A string of hash tags(s) separated by `hashTagsSep` described above. "(none)" if there are no tags.
+    * `{isQueued}`: Indicates if a item is currently in the user's download queue presented as `isQueuedIndicator` or `isNotQueuedIndicator` described above.
+    * `{webDlLink}`: Web download link if generated else `webDlLinkNeedsGenerated` or `webDlLinkNoWebserver` described above.
+    * `{webDlExpire}`: Web download link expiration using `webDlExpireTimeFormat` described above.
+
+#### Details Page
+* MCI 1 (ie: `%HM1`): Navigation menu
+* `%XY2`: Info area's top X,Y position.
+* `%XY3`: Info area's bottom X,Y position.
+* MCI 10..._N_: Custom entries with the format options described above in **Browse Page** via the `detailsInfoFormatXXX` `config` block entry.
+
+#### Details Page - General Tab
+* MCI 10..._N_: Custom entries with the format options described above in **Browse Page** via the `detailsGeneralInfoFormatXXX` `config` block entry.
+
+#### Details Page - NFO/README Viewer Tab
+* MCI 1 (ie: `%MT1`): NFO/README viewer using the entries `longDesc`.
+* MCI 10..._N_: Custom entries with the format options described above in **Browse Page** via the `detailsNfoInfoFormatXXX` `config` block entry.
+
+#### Detilas Page - Archive/File Listing Tab
+* MCI 1 (ie: `%VM1`): List of entries in archive. Entries are formatted using the standard `itemFormat` and `focusItemFormat` properties of the view and have all of the format options described above in **Browse Page**.
+* MCI 10..._N_: Custom entries with the format options described above in **Browse Page** via the `detailsFileListInfoFormatXXX` `config` block entry.
+