sbrl-github/Pepperminty-Wiki
sbrl-github/Pepperminty-Wiki
1
0
Fork 0
mirror of https://github.com/sbrl/Pepperminty-Wiki.git synced 2024-11-16 02:23:01 +00:00
Code Activity
Pepperminty-Wiki/docs/50-Writing-Modules.md

9.7 KiB
Raw Blame History

Developer Documentation

The core of Pepperminty Wiki exposes several global objects, classes, functions, and miscellaneous files that you can use to write your own modules. This page documents these them so that you can create your own modules more easily.

Table of Contents

HTTP API

The HTTP API provided by Pepperminty Wiki itself is documented for bot owners and software developers alike. Find it via the HTTP API section in the sidebar of this page.

Module API

The main PHP-based module API is documented with PHPDoc. It can be found via the PHP Module API section in the sidebar of this page.

This documentation covers all the functions and classes available in both the Pepperminty Wiki core, and the modules stored in this repository - as well as mentioning which module they are a part of.

There are one or two additional things that haven't made their way into the module api docs, which are detailed below:

page_renderer::register_part_preprocessor($code)

This function's use is more complicated to explain. Pepperminty Wiki renders pages with a very simple templating system. For example, in the template a page's content is denoted by {content}. A function registered here will be passed all the components of a page just before they are dropped into the template. Note that the function you pass in here should take a reference to the components, as the return value of the function passed is discarded. Here's an example:

<?php
register_module([
	"name" => "Content shuffler",
	"version" => "0.1",
	"author" => "Bob",
	"description" => "Shuffles the content of a page randomly.",
	"id" => "extra-content-shuffler",
	"code" => function() {
		page_renderer::register_part_preprocessor(function(&$parts) {
			$parts["{body}"] = str_shuffle($parts["{body}"]);
		});
	}
]);

?>

Currently, the following parts are used in the templating process:

Key Purpose
{body} Holds the main body of the page.
{sitename} The name of the current installation of Pepperminty Wiki
{version} The current version of Pepperminty Wiki
{favicon-url} The url of the favicon.
{header-html} The extra HTML that will be added to the <head /> tag.
{navigation-bar} The navigation bar's HTML.
{navigation-bar-bottom} The bottom navigation bar's HTML.
{admin-details-name} The name of the administrator.
{admin-details-email} The email address of the administrator.
{admins-name-list} The list of moderator's (user)names.
{generation-date} The date at which the page was generated.
{all-pages-datalist} The <datalist /> tag that powers the search bar.
{footer-message} The message in the footer of the page.
{content} The main content of the page
{extra} Content that gets put directly after the <main> element.
{title} The page title.

Take a look at the code to see the very latest list of parts.

add_parser($code)

This function adds a parser to Pepperminty Wiki. An example follows below, but please note that this will probably be changing soon so that the parser's name is attached to it when it is registered. This is so that the user can choose which of the registered parsers are used at any one time.

<?php
register_module([
	"name" => "Reverse parser",
	"version" => "0.1",
	"author" => "Bob",
	"description" => "A parser that reverse the page's source.",
	"id" => "parser-reverse",
	"code" => function() {
		add_parser(function($source) {
			return strrev($source);
		});
	}
]);

?>

Global Variables

There are a number of global variables floating around that can give you a lot of information about the current request. I will be tidying them up into a single $env object soon. Most of the below have been tidied up into a single $env object now! Below is a table of all the variables Pepperminty Wiki has lying around:

Variable Description
$version The current version of Pepperminty Wiki
$commit The git commit that the current version of Pepperminty Wiki was built from.
$env An object that contains a bunch of useful information about the current request.
$env->page The current page name.
$env->page_filename The filename that the current page is stored in.
$env->is_history_revision Whether the requested page is a history revision or not.
$env->history->revision_number The requested revision number.
$env->history->revision_data The history revision object from the page index for the current page.
$env->user The current user's name. Defaults to $settings->anonymous_user_name.
$env->is_logged_in Whether the current user is currently logged in.
$env->is_admin Whether the current user is an administrator.
$env->user_data The currently logged in user's data object from $settings. Don't forget to call save_settings() if you edit this.
$env->storage_prefix The location that the wiki data is stored in, including the trailing directory separator.
$env->perfdata Contains various performance information. Feel free to dump additional perf data in here.
$env->action The current action.
$settings The settings object from the top of the file.
$pageindex Contains a list of all the pages that Pepperminty Wiki currently knows about, along with information about each page. Exists to improve performance.
$paths->pageindex The location of the page index. Don't forget about save_pageindex().
$paths->searchindex The location of the search index.
$paths->idindex The location of the page id index. Useful in conjunction with the search index, since page ids are used to compress & optimise the search index. Don't forget about the ids class, which automatically loads this index.
$paths->statsindex The location of the statistics index, which holds a bunch of pre-calculated statistics. These may not all be updated.
$paths->interwiki_index The interwiki index cache.
$paths->cache_directory The cache directory, without a trailing directory separator. Store cached stuff in here. Current parser-parsedown stores HTML versions of pages in here, for example. Guaranteed to exist.
$paths->settings_file The location of peppermint.json.
$paths->extra_data_directory The location of the directory that extra data is extracted to.
$paths->upload_file_prefix The prefix that's prepended when uploading files.

Files

Pepperminty Wiki maintains several files (most of which are indexes) containing various information about the current site that you can utilise. Some of them also have an 'API' of sorts that you can use to interact with them - which is documented in the module api above.

pageindex.json

This is by far the most important index. It contains an entry for each page, under which a number of interesting pieces of information are stored. It's automatically loaded into the global variable $pageindex too, so you don't even have to read it in. Here's an example pageindex:

{
	"Internal link": {
		"filename": "Internal link.md",
		"size": 120,
		"lastmodified": 1446019377,
		"lasteditor": "admin",
		"tags": [
			"testing",
			"test tag with spaces",
			"really really really really really really long tag"
		]
	},
	"Main Page": {
		"filename": "Main Page.md",
		"size": 151,
		"lastmodified": 1446388276,
		"lasteditor": "admin",
		"tags": []
	},
	"Internal link\/Sub": {
		"filename": "Internal link\/Sub.md",
		"size": 35,
		"lastmodified": 1446370194,
		"lasteditor": "admin",
		"tags": [
			"test"
		]
	},
	"Files\/AJ Scr.png": {
		"filename": "Files\/AJ Scr.png.md",
		"size": 29,
		"lastmodified": 1445501914,
		"lasteditor": "admin",
		"uploadedfile": true,
		"uploadedfilepath": "Files\/AJ Scr.png",
		"uploadedfilemime": "image\/png"
	}
}

Currently, Pepperminty Wiki is configured to pretty print the json in the pageindex when saving it to disk, so if you find yourself saving the pageindex please do the same.

Now that alternate data storage directories are supported, the $entry->filename will not contain the $env->storage_prefix prefix. You will need to add this manually if you use it.

idindex.json

The id index converts page ids into page names and vice versa. It's loaded into the global variable $idindex, but you normally wouldn't need to touch that, as there's a seamless API that you can use instead, which can be found under the ids class.

invindex.json

This is the main search index. Obviously, it's only present if the feature-search module is loaded and active. It can be interacted with though the search class that the feature-search module exposes.

recent-changes.json

This is not loaded automatically, but it contains a list of recent changes that have occurred throughout the wiki. You don't have to fiddle with it directly though if you just want to add a new change, because the feature-recent-changes module has a fewe handy methods you can use for that purpose.

statsindex.json

This file is brand new as of v0.15, and contains the most recently calculated statistics about the wiki. The feature-stats module oversees the regeneration of this file. Consult if you need access to such statistics that might be somewhat expensive to calculate.