Skip to content
This repository was archived by the owner on Jan 31, 2020. It is now read-only.

Commit 98cfda6

Browse files
michalbundyramichalbundyra
committed
Merge pull request #188 from froschdesign/hotfix/docs/109
Fixes #109 - HeadTitle helper documentation is too complicated
2 parents b486187 + 860d42a commit 98cfda6

File tree

1 file changed

+170
-62
lines changed

1 file changed

+170
-62
lines changed

‎doc/book/helpers/head-title.md‎

Lines changed: 170 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# HeadTitle
22

3-
The HTML `<title>` element is used to provide a title for an HTML document. The
4-
`HeadTitle` helper allows you to programmatically create and store the title for
5-
later retrieval and output.
3+
The HTML `<title>` element is used to **provide a title for an HTML document**.
4+
The `HeadTitle` helper allows you to programmatically create and store the title
5+
for later retrieval and output.
66

77
The `HeadTitle` helper is a concrete implementation of the [Placeholder helper](placeholder.md).
88
It overrides the `toString()` method to enforce generating a `<title>` element,
@@ -19,62 +19,15 @@ explicitly pass a different attach order as the second parameter.
1919

2020
## Basic Usage
2121

22-
You may specify a title tag at any time. A typical usage would have you setting
23-
title segments for each level of depth in your application: site, module,
24-
controller, action, and potentially resource. This could be achieved in the
25-
module class.
22+
Specify a title tag in a view script, e.g.
23+
`module/Album/view/album/album/index.phtml`:
2624

2725
```php
28-
// module/MyModule/Module.php
29-
<?php
30-
31-
namespace MyModule;
32-
33-
class Module
34-
{
35-
/**
36-
* @param \Zend\Mvc\MvcEvent $e The MvcEvent instance
37-
* @return void
38-
*/
39-
public function onBootstrap($e)
40-
{
41-
// Register a render event
42-
$app = $e->getParam('application');
43-
$app->getEventManager()->attach('render', [$this, 'setLayoutTitle']);
44-
}
45-
46-
/**
47-
* @param \Zend\Mvc\MvcEvent $e The MvcEvent instance
48-
* @return void
49-
*/
50-
public function setLayoutTitle($e)
51-
{
52-
$matches = $e->getRouteMatch();
53-
$action = $matches->getParam('action');
54-
$controller = $matches->getParam('controller');
55-
$module = __NAMESPACE__;
56-
$siteName = 'Zend Framework';
57-
58-
// Getting the view helper manager from the application service manager
59-
$viewHelperManager = $e->getApplication()->getServiceManager()->get('ViewHelperManager');
60-
61-
// Getting the headTitle helper from the view helper manager
62-
$headTitleHelper = $viewHelperManager->get('headTitle');
63-
64-
// Setting a separator string for segments
65-
$headTitleHelper->setSeparator(' - ');
66-
67-
// Setting the action, controller, module and site name as title segments
68-
$headTitleHelper->append($action);
69-
$headTitleHelper->append($controller);
70-
$headTitleHelper->append($module);
71-
$headTitleHelper->append($siteName);
72-
}
73-
}
74-
```
75-
76-
When you're finally ready to render the title in your layout script, echo the
77-
helper:
26+
$this->headTitle('My albums');
27+
```
28+
29+
Render the title in the layout script, e.g.
30+
`module/Application/view/layout/layout.phtml`
7831

7932
```php
8033
<?= $this->headTitle() ?>
@@ -83,18 +36,173 @@ helper:
8336
Output:
8437

8538
```html
86-
<title>action - controller - module - Zend Framework</title>
39+
<title>My albums</title>
8740
```
8841

89-
In case you want the title without the `<title>` and `</title>` tags you can use
90-
the `renderTitle()` method:
42+
### Add the Website Name
43+
44+
A typical usage includes the website name in the title. Add the name and [set a
45+
separator](#using-separator) in the layout script, e.g.
46+
`module/Application/view/layout/layout.phtml`
9147

9248
```php
93-
<?= $this->headTitle()->renderTitle() ?>
49+
<?= $this->headTitle('Music')->setSeparator(' - ') ?>
9450
```
9551

9652
Output:
9753

9854
```html
99-
action - controller - module - Zend Framework
55+
<title>My albums - Music</title>
56+
```
57+
58+
## Set Content
59+
60+
The normal behaviour is to append the content to the title (container).
61+
62+
```php
63+
$this->headTitle('My albums')
64+
$this->headTitle('Music');
65+
66+
echo $this->headTitle(); // <title>My albumsMusic</title>
67+
```
68+
69+
### Append Content
70+
71+
To explicitly append content, the second paramater `$setType` or the concrete
72+
method `append()` of the helper can be used:
73+
74+
```php fct_label="Invoke Usage"
75+
$this->headTitle('My albums')
76+
$this->headTitle('Music', 'APPEND');
77+
78+
echo $this->headTitle(); // <title>My albumsMusic</title>
79+
```
80+
81+
```php fct_label="Setter Usage"
82+
$this->headTitle('My albums')
83+
$this->headTitle()->append('Music');
84+
85+
echo $this->headTitle(); // <title>My albumsMusic</title>
86+
```
87+
88+
The constant `Zend\View\Helper\Placeholder\Container\AbstractContainer::APPEND`
89+
can also be used as value for the second parameter `$setType`.
90+
91+
### Prepend Content
92+
93+
To prepend content, the second paramater `$setType` or the concrete method
94+
`prepend()` of the helper can be used:
95+
96+
```php fct_label="Invoke Usage"
97+
$this->headTitle('My albums')
98+
$this->headTitle('Music', 'PREPEND');
99+
100+
echo $this->headTitle(); // <title>MusicMy albums</title>
101+
```
102+
103+
```php fct_label="Setter Usage"
104+
$this->headTitle('My albums')
105+
$this->headTitle()->prepend('Music');
106+
107+
echo $this->headTitle(); // <title>MusicMy albums</title>
108+
```
109+
110+
The constant `Zend\View\Helper\Placeholder\Container\AbstractContainer::PREPEND`
111+
can also be used as value for the second parameter `$setType`.
112+
113+
### Overwrite existing Content
114+
115+
To overwrite the entire content of title helper, the second parameter `$setType`
116+
or the concrete method `set()` of the helper can be used:
117+
118+
```php fct_label="Invoke Usage"
119+
$this->headTitle('My albums')
120+
$this->headTitle('Music', 'SET');
121+
122+
echo $this->headTitle(); // <title>Music</title>
123+
```
124+
125+
```php fct_label="Setter Usage"
126+
$this->headTitle('My albums')
127+
$this->headTitle()->set('Music');
128+
129+
echo $this->headTitle(); // <title>Music</title>
130+
```
131+
132+
The constant `Zend\View\Helper\Placeholder\Container\AbstractContainer::SET`
133+
can also be used as value for the second parameter `$setType`.
134+
135+
### Set a default Order to add Content
136+
137+
```php
138+
$this->headTitle()->setDefaultAttachOrder('PREPEND');
139+
$this->headTitle('My albums');
140+
$this->headTitle('Music');
141+
142+
echo $this->headTitle(); // <title>MusicMy albums</title>
143+
```
144+
145+
#### Get Current Value
146+
147+
To get the current value of this option, use the `getDefaultAttachOrder()`
148+
method.
149+
150+
```php
151+
$this->headTitle()->setDefaultAttachOrder('PREPEND');
152+
153+
echo $this->headTitle()->getDefaultAttachOrder(); // PREPEND
154+
```
155+
156+
#### Default Value
157+
158+
The default value is
159+
`Zend\View\Helper\Placeholder\Container\AbstractContainer::APPEND` which
160+
corresponds to the value `APPEND`.
161+
162+
## Using Separator
163+
164+
```php
165+
$this->headTitle()->setSeparator(' | ');
166+
$this->headTitle('My albums');
167+
$this->headTitle('Music');
168+
169+
echo $this->headTitle(); // <title>My albums | Music</title>
170+
```
171+
172+
### Get Current Value
173+
174+
To get the current value of this option, use the `getSeparator()`
175+
method.
176+
177+
```php
178+
$this->headTitle()->setSeparator(' | ');
179+
180+
echo $this->headTitle()->getSeparator(); // |
181+
```
182+
183+
### Default Value
184+
185+
The default value is an empty `string` that means no extra content is added
186+
between the titles on rendering.
187+
188+
## Add Prefix and Postfix
189+
190+
The content of the helper can be formatted with a prefix and a postfix.
191+
192+
```php
193+
$this->headTitle('My albums')->setPrefix('Music: ')->setPostfix('𝄞');
194+
195+
echo $this->headTitle(); // <title>Music: My albums 𝄞</title>
196+
```
197+
198+
More descriptions and another example of usage can be found at the
199+
[`Placeholder` helper](placeholder.md#aggregate-content).
200+
201+
## Render without Tags
202+
203+
In case the title is needed without the `<title>` and `</title>` tags the
204+
`renderTitle()` method can be used.
205+
206+
```php
207+
echo $this->headTitle('My albums')->renderTitle(); // My albums
100208
```

0 commit comments

Comments
 (0)