| {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 a Liberty Data Plugins - and a __Lot__ more.
|
| +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 - but in this Tutorial - the word __Plugin__ means a __Liberty Data Plugin__.
|
| +There are many types of Plugins. In this Tutorial - the word __Plugin__ means a __Liberty Data Plugin__. |
|
|
| ! Your Intorduction Seems a Bit Vague!
|
| -I like Feedback! By allowing others to know what I'm doing - and comment on it - I find that many of the uncertanties I feel are addressed and answered __Before__ they can become a __Problem__. That is the reason behind the ((ProposalPage-Plugins)). It is a listing of pages for __Proposed Plugins__. In this Tutorial we are going to create one of those Plugins.
|
| -The __Proposed Plugins__ is named ))EyeCandy(( ))NeonText(( and was originally described on the page ((PluginProposal-EyeCandy NeonText)). Much of that description is repeated in this Tutorial.
|
| +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 Idea
|
| -I wanted a Plugin that would add some __Flair__ to a page. I did a search and found 2 code snippets that would meet my requirements. Those were:
|
| +! 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
|
| -# Unlike most ))JavaScript(( files - Nothing would be added to the Head Section of the page.
|
| +# 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:
|
| +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]>
|
| +# __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 - Liberty Plugins II))__
|
| +The Next Step is the __((Tutorial - Using the PluginSnippet Page))__ |
| Good Luck - [http://www.bitweaver.org/StarRider|StarRider] |