| -{LIB func='libAddAnchor' anchor='PageTop' } {/LIB} {COMMENT }
|
| -1- Please use this format when adding new examples
|
| -2- Every Library Function needs an Example xxx - FunctionName Anchor combination as shown. I will admit that adding an Anchor to a Heading looks strange but on this page it is unavoidable. That is because the Help for { LIB } provides a link to this page with an Anchor - so the Anchor need to be findable - which is not the case when they are inside a Contracted Header.
|
| -!!- Example x - ))libFunctionName(( {LIB func='libAddAnchor' anchor='libFunctionName' } {/LIB}
|
| -Explain what the Example should do
|
| -^~np~{LIB func='' p1= p2= p3= } {/LIB}~/np~^ {LIB func='' p1= p2= p3= } {/LIB}
|
| -Explain what is special about it
|
| -{COMMENT}
|
| -! Introduction
|
| -{maketoc}The Plugin Library contains a lot of small, self-contained functions that are designed to do specific tasks. Some of them are useful to a User. This Plugin provides a Gateway to those functions.
|
| -!- History
|
| -This Plugin came about almost by accident. While working on another Plugin I had a function naming conflict and realized that any function defined in a Plugin is global in nature. Since a large percentage of the code in a Plugin is repetitious - a library of functions could reduce a lot of repetitious code. Further - it could eliminate a lot of time in the development of a new Plugin while increasing their functionality.
|
| -A Library was created and I started converting the Plugin I was working on to use it. A little later - I realized that some of those functions could be useful to a User.
|
| -I decided to create the Plugin to make that happen but the main question was - where was the extra information needed going to come from. There were several options but I wanted maintain the same methodology used everywhere else in bitweaver. By that I mean that nothing could be hardwired. Additions or modifications to the Library had to be automatically included. With Plugins this is done with a registration process that works quite well - but I didn't want all of the overhead that this would require.
|
| -There was also a Page Space problem that had to be addressed. We have a __Lot__ of Plugins and their Help and Parameter Data take a __Lot__ of space. This Plugin would only make matters worse because each Function would need a Description and it’s own set of Parameter Data. I had a discussion about this on IRC with [http://www.bitweaver.org/users/index.php?home=Xing|Xing] a couple of months before but I think he was too busy to fully understand what I was talking about. In any case - I wanted to make some improvements of my own.
|
| -__The Communication Problem__ didn't prove too be as difficult as I thought it would be - but in solving it I found another problem: __Error Testing__. In a Plugin - every Parameter a User enters has to be validated for existence and then converted to the proper type for usage. That isn't a big thing in a Plugin - but doing it in each and every Library Function would have defeated the reason for creating the Library in the first place. Obviously - this Plugin would have to do the Error Testing for every Library Function - which provided the excuse I needed to create several more generic Library Functions.
|
| -I knew how to make the Load Function work - but it was the Help Function that proved to be the most troublesome. I created an Array in the Library that contained all of the necessary information (and it just kept growing). The Library was Global - Right? Not to Arrays! I don't know how many days I spent trying to find a way to access that Array (and I probably wouldn't admit it if I did) - but every approach I found simply didn't work. Upset? __That's putting it mildly!__ I felt like a bloody failure so - __I tried to Cheat!__
|
| -My Load Function basically builds a Library Function call in a string and then executes it. So why couldn't I do that with the Array? What I needed was a way to convert a ))Multi-Dimensional(( Associative Array to a String that could be then be used to recreate the array. It took a lot of time but I got exactly what I wanted - it works beautifully - but there was a problem. Stupid quotation marks! Adding a single quotation mark like this - It's about time - would cause it to crash big time. The worst part was that it always gave the same error message - not very helpful. Scratch that idea! Eventually - I expanded the ))LibertySystem(( a little and added a couple more methods.
|
| -In the process of getting the kinks out of the Help Function (it is very different from the average Plugin) - I solved the Page Space problem by changing the way the Plugin's Help is displayed. Of course that meant modifying the Plugin __((DataPluginPluginHelp|PluginHelp))__ to make it look the same. I don't mind saying that I think they are pretty slick now.
|
| -I thought I was finally finished and was writing this page when I realized something that stopped me cold. Most of the Library Functions accessed by this Plugin are Boxes and the Plugin was using __))requires_pair((__ set to __False!__ That meant that all of the data sent to those boxes had to be placed in parameters. For a Box that would be very limiting. Sounds like a minor inconvenience - Right? __Ha!__ - I thought so at first. I saw an easy solution and made it work - but the more I thought about it - the less I liked it. It required the user to specify where the data was coming from. Clunky! I knew I was going to make the changes to do it right - even if that meant changing everything. It wasn’t quite that bad - but it forced me to rewrite my load function from scratch.
|
| + |
| ! Summary - What Does It Do?
|
| The Plugin Library allows __Selected__ Library Functions to be accessed. The most important is shown in {LIB func='libAddAnchorLink' anchor='libAddAnchor' txt='__Example 1__' } {/LIB} which deals with Anchors and Links to them. At this point - all of the remaining Examples demonstrated different kinds of Boxes.
|
| ! Why Not Just Create Plugins?
|