History of Tutorial - Liberty Plugins II
{maketoc}
! Introduction
This is the Second in a series of Tutorials concerning Liberty Data Plugins. The First Tutorial - __((Tutorial - Liberty Plugins))__ tried to answer the Basic Questions - What / Where / How & Why. __This Tutorial__ Provide a __))Step-by-Step((__ Methodology for Creating Liberty Data Plugins - and a __Lot__ more.
! Should I be Reading This?
This Tutorial is provided for Site Administrators and Developers (or anyone else) wanting to add functionality to a bitweaver Powered Site. A User on a bitweaver Powered Site would find little to interest them by reading this Tutorial.
! Liberty Data Plugins
There are many types of Plugins. In this Tutorial - the word __Plugin__ means a __Liberty Data Plugin__.
! Your Intorduction Seems a Bit Vague!
I created the ((ProposalPage-Plugins)) for several reasons. The main one is to provide people with another place where they can put their ideas / wishes & desires. In this Tutorial we are going to create the __Proposed Plugin__ Named ))EyeCandy(( ))NeonText((. It was originally described on the page ((PluginProposal-EyeCandy NeonText)) and Most of that description is repeated in this Tutorial.
! The Basic Premise Was
I think bitweaver is just a __Wee Bit Stoic__ and I wanted a Plugin that would add a little __Flair__ to a page. I did a search and found 2 code snippets that would meet my requirements. Those Requirements were:
# It would have to have ))Cross-Browser(( Support
# Nothing would be added to the Head Section of the page.
(Most ))JavaScript(( files want to place half their code in the Head Section of the page to be displayed - This was fine in the days when there were only unique HTML pages. With a bitweaver page though - anything included in the Head Section is included in every page displayed - even if it isn't needed. So I did __Not__ want to add anything in there for a Plugin)
I found 2 DHTML Scripts at <[http://www.dynamicdrive.com]> that met those requirements and were similar enough that I thought I could combine them into a single Plugin. They are:
# __Neon Lights Text__ <[http://www.dynamicdrive.com/dynamicindex10/neontext.htm]>
# __Neon Lights Text II__ <[http://www.dynamicdrive.com/dynamicindex10/neontext2.htm]>
! So Lets Begin
Since we know what we are going to try to make the Plugin do - and we have decided that we are going to name it (__))EyeCandy(( ))NeonText((__). Or did we? I mean - that is a really long moniker. When given in all upper or lower case characters - it would be really hard to spot an error.
So lets look at it again. We could eliminate the __))EyeCandy((__ and __Text__. That would save us a little typing. I still like the idea of keeping the Visual Enhansements together - so lets just abreviate __))EyeCandy((__ to __'EC'__. That would give us the Name __'ECNeon'__ which isn't all that bad.
The decission to use a shorter __Tag__ was made on the Proposal Page. We don't have to live with that if we don't want to - and a Plugin Named __'ECNeon'__ doesn't really need a shorter __Tag__
!! Step 1 - Creating The File
Open your Handy Dandy File Manager on your ))DeskTop(( and navigate to where the bitweaver files are located. In the Directory __liberty\plugins__ - Copy the File __data.example.php__ and give it the name __data.ecneon.php__. If you have your Testing Site __(localhost?)__ Open at this point - you will see the following error:
-+Fatal error: Cannot redeclare data_example_help() (previously declared in C:\sokkit\site\Bitweaver\liberty\plugins\data.ecneon.php:40) in C:\sokkit\site\Bitweaver\liberty\plugins\data.example.php on line 62+-
Ignore the Error and Open the New File in your Editor. It should look like this:
{DD title="Here's The Code" } {CODE source='php' num=TRUE }<?php
// $id: data.example.php,v 1.4.2.9 2005/07/14 09:03:36 starrider Exp $
/**
* assigned_modules
*
* @author StarRider starrrider@sourceforge.net
* @version $Revision: 1.4.2.9 $
* @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.
*/
/******************
* Initialization *
******************/
define( 'PLUGIN_GUID_DATAEXAMPLE', 'dataexample' );
global $gLibertySystem;
$pluginParams = array ( 'tag' => 'EXAM',
'auto_activate' => FALSE,
'requires_pair' => FALSE,
'load_function' => 'data_example',
'title' => 'Example (EXAM)',
'help_page' => 'DataPluginExample',
'description' => tra("This Plugin is an Example that does nothing. It functions as a template for the creation of new plugins."),
'help_function' => 'data_example_help',
'syntax' => "{EXAM x1= x2= }",
'plugin_type' => DATA_PLUGIN
);
$gLibertySystem->registerPlugin( PLUGIN_GUID_DATAEXAMPLE, $pluginParams );
$gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_DATAEXAMPLE );
/*****************
* Help Function *
*****************/
function data_example_help() {
$help =
'<table class="data help">'
.'<tr>'
.'<th>' . tra( "Key" ) . '</th>'
.'<th>' . tra( "Type" ) . '</th>'
.'<th>' . tra( "Comments" ) . '</th>'
.'</tr>'
.'<tr class="odd">'
.'<td>x1</td>'
.'<td>' . tra( "string") . '<br />' . tra("(optional)") . '</td>'
.'<td>' . tra( "Specifies something / probably to be displayed.")
.'<br />' . tra( "The Default = <strong>Sorry About That</strong>")
.'</td>'
.'</tr>'
.'<tr class="even">'
.'<td>XXX</td>'
.'<td>' . tra( "number") . '<br />' . tra("(optional)") . '</td>'
.'<td>' . tra( "Specifies something / probably to be displayed.")
.'<br />' . tra( "The Default =") . ' <strong>3</strong> ' . tra( "Which means - What")
.'</td>'
.'</tr>'
.'</table>'
. tra("Example: ") . "{EXAM x1=' ' x2=5 }<br />"
. tra("This will display");
return $help;
}
/****************
* Load Function *
****************/
function data_example($data, $params) {
extract ($params);
$ret = ' ';
return $ret;
}
?>{CODE} {DD}
!! Step 2 - Search & Replace
In the Editor - we are going to do xxx Global Search and Replaces - but here is the key.The Replace should __Only__ happen if the Case is the __Same__.
For Example: In a Search for __dogs__ - All __dogs__ Are Replaced but Not __Dogs__ or __DOGS__
^||-=::Search & Replace::=-
Find What: | ))EXAMPLE((
Replace With: | ))ECNEON((
-=::Click Replace All::=-||^
^||-=::Search & Replace::=-
Find What: | EXAM
Replace With: | ))ECNEON((
-=::Click Replace All::=-||^
^||-=::Search & Replace::=-
Find What: | example
Replace With: | ))ecneon((
-=::Click Replace All::=-||^
__Note:__ At this point - we have a Plugin that doesn't break the system. Save it and see for yourself.
!! Step 3 - Manual Edits
Our Search and Replace didn't leave us with errors - but there are still things that need to be changed manually. I hope your editor displays Line Numbers.
__Line 6__ Change __))StarRider(( starrrider@sourceforge.net__ to your ))UserName(( and Email Address
__Line 20__ Change __False__ to __'TRUE'__
__Line 21__ There are 2 ways that we could work this. First - we could make __'requires_pair' => TRUE,__. This would mean that the Plugin Requires 2 Code Blocks and let the User place the String to be Highlighted between them. It would look something like this: __~123~))ECN((eon ~125~ Text ~123~))ECN((eon ~125~__. The problem with this is that we would have to figure out how to handle more than __One__ String to be Highlighted - because sooner or later somebody is going to dump a bunch of lines in there. They are also going to complain about it not working right no matter what we come up with.
The Second ways is to __Leave This Line Alone__ and provide a Parameter for the String to be Highlighted. Now that sounds really good to me. Lets do it this way.
__Line 23__ Change __'Example (ECNEON)',__ to __'))EyeCandy(( Neon (ECNEON)',__
__Line 24__ Change __'DataPluginExample',__ to __'DataPluginEyeCandyNeon',__
__Line 25__ We need to provide a Description for this Plugin and place it between __tra("__ and __"),__ How about the description given on ((ProposalPage-Plugins)). It said - __ Would apply a Neon Lighting Effect (an age old technique of attracting attention) to a string.__
So __Line 25__ should now look like this:
{DD title="Here's The Code" } {CODE source='php' }'description' => tra("Apply a Neon Lighting Effect (an age old technique of attracting attention) to a string."),{CODE} {DD}
__Line 27__ We need to decide what we are going to need for Parameters.
The First Parameter should be the String to be Highlighted - Lets give it a really expressive Parameter Name like - __text__.
Since we're going to be joining the two scripts together - the Second Parameter could be a Boolean Switch. That doesn't leave any room for Grouth though - and somebody is going to look at this and see a minor change that will provide us with more ))EyeCandy((. Count on it (Wink). So lets make this Parameter a ))KeyWord(( with a default value. We will use __candy__ as the Parameter Name.
Since both scripts write __Colored Text__ - and then __Modify the Colors__. The Third & Fourth Parameters are Colors. Lets go all out with their naming and call them __color1__ and __color2__.
The Fifth Parameter should control the Size of the Text - so lets use our imagination again and give it the name __size__
That means Line 27 should look like this:
{DD title="Here's The Code" } {CODE source='php' }'syntax' => "{ECNEON text= candy= color1= color2= size= }",{CODE} {DD}
__Note:__ Since Editing the Help Function is More Complex - Lets Stop Here and take a look at what we've done so far.'
{DD title="Here's The Code" } {CODE source='php' num=TRUE }<?php
// $id: data.ecneon.php,v 1.4.2.9 2005/07/14 09:03:36 starrider Exp $
/**
* assigned_modules
*
* @author StarRider starrrider@sourceforge.net
* @version $Revision: 1.4.2.9 $
* @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.
*/
/******************
* Initialization *
******************/
define( 'PLUGIN_GUID_DATAECNEON', 'dataecneon' );
global $gLibertySystem;
$pluginParams = array (
'tag' => 'ECNEON',
'auto_activate' => TRUE,
'requires_pair' => FALSE,
'load_function' => 'data_ecneon',
'title' => 'EyeCandy Neon (ECNEON)',
'help_page' => 'DataPluginEyeCandy',
'description' => tra("Apply a Neon Lighting Effect (an age old technique of attracting attention) to a string."),
'help_function' => 'data_ecneon_help',
'syntax' => "{ECNEON text= candy= color1= color2= size= }",
'plugin_type' => DATA_PLUGIN
);{CODE} {DD}
^::__This Tutorial is Not Finished Yet - There is More to Come.__::^
I hope that you've enjoyed my little Tutorial.
The Next Step is the __((Tutorial - Using the PluginSnippet Page))__
Good Luck - [http://www.bitweaver.org/StarRider|StarRider]
! Introduction
This is the Second in a series of Tutorials concerning Liberty Data Plugins. The First Tutorial - __((Tutorial - Liberty Plugins))__ tried to answer the Basic Questions - What / Where / How & Why. __This Tutorial__ Provide a __))Step-by-Step((__ Methodology for Creating Liberty Data Plugins - and a __Lot__ more.
! Should I be Reading This?
This Tutorial is provided for Site Administrators and Developers (or anyone else) wanting to add functionality to a bitweaver Powered Site. A User on a bitweaver Powered Site would find little to interest them by reading this Tutorial.
! Liberty Data Plugins
There are many types of Plugins. In this Tutorial - the word __Plugin__ means a __Liberty Data Plugin__.
! Your Intorduction Seems a Bit Vague!
I created the ((ProposalPage-Plugins)) for several reasons. The main one is to provide people with another place where they can put their ideas / wishes & desires. In this Tutorial we are going to create the __Proposed Plugin__ Named ))EyeCandy(( ))NeonText((. It was originally described on the page ((PluginProposal-EyeCandy NeonText)) and Most of that description is repeated in this Tutorial.
! The Basic Premise Was
I think bitweaver is just a __Wee Bit Stoic__ and I wanted a Plugin that would add a little __Flair__ to a page. I did a search and found 2 code snippets that would meet my requirements. Those Requirements were:
# It would have to have ))Cross-Browser(( Support
# Nothing would be added to the Head Section of the page.
(Most ))JavaScript(( files want to place half their code in the Head Section of the page to be displayed - This was fine in the days when there were only unique HTML pages. With a bitweaver page though - anything included in the Head Section is included in every page displayed - even if it isn't needed. So I did __Not__ want to add anything in there for a Plugin)
I found 2 DHTML Scripts at <[http://www.dynamicdrive.com]> that met those requirements and were similar enough that I thought I could combine them into a single Plugin. They are:
# __Neon Lights Text__ <[http://www.dynamicdrive.com/dynamicindex10/neontext.htm]>
# __Neon Lights Text II__ <[http://www.dynamicdrive.com/dynamicindex10/neontext2.htm]>
! So Lets Begin
Since we know what we are going to try to make the Plugin do - and we have decided that we are going to name it (__))EyeCandy(( ))NeonText((__). Or did we? I mean - that is a really long moniker. When given in all upper or lower case characters - it would be really hard to spot an error.
So lets look at it again. We could eliminate the __))EyeCandy((__ and __Text__. That would save us a little typing. I still like the idea of keeping the Visual Enhansements together - so lets just abreviate __))EyeCandy((__ to __'EC'__. That would give us the Name __'ECNeon'__ which isn't all that bad.
The decission to use a shorter __Tag__ was made on the Proposal Page. We don't have to live with that if we don't want to - and a Plugin Named __'ECNeon'__ doesn't really need a shorter __Tag__
!! Step 1 - Creating The File
Open your Handy Dandy File Manager on your ))DeskTop(( and navigate to where the bitweaver files are located. In the Directory __liberty\plugins__ - Copy the File __data.example.php__ and give it the name __data.ecneon.php__. If you have your Testing Site __(localhost?)__ Open at this point - you will see the following error:
-+Fatal error: Cannot redeclare data_example_help() (previously declared in C:\sokkit\site\Bitweaver\liberty\plugins\data.ecneon.php:40) in C:\sokkit\site\Bitweaver\liberty\plugins\data.example.php on line 62+-
Ignore the Error and Open the New File in your Editor. It should look like this:
{DD title="Here's The Code" } {CODE source='php' num=TRUE }<?php
// $id: data.example.php,v 1.4.2.9 2005/07/14 09:03:36 starrider Exp $
/**
* assigned_modules
*
* @author StarRider starrrider@sourceforge.net
* @version $Revision: 1.4.2.9 $
* @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.
*/
/******************
* Initialization *
******************/
define( 'PLUGIN_GUID_DATAEXAMPLE', 'dataexample' );
global $gLibertySystem;
$pluginParams = array ( 'tag' => 'EXAM',
'auto_activate' => FALSE,
'requires_pair' => FALSE,
'load_function' => 'data_example',
'title' => 'Example (EXAM)',
'help_page' => 'DataPluginExample',
'description' => tra("This Plugin is an Example that does nothing. It functions as a template for the creation of new plugins."),
'help_function' => 'data_example_help',
'syntax' => "{EXAM x1= x2= }",
'plugin_type' => DATA_PLUGIN
);
$gLibertySystem->registerPlugin( PLUGIN_GUID_DATAEXAMPLE, $pluginParams );
$gLibertySystem->registerDataTag( $pluginParams['tag'], PLUGIN_GUID_DATAEXAMPLE );
/*****************
* Help Function *
*****************/
function data_example_help() {
$help =
'<table class="data help">'
.'<tr>'
.'<th>' . tra( "Key" ) . '</th>'
.'<th>' . tra( "Type" ) . '</th>'
.'<th>' . tra( "Comments" ) . '</th>'
.'</tr>'
.'<tr class="odd">'
.'<td>x1</td>'
.'<td>' . tra( "string") . '<br />' . tra("(optional)") . '</td>'
.'<td>' . tra( "Specifies something / probably to be displayed.")
.'<br />' . tra( "The Default = <strong>Sorry About That</strong>")
.'</td>'
.'</tr>'
.'<tr class="even">'
.'<td>XXX</td>'
.'<td>' . tra( "number") . '<br />' . tra("(optional)") . '</td>'
.'<td>' . tra( "Specifies something / probably to be displayed.")
.'<br />' . tra( "The Default =") . ' <strong>3</strong> ' . tra( "Which means - What")
.'</td>'
.'</tr>'
.'</table>'
. tra("Example: ") . "{EXAM x1=' ' x2=5 }<br />"
. tra("This will display");
return $help;
}
/****************
* Load Function *
****************/
function data_example($data, $params) {
extract ($params);
$ret = ' ';
return $ret;
}
?>{CODE} {DD}
!! Step 2 - Search & Replace
In the Editor - we are going to do xxx Global Search and Replaces - but here is the key.The Replace should __Only__ happen if the Case is the __Same__.
For Example: In a Search for __dogs__ - All __dogs__ Are Replaced but Not __Dogs__ or __DOGS__
^||-=::Search & Replace::=-
Find What: | ))EXAMPLE((
Replace With: | ))ECNEON((
-=::Click Replace All::=-||^
^||-=::Search & Replace::=-
Find What: | EXAM
Replace With: | ))ECNEON((
-=::Click Replace All::=-||^
^||-=::Search & Replace::=-
Find What: | example
Replace With: | ))ecneon((
-=::Click Replace All::=-||^
__Note:__ At this point - we have a Plugin that doesn't break the system. Save it and see for yourself.
!! Step 3 - Manual Edits
Our Search and Replace didn't leave us with errors - but there are still things that need to be changed manually. I hope your editor displays Line Numbers.
__Line 6__ Change __))StarRider(( starrrider@sourceforge.net__ to your ))UserName(( and Email Address
__Line 20__ Change __False__ to __'TRUE'__
__Line 21__ There are 2 ways that we could work this. First - we could make __'requires_pair' => TRUE,__. This would mean that the Plugin Requires 2 Code Blocks and let the User place the String to be Highlighted between them. It would look something like this: __~123~))ECN((eon ~125~ Text ~123~))ECN((eon ~125~__. The problem with this is that we would have to figure out how to handle more than __One__ String to be Highlighted - because sooner or later somebody is going to dump a bunch of lines in there. They are also going to complain about it not working right no matter what we come up with.
The Second ways is to __Leave This Line Alone__ and provide a Parameter for the String to be Highlighted. Now that sounds really good to me. Lets do it this way.
__Line 23__ Change __'Example (ECNEON)',__ to __'))EyeCandy(( Neon (ECNEON)',__
__Line 24__ Change __'DataPluginExample',__ to __'DataPluginEyeCandyNeon',__
__Line 25__ We need to provide a Description for this Plugin and place it between __tra("__ and __"),__ How about the description given on ((ProposalPage-Plugins)). It said - __ Would apply a Neon Lighting Effect (an age old technique of attracting attention) to a string.__
So __Line 25__ should now look like this:
{DD title="Here's The Code" } {CODE source='php' }'description' => tra("Apply a Neon Lighting Effect (an age old technique of attracting attention) to a string."),{CODE} {DD}
__Line 27__ We need to decide what we are going to need for Parameters.
The First Parameter should be the String to be Highlighted - Lets give it a really expressive Parameter Name like - __text__.
Since we're going to be joining the two scripts together - the Second Parameter could be a Boolean Switch. That doesn't leave any room for Grouth though - and somebody is going to look at this and see a minor change that will provide us with more ))EyeCandy((. Count on it (Wink). So lets make this Parameter a ))KeyWord(( with a default value. We will use __candy__ as the Parameter Name.
Since both scripts write __Colored Text__ - and then __Modify the Colors__. The Third & Fourth Parameters are Colors. Lets go all out with their naming and call them __color1__ and __color2__.
The Fifth Parameter should control the Size of the Text - so lets use our imagination again and give it the name __size__
That means Line 27 should look like this:
{DD title="Here's The Code" } {CODE source='php' }'syntax' => "{ECNEON text= candy= color1= color2= size= }",{CODE} {DD}
__Note:__ Since Editing the Help Function is More Complex - Lets Stop Here and take a look at what we've done so far.'
{DD title="Here's The Code" } {CODE source='php' num=TRUE }<?php
// $id: data.ecneon.php,v 1.4.2.9 2005/07/14 09:03:36 starrider Exp $
/**
* assigned_modules
*
* @author StarRider starrrider@sourceforge.net
* @version $Revision: 1.4.2.9 $
* @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.
*/
/******************
* Initialization *
******************/
define( 'PLUGIN_GUID_DATAECNEON', 'dataecneon' );
global $gLibertySystem;
$pluginParams = array (
'tag' => 'ECNEON',
'auto_activate' => TRUE,
'requires_pair' => FALSE,
'load_function' => 'data_ecneon',
'title' => 'EyeCandy Neon (ECNEON)',
'help_page' => 'DataPluginEyeCandy',
'description' => tra("Apply a Neon Lighting Effect (an age old technique of attracting attention) to a string."),
'help_function' => 'data_ecneon_help',
'syntax' => "{ECNEON text= candy= color1= color2= size= }",
'plugin_type' => DATA_PLUGIN
);{CODE} {DD}
^::__This Tutorial is Not Finished Yet - There is More to Come.__::^
I hope that you've enjoyed my little Tutorial.
The Next Step is the __((Tutorial - Using the PluginSnippet Page))__
Good Luck - [http://www.bitweaver.org/StarRider|StarRider]