Tutorial - Liberty Plugins
Created by: Lee LaMont Bell Jr., Last modification: 19 Jul 2005 (08:40 UTC)
Introduction
This Tutorial concerns Liberty Data Plugins and tries 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 primarily for Site Administrators and Developers (or anyone) wanting to add functionality 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 Data Plugins anyway - isn't Plugin enough?
There are all kinds of Plugins. Every Package incorporated into bitweaver (in it's 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 kinds 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 Functionality?
Easy! Here's a situation for you. You've just updated a page - and say "Not Bad - I just wish I had some EyeCandy to make this more noticeable". Now if we were doing things the old fashioned way using pure HTML pages - there are literally thousands of different things that could be easily added to give you exactly the effect you want - providing you have the skill to add it. Bitweaver's pages are not like a pure HTML pages - but anything that works in an HTML page can be placed in a Plugin and will work in a bitweaver page.The "EyeCandy NeonText" (ECNT) Plugin is a very good example. It was written for two reasons:
- I renamed a finished a Proposed Plugin PluginProposal-HideText and wanted some EyeCandy to make a Notice - It's Done statement.
- I decided to create the second Tutorial Tutorial - Liberty Plugins II and needed a good example for it.
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 / the ability to look things up / and the ability to experiment a little. Plugins can be as simple or as complex as you want to them to be. They provide an excellent place for a beginner to play and learn.The Plugin "Comment" will be used as an example throughout this Tutorial.
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.How is a Plugin Used?
The Comment Plugin allows text to be stored in a page - and prevents it from being displayed. It is used like this: {COMMENT } The Text Inside the Block {COMMENT}The Comment Plugin (unlike most Plugins) operates on the text encased between a pair of Code Blocks. A Code Block is the Key used to start the Plugin encased in curly brackets “{“ and “}” like this: {COMMENT }
Parameters are used to make a Plugins more useful. They provide additional information / and control how the Plugin works. Parameters are added to the first code block in the form of parameter_name=’value’. This works because the Plugin defines each Parameter that it will use and knows what to expect. The Value can be a single number (123456) / single words like TRUE / FALSE / or a KeyWord (again defined by the Plugin). None of these Has to be quoted. It can also be a String - defined as:
Any series of numbers or text that contains white spaces or non-alphanumeric characters.
Must be Quoted - the quote character can be either a single quote or a double quote (characters ' or ").
Note: Capitalization is Not mandatory with the Plugins Key or with Parameter Names.
{COMMENT } = {Comment } = {comment } / and / PARAMETER_NAME = Prameter_Name = parameter_name
With the Parameter's Value - it could be!
Where do I find the Plugins?
The best way to become fluent with the Plugins is to use them. A complete listing of all Active Plugins can be found inside the Page Editor at the bottom of the page. Look for the Plugin Help tab. Selecting “More Details” shows each of the Plugin's Parameters and explains what they do. Normally - an Example or two is also given.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, that filename is “data.example.php”.
Show me a Plugin then.
1: <?php
2: // $Id: data.comment.php,v 1.1.2.3 2005/07/16 03:52:25 starrrider Exp $
3: /**
4: * assigned_modules
5: *
6: * @author StarRider <starrrider@sourceforge.net>
7: * @version $Revision: 1.1.2.3 $
8: * @package liberty
9: * @subpackage plugins_data
10: * @copyright Copyright (c) 2004, bitweaver.org
11: * All Rights Reserved. See copyright.txt for details and a complete list of authors.
12: * @license Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details.
13: */
14: /******************
15: * Initialization *
16: ******************/
17: global $gLibertySystem;
18: define( 'PLUGIN_GUID_COMMENT', 'comment' );
19: global $gLibertySystem;
20: $pluginParams = array ( 'tag' => 'COMMENT',
21: 'auto_activate' => TRUE,
22: 'requires_pair' => TRUE,
23: 'load_function' => 'data_comment',
24: 'title' => 'Comment',
25: 'help_page' => 'DataPluginComment',
26: 'description' => tra("This plugin allows Comments (Text that will not be displayed) to be added to a page."),
27: 'help_function' => 'data__comment_help',
28: 'syntax' => "{COMMENT}Data Not Displayed{COMMENT}",
29: 'plugin_type' => DATA_PLUGIN
30: );
31: $gLibertySystem->registerPlugin( PLUGIN_GUID_COMMENT, $pluginParams );
32: $gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_COMMENT );
33: /*****************
34: * Help Function *
35: *****************/
36: function data_comment_help() {
37: $help =
38: '<table class="data help">'
39: .'<tr>'
40: .'<th>' . tra( "Key" ) . '</th>'
41: .'<th>' . tra( "Type" ) . '</th>'
42: .'<th>' . tra( "Comments" ) . '</th>'
43: .'</tr>'
44: .'<tr class="odd">'
45: .'<td>' . tra("This plugin uses no parameters. Anything located between the two")
46: . ' <strong>{COMMENT}</strong> ' . tra("Blocks is not displayed.") . '</td>'
47: .'</tr>'
48: .'</table>'
49: . tra("Example: ") . "{COMMENT}" . tra("Everything in here is not displayed.") . "{COMMENT}";
50: return $help;
51: /****************
52: * Load Function *
53: ****************/
54: function data_comment($data, $params) {
55: return ' ';
56: ?>
That's all there is to it. You should be able to see the 4 basic sections in every Plugin. Each of these will be explained below. They are:
- Copyright
- Initialization
- Help Function
- Load Function
The Way It Works!
When a Web Browser asks bitweaver to load a page - bitweaver accesses the database for that page and looks at it to see what has to be done. It scans each and every line looking for Special Symbols / Key-Words and HTML Statements that it has to act uppon. One of the things it looks for are Code Blocks like this:{COMMENT parameter='No' } The Text Inside the Blocks {COMMENT}
When it finds one - it looks up the Plugins Tag and passes the data to the Load Function (in this case the Load Function is function data_comment($data, $params)). The two variables passed to it are:
- $data - contains all of the information between the two Code Blocks - (in this case that would be: The Text Inside the Blocks)
- $params is an array (in this case that array contains a single element with the index of 'parameter_name' and with a value of 'No'). Now if this seems to be getting difficult - relax. There was no reason to include the code in the Comment Plugin - but most Plugins extract the parameter array into variables like this: extract ($params); which would create all of the variables in the array (in this case - $parameter_name and it would have a value of No)
Copyright
With a heading like that - what would you expect to find here?
1: <?php
2: // $Id: data.comment.php,v 1.1.2.3 2005/07/16 03:52:25 starrrider Exp $
3: /**
4: * assigned_modules
5: *
6: * @author StarRider <starrrider@sourceforge.net>
7: * @version $Revision: 1.1.2.3 $
8: * @package liberty
9: * @subpackage plugins_data
10: * @copyright Copyright (c) 2004, bitweaver.org
11: * All Rights Reserved. See copyright.txt for details and a complete list of authors.
12: * @license Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details.
13: */
This Section does more than just post Copyright data though. 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='Explaining Line 1' }The only line in this section that isn't a comment. The first line in every php File tells the Browser what kind of code it is dealing with - php{DD} {DD title='Explaining Line 2' }Line 2 will be changed by the CVS Revision System each time the file is Committed. In this case - the last Commit was made by "Me" at 03:52 (3:52 AM) on July 7, 2005.{DD} {DD title='Providing an 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". It is not mandatory but I include my email address in these Plugins. I use my SourceForge email address mainly because it is a redirect and will remain stable if I happen to move or change ISP's. 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
<?php
14: /******************
15: * Initialization *
16: ******************/
17: global $gLibertySystem;
18: define( 'PLUGIN_GUID_COMMENT', 'comment' );
19: global $gLibertySystem;
20: $pluginParams = array ( 'tag' => 'COMMENT',
21: 'auto_activate' => TRUE,
22: 'requires_pair' => TRUE,
23: 'load_function' => 'data_comment',
24: 'title' => 'Comment',
25: 'help_page' => 'DataPluginComment',
26: 'description' => tra("This plugin allows Comments (Text that will not be displayed) to be added to a page."),
27: 'help_function' => 'data__comment_help',
28: 'syntax' => "{COMMENT}Data Not Displayed{COMMENT}",
29: 'plugin_type' => DATA_PLUGIN
30: );
31: $gLibertySystem->registerPlugin( PLUGIN_GUID_COMMENT, $pluginParams );
32: $gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_COMMENT );
?>
This section is Mandatory and should be edited with care. In the $pluginParams Array : The first part is the index ('tag') and the second part is it's value ('COMMENT'). Only the values should be changed.
{DD title='The GUID'}The Liberty System uses a GUID's (Globally Unique IDentifier) for storing & retrieving data and acts in a manner very similar to the Registry created by MS Windows. It uses GUID's for locating Plugin information as well.
The Define on Line 18 starts this off by storing a value (in this case 'comment') that is used to create the GUID. The $pluginParms Array (Line 20 thru 30) contains the information to be stored. Line 31 Registers the Plugin with the Liberty System & Line 32 Registers the Plugin's Tag. The last is important because it is the Tag that is looked up when the page is displayed.{DD} {DD title='Note 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 Capitalization should remain as it is.{DD} {DD title='tag'}The Tag Controls what the user has to enter to make the Plugin work. Most of the time the Tag should be the same as the Name & Title of the Plugin. Sometimes it makes more sense to use an abbreviated name instead. The Plugin DropDown is a good example. The Tag for it was shortened to 'DD' because I expected it to be used a lot - it creates the expandable boxes that you looking at.{DD} {DD title='auto_activate'}Every Plugin can be turned off in bitweaver by the Administrator - but the 'auto_activate' value provides a Default Value. This can come in handy because it gives lets you turn a Plugin Off or On while working on it without having to use the Admin Menu to make the change.{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(( - Two Code Blocks are needed (the First to Start the Plugin Running and the Second to Shut if Off). Usually - 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'}The Title is the "Unofficial" name of the Plugin and it is only used by Help Routine. If you created a Plugin called "AardvarkAreCute" - you would probably specify the Tag as ))AAC(( and place "Aardvark Are Cute (AAC)" in the Title. The latter provides a visual clue that a user 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. Here are the steps needed:
- Update the DataPlugins page on bitweaver. All of the Plugin Help Pages are named DataPluginX where X is the name of the Plugin. So add a the Plugin to the Table and specify the page to be added. Make sure you provide the name of the page you specified here and save the page.
- 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.
- Test the Plugin. Check to make sure that the Link to the Help Page actually finds the right page.
- Commit - The Plugin is Finished (Sounds of Applause)
- The final item is not really required - but I do it just because it feels good. Send a "Developers Update" email to bitweaver-core@lists.sourceforge.net and let everybody know about the Birth of your New Baby.{DD} {DD title='description'}This should have been named ))provide_a_very_brief_description_here(( because that is all that is needed. 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 Help Function the same name. If the Help doesn't show up in the Page Editor - Look at that First!{DD} {DD title='syntax'}There was no reason to standardize the Syntax before - but there soon will be. The Syntax will be inserted into the page at the cursors position when the Insert Button is clicked. For that reason - a Plugin that only needs one Code Block (requires_pair = ))FALSE(() should look like this:
And a Plugin that Needs Two Code Blocks (requires_pair = ))TRUE(() should look like this:
{COMMENT parameter= }text{COMMENT}{DD} {DD title='plugin_type'}As stated earlier - the Liberty System has 3 different kinds of Plugins. The 'plugin_type' is used to let Liberty know the kind of Plugin that this is. Since this Tutorial is only concerned with Liberty Data Plugins the value should Always be DATA_PLUGIN{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.
<?php
33: /*****************
34: * Help Function *
35: *****************/
36: function data_comment_help() {
37: $help =
38: '<table class="data help">'
39: .'<tr>'
40: .'<th>' . tra( "Key" ) . '</th>'
41: .'<th>' . tra( "Type" ) . '</th>'
42: .'<th>' . tra( "Comments" ) . '</th>'
43: .'</tr>'
44: .'<tr class="odd">'
45: .'<td>' . tra("This plugin uses no parameters. Anything located between the two")
46: . ' <strong>{COMMENT}</strong> ' . tra("Blocks is not displayed.") . '</td>'
47: .'</tr>'
48: .'</table>'
49: . tra("Example: ") . "{COMMENT}" . tra("Everything in here is not displayed.") . "{COMMENT}";
50: return $help;
?>
{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. Lets Face Facts Ok? It is your responsibility to give the users the information they are going to need. Take some pride in your accomplishment - and spend the time needed to explain it. (Watch StarRider slowly climbing off his soap box.)
The Load Function
This is where all the Magic Happens. (Do you hear the sound of my laughter?)
<?php
52: /****************
53: * Load Function *
54: ****************/
55: function data_comment($data, $params) {
56: return ' ';
?>
See The Way It Works (Above)
I hope that you've enjoyed this little Tutorial.
The Next Step is the Tutorial - Liberty Plugins II
Good Luck - StarRider
Comments
Great stuff!