Programming Documentation

NacoWiki is supposed to be extensible. This is done through a Plugin architecture. Plugins can hook events that change the behaviour of NacoWiki or add new functionality.

Documentation for the PHP Programming interface is generated automatically.

php-api

To create a plugin you can refer to the already existing plugins in the standard distribution. At a high-level you need to create a file containing the class that will encapsulate your plugin.

Example

For example:

use NWiki\PluginCollection as Plugins;
use NWiki\Util as Util;
use NWiki\Core as Core;
use NWiki\Cli as Cli;

class SamplePlugin {
  const VERSION ='0.0';
  /** sample command
   *
   * @param \NanoWikiApp $wiki running wiki instance
   * @param array &$argv Command line arguments
   * @phpcod commands##sample
   * @event cli:sample
   */
  static function render(\NacoWikiApp $wiki, array &$argv) : ?bool {
    print_r($argv);
  }
  static function load(array $cfg) : void {
    Plugins::autoload(self::class);
  }
}

This implements a simple plugin that registers a new CLI command. The event registration is by calling Plugins::autoload method. This method looks for the PHP documentation string that contains the tag @event followed by the event to hook: cli:sample in this example.

Event Hooks

The following events can be hooked:

action:[name]

This event is called in response of a $_POST[action] in the HTTP request. It is used to trigger a specific action in response to a HTTP post request.

There are no special event parameters

api:[name]

This event is called in response of a $_GET[api] in the URL's query string. It is used to trigger a specific REST API end point.

Event data:

check_readable

This event can be used by plugins that implement access control. This event is used to check if the given file path can be read by the current user.

Event data:

check_writable

This event can be used by plugins that implement access control. This event is used to check if the given file path can be written by the current user.

Event data:

cli:[name]

This event is used to handle CLI the [name] sub-command.

The event data contains the command line arguments for the sub-command.

context_loaded

This event is called right after the context has been loaded.

There are no special event parameters

do:[name]

This event is called in response of a $_GET[do] in the URL's query string. It is used to trigger a specific command.

There are no special event parameters

edit:[file-extension]

This event is used by media handlers to output to the web browser a possibly custom page to edit media.

Typically this is used to pre-format the editable content separating metadata and body text. Also, to display a codemirror with the right modules loaded and initialized to the right mode.

Event data:

error_msg

This event is called to implement custom error handlers.

Event data:

infobox

This event can be used to add elements to the infobox table of the top nav bar.

Event data:

layout:[file-extension]

This event is used by media handlers to output to the web browser a possibly custom layout for the given media type.

Event data:

log-props

This event is used to manipulate properties and meta headers before a file is saved.

Event data:

missing:[file-extension]

This event is used by media handlers to output to the web browser a possibly custom page to create missing media.

Event data:

missing_page

This event is used to handle http 404 errors (missing resource)

There are no special event parameters

This event can be used to add elements to the meta data drop down.

Event data:

Possible modes:

post-render

This event is used by plugins to post-process data. This specific event triggers for any file regardless of the file extension.

Plugins using this hook can post-process the generated HTML.

Event data:

post-render:[file-extension]

This event is used by plugins to post-process data. This specific event only triggers for pages matching the given file extension.

Plugins using this hook can post-process the generated HTML.

Event data:

postSave

This event is used by plugins to examine data after it was saved to storage.

Usually used to update additional meta data files, like for example update a tag cloud index.

Event data:

postSave:[file-extension]

This event is used by media handlers to examine data after it was saved to storage.

Event data:

pre-render

This event is used by plugins to pre-process data. This specific event triggers for any file regardless of the file extension.

Since this is a pre-render event, the html element actually contains text before HTML is generated, but may be modified by the pre-render hook.

Event data:

pre-render:[file-extension]

This event is used by plugins to pre-process data. This specific event only triggers for pages matching the given file extension.

Since this is a pre-render event, the html element actually contains text before HTML is generated, but may be modified by the pre-render hook.

Event data:

preRead

This event is used to modify data read from disk. It is intended for versioning plugins to display different versions of a file.

Event data:

preSave

This event is used by plugins to pre-parse text before saving to storage.

Hooks can examine the data to be saved in the text element of the event array and modify it if needed.

Event data:

preSave:[file-extension]

This event is used by plugins to pre-parse text before saving to storage.

Hooks can examine the data to be saved in the text element of the event array and modify it if needed.

Usually is used by media handlers to pre-parse data, separating header meta data from actual content. And sanitizing any problematic input.

It is recommended to move 'log' keys from the user entered meta data block to the props array using Core::logProps which will add the log text to the change log.

Event data:

read:[file-extension]

This event is used for media handlers to parse source text and extract header meta data, and the actual payload containing the body of the page content.

Event data:

read_folder

This event is used to handle navigation to a folder. i.e. URL is a folder.

There are no special event parameters

read_page

This event is used to handle navigation to a page. i.e. URL is an actual file.

Event data:

render:[file-extension]

This event is used by media handlers to convert the source to HTML.

The hook must take the html element from the event which contains possibily pre-processed input, and convert it to HTML.

Event data:

run_init

This event is called right when the run method is called. Plugins can use this to initialize things. Specifically for using the declareContext.

There are no special event parameters

save:[file-extension]

This event is used by plugins to save to storage.

Usually is used by media handlers to save data using custom file formats.

Event data:

view:[file-extension]

This event is used by plugins to process data. If a plugin handle this event, it by-passes any other Core related functionality. The plugin then is responsible for generating all the output related to this document.

Event data:

Customizing errors

When hooking the error_msg event, the following errors will be generated:

tag error reference
config WIKI configuration error nacowiki.php,195
duplicate already exists classes/Core.php,900
internal_error Internal error. classes/Core.php,921
invalid internal state plugins/Versions.php,185, plugins/Versions.php,214
broken versions plugins/Versions.php,210
Unable to calculate version plugins/Versions.php,339, plugins/Versions.php,649
invalid_param Specified DO does not exist nacowiki.php,517
Specified action does not exist nacowiki.php,560
un-supported file type plugins/Versions.php,329, plugins/Versions.php,496, plugins/Versions.php,550, plugins/Versions.php,638
no versions found plugins/Versions.php,333, plugins/Versions.php,565, plugins/Versions.php,643
versions to compare missing plugins/Versions.php,508
invalid_target Can not delete root folder classes/Core.php,804
Cannot rename root directory classes/Core.php,881
Folder not editable classes/Core.php,957
folders not editable classes/Core.php,1031
can not attach to file classes/Core.php,1198, classes/Core.php,1203
missing_param Missing input parameter nacowiki.php,550
no-op no changes made classes/Core.php,887
os_error rmdir error classes/Core.php,41, classes/Core.php,841, classes/Core.php,844
mkdir error classes/Core.php,57
unlink error classes/Core.php,812, classes/Core.php,824, classes/Core.php,857
rename file error classes/Core.php,929
write error classes/Core.php,1121
error saving uploaded file classes/Core.php,1229
invalid internal state plugins/Versions.php,167
error saving version data plugins/Versions.php,231
param unknown scope classes/Core.php,170
no name specified classes/Core.php,884
invalid form response classes/Core.php,1213
zero file upload classes/Core.php,1216
upload form error classes/Core.php,1218
missing file upload classes/Core.php,1220
read_access User does not have read-access. nacowiki.php,566, nacowiki.php,578
write_access User does not have write-access. nacowiki.php,547
Delete access error classes/Core.php,800
rename access error classes/Core.php,891
write access error classes/Core.php,960, classes/Core.php,1034
no write access classes/Core.php,1189

REST API

A basic REST API is available for use for use with JavaScript code running on the browser.

The following API calls are currently defined:

page-list

Returns a page list

This is used by the JavaScript to render a tree of available pages.

The event parameter is filled with a property output containing