reworking the create documentation

Author: dbu

bundles/create/introduction.rst

@@ -22,6 +22,36 @@ the lightweight `hallo.js`_ editor bundled with the create.js distribution.
 your HTML for `create.js`_ and map back from the JSON-LD sent by backbone.js
 to your model classes.
 
+Concepts
+--------
+
+CreatePHP uses `RDFa`_ metadata about your model classes. This metadata is
+used to map between your model and the RDFa information. If you know Doctrine,
+you have seen the idea of metadata to know how class fields map to database
+columns.
+
+The CreatePHP metadata is modelled by the ``Type`` class. CreatePHP provides
+metadata loaders that read XML, php arrays and one that just introspects
+objects and creates non-semantical metadata that will be enough for create.js
+to edit.
+
+An ``RdfMapper`` is used to translate between your storage layer and CreatePHP.
+It is passed the model instance and the relevant metadata object.
+
+With the metadata and the twig helper, the content is rendered with RDFa
+annotations. create.js is loaded and enables editing the content. Note that
+you may have several objects editable on a single page. Save operations happen
+through backbone.js with ajax calls containing JSON-LD data. There is one
+request per editable content that was actually modified. The CreateBundle REST
+controller handles those ajax calls and maps the JSON-LD data back onto your
+model classes and stores them in the database.
+
+For image support, CKEditor can use elfinder to upload, browse and insert
+images into the content. See the
+:doc:`MediaBundle elfinder adapter documentation<../media/adapters/elfinder>`
+to enable this powerful image browser.
+
+
 .. index:: CreateBundle
 
 Dependencies
@@ -136,7 +166,7 @@ You also need to configure the FOSRestBundle to handle json:
 Routing
 ~~~~~~~
 
-Finally, you need to register the routing configuration file to your master
+You need to register the routing configuration file in your main
 routing configuration to enable the REST end point for saving content:
 
 .. configuration-block::
@@ -159,155 +189,68 @@ routing configuration to enable the REST end point for saving content:
 
         return $collection;
 
-Access Control
-~~~~~~~~~~~~~~
-
-In order to limit who can edit content, the provided controllers as well as the
-javascript loader check if the current user is granted the configured
-``cmf_create.role``. By default the role is ROLE_ADMIN.
-
-If you need more fine grained access control, look into the CreatePHP
-``RdfMapperInterface`` ``isEditable`` method.  You can extend a mapper and
-overwrite ``isEditable`` to answer whether the passed domain object is
-editable.
-
-Concepts
---------
-
-CreatePHP uses `RDFa`_ metadata about your model classes. If you know Doctrine,
-you should be familiar with this concept, as Doctrine uses such metadata to
-know how your class fields map to database columns.
-
-The metadata is modelled by the ``Type`` class. CreatePHP provides metadata
-loaders that read XML, php arrays and one that just introspects objects and
-creates non-semantical metadata that will be enough for create.js to edit.
-
-An ``RdfMapper`` is used to translate between your storage layer and CreatePHP.
-It is passed the model instance and the relevant metadata object.
-
-With the metadata and the twig helper, the content is rendered with RDFa
-annotations. create.js is loaded and enables editing the content. Note that
-you may have several objects editable on a single page. Save operations happen
-through backbone.js with ajax calls containing JSON-LD data. There is one
-request per editable content that was actually modified. The CreateBundle REST
-controller handles those ajax calls and maps the JSON-LD data back onto your
-model classes and stores them in the database.
-
-For image support, CKEditor can use elfinder to upload, browse and insert
-images into the content. See the
-:doc:`MediaBundle elfinder adapter documentation<../media/adapters/elfinder>`
-to enable this powerful image browser.
-
-Metadata
-~~~~~~~~
-
-CreatePHP needs metadata information for each class of your domain model. By
-default, the create bundle uses the XML metadata driver and looks for metadata
-in every bundles at ``<Bundle>/Resources/rdf-mappings``. If you use a third
-party bundle that does not come with RDFa mapping, you can simply include a
-mapping file for it in any of your bundles, or specify a directory containing
-mapping files with the ``rdf_config_dirs`` option.
-
-The mapping file name needs to be the fully qualified class name of your model
-class, having the backslash (``\\``) replaced by a dot (``.``), i.e.
-``Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml``.
-
-A basic mapping look as follows:
+If you have the :doc:`MediaBundle <../media/index>` present in your project as well, you
+additionally need to register the route for the image upload handler:
 
 .. configuration-block::
 
-    .. code-block:: xml
-
-        <!-- Resources/rdf-mappings/Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml -->
-        <type
-                xmlns:schema="http://schema.org/"
-                typeof="schema:WebPage"
-                >
-            <children>
-                <property property="schema:headline" identifier="title"/>
-                <property property="schema:text" identifier="body" />
-            </children>
-        </type>
-
-The most relevant parts are the ``property`` telling the RDF type, and the
-``identifier`` telling the field of the class you map. If you use namespaces
-like schema.org, your annotations will actually make semantically sense. But
-you can also ignore this and use your own annotations, as long as you declare
-the namespaces you use.
-
-.. tip::
-
-    You need to clear the cache when adding a new mapping XML file, even in
-    the dev environment. The CreateBundle caches where it found mapping files
-    to avoid scanning all folders on every request. Once a file is known, edits
-    will be picked automatically, without the need to clear the cache again.
-
-You can additionally specify the HTML tag to be used when automatically
-rendering this field (see below). The default tag is ``div``. And you can
-specify additional HTML attributes like the ``class`` attribute. A full example
-reads like this:
+    .. code-block:: yaml
 
-.. configuration-block::
+        create_image:
+            resource: "@CmfCreateBundle/Resources/config/routing/image.xml"
 
     .. code-block:: xml
 
-        <!-- Resources/rdf-mappings/Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml -->
-        <type
-                xmlns:schema="http://schema.org/"
-                typeof="schema:WebPage"
-                >
-            <children>
-                <property property="schema:headline" identifier="title" tag-name="h1"/>
-                <property property="schema:text" identifier="body">
-                    <attribute key="class" value="my-css-class"/>
-                </property>
-            </children>
-        </type>
+        <import resource="@CmfCreateBundle/Resources/config/routing/image.xml" />
 
-.. note::
+    .. code-block:: php
 
-    The metadata support in CreatePHP is not as powerful as in Doctrine. There
-    are currently no drivers for annotation or yml mappings. Mappings are not
-    inherited from a parent class but need to be repeated each time. And the
-    mapping file must include the full namespace in the filename to be found.
+        use Symfony\Component\Routing\RouteCollection;
 
-    All of these issues will hopefully be fixed in later versions if people
-    step up and contribute pull requests.
+        $collection = new RouteCollection();
+        $collection->addCollection($loader->import("@CmfCreateBundle/Resources/config/routing/image.xml"));
 
-Mapping Requests to Objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        return $collection;
 
-In version 1.0, the CreateBundle only provides a service to map to Doctrine
-PHPCR-ODM. If you do not enable the phpcr persistence layer, you need to
-configure the ``cmf_create.object_mapper_service_id``.
+Access Control
+~~~~~~~~~~~~~~
+
+In order to limit who can edit content, the provided controllers as well as the
+javascript loader check if the current user is granted the configured
+``cmf_create.role``. By default the role is ``ROLE_ADMIN``.
 
 .. tip::
 
-    Doctrine ORM support is coming soon. There is an open pull request on the
-    CreatePHP library to add such a mapper. This mapper will also be provided
-    as a service by the CreateBundle 1.1.
+    In order to have security in place, you need to configure a
+    "Symfony2 firewall". Read more in the `Symfony2 security chapter`_.
 
-CreatePHP would support specific mappers per RDFa type. If you need that, dig
-into the CreatePHP and CreateBundle and do a pull request to enable this feature.
+If you need more fine grained access control, look into the CreatePHP
+``RdfMapperInterface`` ``isEditable`` method.  You can extend a mapper and
+overwrite ``isEditable`` to answer whether the passed domain object is
+editable.
 
-.. _bundle-create-usage-embed:
+Load create.js Javascript and CSS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Rendering Content
------------------
+This bundle provides templates that load the required Javascript and CSS files
+based on Assetic. The Javascript loader also parametrizes the configuration
+for create.js and the chosen editor.
 
-Rendering the content for create.js consists of adjusting how you output your
-model classes and of loading the necessary javascript and css files.
+Alternatively, you can of course use your own templates to include the assets
+needed by create.js.
 
 In the page header, include the base CSS files (and add your own CSS files
-after those to be able to customize as needed) with
+after those to be able to customize as needed) with:
+
+.. configuration-block::
 
-.. code-block:: jinja
+    .. code-block:: jinja
 
-    {% include "CmfCreateBundle::includecssfiles.html.twig" %}
+        {% include "CmfCreateBundle::includecssfiles.html.twig" %}
 
-.. code-block:: php
+    .. code-block:: php
 
-    <?php echo $view->render("CmfCreateBundle::includecssfiles.html.twig"); ?>
+        <?php echo $view->render("CmfCreateBundle::includecssfiles.html.twig"); ?>
 
 .. caution::
 
@@ -357,16 +300,27 @@ For Symfony 2.1, the syntax is:
     configuration further, you will need to use a
     :ref:`custom template to load the editor<bundle-create-custom>`.
 
-If you provided RDFa mappings for your model classes as explained above, you
-can now adjust your templates to render the RDFa annotations so that create.js
-knows what content is editable.
 
-To render your model named ``page`` with a handle you call ``rdf``, use the
+.. _bundle-create-usage-embed:
+
+Rendering Content
+-----------------
+
+Create.js needs to identify what is editable in your content. To do this,
+it needs the RDF attributes in the HTML. Now that everything is prepared,
+you need to adjust your templates to output that information.
+
+.. note::
+
+    If you use custom models that did not come with RDFa mapping files, see
+    the remainder of this page to learn how to define the mappings.
+
+To render your model named ``cmfMainContent`` with a handle you call ``rdf``, use the
 ``createphp`` twig tag as follows:
 
 .. code-block:: html+jinja
 
-    {% createphp page as="rdf" noautotag %}
+    {% createphp cmfMainContent as="rdf" noautotag %}
     <div {{ createphp_attributes(rdf) }}>
         <h1 class="my-title" {{ createphp_attributes( rdf.title ) }}>{{ createphp_content( rdf.title ) }}</h1>
         <div {{ createphp_attributes( rdf.body ) }}>{{ createphp_content( rdf.body ) }}</div>
@@ -386,7 +340,7 @@ automatically:
 
 .. code-block:: html+jinja
 
-    {% createphp page as="rdf" %}
+    {% createphp cmfMainContent as="rdf" %}
     {{ rdf|raw }}
     {% endcreatephp %}
 
@@ -396,10 +350,106 @@ replace the default ``<div>`` tag with your own choice. And using an
 ``<attribute>`` child to specify CSS classes, you can let CreatePHP generate
 your HTML structure if you want.
 
+Metadata
+--------
+
+CreatePHP needs metadata information for each class of your domain model. By
+default, the create bundle uses the XML metadata driver and looks for metadata
+in every bundles at ``<Bundle>/Resources/rdf-mappings``. If you use a third
+party bundle that does not come with RDFa mapping, you can simply include a
+mapping file for it in any of your bundles, or specify a directory containing
+mapping files with the ``rdf_config_dirs`` option.
+
+The mapping file name needs to be the fully qualified class name of your model
+class, having the backslash (``\\``) replaced by a dot (``.``), i.e.
+``Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml``.
+
+A basic mapping look as follows:
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- Resources/rdf-mappings/Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml -->
+        <type
+                xmlns:schema="http://schema.org/"
+                typeof="schema:WebPage"
+                >
+            <children>
+                <property property="schema:headline" identifier="title"/>
+                <property property="schema:text" identifier="body" />
+            </children>
+        </type>
+
+The most relevant parts are the ``property`` telling the RDF type, and the
+``identifier`` telling the field of the class you map. If you use namespaces
+like schema.org, your annotations will actually make semantically sense. But
+you can also ignore this and use your own annotations, as long as you declare
+the namespaces you use.
+
+.. tip::
+
+    You need to clear the cache when adding a new mapping XML file, even in
+    the dev environment. The CreateBundle caches where it found mapping files
+    to avoid scanning all folders on every request. Once a file is known, edits
+    will be picked automatically, without the need to clear the cache again.
+
+You can additionally specify the HTML tag to be used when automatically
+rendering this field (see below). The default tag is ``div``. And you can
+specify additional HTML attributes like the ``class`` attribute. A full example
+reads like this:
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- Resources/rdf-mappings/Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml -->
+        <type
+                xmlns:schema="http://schema.org/"
+                typeof="schema:WebPage"
+                >
+            <children>
+                <property property="schema:headline" identifier="title" tag-name="h1"/>
+                <property property="schema:text" identifier="body">
+                    <attribute key="class" value="my-css-class"/>
+                </property>
+            </children>
+        </type>
+
+.. note::
+
+    The metadata support in CreatePHP is not as powerful as in Doctrine. There
+    are currently no drivers for annotation or yml mappings. Mappings are not
+    inherited from a parent class but need to be repeated each time. And the
+    mapping file must include the full namespace in the filename to be found.
+
+    All of these issues will hopefully be fixed in later versions if people
+    step up and contribute pull requests.
+
+Mapping Requests to Domain Model
+--------------------------------
+
+One last piece is the mapping between CreatePHP data and the application
+domain model. Data needs to be stored back into the database.
+
+In version 1.0, the CreateBundle only provides a service to map to Doctrine
+PHPCR-ODM. If you do not enable the phpcr persistence layer, you need to
+configure the ``cmf_create.object_mapper_service_id``.
+
+.. tip::
+
+    Doctrine ORM support is coming soon. There is an open pull request on the
+    CreatePHP library to add such a mapper. This mapper will also be provided
+    as a service by the CreateBundle 1.1.
+
+CreatePHP would support specific mappers per RDFa type. If you need that, dig
+into the CreatePHP and CreateBundle and do a pull request to enable this feature.
+
 
 .. _`create.js`: http://createjs.org
 .. _`hallo.js`: http://hallojs.org
 .. _`CreatePHP`: https://github.com/flack/createphp
 .. _`with composer`: http://getcomposer.org
 .. _`symfony-cmf/create-bundle`: https://packagist.org/packages/symfony-cmf/create-bundle
 .. _`RDFa`: http://en.wikipedia.org/wiki/RDFa
+.. _`Symfony2 security chapter`: http://symfony.com/doc/current/book/security.html