XsltMarkup Plugin

Table of Contents [Hide/Show]

Overview¶

The XsltMarkupPlugin allows new wiki markup to be created without coding a plugin. New markup is added to the wiki by uploading a special XML Transforms (or XSLT) file. The markup is both defined and processed by the XSLT markup file. So as long as you know how to write XSLT transforms new wiki markup can be created without writing format provider plugins.

XSLT markup is securable! There are three levels of access granted to allow you to share XSLT markup transforms with confidence:

Restricted - restricts access to readonly information that an standard wiki user can see.
Partly Trusted - gives limited readonly access to most information.
Fully Trusted - gives full access to all information. The XSLT document function and embedded scripting is also enabled!

In addition to the ability to secure the XSLT Markup processors, each Markup defined can also be assigned group level permissions for your users to access them. If a user doesn't have permission to use a markup. It is invisible.

Your XSLT markup file has complete access to a number of extended functions:

http-context - gives complete access to the current HTTP context, access to ALL server variables, application, and session variables, as well as all parameters passed to the page.
wiki-context - gives complete access to the ScrewTurn Wiki APIs so literally anything on the wiki can be read or written by the XSLT transform language.
data-access - gives complete access to any installed .NET Data Provider, access to just about any SQL database, ODBC database, or XML data source. Show your data!

The XsltMarkupPlugin is very optomized. It uses compiled regular expressions to scan for markup. Once found, cached and precompiled XLST transforms are used to process each markup.

So go to W3 Schools XSLT Tutorial and sharpen your XML transform writting skills, cause with the XlstMarkupPlugin you can create just about any kind of markup you desire.

Currently the only real draw back that this plugin suffers from is that it was built using the .NET compiled XSLT engine, which means that only XSLT version 1.0 and XPath version 1.0 are supported. Sorry about that, but the reason for going with this limitation is that the .NET XSLT engine compiles XLST into .NET CLR code so it is extremly fast.

Markup syntax supported by the XsltMarkupPlugin¶

The XsltMarkupPlugin supports two type of markup syntax. A wiki syntax format

The wiki syntax form of markup ¶

_{Note that in the syntax below only characters a words in quotes are required "as-is" in the command. The quotes themselves are for illistration purpose only and are not used as part of the actual markup.}


"{" markup-namespace":" [ {parameter-name "=" parameter-value} | {unnamed-parameter}  [ "|" {parameter-name "=" parameter-value} | {unnamed-parameter} ]...  ] "}"

Where:

markup-namespace - is a the unqiue name of the markup
param="value" - are any optional xml style parameter/value specification
any-other-embedded-markup - is any other embedded markup, including any additional XML.

For example:


{ silverlight:(mypage)mycontrol.xap|width=100 |height=400}

or

{DisplaySQLTable: PARTS_INVENTORY }

Each markup-namespace must be configured in the configuration string of the plugin. Each markup-namespace is mapped to an XSLT transform file that must be created and uploaded to the wiki. This XSLT transform file used to process each occurence of the markup found on a wiki page. The parameters, both named and unnamed, are passed as parameters to the transform for processing. The transform is given access to a context object that allows the transform to access most of the screwturn wiki functions that are available to plugins.

All parameters are passed to the xslt transform as follows:

Named parameters are passed a standard named parameter in xslt i.e. they can be access inside the transform by declaring
Unnamed parameters are named automatically using the series "unnamed-parameter-0" , "unnamed-parameter-1", "unnamed-parameter-2", ...
Unnamed parameters can also be access inside the transform by declaring the parameter like:

The xml syntax form of markup¶


"<" markup-namespace [ param="value" ]* ">"  any-other-embedded-markup  "</" markup-namespace ">"

Where:

markup-namespace - is a the unqiue name of the markup

For example:


<mymarkup height="42" width="42">  
  <additional-stuff>42</additional-stuff>
  ... more text based or xml based markup here ...
</mymarkup>

Each markup-namespace must be configured in the configuration string of the plugin. Each markup-namespace is mapped to an XSLT transform file that must be created and uploaded to the wiki. This XSLT transform file used to process each occurence of the markup found on a wiki page.

The entire markup is parsed into XML and passed to the XSLT Transform for processing.

This means that more complex data can be passed to the transform for process than the wiki version of the syntax, but it also means that any xml found between the markup tags must be well-formed xml.

Configuring markup with the XsltMarkupPlugin¶

The XsltMarkupPlugin is configured through the Format Provider configuration string. This is where a new markup namespace is define and linked to an XSLT file for processing.

To configure the XsltMarkupPlugin:

Go to Screwturn wiki Administration page.
Select the Providers Tab
Click the Formatter Providers radio button
Select the XslMarkupPlugin
Configure the XsltMarkupPlugin using the configuration syntax outlined below, then save.

Each configuration command is required to be on it's own line.

Registering a markup namespace explicity ¶

Each new markup is registered by adding a line to the configuration string using the following syntax:


"register" [restricted | partly-trusted | fully-trusted ] [ phase1 | phase2 | phase3 | dynamic ] "using" xlst-file-path

Where

[ restricted | partly-trusted | fully-trusted ] is the execution sandbox security assigned to the markup processor (The default is partly-trusted).
- restricted -
- partly-trusted -
- fully-trusted -
[ phase1 | phase2 | phase3 | dynamic ] indicates which phase the markup is to be processed in.
- phase1 - indicates that the markup is processed BEFORE standard wiki markup is processed
- phase2 - indicates that the markup is processed after standard wiki markup is processed
- phase3 or dynamic - indicates that the markup is to be processed each time the page is viewed (Phase 3 of the format pipeline).
is any absolute or relative path to an xslt tranform that will be used to process the markup

NOTE: Explicitly registering a markup namespace cause it to replace the existing markup namespace transform (if one already exists).

Of course before you configure a new markup namespace you will need to create an XSLT transform file and upload it to the wiki. The examples in the next section use XSLT transform files uploaded to the file directory /XsltMarkupPlugin/. The transform file can be placed anywhere at its url is accessable by the plugin.

If you need a primer on how to write XSLT transform I suggest that you start at W3Schools XSLT Turtorial

Deregistering a markup namespace ¶

Removed the markup namespace from memory.


"deregister" markup-namespace

Where

markup-namespace - the name of the markup namespace to be deregistered.

Setting up a dynamic path ¶

Set a dynamic directory path that the plug in monitors for markup processing files. New files are automatically registered, any changes to the file are also handled automagically. Up to three dynamic directory paths can be set,one or each security "sand-box". The directory path must resolve to the local file system in order for directory monitoring to work correct. The directory path does not need to be in wiki/public. You can set the directory to an upload path, this will allow for easy updates of markup processors (good for developing new ones). IMPORTANT NOTE: If you specify a partly-trusted or fully-trusted directory path, you should make sure that directory is approriately secured so malicous code is not uploaded. The restricted directory path is particularly useful for a more public upload directory as access to information is restricted to what most public users can already see.


"set" [restricted | partly-trusted | fully-trusted ] "path" "to" directory-path

Where

[ restricted | partly-trusted | fully-trusted ] is the execution sandbox security assigned to markup processor found in the specifed directory path.
- restricted -
- partly-trusted -
- fully-trusted -
directory-path - is either an application(wiki) relative url-path that resolves to a local phyisical file directory or is an absolute local physical directory path.

Enable a markup namespace ¶

Enable a previously disabled markup namespace to cause it to start processing again.


"enable" markup-namespace

Where

markup-namespace - the name of the markup namespace to be enabled.

Disable a markup namespace ¶

Disabling a markup namespace causes that markup namespace to be ignored


"disable" markup-namespace

Where

markup-namespace - the name of the markup namespace to be disabled.

Turning logging off ¶


"nolog"

Turning debug on ¶


"debug"

Changing The Parse Priority ¶

The XsltMarkupPlugin executes during phase two or phase three of the Screwturn wiki formatting pipeline. Changing the parse priority will cause the WikiMarkupPlugin to execute earilier or later during phase two, which may resolve confict issue with other formatting providers. For more information on how wiki formatting works please see:


"priority" priority-value

Where:

priority-value is an integer value between 1 and 100. The default value is 50.
=== Comments in the configuration string ===

Comments can be added anywhere in the configuration string using two forward slashes "//". All text to the end of the current line will be ignored.


"//" comment-text

Where:

comment-text is any text up to the end-of-line and will be ignored by the configuration parser.

Examples¶

Examples of some markup that can be created using the XsltMarkupPlugin:


{silverlight: filename.xap|height=600}

{DumpContext:}

{ServerName:}

{LogThis: Dump this message into the screwturn log}

{silverlight: /ForceDirected/DaisleyHarrison.ForceDirected.UnitTest.xap| height=600 | width=100% | background=white | myparam = 42 }

To configure the above example:

Go to Administration
Select the Providers Tab
then select the Format Providers radio button
Select the XslMarkupPlugin
Add the following to the configuration string, then save.

register using public/upload/XsltMarkup/silverlightMarkup.xslt
register  dynamic using public/upload/XsltMarkup/DumpContextMarkup.xslt
register  using public/upload/XsltMarkup/ServerNameMarkup.xslt
register  using public/upload/XsltMarkup/LogThisMarkup.xslt

Note that you will also need to create a root file directory in screwturn called "XsltMarkup" and upload all of the example files that come it the distribution zip file for these markups to work correctly.

OR

Create an upload directory path in the root called "XsltMarkup" and upload all examples files.
Go to Administration
Select the Providers Tab
then select the Format Providers radio button
Select the XslMarkupPlugin
Add the following to the configuration string, then save.

set fully-trusted path to public/upload/XsltMarkup

To take a look at some of the xslt examples on line please go to XsltMarkupPlugin Transform Examples

Writing an Xslt Markup Processor¶

Please see Writing an Xlst Markup Processor.

Securing Xslt Markup¶

One of the best ways to configure the XlstMarkupPlugin is using a dynamic path (see above), and setting the dynamic path to one of the wiki upload directories. However, in doing so you are allowing anyone who has upload permissions on that diretory to create markup that can compromise the security of your wiki. The XsltMarkupPlugin as several options for ensuring that this does not happen:

Set the permissions on the upload directory to allow only the Administators group access to it.
If wish to allow the more general Users group access to write markup, then configure either a restricted or partly-trusted directory to upload.
NEVER create a fully-trusted upload directory path that is unsecured.
If you are creating markup that exposed sensitive data or allows users to change sensitive settings, set the permissions for the markup namespace to restrict it to trusted user-groups only.

Licensing ¶

(c) copyright 2009 Aaron G. Daisley-Harrison - All rights reserved.

Currently source code is unavailable until I work out a suitable licensing scheme.
You are free to use and distribute the beta versions of this control.
Use this code at your own risk. I have tested the code, but this is beta level code so there will be bugs. Of course I offer no warranty nor will I assume any liability for any damage or problems resulting the use of this code.

Download the latest version¶

XsltMarkupPlugin.zip (3.0.4 Beta)

Release Notes¶

3.0.4 Beta¶

Modified the set path and register configuration commands to allow upload paths to be specified "GetFile.aspx?File=/directory/.../" as well as relative urls.
Modified the file watching to also use the wiki file activity event so that non-physical upload paths are supported
Renamed the wiki:MarkupArguments() function wiki:MarkupParameters() to be more consistent in the application.

3.0.0 Beta¶

Split the context extension namespace into wiki-context and http-context namespaces.
Added additional examples.
Added three "sand box" security levels (Restricted, Partly Trusted, and Fully Trusted).
Added the ability to secure each markup namespace by user group.
Added a processing-instruction to each XSLT file to fully define the markup ( Now each file is a standalone mark package).
Added the ability for the plugin to monitor up to three directories for markup processors (one directory for each security level).
====2.2.0 Beta====

Changes to the content namespace:

All functions consistently return a top level node for example the context:File() function return a top level <files> node
Pages - now returns page attachments and categories
Revisions - new
BackupContent - new
Directories - new
Files - new
SendMail - new
ChangeCurrentUserLanguage - new
PrepareContentForIndexing - new
PrepareTitleForIndexing - new

Changes to the data-access namespace:

Providers - now returns the top level node <providers>
OpenConnection - new
Query - new
Close - new
CloseAll - new
ExecuteCommand - new
ScalarQuery - new
SetParameter - new
GetParameter - new
ClearParameters - new

Added some data-access example xslt.

2.1.0 Beta¶

There have been major changes to context extension object used by the XSLT transform language to access the ScrewTurm Wiki plugin framework api. Now even more functionality is supported, and most functions return proper node sets to make it easier to write good XLST to create tables etc.

I have also added a data-access extentions object that uses the generic .NET System.DataServices package. This means that any .NET compiliant data provider can be used in the XSLT transform to both read and write to a database of your choice. Full transction control is also supported. (I just need to get around to completing the documentation so stay tuned).

Known Issues and Feature Requests¶

currently none.