From 5b20df5b3dde97c9b162bc1d4fe40bf63e93acf6 Mon Sep 17 00:00:00 2001
From: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>
Date: Wed, 14 Feb 2018 22:36:29 +0000
Subject: [PATCH] Add mode parameter support to random action

---
 Changelog.md                  |  4 ++++
 build/index.php               | 25 +++++++++++++++++--------
 docs/RestApi/api_data.js      | 19 ++++++++++++++++---
 docs/RestApi/api_data.json    | 19 ++++++++++++++++---
 docs/RestApi/api_project.js   |  2 +-
 docs/RestApi/api_project.json |  2 +-
 module_index.json             | 18 +++++++++---------
 modules/action-random.php     | 10 ++++++++--
 modules/page-view.php         |  4 ++--
 9 files changed, 74 insertions(+), 29 deletions(-)

diff --git a/Changelog.md b/Changelog.md
index bab6303..9df95eb 100644
--- a/Changelog.md
+++ b/Changelog.md
@@ -3,6 +3,10 @@ This file holds the changelog for Pepperminty Wiki. This is the master list of t
 
 ## v0.16-dev
 
+### Added
+ - [Rest API] Added support for the `mode` parameter to the `random` action.
+ - Fixed various issues with both the module api & the rest api docs.
+
 ### Fixed
  - Properly escaped content of short code box on file pages
  - Display a more meaningful message to a logged in user if editing is disabled
diff --git a/build/index.php b/build/index.php
index 8763dc3..0dc2410 100644
--- a/build/index.php
+++ b/build/index.php
@@ -2271,11 +2271,15 @@ register_module([
 		 * @apiName RawSource
 		 * @apiGroup Page
 		 * @apiPermission Anonymous
+		 *
+		 * @apiParam	{string}	mode	The view mode to redirect to. This parameter is basically just passed through to the direct - it works in the same way as the mode parameter on the _view_ action does.
 		 */
 		
 		add_action("random", function() {
 			global $pageindex;
 			
+			$mode = preg_replace("/[^a-z-_]/i", "", $_GET["mode"] ?? "");
+			
 			$pageNames = array_keys(get_object_vars($pageindex));
 			
 			// Filter out pages we shouldn't send the user to
@@ -2287,7 +2291,9 @@ register_module([
 			$randomPageName = $pageNames[array_rand($pageNames)];
 			
 			http_response_code(307);
-			header("location: ?page=" . rawurlencode($randomPageName));
+			$redirect_url = "?page=" . rawurlencode($randomPageName);
+			if(!empty($mode)) $redirect_url .= "&mode=$mode";
+			header("location: $redirect_url");
 		});
 		
 		add_help_section("26-random-redirect", "Jumping to a random page", "<p>$settings->sitename has a function that can send you to a random page. To use it, click <a href='?action=random'>here</a>. $settings->admindetails_name ($settings->sitename's adminstrator) may have added it to one of the menus.</p>");
@@ -3156,13 +3162,13 @@ SCRIPT;
 
 register_module([
 	"name" => "Page History",
-	"version" => "0.3",
+	"version" => "0.3.1",
 	"author" => "Starbeamrainbowlabs",
 	"description" => "Adds the ability to keep unlimited page history, limited only by your disk space. Note that this doesn't store file history (yet). Currently depends on feature-recent-changes for rendering of the history page.",
 	"id" => "feature-history",
 	"code" => function() {
 		/**
-		 * @api {get} ?action=history&page={pageName} Get a list of revisions for a page
+		 * @api {get} ?action=history&page={pageName}[&format={format}] Get a list of revisions for a page
 		 * @apiName History
 		 * @apiGroup Page
 		 * @apiPermission Anonymous
@@ -3590,7 +3596,7 @@ register_module([
 
 register_module([
 	"name" => "Search",
-	"version" => "0.6",
+	"version" => "0.6.1",
 	"author" => "Starbeamrainbowlabs",
 	"description" => "Adds proper search functionality to Pepperminty Wiki using an inverted index to provide a full text search engine. If pages don't show up, then you might have hit a stop word. If not, try requesting the `invindex-rebuild` action to rebuild the inverted index from scratch.",
 	"id" => "feature-search",
@@ -5159,7 +5165,7 @@ register_module([
 			header("content-disposition: inline; filename=\"$shortFilename\"");
 			header("last-modified: " . gmdate('D, d M Y H:i:s T', $pageindex->{$env->page}->lastmodified));
 			
-			// If the size is set or original, then send (or redirect to) the original image
+			// If the size is set to original, then send (or redirect to) the original image
 			// Also do the same for SVGs if svg rendering is disabled.
 			if(isset($_GET["size"]) and $_GET["size"] == "original" or
 				(empty($settings->render_svg_previews) && $mime_type == "image/svg+xml"))
@@ -6321,6 +6327,7 @@ window.addEventListener("load", function(event) {
 		 * @api {post} ?action=preview-edit&page={pageName}[&newpage=yes]	Get a preview of the page
 		 * @apiDescription	Gets a preview of the current edit state of a given page
 		 * @apiName 		PreviewPage
+		 * @apiGroup		Editing
 		 * @apiPermission	Anonymous
 		 * 
 		 * @apiUse	PageParameter
@@ -6823,11 +6830,13 @@ register_module([
 		global $settings;
 		
 		/**
-		 * @api		{get}	?action=list	List all pages 
+		 * @api		{get}	?action=list[&format={format}]	List all pages 
 		 * @apiDescription	Gets a list of all the pages currently stored on the wiki.
 		 * @apiName		ListPages
 		 * @apiGroup	Page
 		 * @apiPermission	Anonymous
+		 *
+		 * @apiParam	{string}	format	The format to return the page list in. Default: html. Other foramts available: json, text
 		 */
 		
 		/*
@@ -7596,14 +7605,14 @@ register_module([
 	"id" => "page-view",
 	"code" => function() {
 		/**
-		 * @api	{get}	?action=view[&page={pageName}][&revision=rid][&printable=yes]	View a page
+		 * @api	{get}	?action=view[&page={pageName}][&revision=rid][&printable=yes][&mode={mode}]	View a page
 		 * @apiName			View
 		 * @apiGroup		Page
 		 * @apiPermission	Anonymous
 		 * 
 		 * @apiUse PageParameter
 		 * @apiParam	{number}	revision	The revision number to display.
-		 * @apiParam	{string}	mode		Optional. The display mode to use. Can hld the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the `raw` action).
+		 * @apiParam	{string}	mode		Optional. The display mode to use. Can hold the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the `raw` action).
 		 *
 		 * @apiError	NonExistentPageError	The page doesn't exist and editing is disabled in the wiki's settings. If editing isn't disabled, you will be redirected to the edit page instead.
 		 * @apiError	NonExistentRevisionError	The specified revision was not found.
diff --git a/docs/RestApi/api_data.js b/docs/RestApi/api_data.js
index 092f9c2..cda8cec 100644
--- a/docs/RestApi/api_data.js
+++ b/docs/RestApi/api_data.js
@@ -616,7 +616,7 @@ define({ "api": [
   },
   {
     "type": "get",
-    "url": "?action=random",
+    "url": "?action=random[&mode={mode}]",
     "title": "Redirects to a random page.",
     "name": "RawSource",
     "group": "Page",
@@ -627,6 +627,19 @@ define({ "api": [
         "description": ""
       }
     ],
+    "parameter": {
+      "fields": {
+        "Parameter": [
+          {
+            "group": "Parameter",
+            "type": "string",
+            "optional": false,
+            "field": "mode",
+            "description": "<p>The view mode to redirect to. This parameter is basically just passed through to the direct - it works in the same way as the mode parameter on the <em>view</em> action does.</p>"
+          }
+        ]
+      }
+    },
     "version": "0.0.0",
     "filename": "./modules/action-random.php",
     "groupTitle": "Page"
@@ -663,7 +676,7 @@ define({ "api": [
   },
   {
     "type": "get",
-    "url": "?action=view[&page={pageName}][&revision=rid][&printable=yes]",
+    "url": "?action=view[&page={pageName}][&revision=rid][&printable=yes][&mode={mode}]",
     "title": "View a page",
     "name": "View",
     "group": "Page",
@@ -689,7 +702,7 @@ define({ "api": [
             "type": "string",
             "optional": false,
             "field": "mode",
-            "description": "<p>Optional. The display mode to use. Can hld the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the <code>raw</code> action).</p>"
+            "description": "<p>Optional. The display mode to use. Can hold the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the <code>raw</code> action).</p>"
           },
           {
             "group": "Parameter",
diff --git a/docs/RestApi/api_data.json b/docs/RestApi/api_data.json
index a5bff12..123f895 100644
--- a/docs/RestApi/api_data.json
+++ b/docs/RestApi/api_data.json
@@ -616,7 +616,7 @@
   },
   {
     "type": "get",
-    "url": "?action=random",
+    "url": "?action=random[&mode={mode}]",
     "title": "Redirects to a random page.",
     "name": "RawSource",
     "group": "Page",
@@ -627,6 +627,19 @@
         "description": ""
       }
     ],
+    "parameter": {
+      "fields": {
+        "Parameter": [
+          {
+            "group": "Parameter",
+            "type": "string",
+            "optional": false,
+            "field": "mode",
+            "description": "<p>The view mode to redirect to. This parameter is basically just passed through to the direct - it works in the same way as the mode parameter on the <em>view</em> action does.</p>"
+          }
+        ]
+      }
+    },
     "version": "0.0.0",
     "filename": "./modules/action-random.php",
     "groupTitle": "Page"
@@ -663,7 +676,7 @@
   },
   {
     "type": "get",
-    "url": "?action=view[&page={pageName}][&revision=rid][&printable=yes]",
+    "url": "?action=view[&page={pageName}][&revision=rid][&printable=yes][&mode={mode}]",
     "title": "View a page",
     "name": "View",
     "group": "Page",
@@ -689,7 +702,7 @@
             "type": "string",
             "optional": false,
             "field": "mode",
-            "description": "<p>Optional. The display mode to use. Can hld the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the <code>raw</code> action).</p>"
+            "description": "<p>Optional. The display mode to use. Can hold the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the <code>raw</code> action).</p>"
           },
           {
             "group": "Parameter",
diff --git a/docs/RestApi/api_project.js b/docs/RestApi/api_project.js
index 877815f..192597e 100644
--- a/docs/RestApi/api_project.js
+++ b/docs/RestApi/api_project.js
@@ -8,7 +8,7 @@ define({
   "apidoc": "0.3.0",
   "generator": {
     "name": "apidoc",
-    "time": "2018-02-14T22:22:08.521Z",
+    "time": "2018-02-14T22:36:20.697Z",
     "url": "http://apidocjs.com",
     "version": "0.17.6"
   }
diff --git a/docs/RestApi/api_project.json b/docs/RestApi/api_project.json
index dac1281..592bc4c 100644
--- a/docs/RestApi/api_project.json
+++ b/docs/RestApi/api_project.json
@@ -8,7 +8,7 @@
   "apidoc": "0.3.0",
   "generator": {
     "name": "apidoc",
-    "time": "2018-02-14T22:22:08.521Z",
+    "time": "2018-02-14T22:36:20.697Z",
     "url": "http://apidocjs.com",
     "version": "0.17.6"
   }
diff --git a/module_index.json b/module_index.json
index 4ff6766..6d7e385 100755
--- a/module_index.json
+++ b/module_index.json
@@ -23,7 +23,7 @@
         "author": "Starbeamrainbowlabs",
         "description": "Adds an action called 'random' that redirects you to a random page.",
         "id": "action-random",
-        "lastupdate": 1508968415,
+        "lastupdate": 1518647615,
         "optional": false
     },
     {
@@ -73,11 +73,11 @@
     },
     {
         "name": "Page History",
-        "version": "0.3",
+        "version": "0.3.1",
         "author": "Starbeamrainbowlabs",
         "description": "Adds the ability to keep unlimited page history, limited only by your disk space. Note that this doesn't store file history (yet). Currently depends on feature-recent-changes for rendering of the history page.",
         "id": "feature-history",
-        "lastupdate": 1508967873,
+        "lastupdate": 1518645062,
         "optional": false
     },
     {
@@ -100,11 +100,11 @@
     },
     {
         "name": "Search",
-        "version": "0.6",
+        "version": "0.6.1",
         "author": "Starbeamrainbowlabs",
         "description": "Adds proper search functionality to Pepperminty Wiki using an inverted index to provide a full text search engine. If pages don't show up, then you might have hit a stop word. If not, try requesting the `invindex-rebuild` action to rebuild the inverted index from scratch.",
         "id": "feature-search",
-        "lastupdate": 1517751847,
+        "lastupdate": 1517752177,
         "optional": false
     },
     {
@@ -122,7 +122,7 @@
         "author": "Starbeamrainbowlabs",
         "description": "Adds the ability to upload files to Pepperminty Wiki. Uploaded files act as pages and have the special 'File\/' prefix.",
         "id": "feature-upload",
-        "lastupdate": 1517061220,
+        "lastupdate": 1518645569,
         "optional": false
     },
     {
@@ -167,7 +167,7 @@
         "author": "Starbeamrainbowlabs",
         "description": "Allows you to edit pages by adding the edit and save actions. You should probably include this one.",
         "id": "page-edit",
-        "lastupdate": 1514762051,
+        "lastupdate": 1518645807,
         "optional": false
     },
     {
@@ -194,7 +194,7 @@
         "author": "Starbeamrainbowlabs",
         "description": "Adds a page that lists all the pages in the index along with their metadata.",
         "id": "page-list",
-        "lastupdate": 1505769119,
+        "lastupdate": 1518645476,
         "optional": false
     },
     {
@@ -248,7 +248,7 @@
         "author": "Starbeamrainbowlabs",
         "description": "Allows you to view pages. You really should include this one.",
         "id": "page-view",
-        "lastupdate": 1505491849,
+        "lastupdate": 1518647294,
         "optional": false
     },
     {
diff --git a/modules/action-random.php b/modules/action-random.php
index 2755c8f..5ff642e 100644
--- a/modules/action-random.php
+++ b/modules/action-random.php
@@ -8,15 +8,19 @@ register_module([
 	"code" => function() {
 		global $settings;
 		/**
-		 * @api {get} ?action=random Redirects to a random page.
+		 * @api {get} ?action=random[&mode={mode}] Redirects to a random page.
 		 * @apiName RawSource
 		 * @apiGroup Page
 		 * @apiPermission Anonymous
+		 *
+		 * @apiParam	{string}	mode	The view mode to redirect to. This parameter is basically just passed through to the direct - it works in the same way as the mode parameter on the _view_ action does.
 		 */
 		
 		add_action("random", function() {
 			global $pageindex;
 			
+			$mode = preg_replace("/[^a-z-_]/i", "", $_GET["mode"] ?? "");
+			
 			$pageNames = array_keys(get_object_vars($pageindex));
 			
 			// Filter out pages we shouldn't send the user to
@@ -28,7 +32,9 @@ register_module([
 			$randomPageName = $pageNames[array_rand($pageNames)];
 			
 			http_response_code(307);
-			header("location: ?page=" . rawurlencode($randomPageName));
+			$redirect_url = "?page=" . rawurlencode($randomPageName);
+			if(!empty($mode)) $redirect_url .= "&mode=$mode";
+			header("location: $redirect_url");
 		});
 		
 		add_help_section("26-random-redirect", "Jumping to a random page", "<p>$settings->sitename has a function that can send you to a random page. To use it, click <a href='?action=random'>here</a>. $settings->admindetails_name ($settings->sitename's adminstrator) may have added it to one of the menus.</p>");
diff --git a/modules/page-view.php b/modules/page-view.php
index 8c08ce3..7166e26 100644
--- a/modules/page-view.php
+++ b/modules/page-view.php
@@ -7,14 +7,14 @@ register_module([
 	"id" => "page-view",
 	"code" => function() {
 		/**
-		 * @api	{get}	?action=view[&page={pageName}][&revision=rid][&printable=yes]	View a page
+		 * @api	{get}	?action=view[&page={pageName}][&revision=rid][&printable=yes][&mode={mode}]	View a page
 		 * @apiName			View
 		 * @apiGroup		Page
 		 * @apiPermission	Anonymous
 		 * 
 		 * @apiUse PageParameter
 		 * @apiParam	{number}	revision	The revision number to display.
-		 * @apiParam	{string}	mode		Optional. The display mode to use. Can hld the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the `raw` action).
+		 * @apiParam	{string}	mode		Optional. The display mode to use. Can hold the following values: 'normal' - The default. Sends a normal page. 'printable' - Sends a printable version of the page. 'contentonly' - Sends only the content of the page, not the extra stuff around it. 'parsedsourceonly' - Sends only the raw rendered source of the page, as it appears just after it has come out of the page parser. Useful for writing external tools (see also the `raw` action).
 		 *
 		 * @apiError	NonExistentPageError	The page doesn't exist and editing is disabled in the wiki's settings. If editing isn't disabled, you will be redirected to the edit page instead.
 		 * @apiError	NonExistentRevisionError	The specified revision was not found.
