naucon / breadcrumbs
The breadcrumb package helps to integrate a common breadcrumb navigation into a web application. The package includes two components: A breadcrumbs class to add breadcrumb elements and a breadcrumbs helper to render html markup in php or smarty templates.
Installs: 17 073
Dependents: 1
Suggesters: 0
Security: 0
Stars: 11
Watchers: 2
Forks: 2
Open Issues: 0
Requires
- php: >=5.3.0
- naucon/htmlbuilder: ~1.0
- naucon/utility: ~1.1
Requires (Dev)
- phpunit/phpunit: ~4.8
This package is auto-updated.
Last update: 2024-10-29 05:04:36 UTC
README
About
The breadcrumb package helps to integrate a common breadcrumb navigation into a web application. The package includes two components: A breadcrumbs class to add breadcrumb elements and a breadcrumbs helper to render html markup in php or smarty templates.
Features
- add breadcrumbs with a title and a optional URL
- breadcrumb handler (null - default, session)
- breadcrumb helper to render html markup
- smarty plugins for breadcrumb helper
- reverse breadcrumb (fifo, lifo)
- fluent interface ** Breadcrumbs (add) ** BreadcrumbsHelper (setTag, setSeparator, setReverse, setOptions)
Compatibility
- PHP5.3+
Dependencies
- naucon Utility
- naucon Html Elements
Installation
install the latest version via composer
composer require naucon/breadcrumbs
Usage
initialize
To build a breadcrumb menu create a instance of Breadcrumbs
.
use Naucon\Breadcrumbs\Breadcrumbs;
$breadcrumbs = new Breadcrumbs();
Afterwards you can add breadcrumbs to that instance with the method add()
. This the first parameter a title of the breadcrumb must be defined. With the second parameter a URL can be defined (optional).
$breadcrumbs->add('home', '/home/');
$breadcrumbs->add('profile', '/profile/');
$breadcrumbs->add('address');
Another way is with the fluent interface.
$breadcrumbs->add('home', '/home/');
->add('profile', '/profile/');
->add('address');
With foreach
you can iterate through the added breadcrumbs. The value is a instance of Breadcrumb
which have methodes to access breadcrumb title and URL. The breadcrumbs a in the order they are added (FIFO).
foreach ($breadcrumbs as $breadcrumb)
{
if ($breadcrumb->hasUrl()) {
echo '<a href="' . $breadcrumb->getUrl() . '">' . $breadcrumb->getTitle() . '</a>';
} else {
echo $breadcrumb->getTitle();
}
}
The output of the example would be
<a href="/home/">home</a><a href="/profile/">profile</a>address
To reverse the order of the breadcrumb use the method getReverseIterator()
. The breadcrumbs will be interated in the reverse order they are added (LIFO).
$breadcrumbsIterator = $breadcrumbs->getReverseIterator();
foreach ($breadcrumbsIterator as $breadcrumb)
{
if ($breadcrumb->hasUrl()) {
echo '<a href="' . $breadcrumb->getUrl() . '">' . $breadcrumb->getTitle() . '</a>';
} else {
echo $breadcrumb->getTitle();
}
}
The output of the example would be
address<a href="/profile/">profile</a><a href="/home/">home</a>
Breadcrumb Handler
Breadcrumb items are collected in a instance of BreadcrumbCollection
. To read and write into the collection a handler is used.
The default handler is BreadcrumbHandlerNull
which only adds or remove entries to the collection.
In some use cases the breadcrumb entries must persist between page loads. In this cases the BreadcrumbHandlerSession
can be set. The Handler will read and write into the $_SESSION variable.
// start session
session_start();
...
use Naucon\Breadcrumbs\Breadcrumbs;
use Naucon\Breadcrumbs\Handler\BreadcrumbHandlerSession;
$breadcrumbs = new Breadcrumbs();
$breadcrumbs->setBreadcrumbHandler(new BreadcrumbHandlerSession());
...
// add breadcrumb entry
$breadcrumbs->add('Home', '/home/');
...
// close session
session_write_close();
Make sure that you started and close session befor and after you use the breadcrumb.
Breadcrumb helper
With the breadcrumb helper a instance of Breadcrumbs
can be rendered in HTML Markup.
To use the helper create a instance of BreadcrumbsHelper
and give the constructor a instance of Breadcrumbs
.
use Naucon\Breadcrumbs\Helper\BreadcrumbsHelper;
$breadcrumbsHelper = new BreadcrumbsHelper($breadcrumbs);
With the method render()
the html markup will be generated an returned.
echo $breadcrumbsHelper->render();
// <a href="/home/">home</a><a href="/profile/">profile</a>address
With the method setSeparator()
a separator between the breadcrumbs can be defined.
$breadcrumbsHelper->setSeparator(' / ');
echo $breadcrumbsHelper->render();
// <a href="/home/">home</a> / <a href="/profile/">profile</a> / address
With the method setReverse()
the order of the breadcrumbs can be reversed.
$breadcrumbsHelper->setReversed(); // or $breadcrumbsHelper->setReversed(true);
echo $breadcrumbsHelper->render();
// address / <a href="/profile/">profile</a> / <a href="/home/">home</a>
With the method setSkipLinks()
links will be skipped in render.
$breadcrumbsHelper->setSkipLinks(); // or $breadcrumbsHelper->setSkipLinks(true);
echo $breadcrumbsHelper->render();
// home / profile / home
With the method setTag()
a html element can be set surround the breadcrumb. The following html element are supported: span, div, li, ul, ol
Example with span
element:
$breadcrumbsHelper->setTag('span');
$breadcrumbsHelper->setSeparator(' / ');
echo $breadcrumbsHelper->render();
// <span><a href="/home/">home</a></span> / <span><a href="/profile/">profile</a></span> / <span>address</span>
Example with div
element:
$breadcrumbsHelper->setTag('div');
$breadcrumbsHelper->setSeparator(' / ');
echo $breadcrumbsHelper->render();
// <div><a href="/home/">home</a></div> / <div><a href="/profile/">profile</a></div> / <div>address</div>
Example with li
element:
$breadcrumbsHelper->setTag('div');
$breadcrumbsHelper->setSeparator(' / ');
echo $breadcrumbsHelper->render();
// <li><a href="/home/">home</a></li> / <li><a href="/profile/">profile</a></li> / <li>address</li>
When using the tag ul
or ol
also the attributes id
, class
, style
can be defined.
Example with ul
element:
$breadcrumbsHelper->setTag('ul');
$breadcrumbsHelper->setOptions(array('id' => 'breadcrumb', 'class' => 'breadcrumbs'));
echo $breadcrumbsHelper->render();
// <ul id="breadcrumb" class="breadcrumbs"><li><a href="/home/">home</a></li><li><a href="/profile/">profile</a></li><li>address</li></ul>
Example with ol
element:
$breadcrumbsHelper->setTag('ol');
$breadcrumbsHelper->setOptions(array('id' => 'breadcrumb', 'class' => 'breadcrumbs'));
echo $breadcrumbsHelper->render();
// <ol id="breadcrumb" class="breadcrumbs"><li><a href="/home/">home</a></li><li><a href="/profile/">profile</a></li><li>address</li></ol>
Breadcrumb Smarty Plugin
When using the Smarty Template Engine the breadcrumb helper can be integrated with a smarty plugin.
First have hook up the smarty plugins to smarty.
$smartyObject->plugins_dir[] = PATH_LIBRARY . 'vendor/naucon/Breadcrumbs/SmartyPlugins';
Next assign the instance of Breadcrumbs
class to smarty.
$smarty->assign('breadcrumbs', $breadcrumbs);
Then add the plugin to the template.
{ncbreadcrumbs from=$breadcrumbs tag='span' separator=' / '}
or
{ncbreadcrumbs from=$breadcrumbs tag='div' separator=' / '}
or
{ncbreadcrumbs from=$breadcrumbs tag='ul' id='breadcrumb' class='breadcrumbs'}
or
{ncbreadcrumbs from=$breadcrumbs tag='ol' id='breadcrumb' class='breadcrumbs'}
or
{ncbreadcrumbs from=$breadcrumbs tag='ol' id='breadcrumb' class='breadcrumbs' reverse=true}
or
{ncbreadcrumbs from=$breadcrumbs separator=' / ' skip-links=true}
The smarty plugin supports the following parameters
- from = assigned breadcrumbs variable (MUST)
- tag = define html tag surrounding the breadcrumb elements (optional)
- separator = define separator between the breadcrumb elements (optional)
- reverse = define the order that the breadcrumbs is iterated (optional)
- skip-links = links will not be rendered (optional)
- id = define a id attribute on a surrounding html element like ul and ol but not div, span or li (optional)
- class = define a id attribute on a surrounding html element like ul and ol but not div, span or li (optional)
- style = define a id attribute on a surrounding html element like ul and ol but not div, span or li (optional)