Merge branch '9.2RC'master

1 files changed, 175 insertions, 17 deletions

diff --git a/Zotlabs/Module/Help.php b/Zotlabs/Module/Help.php
index 55ac80842..fd5cacee6 100644
--- a/Zotlabs/Module/Help.php
+++ b/Zotlabs/Module/Help.php
@@ -1,7 +1,7 @@
 <?php
 namespace Zotlabs\Module;
 
-require_once('include/help.php');
+use Michelf\MarkdownExtra;
 
 /**
  * You can create local site resources in doc/Site.md and either link to doc/Home.md for the standard resources
@@ -14,7 +14,50 @@ require_once('include/help.php');
  */
 class Help extends \Zotlabs\Web\Controller {
 
-	function get() {
+	use \Zotlabs\Lib\Traits\HelpHelperTrait;
+
+	private string $heading_slug = '';
+
+	/**
+	 * Associative array containing the detected language.
+	 */
+	public array $lang = [
+		'language' => 'en',		//! Detected language, 2-letter ISO 639-1 code ("en")
+		'from_url' => false,	//! true if language from URL overrides browser default
+	];
+
+	/**
+	 * Pre-check before processing request.
+	 *
+	 * Determine language requested, and ensure that a topic was requested.
+	 * If no topic was requested, redirect to the about page, and abort
+	 * processing.
+	 */
+	public function init() {
+		$this->determine_help_language();
+
+		if (argc() === 1) {
+			goaway("/help/{$this->lang['language']}/about/about");
+			killme();
+		}
+	}
+
+	/**
+	 * Process get request for the help module.
+	 *
+	 * Loads the correct help file from the `doc/` directory, and passes it to
+	 * the help template in `view/tpl/help.tpl`.
+	 *
+	 * If the requested help topic does not exist for the currently selected
+	 * language, a 404 status is returned instead.
+	 *
+	 * This function currently also handles search and serving static assets
+	 * that may be used by the help files.
+	 *
+	 * @return string	The rendered help page or a 404 page if help topic was
+	 *	not found.
+	 */
+	public function get() {
 		nav_set_selected('Help');
 
 		$o = '';
@@ -81,6 +124,120 @@ class Help extends \Zotlabs\Web\Controller {
 			killme();
 		}
 
+		//
+		// The args to the module will be along this pattern:
+		//
+		//     help/<lang>/<subdir..>/<topic>
+		//
+		// Where `<lang>` is the language which we want to fetch the topic. This
+		// element is optional, but will be used to override the browser language
+		// preference if it exists.
+		//
+		// There may be zero or more `<subdir...>` elements. If there are any
+		// present, the first subdir will be used as the slug to find the
+		// heading of the help page.
+		//
+		// The `<topic>` should be the name of a file within the given language
+		// and subdirectory tree under the `doc/` directory of the site file
+		// system. The topic is given _without_ the file extension, which will be
+		// determined by the module.
+		//
+		// The valid file extensions for help topic are:
+		//
+		//   - `.md` for markdown formatted source files.
+		//   - `.bb` for bbcode formatted source files.
+		//   - `.html` for help topics in html format.
+		//
+
+		// Strip away the module name from the args
+		$args = array_slice(\App::$argv, 1);
+
+		// Remove language if necessary
+		//
+		// The language was determined during pre-request processing in the
+		// `init` function.
+		if ($this->lang['from_url']) {
+			array_shift($args);
+		}
+
+		// Keep the first remaining arg as the heading slug
+		$this->heading_slug = $args[0];
+
+		// Locate the file for the topic in the doc directory
+		$this->find_help_file(implode('/', $args), $this->lang['language']);
+
+		$this->set_page_title();
+
+		if (empty($this->file_name)) {
+			header($_SERVER["SERVER_PROTOCOL"] . ' 404 ' . t('Not Found'));
+			$tpl = get_markup_template("404.tpl");
+			return replace_macros($tpl, array(
+				'$message' => t('Page not found.')
+			));
+
+		} else {
+			$tpl = get_markup_template('help.tpl');
+			return replace_macros($tpl, [ '$module' => $this ]);
+		}
+	}
+
+	public function render_content(): string {
+		return $this->render_help_file($this->file_name, $this->file_type);
+	}
+
+	public function render_help_file(string $file_name, string $file_type): string {
+		$raw_text = file_get_contents($file_name);
+
+		switch ($file_type) {
+		case 'md':
+			// We need to escape the `#include` statements in the original file,
+			// to be sure it's not rendered as a heading by markdown.
+			$raw_text = preg_replace('/#include/ism', '%%include', $raw_text);
+			$content = MarkdownExtra::defaultTransform($raw_text);
+			$content = preg_replace('/%%include/ism', '#include', $content);
+			break;
+
+		case 'bb':
+			$content = zidify_links(bbcode($raw_text));
+			break;
+
+		case 'html':
+			$content = parseIdentityAwareHTML($raw_text);
+			break;
+		}
+
+		// Replace includes with the contents of the included file
+		$content = preg_replace_callback(
+			"/#include (.*?)\;/ism",
+			function ($matches) {
+				$parts = explode('.', $matches[1]);
+				$sub_file_type = array_pop($parts);
+				$included_content = $this->render_help_file($matches[1], $sub_file_type);
+				return str_replace($matches[0], $included_content, $matches[0]);
+			},
+			$content
+		);
+
+		return translate_projectname($content);
+	}
+
+	public function get_page_title(): string {
+		$title = t('$Projectname Documentation');
+		$heading = $this->get_heading();
+
+		if (! empty($heading)) {
+			$title .= ': ' . $heading;
+		}
+
+		return $title;
+	}
+
+	public function get_toc_heading(): string {
+		return t('Contents');
+	}
+
+
+	private function get_heading(): string {
 		$headings = [
 			'about'     => t('About'),
 			'member'    => t('Members'),
@@ -89,21 +246,22 @@ class Help extends \Zotlabs\Web\Controller {
 			'tutorials' => t('Tutorials')
 		];
 
-		$heading = '';
-		if(array_key_exists(argv(1), $headings))
-			$heading = $headings[argv(1)];
-
-		$content =  get_help_content();
-
-		$language = determine_help_language()['language'];
-
-		return replace_macros(get_markup_template('help.tpl'), array(
-			'$title'      => t('$Projectname Documentation'),
-			'$tocHeading' => t('Contents'),
-			'$content'    => $content,
-			'$heading'    => $heading,
-			'$language'   => $language
-		));
+		if(array_key_exists($this->heading_slug, $headings)) {
+			return $headings[$this->heading_slug];
+		} else {
+			return '';
+		}
 	}
 
+	/**
+	 * Set the page title to an unslugified version of the file name.
+	 *
+	 * @Note This modifies the global `App::$page['title']` property.
+	 */
+	private function set_page_title(): void {
+		$title = basename($this->file_name, ".{$this->file_type}");
+		\App::$page['title'] =
+			t('Help:') . ' '
+			. ucwords(str_replace(['-', '_'],' ',notags($title)));
+	}
 }