|
|
|
This document comprehensively outlines the instructions for the use of phpBanners, a banner insertion script written by Jeremy Jones and Nigel Swinson.
phpBanners inserts banners (blocks of <html> code) into a target file and therefore allows a centrally held banner to be inserted into multiple files. This means that a single change to a banners file will be reflected site wide and allows the useful and efficient use of code without having the repetition of content in multiple pages.
Very little PHP knowledge is required to setup the system, or insert banners. For more advanced functions, an XML file is used for configuration purposes.
phpBanners, related files and the most recent version of this file will be found on the phpBanners homepage: scripts.carrubbers.org/scripts/php/banners/
Banners, like headers and footers are often composed of static code which is spread across multiple files. The header and footers are often cut & pasted from page to page and soon, any changes that need to be made to a 'banner' then require mirroring thorughout 10, 20 or more pages.
Instead of using this cut & paste method of banner creation, phpBanners allows a simple but very effective method of inserting banners which are held in a central file. This means that the code that lives at the top and bottom of your web page doesn't live in each page, but centrally in banners file. If you ever need to change the banner, make one change and all the pages refect the alteration.
phpBanners allows the use of more than one type of banner within a site, and there are some quite advanced functions that can be used to manipulate banners. It is possible to specify what banners to insert, what information to include within them and even to specify how many different banners to insert.
There will be several terms that will be used throughout this document. To ensure that misunderstanding is kept to a minimum, it is important to point out some specific definitions:
A list of files which will be referred to in this document, the recommended directory they should reside in and a summary of what they do:
A banner is simply a section of code, usually <html>, which appears in multiple files. It must be stated that 'banners' does not refer to advertising banners, but to blocks of code which produce a header or footer, like, for example, those on this page.
With the use of this script, you will be able to insert a banner into multiple files using simple PHP which will always be the same, no matter what! The banners are inserted by bannercontrol but are called by the use of code which lives in the target file. Three banners can be inseted into each file - the HeadBanner, TopBanner and BottomBanner - for a comprehensive explaination of what these are, see the getting started section. The three banners will hold the code that will largely defines the page.
The beauty of having centralised code, is that one change to the banners.php file will update all the pages that use that banner. The work of site redesign or expansion is greatly reduced because the code is held in one place.
You will need to ensure that your domain host has PHP running on their servers. You will also need to have the phpXPath and phpXdb classes uploaded. The classes are distributed with phpBanners, but to ensure that there are not more recent versions you should check their homepages.
Upload the files to their respective directories - if you alter the directory tree, be sure to mirror your changes in the code. If you're not sure how to make the alterations, just use the default directory structure.
NB. You may find that a refined version of phpXPath is available from the phpXdb homepage - it will be optimised for use with phpXdb and is the best file to use. Once you have uploaded the three control files, use the included banner insertion test page to make sure that everything is working properly.
There are three types of banners:
Four lines of simple PHP code included in the target file are used to insert a banner.
The banner insertion code
<?
require_once("scripts/php/banners/bannercontrol.php");
DrawHeadBanner(__FILE__);
?>
To insert a TopBanner or BottomBanner, line three is altered:
These are the only three alternatives. In any one file, there could only ever be 12 lines of code to call the three sets of banners.
Your file might look something like this:
An example of what the target file might look like
<html>
<head>
<?
require_once("scripts/php/banners/bannercontrol.php");
DrawHeadBanner(__FILE__);
?>
<title>an example page</title>
</head>
<body>
<?
require_once("scripts/php/banners/bannercontrol.php");
DrawTopBanner(__FILE__);
?>
THE CONTENT OF THE PAGE IS INSERTED HERE
<?
require_once("scripts/php/banners/bannercontrol.php");
DrawBottomBanner(__FILE__);
?>
</body>
</html>
The file must be saved as a .php file OR, you must configure the server to process .html and .htm files with the PHP engine. The rest of the page does not change and it may be that the only PHP used in your site is involved with banner calls.
The alteration of how .html and .htm files are processed can be acheived using .htaccess files.
Banners are held in banners.php files. In any domain there must be at least one banners.php file and it must live at the root. The banners.php file must have at least three functions within it: HeadBanner, TopBanner and BottomBanner.
The basic structure of the banners.php file is illustrated below:
An example banners.php file
<? function HeadBanner() { ?> <p>this is normal HTML code</p> <p>head information is placed here.</p> <? } function TopBanner() { ?> <p>This is the TOP banner.</p> <p>Again we are within HTML mode</p> <p>Javascript can be used.</p> <p>Applets and flash, tables and forms are all used like normal!</p> <? } function BottomBanner() { ?> <p>This is the Bottom banner</p> <p>Same again, normal HTML</p> <? } ?>
When the DrawHeadBanner(__FILE__) function call is made, bannercontrol inserts the code which is held within HeadBanner function. This may be PHP or HTML or a mixture of both. Anything you would usually do in a .html or .htm file will happily live in a banners file. The html lives between the <? and ?> signs.
The same is true for DrawTopBanner and DrawBottomBanner, where the code within TopBanner and BottomBanner functions are inserted respectively.
The end result is something like this:
The final HTML output
<html> <head> <p>this is normal HTML code</p> <p>head information is placed here.</p> <title>an example page</title> </head> <body> <p>This is the TOP banner.</p> <p>Again we are within HTML mode</p> <p>Javascript can be used.</p> <p>Applets and flash, tables and forms are all used like normal!</p> THE CONTENT OF THE PAGE IS INSERTED HERE <p>This is the Bottom banner</p> <p>Same again, normal HTML</p> </body> </html>
The phpBanners script allows the use of more than one banners file in the domain. This means that the banners can be replaced on a directory basis. For example if only one banners.php file exists, and this is at the root level, all calls for banners insertion will have banners inserted from this file.
If a banners.php was placed in another directory (/directory/banners.php) all files within this directory would display banners from this file, as would any files in directories within /directory/
When you call DrawHeadFunction(__FILE__), bannercontrol makes a list of all the banners.php files between the directory of the target file and the document root. bannercontrol then checks through the list of banners.php files in reverse order starting with the file nearest the directory of the target file.
It checks the banners.php file to see whether or not there is a valid function to use for banner insertion. If there is a valid function, the banner is inserted. If there is no valid function, the next banners.php file is checked. This continues until the last file is checked, which must be the banners.php file at the document root. This should always have valid function names and therefore default banners would be inserted.
What is a valid function name? All the functions that hold the banner information have to have different names. To this end, a nomenclature has been adopted which allows predetermined names to be allocated to functions. The directory names from the document root are capitalised and appended to each other and form the prefix for the function name. The type of banner is then added - HeadBanner, TopBanner or BottomBanner, as required.
Examples of how to construct valid function names are given below:
So after searching for all the banners.php files between the directory of the target file and the document root and then finding a valid function name, the banner code is inserted into the target file.
It may be the case that in a particular directory, you only want to alter the BottomBanner. The solution is simple - create the valid function name for the BottomBanner and write the code. Save the file, but do not include the HeadBanner or TopBanner functions. When bannercontrol looks for the HeadBanner in this file, because it can't find the valid function name, it moves onto the next banners.php file in the tree - and so on. With the BottomBanner - providing the function is named correctly, bannercontrol will find the function and insert the banner.
So, the script allows the overwriting of one, two or all three banners, on a directory by directory basis.
phpBanners has some advanced features which work with the inclusion of an XML file. Using this file in any directory allows the following to be acheived:
An XML file is a structured source of markup data. phpBanners uses the XML file to hold data which it uses to decide what banners to insert. An example phpBanners XML file is shown below.
A sample XML file - fileinfo.xml
<xml version="1.0"> <XmlDatabase> <PageInfo> <FileInfo name="index"> <heading1>phpBanners</heading1> <HeadBanner>_Default</HeadBanner> <TopBanner>_Default</TopBanner> <BottomBanner>_Default</BottomBanner> </FileInfo> </PageInfo> </XmlDatabase>
It is very important that every XML file conforms to XML standards and to the style that bannercontrol will expect. If the file is poorly formed XML, you will be met with an error - if you don't create the XML file in the style bannercontrol is expecting, it will ignore it and insert default banners.
The XML file will contain the following components, which are based on those you would find in a standard databse:
The XML file is named fileinfo.xml and holds the information for banner insertion in files which live in the same directory as it does. When a target file calls bannercontrol, the directory is checked to see whether an XML file exists. If it does, and it is well formed, and it conforms to the style that bannercontrol accepts, and it has a record that matches the file name, the information held within the record is used to define what banners are inserted and what file information is included in the banner. If any of these tests fail, the default banner specific to the type of banner called is inserted.
Each record in fileinfo.xml is specific for a particular file which lives in its directory. The information contained within the record is held within fields which are used to identify how the data should be used. There are three fields which are used for the insertion of banners - if they exist, the information they hold is used for banner insertion; if they do not exist, bannercontrol will insert default banners.
The field names are, not surprisingly, named HeadBanner, TopBanner and BottomBanner and the information they hold must adhere to strict form - if it does not, bannercontrol will ignore it and insert default banners. The information may call banners using preset, file specific or function specific declarations. For more information see the appropriate section.
phpBanners also allows the use of banners which are defined in files other than banners.php. Use of other files is simple: just insert the files name (including the directory it lives in - from the document root) in the fileinfo.xml file.
Example: you want to insert a banner held within the special.php file which lives in the dir/special/ directory - the fileinfo.xml file might look like this:
A file specific declaration - fileinfo.xml
<?xml version="1.0"?> <XmlDatabase> <PageInfo> <FileInfo name="target"> <HeadBanner>dir/special/special.php</HeadBanner> <TopBanner>_Default</TopBanner> <BottomBanner>_Default</BottomBanner> </FileInfo> </PageInfo> </XmlDatabase>
It is important to note two things about the declaration dir/special/special.php:
When using a file name declaration, bannercontrol will generate a default function name to look for in the file. For more information see the section which deals with what valid function names are.
Using this declaration, bannercontrol will look for the function called DirSpecialHeadBanner in the file special.php within the directory dir/special/. If it does not find it, the _Default banners are inserted
If you do not want to use the default funciton names, then phpBanners allows the declaration of which function to use for banner insertion.
When declaring a specific function to use, you must also declare what file the function is held in. The file name can take two forms:
When making a declaration about what function to use, the declaration has two parts - the file and the function - and it takes the form 'file,function'
A function specific declaration - fileinfo.xml
<?xml version="1.0"?> <XmlDatabase> <PageInfo> <FileInfo name="target"> <HeadBanner>dir/special/special.php,OtherHeadBanner</HeadBanner> <TopBanner>_Default</TopBanner> <BottomBanner>_Default,AnotherBanner</BottomBanner> </FileInfo> </PageInfo> </XmlDatabase>
In this example there are three different declaration types:
Information that is file specific can be included in a banner. This information does not reside within the target file because, as was stated at the start of the file, there are only ever four lines of code in the target file which are used to insert a banner.
The information that you need to include in the banner is saved in the XML record which refers to the file. The data is placed within a field which is named anything apart from HeadBanner, TopBanner and BottomBanner (the tags and content has to adhere to XML rules).
The the first example XML file above, there is a field [heading1]phpBanners[/heading1] - this is information other than that which defines banners and is therefore treated as file specific information for insertion into a banner.
This data is accessable from the banners.php file by slightly altering the code so that the banner functions are called with a variable - this will be an array of relavent banner information which will include the file specific information included in the xml file.
The same function call as previously defined
function HeadBanner() {
?>
<p>this is normal HTML code</p>
<p>head information is placed here.</p>
<?
}
Function call for inclusion of file specific information
function HeadBanner($aResults) {
?>
<p>this is normal HTML code</p>
<p>head information is placed here.</p>
<p>Now we can insert file specific information!</p>
<?
}
The only thing that changes is the inclusion of $aResults between the parentheses () at the function declaration. The insertion of the information from the XML file requires the use of some simple PHP.
To insert the heading1 from the previous XML example, we might do this:
Inserting file specific information
function TopBanner($aResults) {
?>
<p>this is normal HTML code</p>
<p>Now we can insert file specific information!</p>
<p>Title: <?=$aResults[FileDeclaration][heading1]?></p>
<p></p>
<?
}
This banner would produce this output to screen:
this is normal HTML code Now we can insert file specific information! Title: phpBanners
In this example, <? breaks into PHP mode, = tells the PHP engine to echo the variable which follows it to the screen, $aResults[FileDeclaration][heading1] is the variable and ?> breaks back out of PHP mode and returns to HTML.
$aResults is a multidimentional array. One dimention, [FileDeclaration], contains a list of all the file specific information that was stored in the XML record - hence $aResults[FileDeclaration] which is itself an associative array of [name] => value pairs.
So, $aResults[FileDeclaration][heading1] contains content of the [heading1] field in the fileinfo.xml file.
Any information which is included within a heading in the fileinfo.xml file can be included within any banner by including the ($aResults) in the function declaration and using <?=$aResults[FileDeclaration][...] ?> where you want to include the information.
phpBanners also allows the declaration of directory defaults. This allows all the files within a directory to use a specified banner, but also allows the overriding of the directory defaults by file specific banners. It also means that all the files can have a directory specific information included in a banner. This can, like the directory banners, be overridden by file specific information.
Creating directory defaults is much like creating a file specific set of banners or information. This time though, rather than creating a record with a name="filename=" attribute, the record is created with name="_default". The fields within the records are the same as for a file specific record, as are the declarations.
When bannercontrol is called, it finds the directory of the target file. It opens the fileinfo.xml file is there is one. It searches for file specific declarations, if there are none for the banner in question, directory default declarations are sought. If none of these exist, bannercontrol inserts the default banner.
So, directory defaults are easy to set up and are easily overridden when a page needs to look a little different.
Another phpBanner function which is very useful is the ability to insert more than one banner at a time. This page, for example, has two TopBanners - it's standard header and the 'this page is not finnished yet' header.
The syntax for insertion of multiple banners is very similar to that of single banner insertion. Declarations for banner insertion are separated by a colon (:). So bannercontrol reads the declaration, splits it up when it sees a colon, reads the first part of the declaration and inserts the banner if it can, and then continues onward, breaking up the declaration every time is meets a colon.
This essentially means that a page could have an infinite number of banners, providing that the declarations are valid. If the declaration of a particular banner is invalid, no banner is inserted. If at the end of looking for a number of banners, no valid banner has been inserted, the default banner is added to the page.
Some examples:
Multiple banner declarations
<?xml version="1.0"?> <XmlDatabase> <PageInfo> <FileInfo name="target"> <HeadBanner>_Default:dir/anything/ban.php,DoesntExist:_SiteDefault</HeadBanner> <TopBanner>_Default</TopBanner> <BottomBanner>NoSuchFile.php:TryAgain.php,NoSuchFunction</BottomBanner> </FileInfo> </PageInfo> </XmlDatabase>
The example above has two examples of multiple banner insertion and one default declaration
Multiple banners are simple to define - separate banner calls are separated by a colon and if no valid banner can be found, defaults are inserted.
If you want to find out more about PHP use some of the links below:
There is an online manual at both www.php.net and www.zend.com. Other sites will contain repositories of examples and daily tips - there are loads of links from the sites I have mentioned above.
Need more information about what XML is and how you have lived without it? www.xml.com has all the information you're likely to need, or the links to the site that will have it.
phpBanners uses two classes to manipulate the XML files which are used for configuration purposes.
Both - PHP and XML - are two of the most powerful technologies, which may influence the future of the world wide web and the software development for online applications.
PHP is already available on nearly every web server and has become a new standard in web programming languages. XML is a way of saving data to use them on a lot of different system without any problem, enhancing the possibilities of communication between every kind of application. Therefore these two languages seem to collaborate in a perfect way.
But the power of XML can only be used in PHP if a set of so-called "extensions" is set up on the web server. Unfortunately nearly all hosting companies - even mass hosters - don't think it's necessary to make this useful piece of software available to PHP developers. Therefore XML is not very often used, even though it may simplify a lot of boring and difficult tasks.
phpXpath (XPath.class) is a php class for searching an XML document using XPath, and making modifications using a DOM style API. It does not require the DOM XML PHP library and is the new home and name for the phpxml project.
A PHP class for handling XML databases. An XML database contains one or more tables that can each contain records. Suitable for small-medium databases, where SQL database hosting is not viable. Does not require DOM. Built upon the Php.XPath class.
The phpXdb homepage has more information about the class and latest release versions. The latest version of the phpXPath is also available from this site and will be optimised for phpXdb.
Included in the download files are a test page and banners.php file which can be used to test whether you have set up the file correctly. Upload the three files, xml.php, xmldb.php and bannercontrol.php to their recommended directories and place the test file and the banners.php file at the document root. Upload all the files and try to load the test page - if you get an output which has content which mentions HeadBanner, TopBanner and BottomBanner, everything should be working correctly.
While using the script, it is possible to turn on debugging mode through one of two methods:
Last updated: 17 April 2008 02:15:13.
© 2008 Carrubbers Christian Centre | Registered Charity No. SC011455