Merge pull request #830 from symfony-cmf/block-bundle

block documentation cleanup

Author: dbu

bundles/block/cache.rst

@@ -1,11 +1,11 @@
 Cache
 =====
 
-The Symfony2 CMF BlockBundle integrates with the `SonataCacheBundle`_ to
+The CmfBlockBundle integrates with the `SonataCacheBundle`_ to
 provide several caching solutions. Have a look at the available adapters in the
 `SonataCacheBundle`_ to see all options.
 
-The Symfony2 CMF BlockBundle additionally provides its own adapters for:
+The CmfBlockBundle additionally provides its own adapters for:
 
 * `ESI`_ (service: ``cmf.block.cache.varnish``)
 * `SSI`_ (service: ``cmf.block.cache.ssi``)
@@ -119,7 +119,7 @@ CmfBlockBundle and the SonataBlockBundle:
                     ),
                 ),
                 'blocks_by_class' => array(
-                    'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock' => array(
+                    Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock::class => array(
                             'cache' => 'symfony_cmf.block.cache.js_async',
                         ),
                     ),
@@ -133,8 +133,7 @@ When a block having a cache configured is rendered, the following process
 is triggered:
 
 * The document is loaded based on the name;
-* If caching is configured, the cache is checked and content is returned if
-  found.
+* The cache is checked and content is returned if found.
 
   * Cache keys are computed using:
 

bundles/block/configuration.rst

@@ -34,21 +34,6 @@ is the following configuration:
                     enabled:                  false
                     block_basepath:           /cms/content
                     manager_name:             ~
-                    string_document_class:    Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock
-                    simple_document_class:    Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock
-                    container_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock
-                    reference_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock
-                    action_document_class:    Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock
-                    slideshow_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock
-                    imagine_document_class:   Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock
-                    use_sonata_admin:         auto
-                    string_admin_class:       Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin
-                    simple_admin_class:       Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin
-                    container_admin_class:    Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin
-                    reference_admin_class:    Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin
-                    action_admin_class:       Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin
-                    slideshow_admin_class:    Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin
-                    imagine_admin_class:      Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin
 
     .. code-block:: xml
 
@@ -59,23 +44,8 @@ is the following configuration:
                 <persistence>
                     <phpcr
                         enabled="false"
-                        manager-name="null"
                         block-basepath="/cms/content"
-                        string-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock"
-                        simple-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock"
-                        container-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock"
-                        reference-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock"
-                        action-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock"
-                        slideshow-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock"
-                        imagine-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock"
-                        use-sonata-admin="auto"
-                        string-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin"
-                        simple-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin"
-                        container-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin"
-                        reference-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin"
-                        action-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin"
-                        slideshow-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin"
-                        imagine-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin"
+                        manager-name="null"
                     />
                 </persistence>
             </config>
@@ -90,21 +60,6 @@ is the following configuration:
                     'enabled'                  => false,
                     'block-basepath'           => '/cms/content',
                     'manager_name'             => null,
-                    'string_document_class'    => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock',
-                    'simple_document_class'    => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock',
-                    'container_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock',
-                    'reference_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock',
-                    'action_document_class'    => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock',
-                    'slideshow_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock',
-                    'imagine_document_class'   => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock',
-                    'use_sonata_admin'         => 'auto',
-                    'string_admin_class'       => 'Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin',
-                    'simple_admin_class'       => 'Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin',
-                    'container_admin_class'    => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin',
-                    'reference_admin_class'    => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin',
-                    'action_admin_class'       => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin',
-                    'slideshow_admin_class'    => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin',
-                    'imagine_admin_class'      => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin',
                 ),
             ),
         ));
@@ -130,123 +85,6 @@ the value of ``%cmf_core.persistence.phpcr.basepath%/content``.
 
 .. include:: ../_partials/persistence_phpcr_manager_name.rst.inc
 
-``string_document_class``
-"""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock``
-
-The string block document class.
-
-``simple_document_class``
-"""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock``
-
-The simple block document class.
-
-``container_document_class``
-""""""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock``
-
-The container block document class.
-
-``reference_document_class``
-""""""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock``
-
-The reference block document class.
-
-``action_document_class``
-"""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock``
-
-The action block document class.
-
-If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in
-``Resources/config/admin.xml``.
-
-``slideshow_document_class``
-""""""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock``
-
-The slideshow block document class.
-
-``imagine_document_class``
-""""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock``
-
-The imagine block document class. This document will only work properly if
-you set up the LiipImagineBundle.
-
-``use_sonata_admin``
-""""""""""""""""""""
-
-**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``
-
-If ``true``, the admin classes are activated. If set to ``auto``, they are
-activated only if the SonataPhpcrAdminBundle is present.
-
-If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to the value
-of ``cmf_core.persistence.phpcr.use_sonata_admin``.
-
-``string_admin_class``
-""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin``
-
-The sonata admin class of the string block.
-
-``simple_admin_class``
-""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin``
-
-The sonata admin class of the simple block.
-
-``container_admin_class``
-"""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin``
-
-The sonata admin class of the container block.
-
-``reference_admin_class``
-"""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin``
-
-The sonata admin class of the reference block.
-
-``action_admin_class``
-""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin``
-
-The sonata admin class of the action block.
-
-``slideshow_admin_class``
-"""""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin``
-
-The sonata admin class of the slideshow block.
-
-This admin will only be loaded if ``use_imagine`` is enabled.
-
-``imagine_admin_class``
-"""""""""""""""""""""""
-
-**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin``
-
-The sonata admin class of the imagine block.
-
-This admin will only be loaded if ``use_imagine`` is enabled.
-
 ``twig``
 ~~~~~~~~
 
@@ -275,14 +113,6 @@ The part before the actual path to the block.
 
 The part after the actual path to the block.
 
-``use_imagine``
-~~~~~~~~~~~~~~~
-
-**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``
-
-If ``true``, the imagine related block classes and admin classes are activated.
-If set to ``auto``, they are activated only if the LiipImagineBundle is present.
-
 ``caches``
 ~~~~~~~~~~
 

bundles/block/create_your_own_blocks.rst

@@ -21,13 +21,13 @@ duplication, so instead you decide to create your own block, the ``RssBlock``.
     the CmfBlockBundle, but this one is more powerful as it allows to define a
     specific feed URL per block instance.
 
-Create a block document
+Create a Block Document
 -----------------------
 
 The first thing you need is a document that contains the options and indicates
 the location where the RSS feed should be shown. The easiest way is to extend
 ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\AbstractBlock``, but you are
-free to do create your own document. At least, you have to implement
+free to do create your own document as long as it implements
 ``Sonata\BlockBundle\Model\BlockInterface``. In your document, you
 need to define the ``getType`` method which returns the type name of your block,
 for instance ``rss_block``::
@@ -292,9 +292,8 @@ 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_,
-    rather than having individual ``<link>`` and ``<script>`` tags for each
-    single file.
+    into a single Stylesheet and a single JavaScript file, rather than having
+    individual ``<link>`` and ``<script>`` tags for each single file.
 
 Register the Block Service
 --------------------------
@@ -345,5 +344,3 @@ handles, as per the ``getType`` method of the block. The second argument is the
             ))
             ->addTag('sonata.block')
         ;
-
-.. _Assetic: https://symfony.com/doc/current/cookbook/assetic/asset_management.html

bundles/block/introduction.rst

@@ -9,8 +9,8 @@ BlockBundle
     manage fragments of content, so-called blocks, that are persisted in a
     database and can be incorporated into any page layout.
 
-The CmfBlockBundle also provides a few commonly used standard blocks,
-including the ability to edit them. See :doc:`types`.
+The CmfBlockBundle also provides a few commonly used standard blocks.
+See :doc:`types`.
 
 Installation
 ------------
@@ -151,6 +151,8 @@ specific settings for one of the block classes.
     :ref:`Block Sonata Admin Extension <bundles-block-types-admin_extension>`
     that adds editing of the ``BaseBlock`` general block options.
 
+.. _bundle-block-updated-sonata-defaults:
+
 Updated SonataBlockBundle Defaults
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -193,7 +195,7 @@ your block in the repository. You can do so with the following code snippet::
 
     $dm->persist($myBlock);
 
-Note the ``sidebarBlock`` is the identifier we chose for the block. Together
+The name ``sidebarBlock`` is the identifier we chose for the block. Together
 with the parent document of the block, this defines the unique identifier of
 the block. The other properties (title and body) are specific to the
 ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock``.
@@ -293,12 +295,11 @@ Embedding Blocks in WYSIWYG Content
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The CmfBlockBundle provides a Twig filter ``cmf_embed_blocks`` that
-looks through the content and looks for special tags to render blocks. To use
-the tag, you need to apply the ``cmf_embed_blocks`` filter to your output. If
-you can, render your blocks directly in the template. This feature is only a
-cheap solution for web editors to place blocks anywhere in their HTML content.
-A better solution to build composed pages is to build it from blocks (there
-might be a CMF bundle at some point for this).
+scans through a content and looks for special tags to render blocks. To use
+the tag, you need to apply the ``cmf_embed_blocks`` filter to your output. This
+feature is a rather hacky solution for web editors to place blocks anywhere in
+their HTML content. If you can, render your blocks directly in the template.
+A better solution would be to build composed pages is to build it from blocks.
 
 .. configuration-block::
 
@@ -317,9 +318,6 @@ might be a CMF bundle at some point for this).
     Make sure to only place this filter where you display the content and not
     where editing it, as otherwise your users would start to edit the rendered
     output of their blocks.
-    This feature conflicts with the front-end editing provided by CreateBundle,
-    as create.js operates on the rendered content as displayed to the user.
-    There is an ongoing `discussion how to fix this`_.
 
 When you apply the filter, your users can use this tag to embed a block in
 their content:
@@ -389,22 +387,10 @@ See also the :ref:`the configuration reference <reference-config-block-twig-cmf-
     block and returns an empty string for each failed block instead. The errors
     are logged at level WARNING.
 
-SonataAdminBundle Integration
------------------------------
-
-The BlockBundle also provides Admin classes to enable creating, editing and
-removing blocks from the admin panel. To enable the admin, use the
-``cmf_block.persistence.phpcr.use_sonata_admin`` setting. Both the
-:ref:`BlockBundle <bundles-block-types-admin_extension>` and
-:ref:`CoreBundle <bundles-core-persistence>` provide several extensions for
-SonataAdminBundle.
-
 Examples
 --------
 
 You can find example usages of this bundle in the `Symfony CMF Sandbox`_
-(have a look at the BlockBundle). It also shows you how to make blocks
-editable using the :doc:`CreateBundle <../create/introduction>`.
 
 Read on
 -------
@@ -420,4 +406,3 @@ Read on
 .. _`Symfony CMF Sandbox`: https://github.com/symfony-cmf/cmf-sandbox
 .. _`prepended configuration`: https://symfony.com/doc/current/components/dependency_injection/compilation.html#prepending-configuration-passed-to-the-extension
 .. _`SonataBlockBundle`: https://github.com/sonata-project/SonataBlockBundle
-.. _`discussion how to fix this`: https://github.com/symfony-cmf/block-bundle/issues/143

bundles/block/relation_to_sonata_block_bundle.rst

@@ -1,7 +1,7 @@
 Relation to Sonata Block Bundle
 ===============================
 
-The Symfony2 CMF BlockBundle is based on the `SonataBlockBundle`_.  It replaces
+The Symfony CMF BlockBundle is based on the `SonataBlockBundle`_.  It replaces
 components of the SonataBlockBundle where needed to be compatible with PHPCR.
 
 Class Diagram