EditOverview
To get up to speed on creating plugins for
ScrewTurn Wiki (STW), I created a
Hello World example in C# to get started. I posted it here along with step by step instructions for anyone else that maybe interested in writing a STW plugin.
EditDownload
I have zipped up the source code and the built binary for you to download if you wish. If you would just like to create everything yourself from scratch (which is the point of this example right??), the tutorial section below will walk you through creating all this yourself too.
EditInstructions
Installation
To install this (or any) plugin in your working STW, follow
these instructions.
Usage
To use this plugin, simply enter in the below wiki markup into any of your wiki pages...
{HelloWorld} When the page is rendered to the user, everywhere you had the above text in the page, you will see the text "
Why hello there!" in its place.
EditTutorial
The below will guide you step by step to making your own STW plugin. This example is
very basic, but should be enough to get you going with a working plugin that you can then play around with and expand.
Note: Visual Studio 2008 was used, steps should be basically the same for 2005 as well, but I have not tried myself.
- In Visual Studio (VS), create a new .NET 2.0 Class Library project
- From the Bin folder of your wiki install (or from the download section above), copy the ScrewTurn.Wiki.PluginFramework.dll file to the path of this project (in same folder where Class1.cs is).
- In VS, click on Project > Add Reference.... Then click the Browse tab and navigate to where you copied the ScrewTurn.Wiki.PluginFramework.dll file to, select it and hit OK.
- In VS, edit the Class1.cs file and delete all content from it and paste in all the below...
(note: if copying/pasting introduces problems, the code can be found in the HelloWorldPlugin.cs file in the zip file from the Download section above)
//**********************************************************
// NAME: HelloWorldPlugin
// DATE: 6/1/2009
// AUTHOR: Hoss
// FROM: http://www.hossweb.com
//
// DESCRIPTION: A very simple "Hello World" example plugin
// for the ScrewTurn Wiki engine. This is meant
// as a VERY basic primer for creating your own
// plugin.
//
// MORE INFO: This Plugin... http://www.hossweb.com
// ScrewTurn Wiki... http://www.screwturn.eu
//
// LICENSE: None. Do with it as you please. Pimp it on
// the streets, eat it, smoke it, take credit,
// laugh at it, etc, etc!!! :)
//*********************************************************
using System;
using ScrewTurn.Wiki.PluginFramework;
public class HelloWorldPlugin : IFormatterProvider
{
// Globals to this class.
private IHost _host;
protected string ConfigString = string.Empty;
/// <summary>
/// Implement the Information property from IFormatterProvider.
/// </summary>
/// <remarks>
/// Returns name of plugin, name of author, and url of author/plugin.
/// These get displayed in the Admin>Provider page.
/// </remarks>
public ComponentInformation Information { get { return new ComponentInformation(this.GetType().ToString(), "Hoss", "http://www.hossweb.com"); } }
/// <summary>
/// Implement the PerformPhaseX properties of IFormatterProvider.
/// </summary>
/// <remarks>
/// When a page is requested, the content is formatted in 3 phases. The engine
/// checks these properties to know which phases of formatting it should
/// use this plugin for. In this example, we only want to process Phase 3.
/// </remarks>
/// <seealso cref="http://www.screwturn.eu/PluginFramework.ashx#BC_-_Custom_Formatter_Providers_7"/>
public bool PerformPhase1 { get { return false; } }
public bool PerformPhase2 { get { return false; } }
public bool PerformPhase3 { get { return true; } }
/// <summary>
/// Implement the Init method of IFormatterProvider.
/// </summary>
/// <remarks>This method is called when this provider is loaded.</remarks>
/// <param name="host">Reference to the host of this plugin.</param>
/// <param name="config">The config string provided by admin in the admin>provider page.</param>
public void Init(IHost host, string config)
{
// All this simple example is going to do during Init is to assign host and
// config to Globals in this class so that all methods in this class can
// make use of them (like how the Format method below uses _host to make a
// log entry to the wiki's log in the event of an error).
_host = host;
ConfigString = config;
}
/// <summary>
/// Implement the Format method of the IFormatterProvider.
/// </summary>
/// <remarks>This method is called when the engine is formatting a page.</remarks>
/// <param name="raw">The content of the page being requested.</param>
/// <param name="context">Information about the page being requested.</param>
/// <param name="phase">Which phase of formatting this call is for.</param>
/// <returns>The page content after being altered by this method.</returns>
public string Format(string raw, ContextInformation context, FormattingPhase phase)
{
// Wrap this in a try/catch so that if there are any errors, you can catch them
// (rather than crash) and return the page's content unedited. In this example,
// We also add a log entry to the wiki's log so you can see when an error is hit.
try
{
// This is where the magic happens. The raw parameter is a string that
// contains the content of the currently requested page. All we are doing
// here is finding all occurances of the string "{HelloWorld}" and
// replacing them with the string "Why hello there!" and returning our
// altered version.
return raw.Replace("{HelloWorld}", "Why hello there!");
}
catch (Exception ex)
{
// If any of the code in the try block above fails and hits an exception,
// it will be caught here instead of displaying an error message to the
// user. In this example, we simply add a log entry to the wiki's log (it's
// in the admin area) so the admin knows about it, and then just return
// the pages content unaltered, as if this provider plugin never touched it.
_host.LogEntry("Plugin Provider \"" + this.GetType().ToString() + "\" hit the following exception: " + ex.Message, LogEntryType.Error, this);
return raw;
}
}
/// <summary>
/// Implement the Shutdown method of IFormatterProvider.
/// </summary>
/// <remarks>
/// In this simple example, we have nothing to clean up, disconnect,
/// etc, so do nothing.
/// </remarks>
public void Shutdown()
{ }
}
5. Now, in VS, simply hit
F6 to build the project. Assuming there were no build errors, you should now have a
HelloWorldPlugin.dll file located in the bin folder of your project. You can now login to your wiki and install this plugin dll file via the admin console. See the
Usage section above for more info on installing plugins and how to use this plugin.