Tutorial - Liberty Plugins II

Created by: Lee LaMont Bell Jr., Last modification: 20 Jul 2005 (13:58 UTC)

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:
  1. It would have to have Cross-Browser Support
  2. 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:
  1. Neon Lights Text <http://www.dynamicdrive.com/dynamicindex10/neontext.htm>
  2. 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" }

  1: <?php
  2
// $id: data.example.php,v 1.4.2.9 2005/07/14 09:03:36 starrider Exp $
  
3/**
  4:  * assigned_modules
  5:  *
  6:  * @author   StarRider starrrider@sourceforge.net
  7:  * @version  $Revision: 1.4.2.9 $
  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:  ******************/
 
17define'PLUGIN_GUID_DATAEXAMPLE''dataexample' );
 
18: global $gLibertySystem;
 
19$pluginParams = array ( 'tag' => 'EXAM',
 
20:     'auto_activate' => FALSE,
 
21:     'requires_pair' => FALSE,
 
22:     'load_function' => 'data_example',
 
23:     'title' => 'Example (EXAM)',
 
24:     'help_page' => 'DataPluginExample',
 
25:     'description' => tra("This Plugin is an Example that does nothing. It functions as a template for the creation of new plugins."),
 
26:     'help_function' => 'data_example_help',
 
27:     'syntax' => "{EXAM x1= x2= }",
 
28:     'plugin_type' => DATA_PLUGIN
 29
: );
 
30$gLibertySystem->registerPluginPLUGIN_GUID_DATAEXAMPLE$pluginParams );
 
31$gLibertySystem->registerDataTag$pluginParams['tag'], PLUGIN_GUID_DATAEXAMPLE );
 
32/*****************
 33:  * Help Function *
 34:  *****************/
 
35: function data_example_help() {
 
36:     $help =
 
37:         '<table class="data help">'
 
38:             .'<tr>'
 
39:                 .'<th>' tra"Key" ) . '</th>'
 
40:                 .'<th>' tra"Type" ) . '</th>'
 
41:                 .'<th>' tra"Comments" ) . '</th>'
 
42:             .'</tr>'
 
43:             .'<tr class="odd">'
 
44:                 .'<td>x1</td>'
 
45:                 .'<td>' tra"string") . '<br />' tra("(optional)") . '</td>'
 
46:                 .'<td>' tra"Specifies something / probably to be displayed.")
 
47:                     .'<br />' tra"The Default = <strong>Sorry About That</strong>")
 
48:                 .'</td>'
 
49:             .'</tr>'
 
50:             .'<tr class="even">'
 
51:                 .'<td>XXX</td>'
 
52:                 .'<td>' tra"number") . '<br />' tra("(optional)") . '</td>'
 
53:                 .'<td>' tra"Specifies something / probably to be displayed.")
 
54:                     .'<br />' tra"The Default =") . ' <strong>3</strong> ' tra"Which means - What")
 
55:                 .'</td>'
 
56:             .'</tr>'
 
57:          .'</table>'
 
58:         . tra("Example: ") . "{EXAM x1=' ' x2=5 }<br />"
 
59:         . tra("This will display");
 
60:     return $help;
 
61/****************
 62: * Load Function *
 63:  ****************/
 
64: function data_example($data$params) {
 
65:     extract ($params);
 
66:     $ret ' ';
 
67:     return $ret;
 
68?>
{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: {))ECN((eon } Text {))ECN((eon }. 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" }

<?php
'description' => tra("Apply a Neon Lighting Effect (an age old technique of attracting attention) to a string."),
?>
{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" }

<?php
'syntax' => "{ECNEON text= candy= color1= color2= size= }",
?>
{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" }

  1: <?php
  2
// $id: data.ecneon.php,v 1.4.2.9 2005/07/14 09:03:36 starrider Exp $
  
3/**
  4:  * assigned_modules
  5:  *
  6:  * @author   StarRider starrrider@sourceforge.net
  7:  * @version  $Revision: 1.4.2.9 $
  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:  ******************/
 
17define'PLUGIN_GUID_DATAECNEON''dataecneon' );
 
18: global $gLibertySystem;
 
19$pluginParams = array (
 
20:     'tag' => 'ECNEON',
 
21:     'auto_activate' => TRUE,
 
22:     'requires_pair' => FALSE,
 
23:     'load_function' => 'data_ecneon',
 
24:     'title' => 'EyeCandy Neon (ECNEON)',
 
25:     'help_page' => 'DataPluginEyeCandy',
 
26:     'description' => tra("Apply a Neon Lighting Effect (an age old technique of attracting attention) to a string."),
 
27:     'help_function' => 'data_ecneon_help',
 
28:     'syntax' => "{ECNEON text= candy= color1= color2= size= }",
 
29:     'plugin_type' => DATA_PLUGIN
 30
: );
{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 - StarRider

Related Items

Documentation » Tutorials

Tutorials to help you work out how something in bitweaver is done

  •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •  Anonymous  •  Array  •  Array  •  Array

Documentation » Technical Documentation

Documentation geared towards developers and people who want to learn about the core processes of bitweaver

  •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •