Merge pull request #823 from symfony-cmf/seo-doc-update

dbu · web-flow · commit fea9384e5cbf · 2017-06-17T23:08:09.000+02:00
cleanup seo documentation
diff --git a/bundles/_partials/sonata_admin_form_group.rst.inc b/bundles/_partials/sonata_admin_form_group.rst.inc
@@ -0,0 +1,4 @@
+The name of the form group to use in the admin extension.
+
+The caption for the group is determined by translating the group name. If you
+change the group, be sure to also define a translation for it.
diff --git a/bundles/_partials/sonata_admin_form_tab.rst.inc b/bundles/_partials/sonata_admin_form_tab.rst.inc
@@ -0,0 +1,4 @@
+The name of the form tab to use in the admin extension.
+
+The caption for the tab is determined by translating the tab name. If you
+change the tab name, be sure to also define a translation for it.
diff --git a/bundles/block/types.rst b/bundles/block/types.rst
@@ -28,7 +28,7 @@ information.
 Sonata Admin
 ~~~~~~~~~~~~
 
-All block types provided by the Symfony2 CMF BlockBundle come with a admin
+All block types provided by the Symfony2 CMF BlockBundle come with an admin
 classes for SonataDoctrinePHPCRAdminBundle_. To activate the admin services,
 it is enough to load the SonataDoctrinePHPCRAdminBundle in your application
 kernel and configure the sonata dashboard as desired.
diff --git a/bundles/seo/alternate_locale.rst b/bundles/seo/alternate_locale.rst
@@ -17,7 +17,7 @@ find links like the following in the ``<head>`` part of your HTML pages:
     <link rel="alternate" href="/de/der-titel" hreflang="de">
 
 When using PHPCR-ODM, there is almost no work to do, as the bundle can use the
-Doctrine meta data to figure out which translations exists for a content. More
+Doctrine meta data to figure out which translations exist for a content. More
 information on translating content with the PHPCR-ODM is in the chapter
 :doc:`Doctrine PHPCR-ODM Multilanguage Support <../phpcr_odm/multilang>`.
 
diff --git a/bundles/seo/configuration.rst b/bundles/seo/configuration.rst
@@ -1,8 +1,8 @@
 Configuration Reference
 =======================
 
-The SeoBundle can be configured under the ``cmf_seo`` key in your application
-configuration. When using XML, you can use the
+The SeoBundle is configured under the ``cmf_seo`` key in your application
+configuration. When using XML, use the
 ``http://cmf.symfony.com/schema/dic/seo`` namespace.
 
 Configuration
@@ -90,7 +90,7 @@ about the usage.
 ``original_route_pattern``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``canonical``
+**type**: ``string`` **default**: ``canonical`` **allowed values**: ``canonical`` | ``redirect``
 
 The original route strategy to use when multiple routes have the same content.
 Can be one of ``canonical`` or ``redirect``.
@@ -129,6 +129,9 @@ manually or disable the content listener.
 .. versionadded:: 1.2
     Support for sitemaps was introduced in version 1.2 of the SeoBundle.
 
+For details on the meaning of the sitemap configuration, see the
+:doc:`sitemap section <sitemap>`.
+
 .. configuration-block::
 
     .. code-block:: yaml
@@ -142,6 +145,12 @@ manually or disable the content listener.
                     templates:
                         html: :sitemap/index.html.twig
                         xml: ::sitemap:index.xml.twig
+                    loaders:
+                        - _all
+                    guessers:
+                        - _all
+                    voters:
+                        - _all
                 configurations:
                     sitemap: ~
 
@@ -156,6 +165,9 @@ manually or disable the content listener.
                     <defaults>
                         <template format="html">CmfSeoBundle:Sitemap:index.html.twig</template>
                         <template format="xml">CmfSeoBundle:Sitemap:index.xml.twig</template>
+                        <loader>_all</loader>
+                        <guesser>_all</guesser>
+                        <voter>_all</voter>
                     </defaults>
                     <configuration name="sitemap"/>
                 </sitemap>
@@ -173,6 +185,9 @@ manually or disable the content listener.
                         'html' => 'CmfSeoBundle:Sitemap:index.html.twig',
                         'xml' => 'CmfSeoBundle:Sitemap:index.xml.twig',
                     ],
+                    'loaders' => ['_all'],
+                    'guessers' => ['_all'],
+                    'voters' => ['_all'],
                 ],
                 'configurations' => [
                     'sitemap' => null,
@@ -218,30 +233,22 @@ By default, you have:
 * html: CmfSeoBundle:Sitemap:index.html.twig
 * xml: CmfSeoBundle:Sitemap:index.xml.twig
 
-``sonata_admin_extension``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If set to ``true``, the Sonata Admin Extension provided by the SeoBundle is
-activated.
-
-``enabled``
-"""""""""""
+``loaders``
+***********
 
-**type**: ``enum`` **valid values** ``true|false|auto`` **default**: ``auto``
+**type**: ``array`` **default**: [_all]
 
-If ``true``, the Sonata Admin Extension will be activated. If set to ``auto``,
-it is activated only if the SonataPhpcrAdminBundle is present.
+Limit which of the loaders should be used for this sitemap.
 
-If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to the value
-of ``cmf_core.persistence.phpcr.use_sonata_admin``.
+``guessers``
+************
 
-``form_group``
-""""""""""""""
+**type**: ``array`` **default**: [_all]
 
-**type**: ``string`` **default**: ``form.group_seo``
+``voters``
+**********
 
-The name of the form group of the group provided by the Sonata Admin
-Extension.
+**type**: ``array`` **default**: [_all]
 
 ``form``
 ~~~~~~~~
diff --git a/bundles/seo/error_pages.rst b/bundles/seo/error_pages.rst
@@ -4,14 +4,12 @@ Displaying Relevant Pages in Error Pages
 .. versionadded:: 1.2
     The ``SuggestionProviderController`` was introduced in SeoBundle 1.2.
 
-You don't want to loose visitors when they hit a 404 error page. A good way to
-do this is by showing relevant links on the site, so they can quickly navigate
-to another page (or maybe even the page they were looking for in the
-beginning).
+You don't want to lose visitors when no content is found. Instead of showing a
+generic 404 error page, the SEO bundle provides the means to show potentially
+relevant links to help the user find something useful.
 
-The CmfSeoBundle provides an error controller that does exactly this. By using
-suggestion providers, the controller finds the most relevant pages and shows
-this on the error page.
+This is implemented in the error controller. That controller uses suggestion
+providers to find the most relevant pages and shows them on the error page.
 
 Using the Exception Controller
 ------------------------------
@@ -60,10 +58,10 @@ comes with two built-in providers:
 
 ``ParentSuggestionProvider``
     This provides the parent page of the not found page (e.g. ``/blog`` when
-    ``/blog/foo`` resulted in a 404 page).
+    ``/blog/foo`` was not found).
 ``SiblingSuggestionProvider``
     This provides the siblings of the current page (e.g. ``/blog/something``
-    when ``/blog/foo`` resulted in a 404 page).
+    when ``/blog/foo`` was not found).
 
 .. note::
 
diff --git a/bundles/seo/extractors.rst b/bundles/seo/extractors.rst
@@ -20,10 +20,10 @@ Available Extractors
 | -                              | ``getTitle()``            | If the document has a ``getTitle()`` method, |
 |                                |                           | it'll be used as the page title              |
 +--------------------------------+---------------------------+----------------------------------------------+
-| ``OriginalUrlReadInterface``   | ``getSeoOriginalUrl()``   | Returns a absolute url object to redirect to |
+| ``OriginalUrlReadInterface``   | ``getSeoOriginalUrl()``   | Returns an absolute url to redirect to or    |
 |                                |                           | or create a canonical link from              |
 +--------------------------------+---------------------------+----------------------------------------------+
-| ``OriginalRouteReadInterface`` | ``getSeoOriginalRoute()`` | Return a ``Route`` object to redirect to     |
+| ``OriginalRouteReadInterface`` | ``getSeoOriginalRoute()`` | Returns a ``Route`` object to redirect to    |
 |                                |                           | or create a canonical link from              |
 +--------------------------------+---------------------------+----------------------------------------------+
 | ``ExtrasReadInterface``        | ``getSeoExtras()``        | Returns an associative array using           |
diff --git a/bundles/seo/introduction.rst b/bundles/seo/introduction.rst
@@ -135,8 +135,8 @@ key in ``cmf_seo.content_key``.
 
 If you need different behavior, build your own mechanism to extract the SEO
 information and disable this listener at ``cmf_seo.content_listener.enabled``
-to avoid duplicated work. Things that happen on every request are expensive in
-terms of application performance.
+to avoid unnecessary code execution. Things that happen on every request are
+critical for your application performance.
 
 The Twig Extension
 ~~~~~~~~~~~~~~~~~~
@@ -351,9 +351,9 @@ And then configure the translation messages:
 .. tip::
 
     You don't have to escape the percent characters here, since the
-    Translation loaders know how to deal with them.
+    Translation loaders do not try to evaluate container variables.
 
-For changing the default translation domain (messages), you should use the
+For changing the default translation domain, use the
 ``cmf_seo.translation_domain`` setting:
 
 .. configuration-block::
diff --git a/bundles/seo/seo_aware.rst b/bundles/seo/seo_aware.rst
@@ -1,11 +1,11 @@
 Saving the SeoMetadata in the Object
 ====================================
 
-The ``SeoMetadata`` can be saved in the object, so you can persist it into the
-database. This option gives admins the possibility of changing the SEO data for
-the document.
+The ``SeoMetadata`` can be set on your model classes, so that you can persist
+it into the database. This option gives admins the possibility to change the SEO
+data for the object.
 
-In order to save the ``SeoMetadata`` in the object, the object should
+In order to save the ``SeoMetadata`` in the model, the object should
 implement the ``SeoAwareInterface``. This requires a getter and a setter for
 the ``SeoMetadata``::
 
@@ -32,8 +32,8 @@ the ``SeoMetadata``::
 
 .. tip::
 
-    If you are using PHP5.4+ you may also benefit from using the trait ``SeoAwareTrait``
-    to plug these behavior into your model.
+    Instead of implementing these methods yourself, you can also use the trait
+    ``SeoAwareTrait`` to enable this behavior in your model.
 
 Now you can set some SEO data for this ``Page`` using the metadata::
 
@@ -91,7 +91,7 @@ To be able to use this document, you have to enable the PHPCR persistence:
     bundle. See :doc:`the CoreBundle docs <../core/persistence>` for more
     information.
 
-After you've enabled PHPCR, map ``$seoMetadata`` as a child:
+After you have enabled PHPCR, map ``$seoMetadata`` as a child:
 
 .. configuration-block::
 
@@ -178,7 +178,7 @@ And after that, you can use the
 Doctrine ORM
 ------------
 
-You can also use the Doctrine ORM with the CmfSeoBundle. You can just use the
+You can also use the Doctrine ORM with the CmfSeoBundle. Use the
 ``Symfony\Cmf\Bundle\SeoBundle\SeoMetadata`` class and map it as an
 object:
 
@@ -240,9 +240,9 @@ the ``SeoMetadata`` entity.
 Form Type
 ---------
 
-The bundle also provides a special form type called ``Symfony\Cmf\Bundle\SeoBundle\Form\Type\SeoMetadataType``
-(use ``seo_metadata`` for Symfony versions older than 2.8). This form type can be
-used in forms to edit the ``SeoMetadata`` object::
+The bundle also provides a special form type called
+``Symfony\Cmf\Bundle\SeoBundle\Form\Type\SeoMetadataType``. This form type can
+be used in forms to edit the ``SeoMetadata`` object::
 
     use Sonata\AdminBundle\Form\FormMapper;
     use Symfony\Cmf\Bundle\SeoBundle\Form\Type\SeoMetadataType;
@@ -264,17 +264,9 @@ used in forms to edit the ``SeoMetadata`` object::
     option is set by default, otherwise you need to explicitly specify it in
     your ORM forms.
 
-Sonata Admin Integration
-------------------------
-
-Besides providing a form type, the bundle also provides a Sonata Admin
-Extension. This extension adds a field for the ``SeoMetadata`` when an admin
-edits an object that implements the ``SeoAwareInterface`` in the Sonata Admin
-panel.
-
-.. caution::
+.. tip::
 
-    The Sonata Admin uses the Form Type provided by the CmfSeoBundle, make
-    sure you have the `BurgovKeyValueFormBundle`_ installed.
+    The :doc:`SonataPhpcrAdminIntegrationBundle <../sonata_phpcr_admin_integration/seo>`
+    provides an admin extension for the ``SeoAwareInterface``.
 
 .. _`BurgovKeyValueFormBundle`: https://github.com/Burgov/KeyValueFormBundle
diff --git a/bundles/seo/twig.rst b/bundles/seo/twig.rst
@@ -5,11 +5,11 @@ Setting Seo Metadata from Twig
     The twig extension was added in SeoBundle 1.2.
 
 This bundle provides a twig function ``cmf_seo_update_metadata``
-which lets you populate the seo page from an object.
-For details on how populating the SEO page works, read :doc:`introduction`.
+which lets you populate the SEO data from an object.
+For details on how populating the SEO data works, read :doc:`introduction`.
 
-You must call this function in your twig template before the calls to
-``sonata_seo_title`` and ``sonata_seo_metadatas`` functions. The
+If you use this function, you must make sure to call this in your twig template
+before the calls to ``sonata_seo_title`` and ``sonata_seo_metadatas`` The
 recommended set up for this is to create a metadata block in your
 base twig template and override it in a sub template, calling
 ``cmf_seo_update_metadata`` before calling ``parent()``.
diff --git a/bundles/sonata_phpcr_admin_integration/core.rst b/bundles/sonata_phpcr_admin_integration/core.rst
@@ -82,22 +82,14 @@ admins as needed - see below for details.
 
 **type**: ``string`` **default**: as in above example.
 
-Defines which form group the fields from this extension will appear in within
-the Sonata Admin edit interface.
-
-The caption for the group is determined by translating the group name. If you
-change the group, be sure to also define a translation for it.
+.. include:: ../_partials/sonata_admin_form_group.rst.inc
 
 ``form_tab``
 ~~~~~~~~~~~~
 
 **type**: ``string`` **default**: as in above example.
 
-Defines which form tab the fields from this extension will appear in within
-the Sonata Admin edit interface.
-
-The caption for the tab is determined by translating the tab name. If you
-change the tab name, be sure to also define a translation for it.
+.. include:: ../_partials/sonata_admin_form_tab.rst.inc
 
 Using Child Models: The Child Sonata Admin Extension
 ----------------------------------------------------
@@ -108,7 +100,7 @@ for example when adding documents in an overlay with the
 ``doctrine_phpcr_odm_tree_manager`` or when adding a document in the tree of
 the dashboard.
 
-To enable the extension in your admin classes, simply define the extension
+To activate the extension in your admin classes, define the extension
 configuration in the ``sonata_admin`` section of your project configuration:
 
 .. configuration-block::
@@ -132,8 +124,8 @@ configuration in the ``sonata_admin`` section of your project configuration:
             <config xmlns="http://sonata-project.org/schema/dic/admin">
                 <!-- ... -->
                 <extension id="cmf_sonata_phpcr_admin_integration.core.extension.child">
-                    <implement>Symfony\Cmf\Bundle\CoreBundle\Model\ChildInterface</implement>
-                    <implement>Doctrine\ODM\PHPCR\HierarchyInterface</implement>
+                    <implements>Symfony\Cmf\Bundle\CoreBundle\Model\ChildInterface</implements>
+                    <implements>Doctrine\ODM\PHPCR\HierarchyInterface</implements>
                 </extension>
             </config>
 
@@ -163,7 +155,7 @@ Editing publication information: Publish Workflow Sonata Admin Extension
 When using the :doc:`write interface of the publish workflow <../core/publish_workflow>`,
 this admin extension can be used to edit publication information.
 
-To enable the extensions in your admin classes, define the extension
+To activate the extensions in your admin classes, define the extension
 configuration in the ``sonata_admin`` section of your project configuration:
 
 .. configuration-block::
@@ -189,15 +181,15 @@ configuration in the ``sonata_admin`` section of your project configuration:
             <config xmlns="http://sonata-project.org/schema/dic/admin">
                 <!-- ... -->
                 <extension id="cmf_sonata_phpcr_admin_integration.core.extension.publish_workflow.publishable">
-                    <implement>
+                    <implements>
                         Symfony\Cmf\Bundle\CoreBundle\PublishWorkflow\PublishableInterface
-                    </implement>
+                    </implements>
                 </extension>
 
                 <extension id="cmf_sonata_phpcr_admin_integration.core.extension.publish_workflow.time_period">
-                    <implement>
+                    <implements>
                         Symfony\Cmf\Bundle\CoreBundle\PublishWorkflow\PublishTimePeriodInterface
-                    </implement>
+                    </implements>
                 </extension>
             </config>
         </container>
diff --git a/bundles/sonata_phpcr_admin_integration/menu.rst b/bundles/sonata_phpcr_admin_integration/menu.rst
diff --git a/bundles/sonata_phpcr_admin_integration/routing.rst b/bundles/sonata_phpcr_admin_integration/routing.rst
diff --git a/bundles/sonata_phpcr_admin_integration/seo.rst b/bundles/sonata_phpcr_admin_integration/seo.rst
