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
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 [ 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 ExamplesWriting 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¶