Merge pull request #659 from symfony-cmf/content-listener-enabled

Add docs for content_listener.enable option

Author: dbu

bundles/seo/configuration.rst

@@ -70,7 +70,6 @@ The translation domain to use when translating the title and description
 template. See :ref:`bundles-seo-title-description-template` for more
 information.
 
-
 ``title``
 ~~~~~~~~~
 
@@ -95,16 +94,33 @@ about the usage.
 The original route strategy to use when multiple routes have the same content.
 Can be one of ``canonical`` or ``redirect``.
 
+``content_listener``
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+    The ``content_listener`` configuration key was introduced in SeoBundle 1.2.
+
+``enabled``
+"""""""""""
+
+**type**: ``boolean`` **default**: ``true``
+
+Whether or not the :ref:`bundles-seo-content-listener` should be loaded.
+
 ``content_key``
-~~~~~~~~~~~~~~~
+"""""""""""""""
 
 **type**: ``string`` **default**: ``null`` (or ``DynamicRouter::CONTENT_KEY`` when RoutingBundle is enabled)
 
 The name of the request attribute which contains the content object. This is
 used by the ContentListener to extract SEO information automatically. If the
 RoutingBundle is present, this defaults to ``DynamicRouter::CONTENT_KEY``
 (which evaluates to ``contentDocument``), otherwise you must define this
-manually.
+manually or disable the content listener.
+
+.. versionadded:: 1.2
+    In versions of the SeoBundle prior to 1.2, the ``content_key`` was
+    configured directly in the ``cmf_seo`` root.
 
 ``sonata_admin_extension``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

bundles/seo/introduction.rst

@@ -124,13 +124,18 @@ The ContentListener
 ~~~~~~~~~~~~~~~~~~~
 
 The ``Symfony\Cmf\Bundle\SeoBundle\EventListener\ContentListener`` looks for a
-content document in the request attributes. If it finds a document, it calls
-``SeoPresentationInterface::updateSeoPage``.
+content document in the request attributes. If it finds a document that is
+suitable for extracting metadata, the listener calls
+``SeoPresentationInterface::updateSeoPage`` to populate the metadata
+information.
 
 If the :doc:`RoutingBundle <../routing/introduction>` is installed, the default
 attribute name is defined by the constant ``DynamicRouter::CONTENT_KEY``. When
-not using the RoutingBundle, you need to configure a key in
-``cmf_seo.content_key``.
+not using the RoutingBundle, you need to disable the listener or configure a
+key in ``cmf_seo.content_key``.
+
+You may also want to disable this listener when implementing your own mechanism
+to extract SEO information.
 
 Extracting Metadata
 ~~~~~~~~~~~~~~~~~~~