History of Tutorial - Liberty Plugins
{maketoc}
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:
~123~))COMMENT(( ~125~ The Text Inside the Block ~123~COMMENT~125~
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. ~123~))COMMENT(( ~125~ = ~123~comment ~125~ / 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.
! The Sections in a Plugin
Each Plugin has 4 basic sections. They are:__
# Copyright
# Initialization
# Help Function
# Load Function__
!!- The Copyright Sections
Hay - with a name like that - what else did you expect?
{CODE source=php num=on }<?php
// $Id: data.comment.php,v 1.1.2.2 2005/06/28 15:51:56 lsces Exp $
/**
* assigned_modules
*
* @author StarRider <starrrider@sourceforge.net>
* @version $Revision: 1.1.2.2 $
* @package liberty
* @subpackage plugins_data
* @copyright Copyright (c) 2004, bitweaver.org
* All Rights Reserved. See copyright.txt for details and a complete list of authors.
* @license Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details.
*/ {CODE}
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}
!!- The Initialization Sections
This is where Globals and Defines are kept. It is also where the GUID is defined and then Registered with the Liberty System
{CODE source=php num=on }/******************
* Initialization *
******************/
global $gLibertySystem;
define( 'PLUGIN_GUID_COMMENT', 'comment' );
global $gLibertySystem;
$pluginParams = array (
'tag' => 'COMMENT',
'auto_activate' => TRUE,
'requires_pair' => TRUE,
'load_function' => 'data_comment',
'title' => 'Comment',
'help_page' => 'DataPluginComment',
'description' => tra("This plugin allows Comments (Text that will not be displayed) to be added to a page."),
'help_function' => 'data__comment_help',
'syntax' => "{COMMENT }Data Not Displayed{COMMENT}",
'plugin_type' => DATA_PLUGIN
);
$gLibertySystem->registerPlugin( PLUGIN_GUID_COMMENT, $pluginParams );
$gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_COMMENT );{CODE}
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 ((DataPluginSpyText|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}
{DD title='plugin_type'}The value given here {DD}
!!- The Help Function Sections
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.
{CODE source=php num=on }/*****************
* Help Function *
*****************/
function data_comment_help() {
$help =
'<table class="data help">'
.'<tr>'
.'<th>' . tra( "Key" ) . '</th>'
.'<th>' . tra( "Type" ) . '</th>'
.'<th>' . tra( "Comments" ) . '</th>'
.'</tr>'
.'<tr class="odd">'
.'<td>' . tra("This plugin uses no parameters. Anything located between the two")
. ' <strong>{COMMENT}</strong> ' . tra("Blocks is not displayed.") . '</td>'
.'</tr>'
.'</table>'
. tra("Example: ") . "{COMMENT}" . tra("Everything in here is not displayed.") . "{COMMENT}";
return $help;
}{CODE}
{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.
!!- The Load Function Sections
Each Plugin has 4 basic sections. They are:
{CODE source=php num=on }/****************
* Load Function *
****************/
function data_comment($data, $params) {
return ' ';
}
?>{CODE}
asdf
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:
~123~))COMMENT(( ~125~ The Text Inside the Block ~123~COMMENT~125~
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. ~123~))COMMENT(( ~125~ = ~123~comment ~125~ / 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.
! The Sections in a Plugin
Each Plugin has 4 basic sections. They are:__
# Copyright
# Initialization
# Help Function
# Load Function__
!!- The Copyright Sections
Hay - with a name like that - what else did you expect?
{CODE source=php num=on }<?php
// $Id: data.comment.php,v 1.1.2.2 2005/06/28 15:51:56 lsces Exp $
/**
* assigned_modules
*
* @author StarRider <starrrider@sourceforge.net>
* @version $Revision: 1.1.2.2 $
* @package liberty
* @subpackage plugins_data
* @copyright Copyright (c) 2004, bitweaver.org
* All Rights Reserved. See copyright.txt for details and a complete list of authors.
* @license Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details.
*/ {CODE}
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}
!!- The Initialization Sections
This is where Globals and Defines are kept. It is also where the GUID is defined and then Registered with the Liberty System
{CODE source=php num=on }/******************
* Initialization *
******************/
global $gLibertySystem;
define( 'PLUGIN_GUID_COMMENT', 'comment' );
global $gLibertySystem;
$pluginParams = array (
'tag' => 'COMMENT',
'auto_activate' => TRUE,
'requires_pair' => TRUE,
'load_function' => 'data_comment',
'title' => 'Comment',
'help_page' => 'DataPluginComment',
'description' => tra("This plugin allows Comments (Text that will not be displayed) to be added to a page."),
'help_function' => 'data__comment_help',
'syntax' => "{COMMENT }Data Not Displayed{COMMENT}",
'plugin_type' => DATA_PLUGIN
);
$gLibertySystem->registerPlugin( PLUGIN_GUID_COMMENT, $pluginParams );
$gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_COMMENT );{CODE}
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 ((DataPluginSpyText|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}
{DD title='plugin_type'}The value given here {DD}
!!- The Help Function Sections
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.
{CODE source=php num=on }/*****************
* Help Function *
*****************/
function data_comment_help() {
$help =
'<table class="data help">'
.'<tr>'
.'<th>' . tra( "Key" ) . '</th>'
.'<th>' . tra( "Type" ) . '</th>'
.'<th>' . tra( "Comments" ) . '</th>'
.'</tr>'
.'<tr class="odd">'
.'<td>' . tra("This plugin uses no parameters. Anything located between the two")
. ' <strong>{COMMENT}</strong> ' . tra("Blocks is not displayed.") . '</td>'
.'</tr>'
.'</table>'
. tra("Example: ") . "{COMMENT}" . tra("Everything in here is not displayed.") . "{COMMENT}";
return $help;
}{CODE}
{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.
!!- The Load Function Sections
Each Plugin has 4 basic sections. They are:
{CODE source=php num=on }/****************
* Load Function *
****************/
function data_comment($data, $params) {
return ' ';
}
?>{CODE}
asdf