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

Commit 2554d10

Browse files
wouterjwouterj
committed
Merge pull request #741 from symfony-cmf/issue_606
Document SEO error pages
2 parents 964b41d + de816ed commit 2554d10

File tree

6 files changed

+289
-5
lines changed

6 files changed

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

‎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

‎bundles/seo/twig.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ base twig template and override it in a sub template, calling
3535
{% extends 'base.html.twig' %}
3636

3737
{% block metadata %}
38-
{{ cmf_seo_update_metadata(post) }}
38+
{% do cmf_seo_update_metadata(post) %}
39+
3940
{{ parent() }}
4041
{% endblock metadata %}

0 commit comments

Comments
 (0)