Version 4

PluginProposal-HideText

Created by: Lee LaMont Bell Jr., Last modification: 18 Jul 2005 (09:48 UTC) by Lee LaMont Bell Jr.

Introduction

In this Tutorial - I will try to explain the basics questions about all Liberty Plugins. I'll answer the Basic Questions - What / Where / How & Why. This Tutorial does go get Technical - the contents of a simple Liberty Plugin is displayed. The underlying Sectioning within a Liberty Plugin / what each does / and how they interact is explained. What this Tutorial Does Not Do - is Provide an easy Step-by-Step Methodology for Creating a Liberty Plugin. The Tutorial - Liberty Plugins II page does all of 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 that is added to bitweaver incorporates (as an Application Framework) has it's own definition of what a Plugin is / what it does / and where it is used. There are even three different types of Plugins that belong to the LibertyPackage. 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.

In this Tutorial - saying "Liberty Plugins" means Liberty Data Plugins. These Plugins that can be used in any Package that uses the Liberty Storage System - and that includes: the Wiki / UserPages / Blogs / and - well - nearly everything bitweaver.

Adding Functionallity? How can a Liberty Plugin do that?

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.

Well I'm impressed. I not a Geek or a Computer Guru though.

Liberty Plugins can be fairly simple or as complex as you want to them to be. 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 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.

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 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. 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.


  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;
 
18define'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->registerPluginPLUGIN_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?>
 57: That's all there is to it. You should be able to see why I said the Plugin does nothing. The Load Function returns a single space character. You should also be able to see the 4 basic sections in the Plugin. Each of these will be explained below. They are:__
 58: # Copyright
 59: # Initialization
 60: # Help Function
 61: # Load Function__
 62: !! Copyright
 63: Hay - with a name like that - what else did you expect?
 64: {CODE source=php num=on }{CODE source=php num=on }<?php
 65
// $Id: data.comment.php,v 1.1.2.3 2005/07/16 03:52:25 starrrider Exp $
 
66/**
 67:  * assigned_modules
 68:  *
 69:  * @author   StarRider <starrrider@sourceforge.net>
 70:  * @version  $Revision: 1.1.2.3 $
 71:  * @package  liberty
 72:  * @subpackage plugins_data
 73:  * @copyright Copyright (c) 2004, bitweaver.org
 74:  * All Rights Reserved. See copyright.txt for details and a complete list of authors.
 75:  * @license Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details.
 76:  */

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

<?php
  1
/******************
  2:  * Initialization *
  3:  ******************/
  
4: global $gLibertySystem;
  
5define'PLUGIN_GUID_COMMENT''comment' );
  
6: global $gLibertySystem;
  
7$pluginParams = array ( 'tag' => 'COMMENT',
  
8:      'auto_activate' => TRUE,
  
9:      'requires_pair' => TRUE,
 
10:      'load_function' => 'data_comment',
 
11:      'title' => 'Comment',
 
12:      'help_page' => 'DataPluginComment',
 
13:      'description' => tra("This plugin allows Comments (Text that will not be displayed) to be added to a page."),
 
14:      'help_function' => 'data__comment_help',
 
15:      'syntax' => "{COMMENT}Data Not Displayed{COMMENT}",
 
16:      'plugin_type' => DATA_PLUGIN
 17
: );
 
18$gLibertySystem->registerPluginPLUGIN_GUID_COMMENT$pluginParams );
 
19$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 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.

<?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_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:

<?php
  1
/****************
  2: * Load Function *
  3:  ****************/
  
4: function data_comment($data$params) {
  
5:     return ' ';
?>


Page History
Date/CommentUserIPVersion
14 Jul 2005 (10:17 UTC)
Rollback to version 3 by StarRider
Lee LaMont Bell Jr.68.95.137.1235
Current • Source
Lee LaMont Bell Jr.68.95.129.254
View • Compare • Difference • Source
Lee LaMont Bell Jr.68.95.137.1233
View • Compare • Difference • Source
Lee LaMont Bell Jr.68.95.137.1722
View • Compare • Difference • Source
Lee LaMont Bell Jr.68.95.137.1721
View • Compare • Difference • Source