vendor/zendframework/zend-navigation/doc/book/helpers/links.md

   1 # Links
   2
   3 The `links()` helper is used for rendering HTML `LINK` elements. Links are used for describing
   4 document relationships of the currently active page. Read more about links and
   5 link types at:
   6
   7 - [Document relationships: the LINK element (HTML4 W3C Rec.)](http://www.w3.org/TR/html4/struct/links.html#h-12.3)
   8 - [Link types (HTML4 W3C Rec.)](http://www.w3.org/TR/html4/types.html#h-6.12)
   9
  10 There are two types of relations; forward and reverse, indicated by the kewyords
  11 `rel` and `rev`. Most methods in the helper will take a `$rel` param, which must
  12 be either `rel` or `rev`. Most methods also take a `$type` param, which is used
  13 for specifying the link type (e.g. `alternate`, `start`, `next`, `prev`,
  14 `chapter`, etc).
  15
  16 Relationships can be added to page objects manually, or found by traversing the
  17 container registered in the helper. The method `findRelation($page, $rel,
  18 $type)` will first try to find the given `$rel` of `$type` from the `$page` by
  19 calling `$page>findRel($type)` or `$page>findRel($type)`. If the `$page` has a
  20 relation that can be converted to a page instance, that relation will be used.
  21 If the `$page` instance doesn't have the specified `$type`, the helper will look
  22 for a method in the helper named `search$rel$type` (e.g. `searchRelNext()` or
  23 `searchRevAlternate()`). If such a method exists, it will be used for
  24 determining the `$page`'s relation by traversing the container.
  25
  26 Not all relations can be determined by traversing the container. These are the
  27 relations that will be found by searching:
  28
  29 - `searchRelStart()`, forward `start` relation: the first page in the container.
  30 - `searchRelNext()`, forward `next` relation; finds the next page in the
  31   container, i.e. the page after the active page.
  32 - `searchRelPrev()`, forward `prev` relation; finds the previous page, i.e. the
  33   page before the active page.
  34 - `searchRelChapter()`, forward `chapter` relations; finds all pages on level 0
  35   except the `start` relation or the active page if it's on level 0.
  36 - `searchRelSection()`, forward `section` relations; finds all child pages of
  37   the active page if the active page is on level 0 (a `chapter`).
  38 - `searchRelSubsection()`, forward `subsection` relations; finds all child pages
  39   of the active page if the active pages is on level 1 (a `section`).
  40 - `searchRevSection()`, reverse `section` relation; finds the parent of the
  41   active page if the active page is on level 1 (a `section`).
  42 - `searchRevSubsection()`, reverse `subsection` relation; finds the parent of
  43   the active page if the active page is on level 2 (a `subsection`).
  44
  45 > ### Allowed relation types
  46 >
  47 > When looking for relations in the page instance (`$page->getRel($type)` or
  48 > `$page->getRev($type)`), the helper accepts the values of type `string`,
  49 `array`, `Traversable`,
  50 > or `Zend\Navigation\Page\AbstractPage`:
  51 >
  52 > - `AbstractPage` instances are used directly.
  53 > - If a string is found, it will be converted to a `Zend\Navigation\Page\Uri`.
  54 > - If an array or `Traversable` is found, it will be converted to one or
  55 >   several page instances. If the first key is numeric, it will be considered to
  56 >   contain several pages, and each element will be passed to the [page
  57 >   factory](../pages.md#creating-pages-using-the-page-factory).  If the first key
  58 >   is not numeric, the value will be passed to the page factory directly, and a
  59 >   single page will be returned.
  60
  61 The helper also supports magic methods for finding relations. E.g. to find
  62 forward alternate relations, call `$helper->findRelAlternate($page)`, and to
  63 find reverse section relations, call `$helper->findRevSection($page)`. Those
  64 calls correspond to `$helper->findRelation($page, 'rel', 'alternate')` and
  65 `$helper->findRelation($page, 'rev', 'section')`, respectively.
  66
  67 To customize which relations should be rendered, the helper uses a render flag.
  68 The render flag is an integer value, and will be used in a
  69 [bitwise and (`&`) operation](http://php.net/language.operators.bitwise) against
  70 the helper's render constants to determine if the relation that belongs to the
  71 render constant should be rendered.
  72
  73 See the example below for more information.
  74
  75 The `Links` helper defines the following constants:
  76
  77 - `Zend\View\Helper\Navigation\Links::RENDER_ALTERNATE`
  78 - `Zend\View\Helper\Navigation\Links::RENDER_STYLESHEET`
  79 - `Zend\View\Helper\Navigation\Links::RENDER_START`
  80 - `Zend\View\Helper\Navigation\Links::RENDER_NEXT`
  81 - `Zend\View\Helper\Navigation\Links::RENDER_PREV`
  82 - `Zend\View\Helper\Navigation\Links::RENDER_CONTENTS`
  83 - `Zend\View\Helper\Navigation\Links::RENDER_INDEX`
  84 - `Zend\View\Helper\Navigation\Links::RENDER_GLOSSARY`
  85 - `Zend\View\Helper\Navigation\Links::RENDER_COPYRIGHT`
  86 - `Zend\View\Helper\Navigation\Links::RENDER_CHAPTER`
  87 - `Zend\View\Helper\Navigation\Links::RENDER_SECTION`
  88 - `Zend\View\Helper\Navigation\Links::RENDER_SUBSECTION`
  89 - `Zend\View\Helper\Navigation\Links::RENDER_APPENDIX`
  90 - `Zend\View\Helper\Navigation\Links::RENDER_HELP`
  91 - `Zend\View\Helper\Navigation\Links::RENDER_BOOKMARK`
  92 - `Zend\View\Helper\Navigation\Links::RENDER_CUSTOM`
  93 - `Zend\View\Helper\Navigation\Links::RENDER_ALL`
  94
  95 The constants from `RENDER_ALTERNATE` to `RENDER_BOOKMARK` denote standard HTML
  96 link types.  `RENDER_CUSTOM` denotes non-standard relations specified in pages.
  97 `RENDER_ALL` denotes standard and non-standard relations.
  98
  99 Methods in the links helper:
 100
 101 Method signature                                                                        | Description
 102 --------------------------------------------------------------------------------------- | -----------
 103 `getRenderFlag() : int`                                                                 | Retrieves the render flag; default is `RENDER_ALL`.
 104 `setRenderFlag(int $flag) : self`                                                       | Set the render flag; see examples below.
 105 `findAllRelations(AbstractPage $page, int $flag = null) : array`                        | Finds all relations of all types for a given page.
 106 `findRelation(AbstractPage $page, string $rel, string $type) : AbstractPage|array|null` | Finds all relations of a given type from a given page.
 107 `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.
 108 `searchRev*(AbstractPage $page) : AbstractPage:null`                                    | Traverses a container to find reverse relations to `Section`s or `Subsection`s.
 109 `renderLink(AbstractPage $page, string $attrib, string $relation) : string`             | Renders a single `link` element.
 110
 111 ## Basic usage
 112
 113 ### Specify relations in pages
 114
 115 This example shows how to specify relations in pages.
 116
 117 ```php
 118 use Zend\Config\Config;
 119 use Zend\Navigation\Navigation;
 120 use Zend\Navigation\Page\AbstractPage;
 121
 122 $container = new Navigation([
 123     [
 124         'label' => 'Relations using strings',
 125         'rel'   => [
 126             'alternate' => 'http://www.example.org/',
 127         ],
 128         'rev'   => [
 129             'alternate' => 'http://www.example.net/',
 130         ],
 131     ],
 132     [
 133         'label' => 'Relations using arrays',
 134         'rel'   => [
 135             'alternate' => [
 136                 'label' => 'Example.org',
 137                 'uri'   => 'http://www.example.org/',
 138             ],
 139         ],
 140     ],
 141     [
 142         'label' => 'Relations using configs',
 143         'rel'   => [
 144             'alternate' => new Config([
 145                 'label' => 'Example.org',
 146                 'uri'   => 'http://www.example.org/',
 147             ]),
 148         ],
 149     ],
 150     [
 151         'label' => 'Relations using pages instance',
 152         'rel'   => [
 153             'alternate' => AbstractPage::factory([
 154                 'label' => 'Example.org',
 155                 'uri'   => 'http://www.example.org/',
 156             ]),
 157         ],
 158     ],
 159 ]);
 160 ```
 161
 162 ### Default rendering of links
 163
 164 This example shows how to render a menu from a container registered in the
 165 view helper.
 166
 167 In a view script or layout:
 168
 169 ```php
 170 <?= $this->navigation()->links() ?>
 171 ```
 172
 173 Output:
 174
 175 ```html
 176 <link rel="alternate" href="/products/server/faq/format/xml">
 177 <link rel="start" href="/" title="Home">
 178 <link rel="next" href="/products/server/editions" title="Editions">
 179 <link rel="prev" href="/products/server" title="Foo Server">
 180 <link rel="chapter" href="/products" title="Products">
 181 <link rel="chapter" href="/company/about" title="Company">
 182 <link rel="chapter" href="/community" title="Community">
 183 <link rel="canonical" href="http://www.example.com/?page=server-faq">
 184 <link rev="subsection" href="/products/server" title="Foo Server">
 185 ```
 186
 187 ### Specify which relations to render
 188
 189 This example shows how to specify which relations to find and render.
 190
 191 Render only start, next, and prev:
 192
 193 ```php
 194 use Zend\View\Helper\Navigation\Links;
 195
 196 $links = $this->navigation()->links();
 197 $links->setRenderFlag(Links::RENDER_START | Links::RENDER_NEXT | Links::RENDER_PREV);
 198 echo $links;
 199 ```
 200
 201 Output:
 202
 203 ```html
 204 <link rel="start" href="/" title="Home">
 205 <link rel="next" href="/products/server/editions" title="Editions">
 206 <link rel="prev" href="/products/server" title="Foo Server">
 207 ```
 208
 209 Render only native link types:
 210
 211 ```php
 212 $links->setRenderFlag(Links::RENDER_ALL ^ Links::RENDER_CUSTOM);
 213 echo $links;
 214 ```
 215
 216 Output:
 217
 218 ```html
 219 <link rel="alternate" href="/products/server/faq/format/xml">
 220 <link rel="start" href="/" title="Home">
 221 <link rel="next" href="/products/server/editions" title="Editions">
 222 <link rel="prev" href="/products/server" title="Foo Server">
 223 <link rel="chapter" href="/products" title="Products">
 224 <link rel="chapter" href="/company/about" title="Company">
 225 <link rel="chapter" href="/community" title="Community">
 226 <link rev="subsection" href="/products/server" title="Foo Server">
 227 ```
 228
 229 Render all but chapters:
 230
 231 ```php
 232 $links->setRenderFlag(Links::RENDER_ALL ^ Links::RENDER_CHAPTER);
 233 echo $links;
 234 ```
 235
 236 Output:
 237
 238 ```html
 239 <link rel="alternate" href="/products/server/faq/format/xml">
 240 <link rel="start" href="/" title="Home">
 241 <link rel="next" href="/products/server/editions" title="Editions">
 242 <link rel="prev" href="/products/server" title="Foo Server">
 243 <link rel="canonical" href="http://www.example.com/?page=server-faq">
 244 <link rev="subsection" href="/products/server" title="Foo Server">
 245 ```