Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

Commit 18d5c71

Browse files
wouterjwouterj
committed
Document SEO error pages
1 parent c00addf commit 18d5c71

File tree

5 files changed

+278
-4
lines changed

5 files changed

+278
-4
lines changed

‎bundles/map.rst.inc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,10 @@ library or they introduce a complete new concept.
7171
* :doc:`seo/introduction`
7272
* :doc:`seo/seo_aware`
7373
* :doc:`seo/extractors`
74-
* :doc:`seo/configuration`
7574
* :doc:`seo/twig`
75+
* :doc:`seo/sitemap`
76+
* :doc:`seo/error_pages`
77+
* :doc:`seo/configuration`
7678

7779
* :doc:`tree_browser/index`
7880

‎bundles/seo/configuration.rst

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,3 +261,95 @@ Configures the class to use when creating new ``SeoMetadata`` objects using the
261261

262262
When the `phpcr`_ persistence layer is enabled, this defaults to
263263
``Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata``.
264+
265+
.. _bundles-seo-config-error:
266+
267+
error
268+
~~~~~
269+
270+
.. versionadded::
271+
The ``error`` settings were introduced in SeoBundle 1.2.
272+
273+
.. seealso::
274+
275+
Learn more about error pages in ":doc:`error_pages`".
276+
277+
enable_parent_provider
278+
""""""""""""""""""""""
279+
280+
**type**: ``boolean`` **default**: ``false``
281+
282+
Whether the parent suggestion provider should be enabled.
283+
284+
enable_sibling_provider
285+
"""""""""""""""""""""""
286+
287+
**type**: ``boolean`` **default**: ``false``
288+
289+
Whether the sibling suggestion provider should be enabled.
290+
291+
templates
292+
"""""""""
293+
294+
**type**: ``array`` **default**: ``{ html: 'CmfSeoBundle:Exception:error.html.twig' }``
295+
296+
A list of templates to use for the custom error page. By default, only the HTML
297+
format is configured. The default Symfony exception controller will be used for
298+
the other formats.
299+
300+
exclusion_rules
301+
"""""""""""""""
302+
303+
**type**: ``array``
304+
305+
To specify exclusion rules for pages that shouldn't be handled by the custom
306+
exception controller. In these cases, the default Symfony exception controller
307+
will be used instead.
308+
309+
Exclusion rules allow to match the following fields:
310+
311+
* path
312+
* host
313+
* methods
314+
* ips
315+
316+
For instance, to not use the special exception controller for the ``/admin``
317+
routes, use:
318+
319+
.. configuration-block::
320+
321+
.. code-block:: yaml
322+
323+
# app/config/config.yml
324+
cmf_seo:
325+
error:
326+
exclusion_rules:
327+
- { path: ^/admin }
328+
329+
.. code-block:: xml
330+
331+
<!-- app/config/config.xml -->
332+
<?xml version="1.0" encoding="UTF-8" ?>
333+
<container xmlns="http://symfony.com/schema/dic/services"
334+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
335+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
336+
http://cmf.symfony.com/schema/dic/seo http://cmf.symfony.com/schema/dic/seo/seo-1.0.xsd"
337+
>
338+
339+
<config xmlns="http://symfony.com/schema/dic/seo">
340+
<error>
341+
<exclusion-rule path="^/admin" />
342+
</error>
343+
</config>
344+
</container>
345+
346+
.. code-block:: php
347+
348+
// app/config/config.php
349+
$container->loadFromExtension('cmf_seo', array(
350+
'error' => array(
351+
'exclusion_rules' => array(
352+
array('path' => '^/admin'),
353+
),
354+
),
355+
));

‎bundles/seo/error_pages.rst

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
Displaying Relevant Pages in Error Pages
2+
========================================
3+
4+
.. versionadded:: 1.2
5+
The ``SuggestionProviderController`` was introduced in SeoBundle 1.2.
6+
7+
You don't want to loose visitors when they hit a 404 error page. A good way to
8+
do this is by showing relevant links on the site, so they can quickly navigate
9+
to another page (or maybe even the page they were looking for in the
10+
beginning).
11+
12+
The CmfSeoBundle provides an error controller that does exactly this. By using
13+
suggestion providers, the controller finds the most relevant pages and shows
14+
this on the error page.
15+
16+
Using the Exception Controller
17+
------------------------------
18+
19+
To use the exception controller provided by this bundle, configure the twig
20+
bundle:
21+
22+
.. configuration-block::
23+
24+
.. code-block:: yaml
25+
26+
# app/config/config.yml
27+
twig:
28+
exception_controller: cmf_seo.error.suggestion_provider.controller:showAction
29+
30+
.. code-block:: xml
31+
32+
<!-- app/config/config.xml -->
33+
<?xml version="1.0" encoding="UTF-8" ?>
34+
<container xmlns="http://symfony.com/schema/dic/services"
35+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
36+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
37+
http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd"
38+
>
39+
40+
<config xmlns="http://symfony.com/schema/dic/twig"
41+
exception-controller="cmf_seo.error.suggestion_provider.controller:showAction"
42+
/>
43+
</container>
44+
45+
.. code-block:: php
46+
47+
// app/config/config.php
48+
$container->loadFromExtension('twig', array(
49+
'exception_controller' => 'cmf_seo.error.suggestion_provider.controller:showAction',
50+
));
51+
52+
After this, you need to enable some suggestion providers. Suggestion providers
53+
provide relevant other pages, which are displayed on the error page. The bundle
54+
comes with two built-in providers:
55+
56+
``ParentSuggestionProvider``
57+
This provides the parent page of the not found page.
58+
``SiblingSuggestionProvider``
59+
This provides the siblings of the current page.
60+
61+
.. note::
62+
63+
Both providers only work with PHPCR documents.
64+
65+
You can enable these in your config:
66+
67+
.. configuration-block::
68+
69+
.. code-block:: yaml
70+
71+
# app/config/config.yml
72+
cmf_seo:
73+
error:
74+
enable_parent_provider: true
75+
enable_sibling_provider: true
76+
77+
.. code-block:: xml
78+
79+
<!-- app/config/config.xml -->
80+
<?xml version="1.0" encoding="UTF-8" ?>
81+
<container xmlns="http://symfony.com/schema/dic/services"
82+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
83+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
84+
http://cmf.symfony.com/schema/dic/seo http://cmf.symfony.com/schema/dic/seo/seo-1.0.xsd"
85+
>
86+
87+
<config xmlns="http://symfony.com/schema/dic/seo">
88+
<error enable-parent-provider="true" enable-sibling-provider="true" />
89+
</config>
90+
</container>
91+
92+
.. code-block:: php
93+
94+
// app/config/config.php
95+
$container->loadFromExtension('cmf_seo', array(
96+
'error' => array(
97+
'enable_parent_provider' => true,
98+
'enable_sibling_provider' => true,
99+
),
100+
));
101+
102+
.. tip::
103+
104+
You can customize the template that's used for the error page. It is also
105+
possible to use the default exception controller for some requests. Read
106+
more about the available configuration settings in
107+
:ref:`the configuration reference <bundles-seo-config-error>`.
108+
109+
Creating a Custom Suggestion Provider
110+
-------------------------------------
111+
112+
You can create a custom suggestion provider by implementing
113+
``Symfony\Cmf\Bundle\SeoBundle\SuggestionProviderInterface``. This interface
114+
requires a ``create()`` method that returns a list of routes. For instance,
115+
assume you always want to suggest the homepage, the provider looks like::
116+
117+
// src/AppBundle/Seo/HomepageSuggestionProvider.php
118+
namespace AppBundle\Seo;
119+
120+
use Symfony\Component\Routing\Route;
121+
use Symfony\Component\HttpFoundation\Request;
122+
use Symfony\Cmf\Bundle\SeoBundle\SuggestionProviderInterface;
123+
124+
class HomepageSuggestionProvider implements SuggestionProviderInterface
125+
{
126+
// ...
127+
128+
public function create(Request $request)
129+
{
130+
// somehow get the Route instance of the homepage route (e.g. by quering the database)
131+
$homepageRoute = ...;
132+
133+
return array($homepageRoute);
134+
}
135+
}
136+
137+
Now, register this new class as a service and tag it as
138+
``cmf_seo.suggestion_provider``:
139+
140+
.. configuration-block::
141+
142+
.. code-block:: yaml
143+
144+
# app/config/services.yml
145+
services:
146+
app.suggestions.hompage:
147+
class: AppBundle\Seo\HomepageSuggestionProvider
148+
tags:
149+
- { name: cmf_seo.suggestion_provider }
150+
151+
.. code-block:: xml
152+
153+
<!-- app/config/services.xml -->
154+
<?xml version="1.0" encoding="UTF-8" ?>
155+
<container xmlns="http://symfony.com/schema/dic/services"
156+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
157+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd"
158+
>
159+
160+
<services>
161+
<service id="app.suggestions.homepage"
162+
class="AppBundle\Seo\HomepageSuggestionProvider"
163+
>
164+
<tag name="cmf_seo.suggestion_provider"/>
165+
</service>
166+
</services>
167+
168+
</container>
169+
170+
.. code-block:: php
171+
172+
// app/config/services.php
173+
use Symfony\Component\DependencyInjection\Definition;
174+
175+
$definition = new Definition('AppBundle\Seo\HomepageSuggestionProvider');
176+
$definition->addTag('cmf_seo.suggestion_provider');
177+
$container->setDefinition('app.suggestions.homepage', $definition);
178+
179+
The tag allows a ``group`` attribute, in order to group suggested links.

‎bundles/seo/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,6 @@ SeoBundle
88
seo_aware
99
extractors
1010
sitemap
11+
error_pages
1112
configuration
1213
twig

‎bundles/seo/sitemap.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
Building Sitemaps
22
=================
33

4+
.. versionadded:: 1.2
5+
Sitemap support was introduced in SeoBundle 1.2.
6+
47
This bundle helps loading documents that should go in a sitemap, extracting
58
the information from them and rendering them to a sitemap information.
69

710
You can generate sitemaps in different formats and it is possible to provide
811
more than one set of configurations.
912

10-
.. versionadded:: 1.2
11-
Sitemap support was introduced in SeoBundle 1.2.
12-
1313
Setting Up the Bundle
1414
---------------------
1515

0 commit comments

Comments
 (0)