Introduction

This Tutorial concerns Liberty Data Plugins and trys to answer the Basic Questions - What / Where / How & Why. It uses simple English most of the time but does get Technical in place (the contents of source code is displayed). It describes what each sections within a Liberty Data Plugin does and how the sections interact. What this Tutorial Does Not Do - is Provide a Step-by-Step Methodology for Creating a Liberty Plugin. The Tutorial - Liberty Plugins II does that and a Lot more.

Should I be Reading This?

This Tutorial is provided primarilly for Site Administrators and Developers (or anyone) wanting to add functionallity to a bitweaver Powered Site. A User on a bitweaver Powered Site would gain a little knowledge from reading the Heading "How is a Plugin Used?".

So what is a Liberty Plugin?

And why do you keep saying Liberty anyway - isn't Plugin enough?

There are all kinds of Plugins. Every Package incorporated into bitweaver (in Application Framework mode) has it's own definition of what a Plugin is / what it does / and where it is used. Even within the LibertyPackage there are even three different types of Plugins. They are:

• Liberty Data Plugins - What this tutorial is all about.
• Liberty Format Plugins - Used to handle different types of data.
• Liberty Storage Plugins - Used to store the data in different ways.

Liberty Data Plugins can be used in any Package that uses the Liberty Storage System - that includes: the Wiki / UserPages / Blogs / and - well - nearly everything else bitweaver.

If it will make things easier though - in the remainder of this Tutorial - all Plugins are Liberty Data Plugins.

How can a Plugin Add Functionallity?

Easy! Here is the situation. You are updating a page - and when your finished you look at it and say "Not Bad - but I wish I had some EyeCandy to make this more noticable". If you were doing things the old fashioned way using pure HTML pages - there are thousands of different things that could be easilly added to give you exactly the effect you want - if you have the skill to add it. Wiki page are not like a pure HTML pages - but anything that works in an HTML can be placed in a Plugin and will work in a Wiki page.
The Plugin "EyeCandy NeonText" (ECNT) Plugin is a very good example. It was written for two reasons:

1. I renamed a finished a Proposed Plugin PluginProposal-HideText and wanted some EyeCandy to make a Notice - It's Done statement.
2. I decided to create the second Tutorial Tutorial - Liberty Plugins II and needed a good example for it.

Note: The Plugin "EyeCandy NeonText" (ECNT) applies a Neon Lighting Effect (an age old technique of attracting attention) to a string. A DHTML Script file from http://www.dynamicdrive.com was used as the source.
Of course - not everything is as simple as this - but sometimes the simple things are the most rewarding.

But I'm not a Computer Guru!

You don't have to be. At the minimum - all that is required is a little knowledge of HTML / the PHP language / and the ability to look things up and the ability to experiment a little. Plugins can be fairly simple or as complex as you want to them to be. They provide an excelent place for a beginner to play and learn.

What does this Plugin do?

The Comment Plugin is the simplest Plugin imaginable. All it does is - well - nothing. By doing "nothing" though - it allow text to be stored in a page that is not displayed or processed in any way.

So how is a Plugin used?

The Comment Plugin (unlike most Plugins) operates on the text encased between a pair of Code Blocks. A Code Block is the name of the Plugin within a pair of curly brackets “{“ and “}” like this: {COMMENT }
{COMMENT } The Text Inside the Block {COMMENT}
In this case - the Comment Plugin prevents the text from being displayed.

To make Plugins more functional, additional information (parameters) can be passed to it. The parameters are added to the first code block in the form of parameter_name=’value’. Each Plugin defines the names of the parameters and what is expected. Most Plugins accept multiple parameters – which are separated by a space character.
Please Note: The 'Value' does not always have to be encased in quotes. A single number (123456) / single words like TRUE / FALSE / or KeyWords (defined by the plugin) do not require quotation. Strings Do! Any text that contains whitespaces or non-alphanumeric characters is considered to be a String and Has to be quoted. The quote character can be either a single quote or a double quote (characters ' or ").
Note 2: Capitolization is not manditory. {COMMENT } = {comment } / and / PARAMETER_NAME = Prameter_Name = parameter_name.

Where do I find these Plugins?

The best way to become fluent with the Plugins is to use them. A complete listing of all Active Plugins can be found at the bottom of the page while editing a Page. Look for the Plugin Help tab. Selecting “More Details” shows the Plugins Parameters are and what they do. It will also show an example or two.
The Files are stored in the Liberty/Plugins directory. The files use a strict file naming convention that must be adhered to. For our Example Plugin, the filename is “data.example.php”.

Show me a Plugin then.

The Copyright Section does do a little more than just provide Copyright data. It is an integral part of our Documentation Effort. We are using the Doxygen Documentation System to help us build our API Documentation. For more information - please read APIDocumentation
{DD title='Line 1' }<?php - tells the Browser that the code is php{DD}
{DD title='Line 2' }Line 2 will be changed by the CVS Revision System each time the file is Commited. In this case - starrrider made the Commit at 03:52 (3:52 AM) on July 7, 2005 - it also gives the name of the file. None of this needs to be changed when creating a new Plugin.{DD}
{DD title='Overview' }Most of this section contains variables that are supplied to Doxygen System and never need to be edited. The only one that needs to be edited when creating a New Plugin is the author. In this case that is "Me" and I always include my SourceForge email address. All the rest of the variables are never changing or will be change automatically ( $Id: and version).{DD}

Initialization

This is where Globals and Defines are kept. It is also where the GUID is defined and then Registered with the Liberty System

This entire section is Mandantory and only the values should be changed.

{DD title='The Comments'}When creating a new Plugin - each of the Comments (both upper & lower case) should be changed to the name of your new Plugin. The Capitolization should remain as it is. Capitolized "Comments" (Lines 5, 18, & 19) relate to the GUID / While Lines 7 & 15 are described below.{DD}
{DD title='tag'}The value given here dontrols what the user will have to enter to make your function operate. Most of the tag should be the same as the name given to the Plugin. When the name is unweldy because of it's length - we can shorten it to whatever is desired. The plugin DropDown as an example was shortened to 'DD' because I expected it to be used a lot - it creates the expandable box you looking at.{DD}
{DD title='auto_activate'}Plugins can be turned off in bitweaver. A default value can be provided by specifing TRUE or FALSE here. This gives you the ability to turn a plugin off when you know there are problems with it.{DD}
{DD title='requires_pair'}This controls how the Plugin operates. When TRUE all of the information needed by the Plugin is contained in a single Code Block. Plugins like AddTabs and AgentInfo operate with this model. When it is FALSE - 2 Code Blocks are needed (the first to start the Plugin running and the second to end it). Normally - this type of Plugin operates on the Data located between the Code Blocks. Both Comment and ))DropDown operate with this model.{DD}
{DD title='load_function'}This specifies the name of the function that does all the work and is called by bitweaver. I normally use a name like 'data_X' where X is the name of the plugin. Note Be sure to actually give the Load Function the same name. Please don't laugh - I've made that mistake. In some editors it's hard to see if there are 1 or 2 underline character.{DD}
{DD title='title'}This is an "Unofficial" name for the Plugin that is only used by Help routine. If the name of your Plugin is "AardvarkAreCute" and you specified the Tag to ))AAC(( then the Ttitle should probably be "Aardvark Are Cute (AAC)". The latter provides a visual clue to the users shouldn't be able to miss.{DD}
{DD title='help_page'}Every Plugin should have a Help Page on bitweaver. The value given ends up as a URL - so while viewing the limited Help provided by the Help Function - the user can click a button and launch a new browser window to that page. For those of us who create the Plugins - it's not quite that simple. On the bitweaver site - all of the Plugin Help Pages are named DataPluginX where X is the name of the plugin. When your Plugin is finished and you are ready to Commit it - visit DataPlugins and add the name of the Plugin to the list of Plugins. Make sure you provide the name of the page you specified here. Once the page is saved - create the Help Page and give plenty of examples how it is used. I like using the page snippets that I have already created while testing the Plugin. Look at the Spy Text Help Page to see what I mean.{DD}
{DD title='description'}This should have been named provide_a_very_brief_description because that is all that is needed here. Just a fast blurb to remind the user what this Plugin does.{DD}
{DD title='help_function'}This specifies the name of the function that is called by bitweaver's Help Routines. I normally use a name like 'data_X_help' where X is the name of your plugin. Note: Be sure to actually give the Load Function the same name. Please don't laugh - I've made that mistake and at times it's hard to figure out why the stupid thing just isn't working. In some editors it's hard to see if there are 1 or 2 underline character.{DD}

{DD title='syntax'}This should provide the Tag and show all of the parameter names. e value given here {DD}

{DD title='plugin_type'}This will always be DATA_PLUGIN and should not be changed.{DD}

The Help Function

Help - how can it provide Help? . . . Oh yeah - there was that listing of Plugins at the bottom of the of the page in the editor. So that means that - each Plugin provides the data that is displayed by the bitweaver.

{DD title='Line 4'}The name of the Help Function Must match the name supplied in the Initialization Section's
'help_function'{DD}
NOTE: As the creator of a plugin - you get to decide what how much information it provides. This Tutorial provides some Guidelines - but it is your responsibility to give your users the information they are going to need - so take pride in your accomplishment and explain it.

The Load Function

Each Plugin has 4 basic sections. They are:


Good Luck