Add docs for TopX module

This commit is contained in:
Bryan Ashby 2019-01-18 23:13:22 -07:00
parent 0457a6601f
commit 4173a2e6db
2 changed files with 61 additions and 0 deletions

View File

@ -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 %})

60
docs/modding/top-x.md Normal file
View File

@ -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.