iLance Plugins
The iLance Auction Platform is an extensive system designed to provide you with a professional level competition system to be hosted on your web server. Well, you already know this because you are reading this. AND – if you are reading this you are wondering : “How do I make changes and customize this system to suit my Web site and MY NEEDS??”.
The Basics
…. REMEMBER THIS RULE ….
Never Never Never Never Never Never times 1,000,000 ever :
Edit core files in iLance!!!
You will find yourself in tears. Literally. Resist the temptation to make a “snip here” and “a snip there”. The reason is that iLance is always evolving, always improving, and adding features and functionality. That means that soon, you will need to upload files to your iLance install and that means soon, you will be over writing all of those customisations that you and your developer worked so hard to make.
BOOO!
The APIHook. Your Friend.
If you open up anyone of the files (main.php for example) in iLance and do a search for “$apihook” you will find something that looks like the following:
($apihook = $ilance->api('main_categories')) ? eval($apihook) : false;
That is an apihook. Get to know it. It is the principle way to inject code into iLance and override anything you like. You can ask to have one put in almost anywhere in the code base by submitting a request to the apihook forum thread @ http://www.ilance.com/forum/showthread.php?t=3008&highlight=apihook .
The “Work Horse” of the apihook system is the “ilance::api”" method. It checks to see if we have specified any code for this api location, which in our example is “main_categories”. If there is code for that location, it is returned and the evaluated. This is exactly the same as placing the code in the script your are trying to modify. We’ll put up an example soon.
Where do we put our custom code?
The next “Friend” you’ll want to become acquainted with is the /functions/xml/ folder of your iLance install. When the $ilance global (the Master of the iLance Universe), is loaded (or constructed) in init.php, one of the first things it does is check the /functions/xml/ to look for files that start with the “plugin_” token (just a geeky word for character pattern) in the file name.
The plugin files have the same standardized structure and as you can see, are all XML files. Aside from the header: UTF-8”?>, the first/root tag is the tag. Makes sense. The next level in is the tag pair, but the most important one that we need is the tag pair and the tag pair. The contents of the tag is the location (in our case “main_categories”) :
main_categories
Now whatever is in the CDATAtag enclosure, inside the php tags will is gathered up by the ilance::api method, returned to the api hook (as a string), where the ‘eval’ statement executes the code as if it were just placed right there, look at the hook again:
($apihook = $ilance->api('main_categories')) ? eval($apihook) : false; line in our code.
I.E.
So, if we put all this together:
What about Templates?
There is no doubt that a fair bit of the customization that you do on your new iLance marketplace will be on the visual presentation.
You can use CSS to change colors, positions, visibility of elements. But what if you want to add some new structure to the page without carving into the actual template? Well, there is an ‘html’ counterpart to the ‘php’ api hook we discussed above.
In the xml plugin file it is used in the exact same way. The only difference is that it looks like this:
My first html hook
]]>
You’ll notice that we have replaced php with html in the surrounding tags.
The hooks are represented in template files with the following pattern {apihook[hook_name]}. The iLance system looks for these at template rendering time. For each of the patterns that it finds in the template file, it will look for a matching html api i.e. hook_name in the plugin xml file. If it finds one, it will replace the entire pattern with what it finds between the <![CDATA[ ]> tag set, and if it doesn’t find one, it removed the pattern from the buffer (this is why you don’t see {apihook[hook_name]} all over the page).
Let’s put all of this together in a real example.
Real Example. “HELLO iLance” Banner
To put all of this stuff together, we are going to produce a simple plugin to place a banner on the top of the front page of our iLance install.
Our Steps:
- build the banner (php)
- assign the banner to a variable (php)
- get the variable to the template (html)
So let’s do the first two steps. Build the banner in PHP.
/** * ASSUME WE HAVE BUILD A BANNER MAKING CLASS IN A FILE CALLED
‘class.bannermaker.inc.php’ AND PLACED THE FILE IN ‘/functions/custom/’ DIRECTORY
*/
$ilance→banner_maker = & construct_object(‘custom.bannermaker’);
$banner = $ilance→banner_maker→get_banner(‘main’);
OK GREAT! But now what?
We need to find the most appropriate place in the code where we would like to add our code.
Since the home page of iLance is generated by main.php, we’ll start there.
HINT: if there are no variables in the address bar after the script file, i.e. no cmd=something then the code block (if/else) you are looking for will be the last in the top level conditionals (At the end of the file).
Close to the end of the file, in the last top level conditional, we see the comment:
// #### MAIN MENU LANDING PAGE #################################################
This must be the place.
Since we have made a commitment to the iLance plugin system, we need to find the $apihook that we want to use. If we examine the code, we see that there are three (3) api hooks that we can choose from.
- ‘main_stats_end’
- ‘main_start’
- ‘main_end’
Which one should we choose? To answer that question, we need to have some knowledge of how iLance renders content: iLance Pseudo-MVC Structure
HINT: Get to know the $pprint_array variable.
This array tells the iLance template system what variables to look for in the templates to render. Open up the main.html template file and look for things that are wrapped in curly braces {}, i.e.{varname}. If the variable name isn’t in the $pprint_array array, it will not show up on our page!
The first opportunity we have to add our new variable to the $pprint_array array is the ‘main_stats_end’ apihook. If we were to use this hook and put our new variable name in the $pprint_array, it will be overwritten when $pprint_array is declared again in the normal code. The ‘main_start’ hook however, comes after the $pprint_array is declared and therefore, our new variable name will get passed to template::pprint method (this is good). So lets use the ‘main_start’ api hook.
When we save this file to our functions/xml directory and refresh the page NOTHING HAPPENS. This is expected. We need to put a template variable holder (remember {variable}}in the template for the iLance template system to find and render.
To do this, we aren’t going to edit the template file directly. Instead, we are going to use the html template hook we talked about above. Since we can see the template we are using is ‘main.html’ from this line:
$ilance->template->fetch('main', 'main.html');
Let’s open it and look for our api hook. For this exercise let’s aim to put the banner right up at top of the main content. Right at the top of the main.html file is an apihook: {apihook[main_template_start]} and looks like a very good candidate. Lets use it:
NOTE: You can put the html hooks into the same file as your php hooks or you can separate them out into there own file and keep them separate.
Notice the {banner} in the code. This is the important part of the code. Because we built the $banner variable in the our main_start apihook in php, and passed the ‘banner’ variable name as part of the $pprint_array to the template system, the template system looks for that pattern in the ‘main.html’ template after the apihooks have been loaded and replaced. At this point our banner should show up like so:
So, lets recap the steps:
The PHP Part
- build the $banner variable in the main_start php apihook in the plugin_banner.xml file.
- add the ‘banner’ variable name to the $pprint_array variable.
The HTML part
- add {banner} into a new html apihook main_template_start in the plugin_banner.xml file .
download the bannertutorial.zip code
That is it. So go ahead and start customizing your iLance Auction powered web site, and keep your system open for upgrades.
