Lots of fixes

wouterj · wouterj · commit 3b16b818c9fa · 2014-05-14T19:34:06.000+02:00
diff --git a/bundles/seo/index.rst b/bundles/seo/index.rst
@@ -6,3 +6,4 @@ SeoBundle
 
     introduction
     seo_aware
+    extractors
diff --git a/bundles/seo/introduction.rst b/bundles/seo/introduction.rst
@@ -44,7 +44,7 @@ The simplest use of this bundle would be to just set some configuration to the
             page:
                 title: Page's default title
                 metas:
-                    names:
+                    name:
                         description: The default description of the page
                         keywords: default, sonata, seo
 
@@ -55,7 +55,7 @@ The simplest use of this bundle would be to just set some configuration to the
             'page' => array(
                 'title' => 'Page's default title',
                 'metas' => array(
-                    'names' => array(
+                    'name' => array(
                         'description' => 'default description',
                         'keywords' => 'default, key, other',
                     ),
@@ -110,12 +110,15 @@ This bundle provides two ways of using this metadata:
 #. Using the extractors, to extract the ``SeoMetadata`` from already existing
    values (e.g. the title of the page).
 
-You can also use both ways at the same time for the document. In that case,
-the persisted ``SeoMetadata`` can be changed by the extractors.
+You can also combine both ways, even on the same document. In that case, the
+persisted ``SeoMetadata`` can be changed by the extractors, to add or tweak
+the current available SEO information. For instance, if you are writing a
+``BlogPost`` class, you want the SEO keywords to be set to the tags/category
+of the post and any additional tags set by the admin.
 
 Persisting the ``SeoMetadata`` with the document makes it easy to edit for the
-admin, while using the extractors makes it perfect to use without doing
-anything.
+admin, while using the extractors are perfect to easily use values from the
+displayed content.
 
 Both ways are documented in detail in seperate sections:
 
@@ -130,8 +133,8 @@ URLs. The CMF allows you to have several URLs for the same content if you need
 that. There are two solutions to avoid penalties with search engines:
 
 * Create a canonical link that identifies the original URL:
-  ``<link rel="canonical" href="/route/org/content">``;
-* Define an "original url" and redirect the other to that one.
+  ``<link rel="canonical" href="/route/org/content">``
+* Define an "original url" and redirect all duplicate URLs to it.
 
 The ``SeoMetadata`` can be configured with the original URL for the current
 page. By default, this bundle will create a canonical link for the page. If
@@ -162,56 +165,25 @@ you want to change that to redirect instead, you can set the
             ),
         );
 
-Defining a Default
-------------------
-
-You've learned everything about extracting SEO information from objects.
-However, in some cases the object doesn't provide any information or there is
-no object (e.g. on a login page). For these cases, you have to configure a
-default value. These default values can be configured for the SonataSeoBundle:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/config.yml
-        sonata_seo:
-            page:
-                title: A Default Title
-                metas:
-                    names:
-                        keywords: default, sonata, seo
-                        description: A default description
-
-    .. code-block:: php
-
-        // app/config/config.php
-        $container->loadFromExtension(
-            'sonata_seo', array(
-                'page' => array(
-                    'title' => 'A Default Title',
-                    'metas' => array(
-                        'names' => array(
-                            'keywords'    => 'default, key, other',
-                            'description' => 'A default description',
-                        ),
-                    ),
-                ),
-            ),
-        );
-
-The Standard Title and Description
-----------------------------------
+Defining a Title and Description Template
+-----------------------------------------
 
 Most of the times, the title of a site has a static and a dynamic part. For
-instance, "The title of the Page - Symfony". Here "- Symfony" is static and
+instance, "The title of the Page - Symfony". Here, "- Symfony" is static and
 "The title of the Page" will be replaced by the current title. It is of course
-not nice if you need to add this static part to all your titles in documents.
+not nice if you had to add this static part to all your titles in documents.
+
+That's why the CmfSeoBundle provides defining a title and description
+template. When using these settings, there are 2 placeholders available:
+``%content_title%`` and ``%content_description%``. These will be replaced with
+the title extracted from the content object and the description extracted from
+the content object.
+
+.. caution::
 
-That's why the CmfSeoBundle provides standard titles and descriptions. When
-using these settings, there are 2 placeholders available: ``%content_title%``
-and ``%content_description%``. This will be replaced with the title extracted
-from the content object and the description extracted from the content object.
+    The default title and description set by the SonataSeoBundle do override
+    this template. You should make sure that the defaults also follow the
+    template.
 
 For instance, to configure the titles of the symfony.com pages, you would do:
 
@@ -243,10 +215,10 @@ For instance, to configure the titles of the symfony.com pages, you would do:
     character, otherwise the container will try to replace it with the value
     of a container parameter.
 
-This syntax might look familiair if you have used with the Translation
-component before. And that's correct, under the hood the Translation component
-is used to replace the placeholders with the correct values. This also means
-you get Multi Language Support for free!
+This syntax might look familiar if you have used the Translation component
+before. And that's correct, under the hood the Translation component is used
+to replace the placeholders with the correct values. This also means you get
+Multi Language Support for free!
 
 For instance, you can do:
 
@@ -315,6 +287,11 @@ And then configure the translation messages:
             title:       "%content_title% | Default title"
             description: "Default description. %content_description%"
 
+.. tip::
+
+    You don't have to escape the percent characters here, since the
+    Translation loaders know how to deal with them.
+
 For changing the default translation domain (messages), you should use the
 ``cmf_seo.translation_domain`` setting:
 
diff --git a/bundles/seo/seo_aware.rst b/bundles/seo/seo_aware.rst
@@ -30,8 +30,16 @@ the ``SeoMetadata``::
         }
     }
 
-Now you can set some SEO data for this ``Page`` using the metadata. For
-instance inside a data fixture::
+Now you can set some SEO data for this ``Page`` using the metadata::
+
+    $page = new Page();
+    // ... set some page properties
+
+    $pageMetadata = new SeoMetadata();
+    $pageMetadata->setDescription('A special SEO description.');
+    $pageMetadata->setTags('seo, cmf, symfony');
+
+    $page->setSeoMetadata($pageMetadata);
 
     // src/Acme/SiteBundle/DataFixture/PHPCR/LoadPageData.php
     namespace Acme\SiteBundle\DataFixtures\PHPCR;
@@ -59,23 +67,14 @@ instance inside a data fixture::
         }
     }
 
-.. tip::
-
-    While this examples shows a Doctrine PHPCR ODM data fixture, the bundle
-    works fully storage agnostic. You can use it with every storage system you
-    like.
-
-Persisting the SeoMetadata with Doctrine
-----------------------------------------
+Doctrine PHPCR-ODM Integration
+------------------------------
 
-Since Doctrine doesn't allow you to persist an object as a database field,
-there is a problem. The bundle provides a solution to solve this by providing
-a Doctrine Listener. This listener will serialize the metadata object when
-persisting it and it'll unserialize the metadata when the object is fetched
-from the database.
+In order to easily persist the SeoMetadata when using Doctrine PHPCR-ODM, the
+SeoBundle provides a special ``SeoMetadata`` document with the correct
+mappings. This document should be mapped as a child of the content document.
 
-In order to use this listener, you should activate either ``orm`` or ``phpcr``
-as persisting layer for the SeoBundle:
+To be able to use this document, you have to enable the PHPCR persistence:
 
 .. configuration-block::
 
@@ -85,18 +84,13 @@ as persisting layer for the SeoBundle:
         cmf_seo:
             persistence:
                 phpcr: true
-                # when using the ORM:
-                # orm: true
 
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
         <config xmlns="http://cmf.symfony.com/schema/dic/seo">
             <persistence>
                 <phpcr />
-                <!-- when using the ORM:
-                <orm />
-                -->
             </persistence>
         </config>
 
@@ -106,45 +100,105 @@ as persisting layer for the SeoBundle:
         $container->loadFromExtension('cmf_seo', array(
             'persistence' => array(
                 'phpcr' => true,
-                // when using the ORM:
-                // 'orm' => true,
             ),
         ));
 
-This will automatically enable the listener. If you don't want to enable the
-listener, but you want to enable a persistence layer, you can set the
-``metadata_listener`` option to ``false``:
+.. tip::
+
+    This is not needed if you already enabled PHPCR on the ``cmf_core``
+    bundle. See :doc:`the CoreBundle docs <../core/persistence>` for more
+    information.
+
+After you've enabled PHPCR, map your seoMetadata as a child:
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        // src/Acme/SiteBundle/Document/Page.php
+        namespace Acme\SiteBundle\Document;
+
+        use Symfony\Cmf\Bundle\SeoBundle\Model\SeoAwareInterface;
+        use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;
+
+        /**
+         * @PHPCR\Document()
+         */
+        class Page implements SeoAwareInterface
+        {
+            /**
+             * @PHPCR\Child
+             */
+            protected $seoMetadata;
+
+            // ...
+        }
+
     .. code-block:: yaml
 
-        # app/config/config.yml
-        cmf_seo:
-            persistence:
+        # src/Acme/SiteBundle/Resources/config/doctrine/Page.odm.yml
+        Acme\SiteBundle\Document\Page:
+            # ...
+            child:
                 # ...
-            metadata_listener: false
+                seoMetadata: ~
 
     .. code-block:: xml
 
-        <!-- app/config/config.xml -->
-        <config xmlns="http://cmf.symfony.com/schema/dic/seo"
-            metadata-listener="false"
+        <!-- src/Acme/SiteBundle/Resources/config/doctrine/Page.odm.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <doctrine-mapping
+            xmlns="http://doctrine-project.org/schemas/phpcr-odm/phpcr-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://doctrine-project.org/schemas/phpcr-odm/phpcr-mapping
+            https://github.com/doctrine/phpcr-odm/raw/master/doctrine-phpcr-odm-mapping.xsd"
         >
-            <persistence>
+            <document name="Acme\SiteBundle\Document\Page">
                 <!-- ... -->
-            </persistence>
-        </config>
+                <child fieldName="seoMetadata" />
+            </document>
+        </doctrine-mapping>
 
-    .. code-block:: php
+And after that, you can use the
+``Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata`` document::
 
-        // app/config/config.php
-        $container->loadFromExtension('cmf_seo', array(
-            'persistence' => array(
-                // ...
-            ),
-            'metadata_listener' => false,
-        ));
+    // src/Acme/SiteBundle/DataFixture/PHPCR/LoadPageData.php
+    namespace Acme\SiteBundle\DataFixtures\PHPCR;
+
+    use Acme\SiteBundle\Document\Page;
+    use Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata;
+    use Doctrine\Common\Persistence\ObjectManager;
+    use Doctrine\Common\DataFixtures\FixtureInterface;
+
+    class LoadPageData implements FixtureInterface
+    {
+        public function load(ObjectManager $manager)
+        {
+            $page = new Page();
+            // ... set some page properties
+
+            $pageMetadata = new SeoMetadata();
+            $pageMetadata->setDescription('A special SEO description.');
+            $pageMetadata->setTags('seo, cmf, symfony');
+
+            $page->setSeoMetadata($pageMetadata);
+
+            $manager->persist($page);
+            $manager->flush();
+        }
+    }
+
+Doctrine ORM
+------------
+
+You can also use the Doctrine ORM with the CmfSeoBundle. You can just use the
+``Symfony\Cmf\Bundle\SeoBundle\Model\SeoMetadata`` class and map it as an
+object.
+
+You can also choose put the ``SeoMetadata`` class into a seperate table and
+adding a relation between the ``SeoMetadata`` class and the content entity. To
+do this, you have to enable ORM support just like you enabled PHPCR enabled
+above.
 
 Form Type
 ---------
@@ -159,3 +213,10 @@ 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 objec that implements the ``SeoAwareInterface`` in the Sonata Admin
 panel.
+
+.. note::
+
+    The bundles requires the `BurgovKeyValueFormBundle`_ when using the sonata
+    admin. Make sure you install and enable it.
+
+.. _`BurgovKeyValueFormBundle`: https://github.com/Burgov/KeyValueFormBundle

Original file line number	Diff line number	Diff line change
`@@ -6,3 +6,4 @@ SeoBundle`
`6`	`6`
`7`	`7`	`introduction`
`8`	`8`	`seo_aware`
	`9`	`+ extractors`