Usage

This plugin is designed to be used in a web page to enable Wiki text to be rendered as HTML. To use the plugin you will need to add the following to your web pages:

  • link to the jQuery script
  • link to the Wiki Text plugin script
  • add some JavaScript to use the Wiki Text plugin

Link to the jQuery Script

The Wiki Text Plugin is a jQuery plugin - so you need to include the jQuery script in your web pages first of all. You have some choices to make.

First, the script is available in two formats - a neatly structured "uncompressed" version or a smaller (cryptic) "compressed" version. While writing and maintaining JavaScript you need it to be well laid out and commented - but if it's being downloaded across the internet its better if the file is much smaller. So a compression utility can be used to strip the comments, unnecessary white space and long variable names.

Second, you can download a copy of the jQuery library and deploy it with your site or you can link to the script on a CDN (Content Delivery Network) host.

I find it's easier to download an uncompressed version for development and then change to a compressed CDN hosted link when the site goes live.

So, you can include jQuery in your page using one of the following <script/> tags in the page <head>...</head> section.

<!-- If you have downloaded the uncompressed script to your site's ./script folder: -->
<script type="text/javascript" src="script/jquery.js"></script>

<!-- If you have downloaded the compressed script to your site's ./script folder: -->
<script type="text/javascript" src="script/jquery.min.js"></script>

<!-- Or to link to the compressed script on the Google CDN site:-->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>

For more details of how to add jQuery to your web pages go to Downloading jQuery .

The plugin has been tested with versions 1.4.x and 1.5.x - but since it makes minimal use of jQuery functionality it should work with most versions.

Link to the Wiki Text Plugin Script

Once you have added jQuery to the page you need to add the Wiki Text Plugin.

To do this, download the plugin and put it on the site (e.g. in the ./script directory of the site.

Then add another <script/> tag in the page <head>...</head> section:


<!-- Add the Kajabity Wiki Text Plugin for jQuery. -->
<script type="text/javascript" src="script/jquery-wikitext-0.3.js"></script>
					

Use the Wiki Text Plugin

Once you have linked to the plugin in the page it's time to make use of it.

The following HTML code is a simplified version of the Plugin Test Page . The page includes a <textarea> where you can enter code and a <div/> where the resulting HTML is added.


<html>
<head>
    <title>Kajabity.com - Wiki Text Plugin for jQuery Sample</title>
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
    <script type="text/javascript" src="script/jquery-wikitext-0.3.js"></script>

    <script type="text/javascript">
    $( function()
    {
        // Update the HTML everytime the textarea content is changed.
        $('#plaintext').keyup( function()
        {
            $('#wikioutput').wikiText( $(this).val() );
        } );

        // Force the HTML to update on page load.
       $('#wikioutput').wikiText( $('#plaintext').val() );
    });
    </script>
</head>

<body>
    <h1>Wiki Text Plugin Test</h1>

    <form id="testform">
        <textarea id="plaintext" cols="80" rows="15">Edit the text in here</textarea>
    </form>

    <div id="wikioutput"></div>
</body>
</html> 

Examples

To see how the plugin can be used have a look at how it is used in the following pages:

  • Wiki Text Test Page - of course it's here so you can try it for yourself.
  • Thistle Society Events - this is the page I originally wrote it for so I could improve the formatting of the event descriptions.
  • The included test page in the zip file - which also shows you the HTML version. I use it as a quick and easy way to convert any text to HTML - including this!

Have a look at their sources to see how it's done.

If you do use this plugin let me know and I can add a link to it here.

Learn More About JavaScript and jQuery

I have used JavaScript a few years ago when DHTML was the exciting new technology. I thought I knew it reasonably well. I didn't.

If you are developing web pages using this plugin and other jQuery plugins then you will find the following books invaluable: -

  • JavaScript: The Definitive Guide - I borrowed this one and now I've ordered the newer edition for myself. As well as being a good reference I found it easy to read.
  • jQuery in Action, Second Edition - as you would hope, this is a great introduction to jQuery starting of gently and then digging into more detail later. It's not quite a reference, but then that's what the web site's for, isn't it?

You may also find the following web sites useful.