README

关于

导航路径插件帮助将通用的导航路径集成到Web应用程序中。该插件包含两个组件：一个用于添加导航路径元素的导航路径类，以及一个用于在PHP或Smarty模板中渲染HTML标记的导航路径助手。

功能

• 添加带有标题和可选URL的导航路径
• 导航路径处理器（null - 默认，会话）
• 渲染HTML标记的导航路径助手
• 导航路径助手Smarty插件
• 反转导航路径（FIFO，LIFO）
• 流畅接口 ** 导航路径（添加）** 导航路径助手（setTag、setSeparator、setReverse、setOptions）

兼容性

• PHP5.3+

依赖

• naucon工具
• naucon HTML元素

安装

使用composer安装最新版本

composer require naucon/breadcrumbs

用法

初始化

要创建导航路径菜单，请创建一个Breadcrumbs实例。

use Naucon\Breadcrumbs\Breadcrumbs;
$breadcrumbs = new Breadcrumbs();

之后，您可以使用add()方法向该实例添加导航路径。第一个参数必须定义导航路径的标题。第二个参数可以定义一个URL（可选）。

$breadcrumbs->add('home', '/home/');
$breadcrumbs->add('profile', '/profile/');
$breadcrumbs->add('address');

另一种方法是使用流畅接口。

$breadcrumbs->add('home', '/home/');
    ->add('profile', '/profile/');
    ->add('address');

使用foreach可以遍历添加的导航路径。值是一个Breadcrumb实例，该实例具有访问导航路径标题和URL的方法。导航路径按照添加的顺序排列（FIFO）。

foreach ($breadcrumbs as $breadcrumb)
{
    if ($breadcrumb->hasUrl()) {
        echo '<a href="' . $breadcrumb->getUrl() . '">' . $breadcrumb->getTitle() . '</a>';
    } else {
        echo $breadcrumb->getTitle();
    }
}

示例输出的结果将是

<a href="/home/">home</a><a href="/profile/">profile</a>address

要反转导航路径的顺序，请使用getReverseIterator()方法。导航路径将按照添加的相反顺序迭代（LIFO）。

$breadcrumbsIterator = $breadcrumbs->getReverseIterator();
foreach ($breadcrumbsIterator as $breadcrumb)
{
    if ($breadcrumb->hasUrl()) {
        echo '<a href="' . $breadcrumb->getUrl() . '">' . $breadcrumb->getTitle() . '</a>';
    } else {
        echo $breadcrumb->getTitle();
    }
}

示例输出的结果将是

address<a href="/profile/">profile</a><a href="/home/">home</a>

导航路径处理器

导航路径项收集在一个BreadcrumbCollection实例中。要读取和写入集合，请使用处理器。默认处理器是BreadcrumbHandlerNull，它只会向集合中添加或删除条目。

在某些情况下，导航路径条目必须在页面加载之间持久化。在这种情况下，可以设置BreadcrumbHandlerSession。处理器将读取和写入到$_SESSION变量。

// 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();

确保在使用导航路径之前和之后启动和关闭会话。

导航路径助手

使用导航路径助手可以在HTML标记中渲染Breadcrumbs实例。

要使用助手，请创建一个BreadcrumbsHelper实例，并将Breadcrumbs实例传递给构造函数。

use Naucon\Breadcrumbs\Helper\BreadcrumbsHelper;
$breadcrumbsHelper = new BreadcrumbsHelper($breadcrumbs);

使用render()方法将生成并返回HTML标记。

echo $breadcrumbsHelper->render();

// <a href="/home/">home</a><a href="/profile/">profile</a>address

使用setSeparator()方法可以定义导航路径之间的分隔符。

$breadcrumbsHelper->setSeparator(' / ');
echo $breadcrumbsHelper->render();

// <a href="/home/">home</a> / <a href="/profile/">profile</a> / address

使用setReverse()方法可以反转导航路径的顺序。

$breadcrumbsHelper->setReversed(); // or $breadcrumbsHelper->setReversed(true);
echo $breadcrumbsHelper->render();

// address / <a href="/profile/">profile</a> / <a href="/home/">home</a>

使用setSkipLinks()方法可以跳过渲染中的链接。

$breadcrumbsHelper->setSkipLinks(); // or $breadcrumbsHelper->setSkipLinks(true);
echo $breadcrumbsHelper->render();

// home / profile / home

使用setTag()方法可以将HTML元素设置为围绕导航路径。支持以下HTML元素：span、div、li、ul、ol

使用span元素的示例

$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>

使用div元素的示例

$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>

使用li元素的示例

$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>

当使用ul或ol时，还可以定义id、class、style属性。

使用ul元素的示例

$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>

使用ol元素的示例

$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>

导航路径Smarty插件

当使用Smarty模板引擎时，可以通过smarty插件集成导航路径助手。

首先，将smarty插件连接到smarty。

$smartyObject->plugins_dir[] = PATH_LIBRARY . 'vendor/naucon/Breadcrumbs/SmartyPlugins';

然后，将Breadcrumbs类的实例分配给smarty。

$smarty->assign('breadcrumbs', $breadcrumbs);

然后，将插件添加到模板中。

{ncbreadcrumbs from=$breadcrumbs tag='span' separator=' / '}

或者

{ncbreadcrumbs from=$breadcrumbs tag='div' separator=' / '}

或者

{ncbreadcrumbs from=$breadcrumbs tag='ul' id='breadcrumb' class='breadcrumbs'}

或者

{ncbreadcrumbs from=$breadcrumbs tag='ol' id='breadcrumb' class='breadcrumbs'}

或者

{ncbreadcrumbs from=$breadcrumbs tag='ol' id='breadcrumb' class='breadcrumbs' reverse=true}

或者

{ncbreadcrumbs from=$breadcrumbs separator=' / ' skip-links=true}

smarty插件支持以下参数

• from = 分配的面包屑变量（必须）
• tag = 定义围绕面包屑元素的HTML标签（可选）
• separator = 定义面包屑元素之间的分隔符（可选）
• reverse = 定义遍历面包屑的顺序（可选）
• skip-links = 链接将不会渲染（可选）
• id = 在ul和ol等周围HTML元素上定义一个id属性，但不能是div、span或li（可选）
• class = 在ul和ol等周围HTML元素上定义一个id属性，但不能是div、span或li（可选）
• style = 在ul和ol等周围HTML元素上定义一个id属性，但不能是div、span或li（可选）