Document recentchanges.json

docs/61-ref-recentchanges.md

@@ -0,0 +1,32 @@
+# `recentchanges.json` Reference
+
+Like the page index stored in [`pageindex.json`](./60-ref-pageindex.md), `recentchanges.json` contains a list of all the recent changes on a wiki. It is located in the root of the data directory (along with the page index), and is formatted as JSON (as you might expect). It consists of an array of objects in reverse-chronological order - i.e. the most recent change is at the top of the file. Not _every_ change will be documented here however - as wikis may limit the number of recent changes stored (the default is currently `512` - this  is controlled by the `[max_recent_changes`](https://starbeamrainbowlabs.com/labs/peppermint/peppermint-config-info.php#config_max_recent_changes) setting).
+
+Note that if you are writing a module, you should **NOT** write to the recent changes list directly. Instead, you should use the `add_recent_change()` method provided by the `feature-recent-changes` module.
+
+Each object in the array contains a number of common keys:
+
+Property		| Type		| Purpose
+----------------|-----------|----------------------------
+`type`			| `string`	| The type of change that was made. The currently recognised values are detailed in the table below.
+`timestamp`		| `int`		| The UNIX timestamp at which the change was made. Note that this is probably going to change to be a datetime string instead soon.
+`page`			| `string`	| The name of the page that changed.
+`user`			| `string`	| The username of the user that made the change.
+`newsize`		| `int`		| Optional. If `type` is `edit` or `revert`, this is the new size of the page after the edit was made.
+`sizediff`		| `int`		| Optional. If `type` is `edit` or `revert`, this is the size difference from old page to the new page.
+`filesize`		| `int`		| Optional. If `type` is `upload`, then this is the size of the file that was uploaded.
+`oldpage`		| `string`	| Optional. If `type` is `move`, then this is the name of the old page that was moved to the name present in the `page` property.
+`comment_id`	| `string`	| Optional. If `type` is `comment`, then this is the ID of the comment that was made. Useful for linking directly to a comment (e.g. `#comment-COMMENT_ID_HERE`).
+
+The following values for the `type` property are currently recognised:
+
+Type		| Extra properties		| Meaning
+------------|-----------------------|-----------------------
+edit		| `newsize`, `sizediff`	| A page was edited.
+revert		| `newsize`, `sizediff`	| A page was reverted to a previous history revision (this generates a new history revision with a copy of the data from the old revision).
+deletion	| 						| A page was deleted.
+move		| `oldpage`				| A page was moved to a new name.
+upload		| `filesize`			| A file was uploaded.
+comment		| `comment_id`			| A comment was made on a page.
+
+It is not recommended that `type` is set to any other value than those in the above table, as this will result in undefined behaviour.

docs/README.md

@@ -16,6 +16,7 @@
  * **Development**
      * [Writing Modules](50-Writing-Modules.md)
      * [`pageindex.json` reference](60-ref-pageindex.md)
+     * [`recentchanges.json` reference](60-ref-recentchanges.md)
  * **References**
 	 * [Configuration Settings](https://starbeamrainbowlabs.com/labs/peppermint/peppermint-config-info.php)
 	 * [HTTP API](https://starbeamrainbowlabs.com/labs/peppermint/docs/RestApi/)

peppermint.guiconfig.json

@@ -232,7 +232,7 @@
 	"max_preview_size": { "type": "number", "description": "The maximum allowed size of generated preview images in pixels.", "default": 2048 },
 	"avatars_show": { "type": "checkbox", "description": "Whether or not to show avatars requires the 'user-preferences' and 'upload' modules, though uploads themselves can be turned off so long as all avatars have already been uploaded - it's only the 'preview' action that's actually used.", "default": true },
 	"avatars_gravatar_enabled": { "type": "checkbox", "description": "Whether gravatars should be displayed if an uploaded avatar is not found. If disabled, users without avatars will show a blank image instead.", "default": true },
-	"avatars_size": { "type": "number", "description": "The image size to render avatars at. Does not affect the size they're stored at - only the inline rendered size (e.g. on the recent changes page etc.)", "default": 32},
+	"avatars_size": { "type": "number", "description": "The image size to render avatars at. Does not affect the size they're stored at - only the inline rendered size (e.g. on the recent changes page etc.)", "default": 32 },
 	"search_characters_context": { "type": "number", "description": "The number of characters that should be displayed either side of a matching term in the context below each search result.", "default": 75},
 	"search_characters_context_total": { "type": "number", "description": "The total number of characters that a search result context should display at most.", "default": 250 },
 	"search_title_matches_weighting": { "type": "number", "description": "The weighting to give to search term matches found in a page's title.", "default": 50 },
@@ -256,7 +256,7 @@
 	"minify_pageindex": { "type": "checkbox", "description": "Whether to minify the page index when saving it. Improves performance slightly (especially on larger wikis), but can make debugging and quick ninja-edits more awkward. Note that this only takes effect when the page index is next saved.", "default": true },
 	"http2_server_push": { "type": "checkbox", "description": "Whether HTTP/2.0 server should should be enabled. If true, then 'link' HTTP headers will be attached to rendered pages specifying files to push down. Note that web server support <em>also</em> has to be abled for this to work, as PHP can't push resources to the client on its own.", "default": true },
 	"http2_server_push_items": { "type": "server-push", "description": "An array of items to push to clients when rendering pages. Should be in the format <code>[ [type, path], [type, path], ....]</code>, where <code>type</code> is a <a href='https://fetch.spec.whatwg.org/#concept-request-destination'>resource type</a>, and <code>path</code> is a relative url path to a static file to send via <em>HTTP/2.0 Server Push</em>.<br />Note: These resources will only be pushed if your web server also has support for the link: HTTP/2.0 header, and it's a page that being rendered. If it's some other thing that being sent (e.g. an image, error message, event stream, redirect, etc.), then no server push is indicated by <em>Pepperminty Wiki</em>. Test your estup with your browser's developer tools, or <a href='https://http2-push.io/'>This testing site</a>.", "default": [] },
-	"max_recent_changes": { "type": "number", "description": "The maximum number of recent changes to display on the recent changes page.", "default": 512},
+	"max_recent_changes": { "type": "number", "description": "The maximum number of recent changes to display on the recent changes page.", "default": 512 },
 	"export_allow_only_admins": { "type": "checkbox", "description": "Whether to only allow adminstrators to export the your wiki as a zip using the page-export module.", "default": false},
 	"stats_update_interval": { "type": "number", "description": "The number of seconds which should elapse before a statistics update should be scheduled. Defaults to once a day.", "default": 86400},
 	"stats_update_processingtime": { "type": "number", "description": "The maximum number of milliseconds that should be spent at once calculating statistics. If some statistics couldn't fit within this limit, then they are scheduled and updated on the next page load. Note that this is a target only - if an individual statistic takes longer than this, then it won't be interrupted. Defaults to 100ms.", "default": 100},