XmlWiki

From Organic Design wiki
Revision as of 03:17, 21 August 2008 by Nad (talk | contribs) (remove fromhelp)
Legacy.svg Legacy: This article describes a concept that has been superseded in the course of ongoing development on the Organic Design wiki. Please do not develop this any further or base work on this concept, this is only useful for a historic record of work done. You may find a link to the currently used concept or function in this article, if not you can contact the author to find out what has taken the place of this legacy item.
  1. REDIRECT XmlWiki Summary

Technical Details

Articles in xmlWiki work just like the normal MediaWiki articles except that they can have an associated "properties" article named xml:Article, the contents of which is xml. This properties article defines rendering transforms, permissions, publishing etc for its "parent" article. XML articles are represented as a DOM object at runtime, and the content will be validated against any referenced DTD or xml-schema. If any XSLT's are referenced, xmlWiki will attempt to apply them to the article. If the XSLT-output-method is "html" then it will be reduced to a string.

The names of posted form data, or query-string data can contain XPath queries to direct the information into the artiles' properties-DOM before rendering (but after permissions!)

How does it tie in with MediaWiki?

The main script xmlwiki.php, and its many supporting transforms are all articles in the wiki itself, so development and collaboration on XmlWiki is made very simple. There is also a number of files in the /wiki/xmlwiki directory containing some images and libraries required by XmlWiki and some of its components. Since XmlWiki requires some hooks which are not available in the standard imstallation, an admin script is also supplied in the xmlwiki directory to apply or remove the hooks. Most of the hooks are into the MediaWiki index.php file and one of them into parser.php. Note that if XmlWiki is disabled then the security layer it provides is also disabled, so the xmlwiki directory should be accessible only by admin.

Two pseudo-namespaces have been added "xml" and "sys". These are both XML articles, and their contents affects the article they're associated with. Any sys:article is readable and writable only by users in the "admin" group. Pseudo namespaces have been used rather than using the official namespace paradigm because they have to apply to articles regardless of their namespace.

  • The sys:user-article holds security information: <groups>a,b,c</groups>
  • The xml:article (properties) contains information pertaining to the content like transforms, publishing settings, data-sources and queries, and permissions.
  • sys:user articles are of docType xmlwiki:system, and xml:articles are xmlwiki:properties.

The XmlWiki Environment

XmlWiki uses these features to create a more flexible wiki environment offering content, template and transform management... The following tranform articles form the XmlWIki environment:

XmlWiki Hooks

XmlWiki consists of five hooks which attach into the MediaWiki environment through /wiki/index.php and /wiki/includes/parser.php, so those two files need to be writable by the admin script (/wiki/xmlwiki/index.php). The hooks now work in accord with the official MediaWiki Hooks paradigm, except for the SKIN-HOOK which uses an extra dummy skin called xwSkin in the /wiki/skins directory. Following is a brief description of each hook and a list of the processes executed in each.

INIT:

This hooks into index.php after the environment has been established by DefaultSettings.php and LocalSettings.php, but before any article or input processing occurs. This hook is actually the initial retreival and execution of the xmlwiki.php article.

  • Modify MediaWiki environment defined by DefaultSettings.php and LocalSettings.php
  • Define XmlWiki system-globals
  • Define XmlWiki user-globals
  • Define XmlWiki article-globals
  • Retreive sys:user and user-prefs
  • Retreive article-properties and default-properties and merge
  • Security (Process permissions for this article and deny access if not readable)

INPUT:

This hooks into index.php before input processing so it can direct any XPath inputs into the article-DOM and transform them into a standard input for xmlWiki. This also handles write-permissions. This could probably be changed to the official ArticleSaveComplete Hook.

  • Security (If not writable, change action to "view")
  • Apply any POSTed XPath-queries to article-properties
  • If saving and content is XML, apply XML-validation and change action to "edit" if invalid

OUTPUT:

This replaces the output rendering in index.php. It handles read permissions and transforms the xwskin-generated DOM-output with default-skin.xslt.

  • Activate the xwSkin and request wiki-output
  • If article has just been saved, apply onChange transforms
  • If editing a new sys:user or xml:article, fill text-input with default content
  • Insert any pending messages into output
  • Return final result to browser

PARSER:

This hooks into the parse-function in includes/Parser.php. If the article is XML, it is validated and domificated. If it includes XSLT references, or has a transform-list in its xml:article then those transforms are also applied here. The article will be back in string form again after this.

  • Check if content being parsed is the article, and is readable
  • Apply data-transforms (article is a string after these are done)
  • Returns boolean determining if normal parsing should still occur or not.

SKIN:

This is a new compulsory skin (skins/xwskin.php) which renders the page output as a DOM-object so xmlWiki can apply design transforms to it rather than PHP-based templates. If raw content is requested, then only the articles own transforms are applied, because skins and page-layout are part of the xmlWiki environment, not the article.

  • Apply view-transforms

Required Articles:

Before installing xmlWiki, the following articles should be present on the target MediaWiki. Later the admin script will install these if not present.

Other Required Scripts:

A number of other support files ae required which should all be in /wiki/xmlwiki/

  1. Article Properties

<read>User|group,User|group,User|group...</read>

<write>User|group,User|group,User|group...</write>

Read and write elements contain a comma-separated list defining access permissions for the article. Note that users have upper-case and groups are lower-case. Assigning group membership for users is set by admin in the users' sys:User page.

Transform Stacks:

(data, view, edit, save) There can be any number of each of these four kinds of element. Each one contains a single transform (*.php, *.xslt or *.css). Each time one is applied, its element is removed from the properties object until there are none left. It's done this way so that transforms can push more transforms onto the stack while they execute.

  • If a transform is PHP it is executed, but for security reasons it will only execute if it is writable only by dev or admin.
  • If the transform is XML and is a valid xmlwiki:properties document, then it will be merged with the current properties object.
  • If the transform is a CSS it is output as a stylesheet link in the document head with any other stylesheets such as default-skin.css.
  • If it is an XSLT, then it will be applied immediately if the article is XML, or otherwise will be included as a reference in the output like a CSS.

Following is some more details on each of the four transform stacks.

<data>

The transforms are applied in the order they appear in the properties object. The data transforms are applied before any wiki-parsing occurs, so they can generate wiki-markup if they need to. The data transforms are intended to apply to queries, filters and data sources of the article content.

Commonly used data-transforms will be for database-querying which makes the article content into the result of the query. This resultant list then gets parsed and converted to html, then is processed by any view transforms.

<view>

This is a transform stack which works in exactly the same way as the data transforms, except that they're all applied after the wiki parser has applied its markup rules and converted the article to html. These are intended to be dedicated to content presentation such as layout, language and style.

<edit>

The transforms in the stack formed by the edit elements of an articles properties object are very similar to the view transforms in that they are applied after the wiki parser and apply to layout, language and style. The difference is simply that the edit transforms apply instead of the view transforms if the page is being edited. These transforms are intended to allow specific kinds of articles to customise their input forms.

<save>

The last of the transform stacks; these are applied after the article has just been saved. One of these transforms which will be commonly used is the publish.php transform.

<publish>

<publish username="..." password="...">destination URL</publish>

A transform can use its name as the root-element(s) of its data in the properties object. There can be any number of publish elements each specifying a remote destination for the article to be published to whenever it changes.

The publish elements are only checked if the publish(.php) transform is included in the save list.

XPath queries

The names of posted form data, or query-string data can contain XPath queries to direct the information into the articles' properties-DOM.

The syntax of these names is:

xpath:''query'':[[@]''new-node''][+]=''value''

where new-node is the name of a new element (or attribute if @name used) to create in the query result nodes. If no node name is specified the value overwrites (or appends if "+" included) the current result-node contents.

XPath queries allow the rendered articles to include forms which can direct information and requests back into the articles' properties to direct further processing.