erisco
11-12-2006, 12:50 AM
Breadcrumb script download (http://pack.abstractflow.com/php/breadcrumb/breadcrumb.zip)
It was too big to have posted here!
Usage and Examples
If you have not already, download the breadcrumb script and take a look at the documentation already included in the README. Many of the options left at default will be fine. I will explain the usage of what are likely to be the popular options. The descriptions provided in the download should suffice for the ones I do not talk about, however. To get a feel as how customization works, try calling the function without anything special like this:
<?php
echo breadcrumb();
The echo, or print, is required because breadcrumb() returns a string. It does not output the breadcrumb itself. Now, lets change the separator by changing the separator option.
<?php
echo breadcrumb(array('separator' => '/'));
Now, instead of the double angle bracket, a forward slash appears between each link. By default the link back to the root of your site is called Home. We can change this through the home_link option.
<?php
echo breadcrumb(array('home_link' => 'Index', 'separator' => '/'));
Now the first link appears as Index rather than Home. Note, the order of the options does not matter. We could have also defined the options in an associative array assigned to a variable, and then passed that variable to the function. This will be ideal if you have many options to change.
Often, sites have extensions on the URIs such as /page.php, where .php is the extension. This will produce a link in our breadcrumb that will look like page.php, which is sometimes undesirable. We can have the extension removed by setting the rm_file_ext option to true.
<?php
echo breadcrumb(array('rm_file_ext' => true));
The last, most useful, options are the templates. These specify how each link is outputted. This is useful if you are not necessarily outputting HTML, or you need to add a class to each anchor tag, or whatever the case may be. We have three templates to make use of: the "first_tpl", the "tpl", and the "last_tpl". The first_tpl is applied to the first link in the breadcrumb, which is always your home link. The tpl template is applied to every link after that except for the last link, where the last_tpl is used. Typically, you only care about about the "tpl" template.
<?php
$options = array('tpl' => '<a href="%s" class="breadcrumb_link">%s</a>');
echo breadcrumb($options);
Each template uses string formatting to specify where the link and where the link text are inserted. If you are not familiar with string formatting, check out http://php.net/sprintf. If you need to insert the values in reverse order, or you need to insert each one multiple times, make use of numbered placeholders. The link is argument 1, and the link text is argument 2. Example:
<?php
$options = array('tpl' => '<a href="%1s" onclick="return popup(\'%1s\')">%2s</a>');
echo breadcrumb($options);
Where first_tpl and last_tpl come into use may be with CSS styling. Let's pretend that we want dividers between each breadcrumb link, so we use the border-left css property to achieve this. However, it looks silly to have the first link with a border to the left of it. We can repair this by using first_tpl to specify it has a class named "first_link" that sets the width of the left border to zero.
<?php
$options = array('first_tpl' => '<a href="%s" class="first_link">%s</a>');
echo breadcrumb($options);
And that concludes the mini-tutorial of how to use my breadcrumb function. If you are still confused, please make sure you have read the documentation included in the README. If that does not help, feel free to leave a post below and I will try to answer your question the best that I can.
New features!
Package Update Dec 27, 2008: The documentation is now in a README and the breadcrumb.php file received a few changes. None should break BC other than the new default formatting. If this new default formatting is in the way, please let me know.
Feature Added Dec 27, 2008: You can now provide a callback to format your link text. By default a formatter that replaces hyphens and underscores with spaces and capitalizes all words is included. If you do not want this functionality, pass a callback that simply returns the string unchanged. This new option is called "format_callback". Ex:
<?php
$format = create_function('$s', 'return $s;');
echo breadcrumb(array('format_callback' => $format));
This should address issues raised by pschena.
Where did the old post go???
This breadcrumb function has received a fair bit of popularity and I felt it necessary to address a few issues I have been getting emails about.
This script does not adapt to all breadcrumb schemes.
When I originally wrote the breadcrumb function (the ones that used to be listed below, removed in favour of the new version) I had a fair bit less experience with PHP than I do now. I fixed most of issues with the function's design with my "new breadcrumb script" which was offered via download from my web site as a zip (a link used to be here, still is). However, the primary issue is that it is not practical to create a function to adapt to every breadcrumb scheme. While I offered quite a bit of configuration, there is bound to be case after case where it isn't enough. For simple, run of the mill PHP powered web sites, this function will likely do its job. For more complex applications it is likely to hit some snags. So keep in mind that while I attempted to cover a reasonable amount of possibilities, I did not cover every single one. If you are struggling getting my function configured to work for you, it may just be easier to create your own solution.
One of the biggest hurdles for using my breadcrumb function is if the URI does not actually reflect the breadcrumb you want to generate. The data that should be used to generate the breadcrumb may come from other sources. This is quite common in sites using rewriting or get or post data to pull up pages. For example, consider this:
http://www.example.com/pages.php?page=portfolio
The best breadcrumb you are going to get is something like:
Home >> pages
Which is obviously not what you want. The links will work properly, but the link text is suboptimal. I could add an option that would allow you to specify something like:
array('pages' => 'Portfolio');
But that will only work in situations where the number of hooks given by the URI is equal to the amount of links you really need in the breadcrumb. Let's consider this scheme:
http://www.example.com/view.php?catid=493
However, category 493 is actually a sub category of a sub category of a category. So while we could use the config array to turn
Home >> view
Into...
Home >> LCD Monitors
But we really need...
Home >> Electronics >> Displays >> LCD Monitors
Now we have yet another problem. Not only are there not enough hooks, there is no way to specify the links associated with them. You could specify the needed breadcrumb as an associative array, perhaps, such as:
array('Home' => '/',
'Electronics' => '/view.php?catid=200',
'Displays' => '/view.php?catid=302',
'LCD Monitors' => '/view.php?catid=493');
However, if this were the case, you could easily transverse the array yourself. By the time you solve the issues associated with my limited breadcrumb function, you find yourself not needing of it anyhow. The function is targeted towards a particular use-case where the data needed for the breadcrumb is in the URI. For example, HTMLForums's URI scheme should work fine because of their use of URL rewriting. Our /view.php?catid=xxx example could be fixed with rewriting, and we could have /electronics/displays/lcd-monitors/. The breadcrumb function would work fine with that as well. Such uses of rewriting are also very beneficial to SEO. Not every rewriting scheme is that simple though, and it will not always result in a form that works nicely with my breadcrumb script. Again, it is not practical to adapt to every rewriting scheme either.
That said, if you have any suggestions, improvements, or questions for this script please let me know via private message or a post below. I hope that this script continues to solve many breadcrumb'ing needs.
It was too big to have posted here!
Usage and Examples
If you have not already, download the breadcrumb script and take a look at the documentation already included in the README. Many of the options left at default will be fine. I will explain the usage of what are likely to be the popular options. The descriptions provided in the download should suffice for the ones I do not talk about, however. To get a feel as how customization works, try calling the function without anything special like this:
<?php
echo breadcrumb();
The echo, or print, is required because breadcrumb() returns a string. It does not output the breadcrumb itself. Now, lets change the separator by changing the separator option.
<?php
echo breadcrumb(array('separator' => '/'));
Now, instead of the double angle bracket, a forward slash appears between each link. By default the link back to the root of your site is called Home. We can change this through the home_link option.
<?php
echo breadcrumb(array('home_link' => 'Index', 'separator' => '/'));
Now the first link appears as Index rather than Home. Note, the order of the options does not matter. We could have also defined the options in an associative array assigned to a variable, and then passed that variable to the function. This will be ideal if you have many options to change.
Often, sites have extensions on the URIs such as /page.php, where .php is the extension. This will produce a link in our breadcrumb that will look like page.php, which is sometimes undesirable. We can have the extension removed by setting the rm_file_ext option to true.
<?php
echo breadcrumb(array('rm_file_ext' => true));
The last, most useful, options are the templates. These specify how each link is outputted. This is useful if you are not necessarily outputting HTML, or you need to add a class to each anchor tag, or whatever the case may be. We have three templates to make use of: the "first_tpl", the "tpl", and the "last_tpl". The first_tpl is applied to the first link in the breadcrumb, which is always your home link. The tpl template is applied to every link after that except for the last link, where the last_tpl is used. Typically, you only care about about the "tpl" template.
<?php
$options = array('tpl' => '<a href="%s" class="breadcrumb_link">%s</a>');
echo breadcrumb($options);
Each template uses string formatting to specify where the link and where the link text are inserted. If you are not familiar with string formatting, check out http://php.net/sprintf. If you need to insert the values in reverse order, or you need to insert each one multiple times, make use of numbered placeholders. The link is argument 1, and the link text is argument 2. Example:
<?php
$options = array('tpl' => '<a href="%1s" onclick="return popup(\'%1s\')">%2s</a>');
echo breadcrumb($options);
Where first_tpl and last_tpl come into use may be with CSS styling. Let's pretend that we want dividers between each breadcrumb link, so we use the border-left css property to achieve this. However, it looks silly to have the first link with a border to the left of it. We can repair this by using first_tpl to specify it has a class named "first_link" that sets the width of the left border to zero.
<?php
$options = array('first_tpl' => '<a href="%s" class="first_link">%s</a>');
echo breadcrumb($options);
And that concludes the mini-tutorial of how to use my breadcrumb function. If you are still confused, please make sure you have read the documentation included in the README. If that does not help, feel free to leave a post below and I will try to answer your question the best that I can.
New features!
Package Update Dec 27, 2008: The documentation is now in a README and the breadcrumb.php file received a few changes. None should break BC other than the new default formatting. If this new default formatting is in the way, please let me know.
Feature Added Dec 27, 2008: You can now provide a callback to format your link text. By default a formatter that replaces hyphens and underscores with spaces and capitalizes all words is included. If you do not want this functionality, pass a callback that simply returns the string unchanged. This new option is called "format_callback". Ex:
<?php
$format = create_function('$s', 'return $s;');
echo breadcrumb(array('format_callback' => $format));
This should address issues raised by pschena.
Where did the old post go???
This breadcrumb function has received a fair bit of popularity and I felt it necessary to address a few issues I have been getting emails about.
This script does not adapt to all breadcrumb schemes.
When I originally wrote the breadcrumb function (the ones that used to be listed below, removed in favour of the new version) I had a fair bit less experience with PHP than I do now. I fixed most of issues with the function's design with my "new breadcrumb script" which was offered via download from my web site as a zip (a link used to be here, still is). However, the primary issue is that it is not practical to create a function to adapt to every breadcrumb scheme. While I offered quite a bit of configuration, there is bound to be case after case where it isn't enough. For simple, run of the mill PHP powered web sites, this function will likely do its job. For more complex applications it is likely to hit some snags. So keep in mind that while I attempted to cover a reasonable amount of possibilities, I did not cover every single one. If you are struggling getting my function configured to work for you, it may just be easier to create your own solution.
One of the biggest hurdles for using my breadcrumb function is if the URI does not actually reflect the breadcrumb you want to generate. The data that should be used to generate the breadcrumb may come from other sources. This is quite common in sites using rewriting or get or post data to pull up pages. For example, consider this:
http://www.example.com/pages.php?page=portfolio
The best breadcrumb you are going to get is something like:
Home >> pages
Which is obviously not what you want. The links will work properly, but the link text is suboptimal. I could add an option that would allow you to specify something like:
array('pages' => 'Portfolio');
But that will only work in situations where the number of hooks given by the URI is equal to the amount of links you really need in the breadcrumb. Let's consider this scheme:
http://www.example.com/view.php?catid=493
However, category 493 is actually a sub category of a sub category of a category. So while we could use the config array to turn
Home >> view
Into...
Home >> LCD Monitors
But we really need...
Home >> Electronics >> Displays >> LCD Monitors
Now we have yet another problem. Not only are there not enough hooks, there is no way to specify the links associated with them. You could specify the needed breadcrumb as an associative array, perhaps, such as:
array('Home' => '/',
'Electronics' => '/view.php?catid=200',
'Displays' => '/view.php?catid=302',
'LCD Monitors' => '/view.php?catid=493');
However, if this were the case, you could easily transverse the array yourself. By the time you solve the issues associated with my limited breadcrumb function, you find yourself not needing of it anyhow. The function is targeted towards a particular use-case where the data needed for the breadcrumb is in the URI. For example, HTMLForums's URI scheme should work fine because of their use of URL rewriting. Our /view.php?catid=xxx example could be fixed with rewriting, and we could have /electronics/displays/lcd-monitors/. The breadcrumb function would work fine with that as well. Such uses of rewriting are also very beneficial to SEO. Not every rewriting scheme is that simple though, and it will not always result in a form that works nicely with my breadcrumb script. Again, it is not practical to adapt to every rewriting scheme either.
That said, if you have any suggestions, improvements, or questions for this script please let me know via private message or a post below. I hope that this script continues to solve many breadcrumb'ing needs.