NacoWiki PHP API

Core
in package

NWiki

Main NacoWiki functionality

This class contains the main functionality included by NacoWiki

Constants

CODEMIRROR = 'https://cdn.jsdelivr.net/npm/codemirror@5.65.4/': URL to the supported CODEMIRROR version
HIGHLIGHT_JS = 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/': URL to the supported HIGHLIGHT_JS version
PROP_FILE_PREFIX = '/.prop;': alternative property files prefix (for background compatibility)
PROPS_FILE_PREFIX = '/.props;': property files prefix

Methods

apiPageList() : bool|null: Returns a page list
attachToPage() : bool|null: attach to page event handler
codeMirror() : void: Show a CodeMirror editor web view
defaultProps() : array<string|int, mixed>: Default props
deletePage() : bool|null: delete page event handler
editPage() : bool|null: edit page event handler
folderContents() : array<string|int, mixed>: Get the contents of a folder
load() : void: Loading entry point for this class
logProps() : void: Add log entires to props
makePath() : void: Make sure a directory (and parent directories in between) exist
missingPage() : bool|null: Missing page event handler
preparePayload() : array<string|int, mixed>: Utility function to initialize a prepare payload event array
propEntryStr() : string: Calculate a string from an Prop change-log entry
prunePath() : string: When a file/directory is deleted, make sure no empty dirs remain
rawPage() : bool|null: Raw page display
readFolder() : bool|null: Show the contents of a folder
readPage() : bool|null: Read page event handler
readProps() : array<string|int, mixed>: Read properties from props file.
renamePage() : bool|null: rename page event handler
savePage() : bool|null: save page event handler
saveProps() : bool: Save properties to props file.
search() : array<string|int, mixed>: Implements search functionality
searchPage() : bool|null: Search results event handler
theme() : void: Link theme assets
updateProps() : mixed: Update props

CODEMIRROR

URL to the supported CODEMIRROR version


    public
        string
    CODEMIRROR
    = 'https://cdn.jsdelivr.net/npm/codemirror@5.65.4/'

HIGHLIGHT_JS

URL to the supported HIGHLIGHT_JS version


    public
        string
    HIGHLIGHT_JS
    = 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/'

PROP_FILE_PREFIX

alternative property files prefix (for background compatibility)


    public
        string
    PROP_FILE_PREFIX
    = '/.prop;'

PROPS_FILE_PREFIX

property files prefix


    public
        string
    PROPS_FILE_PREFIX
    = '/.props;'

apiPageList()

Returns a page list


    public
            static        apiPageList(NacoWikiApp $wiki, array<string|int, mixed> &$ev) : bool|null

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

The event parameter is filled with a property output containing

array with directories
array with files
current page
base URL from $cfg[base_url]

Parameters

$wiki : NacoWikiApp: NacoWiki instance
$ev : array<string|int, mixed>: Event data.

Return values

bool|null —

Returns \NWiki\PluginCollection::OK to indicate that it was handled.

attachToPage()

attach to page event handler


    public
            static        attachToPage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:attach event.

Handles POST requests to upload files to pages or folders. The uploaded file is expected to be in the fileToUpload POST element.

If uploading to a folder, it will simply upload the file to the directory for that folder.

If uploading to a page with $cfg[default_doc] name, it will treat it as uploading to the directory for that default doc page.

If uploading to a normal page, it will create a folder with the same name as the page without file extension and upload the file there.

As it is, attachments are essentially ordinary files that convention that files in a folder the same name as the page (without extension) are its attachments.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

codeMirror()

Show a CodeMirror editor web view


    public
            static        codeMirror(NacoWikiApp $wiki[, array<string|int, mixed> $cm_opts = [] ]) : void

Will create a web page in the style of the wiki containing a CodeMirror editor for use.

The $cm_opts is an array which should contain:

array 'js' : list of CodeMirror modules to load.
array 'css' : list of CodeMirror CSS to load. Usually for themeing
string 'mode' : CodeMirror editor mode
string 'view' : file path to a view template file

Parameters

$wiki : NacoWikiApp: Current wiki instance
$cm_opts : array<string|int, mixed> = []: configurable options

defaultProps()

Default props


    public
            static        defaultProps(NacoWikiApp $wiki) : array<string|int, mixed>

Return default properties due to a file being created.

Parameters

$wiki : NacoWikiApp: running wiki instance

Return values

array<string|int, mixed> —

Array containing new file properties.

deletePage()

delete page event handler


    public
            static        deletePage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:delete event.

Deletes the given page. If the current page is a folder and it contains files (not just more folders), it will show the folder contents and ask the user for confirmation.

If after the page is deleted, there are no more files in the folder containing the page, it will also delete the containing folder (or folders).

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

editPage()

edit page event handler


    public
            static        editPage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:edit event.

The default shows a page with a text area to edit the page.

Media handlers can use this event to display a customize the page used to edit the media.

Usually media handlers would use this to separate content from header data, and also customize a CodeMirror instance to the correct modes for the given media.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

folderContents()

Get the contents of a folder


    public
            static        folderContents(NacoWikiApp $wiki, string $folder) : array<string|int, mixed>

This function reads te contents of a folders and returns to caller as a array with the full URL path as the key and the base name as the data element

Parameters

$wiki : NacoWikiApp
$folder : string: folder to read

Return values

array<string|int, mixed>

load()

Loading entry point for this class


    public
            static        load() : void

Hooks events implemented by this class

logProps()

Add log entires to props


    public
            static        logProps(NacoWikiApp $wiki, array<string|int, mixed> &$props, array<string|int, mixed> &$meta[, string $extra = NULL ]) : void

Check if a $meta array contains add-log entries and adds them.

The add-log entry from the $meta array is removed.

This function should be called from a preSave event handler by a plugin as plugins are responsible from parsing and updating meta data.

It may also used by other plugins to modify the saved meta data and/or props arrays. (One use is to implement auto-tagging).

For this to work the media handler plugin must support this. i.e. The plugin must rewrite the $event['text'] with the updated meta data.

Parameters

$wiki : NacoWikiApp

running wiki instance

$props : array<string|int, mixed>

properties array that will receive log entries

$meta : array<string|int, mixed>

meta array with log entires

$extra : string = NULL

(Optional) additonal text to be send (usually the article body text).

makePath()

Make sure a directory (and parent directories in between) exist


    public
            static        makePath(NacoWikiApp $wiki, string $dir) : void

Parameters

$wiki : NacoWikiApp: Current wiki instance
$dir : string

missingPage()

Missing page event handler


    public
            static        missingPage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the missing_page event.

The default shows a page that has a link to create the page or to upload a new file.

Media handlers can use this event to display a custom page used to create new media.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

preparePayload()

Utility function to initialize a prepare payload event array


    public
            static        preparePayload(NacoWikiApp $wiki, string $url[, string $ext = NULL ]) : array<string|int, mixed>

If available a read:filextension event is used to parse the page contents to read meta data, and split any header information from the content body.

Parameters

$wiki : NacoWikiApp: running wiki instance
$url : string: URL of the page being prepared
$ext : string = NULL: media handler file extension

Return values

array<string|int, mixed> —

Prepared event array

propEntryStr()

Calculate a string from an Prop change-log entry


    public
            static        propEntryStr(array<string|int, mixed> $entry) : string

Used to reduce the number of change log entries. It uses the remote user if available and remote IP address. Also, the time stamp is reduced to date only (time is removed). The reason is that changes by the same user on the same date should only result in a single change-log entry.

Parameters

$entry : array<string|int, mixed>: Entry to convert to a comparable string.

Return values

string

prunePath()

When a file/directory is deleted, make sure no empty dirs remain


    public
            static        prunePath(NacoWikiApp $wiki, string $dpath) : string

When a file or directory is deleted, it checks if afterwards the directory is empty. If it is, it will also delete that directory until we find a directory that is populated.

Parameters

$wiki : NacoWikiApp: Current wiki instance
$dpath : string: file path relative to $wiki->cfg[file_store] to prune

Return values

string

rawPage()

Raw page display


    public
            static        rawPage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:raw event.

Will serve pages without rendering i.e. raw source code.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

readFolder()

Show the contents of a folder


    public
            static        readFolder(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the read_folder event.

If the URL does not end with /, it will redirect to the default_doc (usually index.md ) if it exists, or it will redirect to an URL ending with /. HTTP request. It is used to trigger a specific action in response to a HTTP post request.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

readPage()

Read page event handler


    public
            static        readPage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the read_page event.

Handles read page requests from the web browser.

If the page is media that can be handled by a plugin, it will trigger the necessary events to use the plugin hooks.

The general sequence is as follows

Check if this file extension is handled by a plugin.
- If view event is available, it will let a plugin to handle the whole process.
- fires pre-render events to pre-process the page. It will first try the pre-render:ext for file extension specific pre-renders. Following, the generic pre-render event will be triggered.
- fires render:ext event to convert the page data into html.
- fires post-render render events to post-process the page. It will first try post-render:ext, followed by post-render.
- fires the layout:ext to output the page on a custom layout, otherwise the default layout is used.
If no media handler has been registered for this page's file extension, the file will be send verbatim (without any processing). So binary files such as videos, images, audio, etc, can be loaded into the Wiki and served directly.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

readProps()

Read properties from props file.


    public
            static        readProps(NacoWikiApp $wiki, string $file) : array<string|int, mixed>

Read properties from a YAML file. If not found, it should pre-initalize things accordingly.

Parameters

$wiki : NacoWikiApp: running wiki instance
$file : string: name of file to use

Return values

array<string|int, mixed> —

Array containing properties

renamePage()

rename page event handler


    public
            static        renamePage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:rename event.

Renames the given page to the http query string name field.

If after the page is renamed, there are no more files in the folder that was containing the page, it will also delete the containing folder (or folders).

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

savePage()

save page event handler


    public
            static        savePage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:save event.

Normally it will get the payload from a field name text from the POST data.

UNIX EOL conversion is handled here.

The following events are triggered:

preSave
preSave:ext
- preSave events happen before data is written. Can be used to sanitize user input, by for example, pre-parsing headers.
- There are two events, generic and file extension specific.
  If a media handler is available, both events will be triggered. Otherwise, only the generic one will be triggered.
save:ext
- This actually saves the page. If no plugin hooked this event, it will simply save payload using file_put_contents and save properties.
postSave
postSave:ext
- postSave events happen after data is written. Can be used to for example update tag cloud information.
- There are two events, generic and file extension specific.
  If a media handler is available, both events will be triggered. Otherwise, only the generic one will be triggered.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

saveProps()

Save properties to props file.


    public
            static        saveProps(NacoWikiApp $wiki, array<string|int, mixed> $props[, string $fpath = NULL ]) : bool

Save properties ta props file in YAML format.

Parameters

$wiki : NacoWikiApp: running wiki instance
$props : array<string|int, mixed>: Array containing properties
$fpath : string = NULL: File to save, otherwise uses $wiki->filePath()

Return values

bool —

true on succes, false on error.

search()

Implements search functionality


    public
            static        search(NacoWikiApp $wiki, string $folder, string $scope, string $q, array<string|int, mixed>|null &$matches) : array<string|int, mixed>

It will look for grep style regular expression in $q and returns matches in $folder. If the $scope is given, it can be:

local : searches in the current folder,
recursive : searches in the current folder and sub-folders
global : searches the whole wiki.

The $q search term can be either some text that will be converted into '/'.$q.'/i', with any slashes escaped, or a valid regulare expression (with the start and end delimiters).

This means that by default it is a case-insensitve search. To override these defaults you must specify a full RE including the start and end delimiters and any optional modifiers.

Returns a list of files in a fomrat similar to folderContents.

The optional matches array receives the matching lines. With the key matching the key in the returned files, and the element being an array with line context (index 0) amd matching text (index 1).

Parameters

$wiki : NacoWikiApp: current wiki instance
$folder : string: folder to start the search
$scope : string: search context: "local", "recursive", "global"
$q : string: search term
$matches : array<string|int, mixed>|null: optional array that will receive the search matches

Return values

array<string|int, mixed> —

list of matching files.

searchPage()

Search results event handler


    public
            static        searchPage(NanoWikiApp $wiki, array<string|int, mixed> &$data) : bool|null

This is the Core event handler that handles the do:search event.

Handles search requests from the web browser.

Parameters

$wiki : NanoWikiApp: current wiki instance
$data : array<string|int, mixed>: ignored

Return values

bool|null

theme()

Link theme assets


    public
            static        theme(NacoWikiApp $wiki) : void

Outputs the HTML tags to link the theme assets to the currently displayed page

Parameters

$wiki : NacoWikiApp: running wiki instance

updateProps()

Update props


    public
            static        updateProps(NacoWikiApp $wiki, array<string|int, mixed> &$props) : mixed

Update props by creating a new entry in the change log

Parameters

$wiki : NacoWikiApp: running wiki instance
$props : array<string|int, mixed>: Array containing properties

Core in package NWiki

Table of Contents

Constants

Methods

Constants

CODEMIRROR

HIGHLIGHT_JS

PROP_FILE_PREFIX

PROPS_FILE_PREFIX

Methods

apiPageList()

Parameters

Tags

Return values

attachToPage()

Parameters

Tags

Return values

codeMirror()

Parameters

defaultProps()

Parameters

Return values

deletePage()

Parameters

Tags

Return values

editPage()

Parameters

Tags

Return values

folderContents()

Parameters

Return values

load()

logProps()

Parameters

makePath()

Parameters

missingPage()

Parameters

Tags

Return values

preparePayload()

Parameters

Return values

propEntryStr()

Parameters

Return values

prunePath()

Parameters

Return values

rawPage()

Parameters

Tags

Return values

readFolder()

Parameters

Tags

Return values

readPage()

Parameters

Tags

Return values

readProps()

Parameters

Return values

renamePage()

Parameters

Tags

Return values

savePage()

Parameters

Tags

Return values

saveProps()

Parameters

Return values

search()

Parameters

Core
in package

NWiki