On this page
View Helpers
Links
The links()
helper is used for rendering HTML LINK
elements. Links are used for describing
document relationships of the currently active page. Read more about links and
link types at:
There are two types of relations; forward and reverse, indicated by the kewyords
rel
and rev
. Most methods in the helper will take a $rel
param, which must
be either rel
or rev
. Most methods also take a $type
param, which is used
for specifying the link type (e.g. alternate
, start
, next
, prev
,
chapter
, etc).
Managing Relationships within the Helper
Relationships can be added to page objects manually, or found by traversing the
container registered in the helper. The method findRelation($page, $rel,
$type)
will first try to find the given $rel
of $type
from the $page
by
calling $page>findRel($type)
or $page>findRel($type)
. If the $page
has a
relation that can be converted to a page instance, that relation will be used.
If the $page
instance doesn't have the specified $type
, the helper will look
for a method in the helper named search$rel$type
(e.g. searchRelNext()
or
searchRevAlternate()
). If such a method exists, it will be used for
determining the $page
's relation by traversing the container.
Not all relations can be determined by traversing the container. These are the relations that will be found by searching:
searchRelStart()
, forwardstart
relation: the first page in the container.searchRelNext()
, forwardnext
relation; finds the next page in the container, i.e. the page after the active page.searchRelPrev()
, forwardprev
relation; finds the previous page, i.e. the page before the active page.searchRelChapter()
, forwardchapter
relations; finds all pages on level 0 except thestart
relation or the active page if it's on level 0.searchRelSection()
, forwardsection
relations; finds all child pages of the active page if the active page is on level 0 (achapter
).searchRelSubsection()
, forwardsubsection
relations; finds all child pages of the active page if the active pages is on level 1 (asection
).searchRevSection()
, reversesection
relation; finds the parent of the active page if the active page is on level 1 (asection
).searchRevSubsection()
, reversesubsection
relation; finds the parent of the active page if the active page is on level 2 (asubsection
).
Allowed relation types
When looking for relations in the page instance (
$page->getRel($type)
or$page->getRev($type)
), the helper accepts the values of typestring
,array
,Traversable
, orLaminas\Navigation\Page\AbstractPage
:
AbstractPage
instances are used directly.- If a string is found, it will be converted to a
Laminas\Navigation\Page\Uri
.- If an array or
Traversable
is found, it will be converted to one or several page instances. If the first key is numeric, it will be considered to contain several pages, and each element will be passed to the page factory. If the first key is not numeric, the value will be passed to the page factory directly, and a single page will be returned.
The helper also supports magic methods for finding relations. E.g. to find
forward alternate relations, call $helper->findRelAlternate($page)
, and to
find reverse section relations, call $helper->findRevSection($page)
. Those
calls correspond to $helper->findRelation($page, 'rel', 'alternate')
and
$helper->findRelation($page, 'rev', 'section')
, respectively.
To customize which relations should be rendered, the helper uses a render flag.
The render flag is an integer value, and will be used in a
bitwise and (&
) operation against
the helper's render constants to determine if the relation that belongs to the
render constant should be rendered.
See the example below for more information.
The Links
helper defines the following constants:
Laminas\View\Helper\Navigation\Links::RENDER_ALTERNATE
Laminas\View\Helper\Navigation\Links::RENDER_STYLESHEET
Laminas\View\Helper\Navigation\Links::RENDER_START
Laminas\View\Helper\Navigation\Links::RENDER_NEXT
Laminas\View\Helper\Navigation\Links::RENDER_PREV
Laminas\View\Helper\Navigation\Links::RENDER_CONTENTS
Laminas\View\Helper\Navigation\Links::RENDER_INDEX
Laminas\View\Helper\Navigation\Links::RENDER_GLOSSARY
Laminas\View\Helper\Navigation\Links::RENDER_COPYRIGHT
Laminas\View\Helper\Navigation\Links::RENDER_CHAPTER
Laminas\View\Helper\Navigation\Links::RENDER_SECTION
Laminas\View\Helper\Navigation\Links::RENDER_SUBSECTION
Laminas\View\Helper\Navigation\Links::RENDER_APPENDIX
Laminas\View\Helper\Navigation\Links::RENDER_HELP
Laminas\View\Helper\Navigation\Links::RENDER_BOOKMARK
Laminas\View\Helper\Navigation\Links::RENDER_CUSTOM
Laminas\View\Helper\Navigation\Links::RENDER_ALL
The constants from RENDER_ALTERNATE
to RENDER_BOOKMARK
denote standard HTML
link types. RENDER_CUSTOM
denotes non-standard relations specified in pages.
RENDER_ALL
denotes standard and non-standard relations.
Methods in the links helper:
Method signature | Description |
---|---|
getRenderFlag() : int |
Retrieves the render flag; default is RENDER_ALL . |
setRenderFlag(int $flag) : self |
Set the render flag; see examples below. |
findAllRelations(AbstractPage $page, int $flag = null) : array |
Finds all relations of all types for a given page. |
findRelation(AbstractPage $page, string $rel, string $type) : AbstractPage|array|null |
Finds all relations of a given type from a given page. |
searchRel*(AbstractPage $page) : AbstractPage|null |
Traverses a container to find forward relations to the Start page, the Next page, the Prev ious page, Chapter s, Section s, and Subsection s. |
searchRev*(AbstractPage $page) : AbstractPage|null |
Traverses a container to find reverse relations to Section s or Subsection s. |
renderLink(AbstractPage $page, string $attrib, string $relation) : string |
Renders a single link element. |
Basic usage
Specify relations in pages
This example shows how to specify relations in pages.
use Laminas\Config\Config;
use Laminas\Navigation\Navigation;
use Laminas\Navigation\Page\AbstractPage;
$container = new Navigation([
[
'label' => 'Relations using strings',
'rel' => [
'alternate' => 'http://www.example.org/',
],
'rev' => [
'alternate' => 'http://www.example.net/',
],
],
[
'label' => 'Relations using arrays',
'rel' => [
'alternate' => [
'label' => 'Example.org',
'uri' => 'http://www.example.org/',
],
],
],
[
'label' => 'Relations using configs',
'rel' => [
'alternate' => new Config([
'label' => 'Example.org',
'uri' => 'http://www.example.org/',
]),
],
],
[
'label' => 'Relations using pages instance',
'rel' => [
'alternate' => AbstractPage::factory([
'label' => 'Example.org',
'uri' => 'http://www.example.org/',
]),
],
],
]);
Default rendering of links
This example shows how to render a menu from a container registered in the view helper.
In a view script or layout:
<?= $this->navigation()->links() ?>
Output:
<link rel="alternate" href="/products/server/faq/format/xml">
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
<link rel="chapter" href="/products" title="Products">
<link rel="chapter" href="/company/about" title="Company">
<link rel="chapter" href="/community" title="Community">
<link rel="canonical" href="http://www.example.com/?page=server-faq">
<link rev="subsection" href="/products/server" title="Foo Server">
Specify which relations to render
This example shows how to specify which relations to find and render.
Render only start, next, and prev:
use Laminas\View\Helper\Navigation\Links;
$links = $this->navigation()->links();
$links->setRenderFlag(Links::RENDER_START | Links::RENDER_NEXT | Links::RENDER_PREV);
echo $links;
Output:
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
Render only native link types:
$links->setRenderFlag(Links::RENDER_ALL ^ Links::RENDER_CUSTOM);
echo $links;
Output:
<link rel="alternate" href="/products/server/faq/format/xml">
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
<link rel="chapter" href="/products" title="Products">
<link rel="chapter" href="/company/about" title="Company">
<link rel="chapter" href="/community" title="Community">
<link rev="subsection" href="/products/server" title="Foo Server">
Render all but chapters:
$links->setRenderFlag(Links::RENDER_ALL ^ Links::RENDER_CHAPTER);
echo $links;
Output:
<link rel="alternate" href="/products/server/faq/format/xml">
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
<link rel="canonical" href="http://www.example.com/?page=server-faq">
<link rev="subsection" href="/products/server" title="Foo Server">