From 4173a2e6db9e55595b14845c20edc2f481b60fa1 Mon Sep 17 00:00:00 2001
From: Bryan Ashby <bryan@l33t.codes>
Date: Fri, 18 Jan 2019 23:13:22 -0700
Subject: [PATCH] Add docs for TopX module

---
 docs/_includes/nav.md |  1 +
 docs/modding/top-x.md | 60 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 docs/modding/top-x.md

diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md
index 79ce2f31..e67f1163 100644
--- a/docs/_includes/nav.md
+++ b/docs/_includes/nav.md
@@ -82,6 +82,7 @@
     - [Web Download Manager]({{ site.baseurl }}{% link modding/file-base-web-download-manager.md %})
     - [Set Newscan Date]({{ site.baseurl }}{% link modding/set-newscan-date.md %})
     - [Node to Node Messaging]({{ site.baseurl }}{% link modding/node-msg.md %})
+    - [Top X]({{ site.baseurl }}{% link modding/top-x.md %})
 
   - Administration
     - [oputil]({{ site.baseurl }}{% link admin/oputil.md %})
diff --git a/docs/modding/top-x.md b/docs/modding/top-x.md
new file mode 100644
index 00000000..6ab9c545
--- /dev/null
+++ b/docs/modding/top-x.md
@@ -0,0 +1,60 @@
+---
+layout: page
+title: TopX
+---
+## The TopX Module
+The built in `top_x` module allows for displaying oldschool top user stats for the week, month, etc. Ops can configure what stat(s) are displayed and how far back in days the stats are considered.
+
+## Configuration
+### Config Block
+Available `config` block entries:
+* `mciMap`: Supplies a mapping of MCI code to data source. See `mciMap` below.
+
+#### MCI Map (mciMap)
+The `mciMap` `config` block configures MCI code mapping to data sources. Currently the following data sources (determined by `type`) are available:
+
+| Type | Description |
+|-------------|-------------|
+| `userEventLog` | Top counts or sum of values found in the User Event Log. |
+| `userProp` | Top values (aka "scores") from user properties. |
+
+##### User Event Log (userEventLog)
+When `type` is set to `userEventLog`, entries from the User Event Log can be counted (ie: individual instances of a particular log item) or summed in the case of log items that have numeric values. The default is to sum.
+
+Some current User Event Log `logName` examples include `ul_files`, `dl_file_bytes`, or `achievement_earned`. See [user_log_name.js](/core/user_log_name.js) for additional information.
+
+Example `userEventLog` entry:
+```hjson
+mciMap: {
+    1: { //  e.g.: %VM1
+        type: userEventLog
+        logName: achievement_pts_earned // top achievement points earned
+        sum: true // this is the default
+        daysBack: 7 // omit daysBack for all-of-time
+    }
+}
+```
+
+#### User Properties (userProp)
+When `type` is set to `userProp`, data is collected from individual user's properties. For example a `propName` of `minutes_online_total_count`. See [user_property.js](/core/user_property.js) for more information.
+
+Example `userProp` entry:
+```hjson
+mciMap: {
+    2: { // e.g.: %VM2
+        type: userProp
+        propName: minutes_online_total_count // top users by minutes spent on the board
+    }
+}
+```
+
+### Theming
+Generally `mciMap` entries will point to a Vertical List View Menu (`%VM1`, `%VM2`, etc.). The following `itemFormat` object is provided:
+* `value`: The value acquired from the supplied data source.
+* `userName`: User's username.
+* `realName`: User's real name.
+* `location`: User's location.
+* `affils` or `affiliation`: Users affiliations.
+* `position`: Rank position (numeric).
+
+Remember that string format rules apply, so for example, if displaying top uploaded bytes (`ul_file_bytes`), a `itemFormat` may be `{userName} - {value!sizeWithAbbr}` yielding something like "TopDude - 4 GB". See [MCI](/docs/art/mci.md) for additional information.