In this tutorial, I will try to explain Liberty Plugins, how they work, and what is needed to create or modify them.
So - why should I learn this?
By creating a Liberty Plugin, an administrator or developer is adding functionality to his site. This functionality has a lot of bang for the buck because a Liberty Plugin accesses the Liberty Storage System, which is used by most of the Packages.
Liberty Plugins can be fairly simple or extremely complex. They provide a good place for a beginners to play and learn. At the minimum - all that is required is a little knowledge of HTML / the PHP language / and the ability to look things up.
-=
The Plugin “Comment” will be used in the first part for this Tutorial
=-
What does the Plugin do?
The Comment Plugin is the simplest Plugin imaginable. All it does is - well - nothing. In doing "nothing" - it does 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 (unlike most Plugins) operates on 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 } 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 Liberty 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. Be sure to select “More Details” to see all of the parameters for the Plugin as well as an example or two. The actual 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”.
A Little History
A lot of the Plugins in bitweaver have been around since the split from TikiWiki. The Bonnie version of TikiPro gave most of them a face-lift and a lot of standardization. When the Liberty Package was introduced - all of the Plugins were re-evaluated and most of them were completely rewritten.
The File Name / Function Name Standard
There are several types of Plugins used in the Liberty Package. This Tutorial only deals with Data Plugins - but there are Format and Storage Plugins as well. A Data Plugin is Always Named "data.name_of_plugin.php. The Liberty Package requires that each Plugin have it's own GUID (more on this later) and every data.x.php file is examined when bitweaver starts so that it's GUID can be extracted. The nice thing about this is that it allows a lot more flexibility in Function Naming.
Hay - with a name like that - what else did you expect?
1: <?php 2: // $Id: data.comment.php,v 1.1.2.2 2005/06/28 15:51:56 lsces Exp $ 3: /** 4: * assigned_modules 5: * 6: * @author StarRider <starrrider@sourceforge.net> 7: * @version $Revision: 1.1.2.2 $ 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: */
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 is used to indicate to the Browser that the code is php{DD} {DD title='Line 2 & 7' }Will be changed by the CVS Revision System each time the file is Commited. In this case - Isces made the Commit at 15:51 (3:51 pm) on June 28, 2005 - it also gives the name of the file (WooHo). The Revision variable is also changed with each Commit.{DD} {DD title='Line 6 thru 12' }Data Supplied to Doxygen.{DD}
This is where Globals and Defines are kept. It is also where the GUID is defined and then Registered with the Liberty System
<?php 1: /****************** 2: * Initialization * 3: ******************/ 4: global $gLibertySystem; 5: define( 'PLUGIN_GUID_COMMENT', 'comment' ); 6: global $gLibertySystem; 7: $pluginParams = array ( 8: 'tag' => 'COMMENT', 9: 'auto_activate' => TRUE, 10: 'requires_pair' => TRUE, 11: 'load_function' => 'data_comment', 12: 'title' => 'Comment', 13: 'help_page' => 'DataPluginComment', 14: 'description' => tra("This plugin allows Comments (Text that will not be displayed) to be added to a page."), 15: 'help_function' => 'data__comment_help', 16: 'syntax' => "{COMMENT }Data Not Displayed{COMMENT}", 17: 'plugin_type' => DATA_PLUGIN 18: ); 19: $gLibertySystem->registerPlugin( PLUGIN_GUID_COMMENT, $pluginParams ); 20: $gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_COMMENT ); ?>
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 a_very_brief_description because that is what 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}
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 this function is used by the program where it is used.
<?php 1: /***************** 2: * Help Function * 3: *****************/ 4: function data_comment_help() { 5: $help = 6: '<table class="data help">' 7: .'<tr>' 8: .'<th>' . tra( "Key" ) . '</th>' 9: .'<th>' . tra( "Type" ) . '</th>' 10: .'<th>' . tra( "Comments" ) . '</th>' 11: .'</tr>' 12: .'<tr class="odd">' 13: .'<td>' . tra("This plugin uses no parameters. Anything located between the two") 14: . ' <strong>{COMMENT}</strong> ' . tra("Blocks is not displayed.") . '</td>' 15: .'</tr>' 16: .'</table>' 17: . tra("Example: ") . "{COMMENT}" . tra("Everything in here is not displayed.") . "{COMMENT}"; 18: return $help; ?>
{DD title='Line 4'}The name of the Help function must match the name supplied in the Initialization Section's 'help_page' 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.