Merge remote-tracking branch 'origin/1.2'

Conflicts:
	book/routing.rst
	bundles/create/developing-hallo.rst

Author: dbu

book/database_layer.rst

@@ -131,7 +131,7 @@ class via annotations:
 
     .. code-block:: yaml
 
-        # src/Acme/TaskBundle/Resources/config/doctrine/Task.odm.yml
+        # src/Acme/TaskBundle/Resources/config/doctrine/Task.phpcr.yml
         Acme\TaskBundle\Document\Task:
             id: id
 
@@ -143,7 +143,7 @@ class via annotations:
 
     .. code-block:: xml
 
-        <!-- src/Acme/TaskBundle/Resources/config/doctrine/Task.odm.xml -->
+        <!-- src/Acme/TaskBundle/Resources/config/doctrine/Task.phpcr.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping
             xmlns="http://doctrine-project.org/schemas/phpcr-odm/phpcr-mapping"
@@ -261,7 +261,7 @@ you've configured a route to display a specific task by name::
     public function showAction($name)
     {
         $repository = $this->get('doctrine_phpcr')->getRepository('AcmeTaskBundle:Task');
-        $task = $repository->find('/task/'.$name);
+        $task = $repository->find('/tasks/'.$name);
 
         if (!$task) {
             throw $this->createNotFoundException('No task found with name '.$name);

book/installation.rst

@@ -96,9 +96,17 @@ dependencies, use the ``install`` command:
 
     $ composer install
 
+To try out things, you can accept the default values for all questions you are
+asked about the parameters.yml. Revisit that file later when you know more
+about Jackalope.
+
+Setup
+-----
+
+You are almost there. A few more steps need to be done to be ready.
 
 Set up the Database
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 The next step is to set up the database. If you want to use SQLite as your
 database backend just go ahead and run the following:
@@ -115,7 +123,20 @@ folder, containing the database content. The two commands after it will setup
 PHPCR and the final command will load some fixtures, so you can access the
 Standard Edition using a web server.
 
-The project should now be accessible on your web server. If you have PHP 5.4
+Preparing Assetic
+~~~~~~~~~~~~~~~~~
+
+To use the frontend editing in ``prod`` environment, you need to tell Assetic
+to dump the assets to the filesystem:
+
+.. code-block:: bash
+
+    $ php app/console --env=prod assetic:dump
+
+Configure a Webserver
+~~~~~~~~~~~~~~~~~~~~~
+
+The project is now ready to be served by your web server. If you have PHP 5.4
 installed you can alternatively use the PHP internal web server:
 
 .. code-block:: bash
@@ -128,7 +149,6 @@ And then access the CMF via:
 
     http://localhost:8000
 
-
 If you run an Apache installation as described in the `Symfony cookbook article on setup`_,
 your URL will look like this:
 

book/routing.rst

@@ -478,8 +478,10 @@ follows::
             $content = new StaticContent();
             $content->setParentDocument($dm->find(null, '/cms/content'));
             $content->setName('my-content');
+            $content->setTitle('My Content');
+            $content->setBody('Some Content');
             $dm->persist($content);
-            $route->setRouteContent($content);
+            $route->setContent($content);
 
             // now define an id parameter; do not forget the leading slash if you
             // want /projects/{id} and not /projects{id}
@@ -505,7 +507,7 @@ also ``/projects`` as there is a default for the id parameter.
     doing it in a fixture like this).
 
 Because you defined the ``{id}`` route parameter, your controller can expect an
-``$id`` parameter. Additionally, because you called ``setRouteContent`` on the
+``$id`` parameter. Additionally, because you called ``setContent`` on the
 route, your controller can expect the ``$contentDocument`` parameter.
 The content could be used to define an intro section that is the same for each
 project or other shared data. If you don't need content, you can just not set it

bundles/block/create_your_own_blocks.rst

@@ -136,7 +136,7 @@ that knows how to fetch the feed data of an ``RssBlock``::
         public function execute(BlockContextInterface $blockContext, Response $response = null)
         {
             $block = $blockContext->getBlock();
-            
+
             if (!$block->getEnabled()) {
                 return new Response();
             }
@@ -145,7 +145,7 @@ that knows how to fetch the feed data of an ``RssBlock``::
             $settings = $blockContext->getSettings();
             $resolver = new OptionsResolver();
             $resolver->setDefaults($settings);
-            $settings = $resolver->resolve($block->getOptions());
+            $settings = $resolver->resolve($block->getSettings());
 
             $feeds = false;
             if ($settings['url']) {
@@ -291,7 +291,7 @@ on the current page:
 
     This mechanism is not recommended. For optimal load times, it is better
     to have a central assets definition for your project and aggregate them
-    into a single Stylesheet and a single JavaScript file, e.g. with assetic_,
+    into a single Stylesheet and a single JavaScript file, e.g. with Assetic_,
     rather than having individual ``<link>`` and ``<script>`` tags for each
     single file.
 
@@ -341,4 +341,4 @@ handles, as per the ``getType`` method of the block. The second argument is the
             ->addTag('sonata.block')
         ;
 
-.. _assetic: http://symfony.com/doc/current/cookbook/assetic/asset_management.html
+.. _Assetic: http://symfony.com/doc/current/cookbook/assetic/asset_management.html

bundles/create/developing-hallo.rst

@@ -34,10 +34,10 @@ To use this template, specify ``hallo-coffee`` as editor in the
             ))
         ) ?>
 
-The hallo-coffee template uses assetic to load the coffee script files from
+The hallo-coffee template uses Assetic to load the coffee script files from
 ``Resources/public/vendor/hallo/src``, rather than the pre-compiled JavaScript
 from ``Resources/public/vendor/create/deps/hallo-min.js``. This also means
-that you need to add a mapping for coffeescript in your assetic configuration
+that you need to add a mapping for coffeescript in your Assetic configuration
 and you need the `coffee compiler set up correctly`_.
 
 .. configuration-block::

bundles/create/introduction.rst

@@ -194,8 +194,8 @@ You also need to configure the FOSRestBundle to handle json:
         ));
 
 If you want to use Assetic to combine the CSS and JavaScript used for
-create.js, you need to enable the CreateBundle in the assetic configuration.
-Find the configuration for ``assetic.bundles``. If it is not present, assetic
+create.js, you need to enable the CreateBundle in the Assetic configuration.
+Find the configuration for ``assetic.bundles``. If it is not present, Assetic
 automatically scans all bundles for assets and you don't need to do anything.
 If you limit the bundles, you need to add ``CmfCreateBundle`` to the list of
 bundles.
@@ -227,6 +227,14 @@ bundles.
             ),
         ));
 
+If you were not using Assetic previously, you need to call the ``assetic:dump``
+command in your deployment process, or the Javascript and CSS files will not be
+found:
+
+.. code-block:: bash
+
+    $ php app/console --env=prod assetic:dump
+
 Routing
 ~~~~~~~
 
@@ -256,7 +264,7 @@ routing configuration to enable the REST end point for saving content:
         $collection->addCollection($loader->import("@CmfCreateBundle/Resources/config/routing/rest.xml"));
 
         return $collection;
-        
+
 .. tip::
 
     If you don't want these routes to be prefixed by the current locale, you can
@@ -350,7 +358,7 @@ after those to be able to customize as needed) with:
 
 .. caution::
 
-    Make sure assetic is rewriting the paths in your CSS files properly or you
+    Make sure Assetic is rewriting the paths in your CSS files properly or you
     might not see icon images.
 
 In your page bottom area, load the JavaScript files. If you are using Symfony 2.2 or

bundles/seo/configuration.rst

@@ -100,9 +100,11 @@ Can be one of ``canonical`` or ``redirect``.
 
 **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
-required when the RoutingBundle is not enabled, otherwise it defaults to
-``DynamicRouter::CONTENT_KEY`` (which evaluates to ``contentDocument``).
+The name of the request attribute which contains the content object. This is
+used by the ContentListener to exctract SEO information automatically. If the
+RoutingBundle is present, this defaults to ``DynamicRouter::CONTENT_KEY``
+(which evaluates to ``contentDocument``), otherwise you must define this
+manually.
 
 ``sonata_admin_extension``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

bundles/seo/introduction.rst

@@ -32,6 +32,15 @@ Both the CmfSeoBundle and SonataSeoBundle must be registered in the
 Usage
 ~~~~~
 
+SEO data tracks some or all of the following:
+
+* The title;
+* The meta keywords;
+* The meta description;
+* The original URL (when more than one URL contains the same content).
+* Anything else that uses the ``<meta>`` tag with the ``property``, ``name``
+  or ``http-equiv`` type (e.g. Open Graph data).
+
 The simplest use of this bundle would be to just set some configuration to the
 ``sonata_seo`` configuration section and use the twig helper in your templates.
 
@@ -62,8 +71,12 @@ The simplest use of this bundle would be to just set some configuration to the
                 ),
             ),
         ));
-    
-The only thing to do now is to use the twig helper in your templates:
+
+This sets default values for the ``SeoPage`` value object. You can later update
+that object with more precise information. It is available as service
+``sonata.seo.page.default``.
+
+To render the information, use the following twig functions in your templates:
 
 .. code-block:: html+jinja
 
@@ -80,54 +93,73 @@ The only thing to do now is to use the twig helper in your templates:
         </body>
     </html>
 
-This will render a page with the default title ("Page's default title") as
-title element. The information defined for description and keywords will go
-into the correct metatags.
+This will render the last title set on the ``SeoPage`` ("Page's default title"
+if you did not add calls to the value object in your code). The information
+added for description and keywords will render as ``<meta>`` HTML tags.
 
 .. seealso::
 
     To get a deeper look into the SonataSeoBundle, you should visit the
     `Sonata documentation`_.
 
-Using SeoMetadata
------------------
+Using the CmfSeoBundle
+----------------------
 
 The basic example shown above works perfectly without the CmfSeoBundle. The
-CmfSeoBundle provides more extension points to configure the SEO data with
-data from the document (e.g. a ``StaticContent`` document). This is done by
-using SEO metadata. This is SEO data which will be used for a particular
-document. This metadata can hold:
+CmfSeoBundle provides extension points to extract the SEO data from
+content documents, e.g. a ``StaticContent``, along with utility systems
+to automatically extract the information.
 
-* The title;
-* The meta keywords;
-* The meta description;
-* The original URL (when more than one URL contains the same content).
-* Anything else that uses the ``<meta>`` tag with the ``property``, ``name``
-  or ``http-equiv`` type (e.g. Open Graph data).
+The process is:
+
+1. The content listener checks for a document in the request
+2. It invokes ``SeoPresentationInterface::updateSeoPage``
+3. The presentation checks of the document provides a ``SeoMetadata`` value
+   object and runs the metadata extractors.
+4. The presentation updates the Sonata ``SeoPage`` with the gathered meta data.
+
+.. _bundles-seo-content-listener:
 
-The content object is retrieved from the request attributes. By default, it
-uses the ``DynamicRouter::CONTENT_KEY`` constant when the
-:doc:`RoutingBundle <../routing/introduction>` is installed. To change this,
-or if you don't use the RoutingBundle, you can configure it with
+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``.
+
+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``.
-This bundle provides two ways of using this metadata:
+
+Extracting Metadata
+~~~~~~~~~~~~~~~~~~~
+
+A service implementing ``SeoPresentationInterface`` is responsible for
+determining metadata from an object and updating the Sonata ``SeoPage`` with that
+information. A default implementation is provided as ``cmf_seo.presentation``.
+
+Defining Metadata
+~~~~~~~~~~~~~~~~~
+
+This bundle provides two ways to define metadata on objects:
 
 #. Implementing the ``SeoAwareInterface`` and persisting the ``SeoMetadata``
    with the object.
-#. Using the extractors, to extract the ``SeoMetadata`` from already existing
-   values (e.g. the title of the page).
+#. Using ``ExtractorInterface`` instances, to extract the ``SeoMetadata`` from
+   already existing values (e.g. the title of the page).
 
 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.
+of the post and any additional tags set by the editor.
 
-Persisting the ``SeoMetadata`` with the document makes it easy to edit for the
-admin, while using the extractors are perfect to easily use values from the
-displayed content.
+Persisting the ``SeoMetadata`` with the document makes it easy to override SEO
+information for the editor, while using the extractors adds the convenience
+that values from the normal content of the document can be reused.
 
-Both ways are documented in detail in separate sections:
+Both methods are documented in detail in separate sections:
 
 * :doc:`seo_aware`
 * :doc:`extractors`

components/routing/dynamic.rst

@@ -201,7 +201,7 @@ for your content in three ways:
 * Or provide an implementation of ``ContentRepositoryInterface`` and pass the id
   of the content object as parameter ``content_id`` and ``null`` as $name.
 
-If you want to implement your own generator for ``$name``s that are not
+If you want to implement your own generator for ``$name`` values that are not
 strings, you need to implement the ``ChainedRouterInterface`` and implement the
 ``supports($name)`` method to tell the ``ChainRouter`` if your router can
 accept this ``$name`` to generate a URL.

cookbook/editions/cmf_sandbox.rst

@@ -158,7 +158,7 @@ The sandbox should now be accessible on your web server.
     http://localhost/app_dev.php
 
 In order to run the sandbox in production mode you need to generate the
-doctrine proxies and dump the assetic assets:
+doctrine proxies and dump the Assetic assets:
 
 .. code-block:: text