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,197
duplicate already exists classes/Core.php,918
internal_error Internal error. classes/Core.php,939
invalid internal state plugins/Versions.php,224, plugins/Versions.php,254
broken versions plugins/Versions.php,250
Unable to calculate version plugins/Versions.php,382, plugins/Versions.php,726
invalid_param Specified DO does not exist nacowiki.php,519
Specified action does not exist nacowiki.php,562
un-supported file type plugins/Versions.php,372, plugins/Versions.php,540, plugins/Versions.php,628, plugins/Versions.php,715
no versions found plugins/Versions.php,376, plugins/Versions.php,643, plugins/Versions.php,720
versions to compare missing plugins/Versions.php,552
invalid_target Can not delete root folder classes/Core.php,822
Cannot rename root directory classes/Core.php,899
Folder not editable classes/Core.php,975
folders not editable classes/Core.php,1049
can not attach to file classes/Core.php,1216, classes/Core.php,1221
missing_param Missing input parameter nacowiki.php,552
no-op no changes made classes/Core.php,905
os_error rmdir error classes/Core.php,44, classes/Core.php,859, classes/Core.php,862
mkdir error classes/Core.php,60
unlink error classes/Core.php,830, classes/Core.php,842, classes/Core.php,875
rename file error classes/Core.php,947
write error classes/Core.php,1139
error saving uploaded file classes/Core.php,1247
invalid internal state plugins/Versions.php,206
error saving version data plugins/Versions.php,271
param unknown scope classes/Core.php,173
no name specified classes/Core.php,902
invalid form response classes/Core.php,1231
zero file upload classes/Core.php,1234
upload form error classes/Core.php,1236
missing file upload classes/Core.php,1238
read_access User does not have read-access. nacowiki.php,568, nacowiki.php,580
write_access User does not have write-access. nacowiki.php,549
Delete access error classes/Core.php,818
rename access error classes/Core.php,909
write access error classes/Core.php,978, classes/Core.php,1052
no write access classes/Core.php,1207

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