Metadata Storage

experimental

If the content stored in a wiki page is data, things like the time of last update, who updated it, the filesize etc. could all be regarded as metadata for the wiki page. This page describes where and how such additional data is stored in DokuWiki.

DokuWiki does not store all metadata at central place (like a database or registry). For a discussion on why this is good or bad see the discussion page. Instead there are several places where metadata can be found: the changelog, the datafile's properties (eg. filesize, last modified date) and the meta directory.

Info in the meta directory is initially written by the metadata renderer. It creates a parallel file for each page named $id.meta in the meta directory. The file is a serialized multi-dimensional PHP array whose keys follow the Dublin Core element names. The renderer gets invoked when a page is saved or through the indexer when the page was added through ways other than DokuWiki (eg. a script).

There are two functions in inc/parserutils.php to deal with metadata:

• p_get_metadata($id) returns the multi-dimensional array of a page.
  • $id is the ID of a wiki page; required
• p_set_metadata($id, $data, $render, $persistent) sets some properties in the metadata.
  • $id is the ID of a wiki page; required
  • $data is an array with key ⇒ value pairs to be set in the metadata, required
  • $render is a boolean whether or not the page metadata should be generated with the renderer; optional, default is false
  • $persistent a boolean which indicates whether or not the particular metadata value will persist through the next metadata rendering. The default value is true.

Currently, the following metadata is saved by the core metadata renderer:

• 'title' – string, first heading
• 'creator' – string, full name of the user who created the page
• 'description' – array
  • 'abstract' – raw text abstract (250 to 500 chars) of the page
  • 'tableofcontents' – array, list of header id ('hid'), title ('title'), list item type ('type') and header level ('level')
• 'contributor' array, list of user ID ⇒ full name of users, who have contributed to the page
• 'date' – array
  • 'created' – timestamp, creation date
  • 'modified'– timestamp, date of last non-minor modification
• 'relation' – array
  • 'isreferencedby' – array, list of pages that link to this page: ID ⇒ boolean exists
  • 'references' – array, list of linked pages: ID ⇒ boolean exists

Additionally, plugins can support more metadata elements. Currently used:

• 'relation' – array
  • 'ispartof' – array, list of pages that include the current page: ID ⇒ boolean exists (include plugin)
  • 'haspart' – array, list of included pages: ID ⇒ boolean exists (include plugin)
• 'subject' – array, lists of tags (tag plugin)
• 'type' – string, 'draft' for drafts (blog plugin)

It's recommended to use keys from the Dublin Core element set for any metadata that might be interesting for external use.

Internally DokuWiki maintains two arrays of metadata, current & persistent. The persistent array holds duplicates of those key/values which should not be cleared during the rendering process. All requests for metadata values using p_get_metadata() are met using the current array.

Examples of persistent metadata keys are:

• 'creator'
• 'contributor'

In addition to the get and set metadata functions mentioned above, there are two other mechanisms plugins can use to interact with metadata.

Syntax plugins can create metadata for the current page with their render() method by handling the $format==“metadata”. Metadata key/value pairs are added to the renderer->meta array and persistent values are also added to the renderer->persistent array.

Action plugins can register for the PARSER_METADATA_RENDER method to inspect or modify metadata before or after metadata rendering.