diff --git a/bundles/block/cache.rst b/bundles/block/cache.rst index 73adf9fd..9dd53f9a 100644 --- a/bundles/block/cache.rst +++ b/bundles/block/cache.rst @@ -1,13 +1,11 @@ Cache ===== -.. include:: ../_outdate-caution.rst.inc +The Symfony2 CMF BlockBundle integrates with the `SonataCacheBundle`_ to +provide several caching solutions. Have a look at the available adapters in the +`SonataCacheBundle`_ to see all options. -The BlockBundle integrates with the `SonataCacheBundle`_ to provide several -caching solutions. Have a look at the available adapters in the -SonataCacheBundle to see all options. - -The BlockBundle additionally provides its own adapters for: +The Symfony2 CMF BlockBundle additionally provides its own adapters for: * `ESI`_ * `SSI`_ @@ -58,7 +56,8 @@ CmfBlockBundle and the SonataBlockBundle: + prefix="/" + /> .. code-block:: php @@ -74,70 +73,82 @@ CmfBlockBundle and the SonataBlockBundle: 3. *SonataBlockBundle* - Use the ``sonata_block`` key to configure the cache adapter for each block service: - .. configuration-block:: + .. configuration-block:: - .. code-block:: yaml + .. code-block:: yaml - # app/config/config.yml - sonata_block: - # ... - blocks: - acme_main.block.news: - # use the service id of the cache adapter - cache: cmf.block.cache.js_async - blocks_by_class: - # cache only the RssBlock and not all action blocks - Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock: + # app/config/config.yml + sonata_block: + # ... + blocks: + symfony_cmf.block.action: + # use the service id of the cache adapter cache: cmf.block.cache.js_async + blocks_by_class: + # cache only the RssBlock and not all action blocks + Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock: + cache: cmf.block.cache.js_async - .. code-block:: xml + .. code-block:: xml - - - + + + - + - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('sonata_block', array( - 'blocks' => array( - 'symfony_cmf.block.action' => array( - // use the service id of the cache adapter - 'cache' => 'symfony_cmf.block.cache.js_async', - ), - ), - )); + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('sonata_block', array( + 'blocks' => array( + 'symfony_cmf.block.action' => array( + // use the service id of the cache adapter + 'cache' => 'symfony_cmf.block.cache.js_async', + ), + ), + 'blocks_by_class' => array( + 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock' => array( + 'cache' => 'symfony_cmf.block.cache.js_async', + ), + ), + ), + )); Workflow -------- -The following happens when a block is rendered using cache: +When a block having a cache configured is rendered, the following process +is triggered: -* A document is loaded based on the name +* The document is loaded based on the name; * If caching is configured, the cache is checked and content is returned if - found + found. * Cache keys are computed using: - * The cache keys of the block service - * The extraCacheKeys passed from the template + * The cache keys of the block service; + * The extraCacheKeys passed from the template. - * The cache adapter is asked for a cache element + * The cache adapter is asked for a cache element: * The ESI and SSI adapter add a specific tag and a url to retrieve the - block content - * The Javascript adapter adds javascript and a url to retrieve the block - content + block content; + * The javascript adapter adds javascript and a url to retrieve the block + content. - * If the cache element is not expired and has data it is returned + * If the cache element is not expired and has data it is returned. * The template is rendered: * For ESI and SSI the url is called to retrieve the block content @@ -150,45 +161,47 @@ The following happens when a block is rendered using cache: cache is found, have a look at the ``has`` method of the adapters in the SonataCacheBundle to see how they respond. -If cache is checked and the cache adapter returned that no cache was found, +If the cache is checked and the cache adapter returned that no cache was found, the workflow proceeds like this: -* Each block document also has a block service, the execute method of it is - called to render the block and return a response -* If the response is cacheable the configured adapter creates a cache element, - it contains +* The block service is asked to render the block + :ref:`as usual `; +* If the ``Response`` is cacheable, the configured adapter creates a cache + element containing: - * The computed cache keys - * The ttl of the response - * The response - * And additional contextual keys + * The computed cache keys; + * The time to live (TTL) of the response; + * The ``Response``; + * Any additional contextual keys. -* The template is rendered +* The template is rendered. Cache Keys ---------- -The block service has the responsibility to generate the cache keys, the -method ``getCacheKeys`` returns these keys, see :ref:`bundle-block-service`. +It is the responsibility of the :ref:`block service ` to generate the cache keys in +the method ``getCacheKeys``. -The block services shipped with the BlockBunde use the ``getCacheKeys`` method -of the ``Sonata\BlockBundle\Block\BaseBlockService``, and return: +The block services shipped with the Symfony CMF BlockBunde use the +``getCacheKeys`` method of the ``Sonata\BlockBundle\Block\BaseBlockService`` +which returns: * ``block_id`` * ``updated_at`` -.. note:: +.. caution:: - If block settings need to be persisted between requests it is advised to - store them in the block document. Alternatively they can be added to the - cache keys. However be very cautious because, depending on the adapter, - the cache keys can be send to the browser and are not secure. + If block settings need to be persisted between requests, it is advised to + store them in the block document. If you add them to the cache keys, you + have to be aware that depending on the adapter, the cache keys can be sent + to the browser and thus are neither hidden nor safe from manipulation by a + client. Extra Cache Keys ~~~~~~~~~~~~~~~~ The extra cache keys array is used to store metadata along the cache element. -The metadata can be used to invalidate a set of cache elements. +The metadata can be used to invalidate a set of cached elements. Contextual Keys ~~~~~~~~~~~~~~~ @@ -196,9 +209,12 @@ Contextual Keys The contextual cache array hold the object class and id used inside the template. This contextual cache array is then added to the extra cache key. -This feature can be use like this ``$cacheManager->remove(array('objectId' => 'id'))``. +This feature can be use like this:: + + $cacheManager->remove(array('objectId' => 'id')); -Of course not all cache adapters support this feature, varnish and MongoDB do. +While not all cache adapters support this feature, the Varnish and MongoDB +adapters do. The BlockBundle also has a cache invalidation listener that calls the ``flush`` method of a cache adapter automatically when a cached block document @@ -235,7 +251,7 @@ your Twig template when using cache: ), )) ?> -When using the Esi, Ssi or Js cache adapters the settings passed here are remembered: +When using the Esi, Ssi or Js cache adapters, the settings passed here are remembered: .. configuration-block:: @@ -269,9 +285,9 @@ also the `SonataBlockBundle Advanced usage`_ documentation. .. caution:: - Because, as mentioned above, settings can be added to the url as parameters - avoid exposing sensitive settings from ``sonata_block_render`` and try to - store them in the block document. + Because, as mentioned above, settings can be added to the URL as + parameters, you have to avoid exposing sensitive settings from + ``sonata_block_render`` and store them in the block document instead. Adapters -------- diff --git a/bundles/block/create_your_own_blocks.rst b/bundles/block/create_your_own_blocks.rst index 40f2ec46..817b05eb 100644 --- a/bundles/block/create_your_own_blocks.rst +++ b/bundles/block/create_your_own_blocks.rst @@ -1,30 +1,35 @@ Create your own Blocks ====================== -.. include:: ../_outdate-caution.rst.inc - Follow these steps to create a block: -* create a block document; -* create a block service and declare it (optional); -* create a data object representing your block in the repository, see +* define a block document class; +* if needed, create a block service and declare it (optional); +* instantiate a data object representing your block in the repository, see :ref:`bundle-block-document`; * render the block, see :ref:`bundle-block-rendering`; Lets say you are working on a project where you have to integrate data received from several RSS feeds. Of course you could create an ActionBlock -for each of these feeds, but wouldn't this be silly? In fact all those actions +for each of these feeds, but wouldn't this be silly? In fact, all those actions would look similar: Receive data from a feed, sanitize it and pass the data to -a template. So instead you decide to create your own block, the RSSBlock. +a template. So instead you decide to create your own block, the ``RssBlock``. + +.. tip:: + + In this example, we create an ``RssBlock``. This particular block type + already exists in the Symfony2 CMF BlockBundle, so you can also look at + the end result if you want. Create a block document ----------------------- -The first thing you need is an document that contains the data. It is -recommended to extend ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\AbstractBlock`` -contained in this bundle (however you are not forced to do so, as long as you -implement ``Sonata\BlockBundle\Model\BlockInterface``). In your document, you -need to define the ``getType`` method which just returns ``acme_main.block.rss``. +The first thing you need is an document that holds the data. It is +recommended to extend ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\AbstractBlock``. +You are of course free to do your own document, but need to at least implement +``Sonata\BlockBundle\Model\BlockInterface``. In your document, you +need to define the ``getType`` method which returns the type name of your block, +for instance ``acme_main.block.rss``. .. code-block:: php @@ -51,33 +56,56 @@ Create a Block Service ---------------------- You could choose to use a an already existing block service because the -configuration and logic already satisfy your needs. For our rss block we -create a service that knows how to handle RSSBlocks: +configuration and logic already satisfy your needs. For our RSS block we +create a service that knows how to handle ``RssBlocks``: * The method ``setDefaultSettings`` configures a template, title, url and the maximum amount of items:: - // ... - public function setDefaultSettings(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'template' => 'AcmeMainBundle::Block::block_rss.html.twig', - 'url' => false, - 'title' => 'Insert the rss title', - 'maxItems' => 10, - )); - } - // ... + use Symfony\Component\OptionsResolver\OptionsResolverInterface; + use Symfony\Component\HttpFoundation\Response; + use Sonata\BlockBundle\Block\BaseBlockService; + use Sonata\BlockBundle\Block\BlockContextInterface; + + class RssBlockService extends extends BaseBlockService + { + // ... + public function setDefaultSettings(OptionsResolverInterface $resolver) + { + $resolver->setDefaults(array( + 'template' => 'AcmeMainBundle::Block::block_rss.html.twig', + 'url' => false, + 'title' => 'Feed items', + 'maxItems' => 10, + )); + } + // ... -* The execute method passes the settings to an rss reader service and forwards -* The feed items to a template, see :ref:`bundle-block-execute` + public function execute(BlockContextInterface $blockContext, Response $response = null) + { + /** @var $block RssBlock */ + $block = $blockContext->getBlock(); + + if (!$block->getEnabled()) { + return new Response(); + } + + $requestParams = $block->resolveRequestParams($this->request, $blockContext); + + return new Response($this->renderer->render(new ControllerReference( + 'acme_main.controller.rss:block', + $requestParams + ) + )); + } + } -Make sure you implement the interface -``Sonata\BlockBundle\Block\BlockServiceInterface`` or an existing block -service like ``Sonata\BlockBundle\Block\BaseBlockService``. +The execute method passes the settings to an RSS reader service and forwards +the feed items to a template. (See :ref:`bundle-block-execute` for more on the +block service ``execute`` method). -Define the service in a config file. It is important to tag your BlockService -with ``sonata.block``, otherwise it will not be known by the Bundle. +Define the service in a configuration file. It is important to tag your BlockService +with ``sonata.block`` to make it known to the SonataBlockBundle. .. configuration-block:: @@ -116,13 +144,15 @@ with ``sonata.block``, otherwise it will not be known by the Bundle. $container->register('acme_main.rss_reader', 'Acme\MainBundle\Feed\SimpleReader'); - $container->addDefinition('sandbox_main.block.rss', new Definition( - 'Acme\MainBundle\Block\RssBlockService', - array( - 'acme_main.block.rss', - new Reference('templating'), - new Reference('sonata.block.renderer'), - new Reference('acme_main.rss_reader'), - ) - )) - ->addTag('sonata.block'); + $container + ->addDefinition('sandbox_main.block.rss', new Definition( + 'Acme\MainBundle\Block\RssBlockService', + array( + 'acme_main.block.rss', + new Reference('templating'), + new Reference('sonata.block.renderer'), + new Reference('acme_main.rss_reader'), + ) + )) + ->addTag('sonata.block') + ; diff --git a/bundles/block/introduction.rst b/bundles/block/introduction.rst index d0f5c4cb..dc98a1f9 100644 --- a/bundles/block/introduction.rst +++ b/bundles/block/introduction.rst @@ -9,8 +9,8 @@ The BlockBundle manage fragments of content, so-called blocks, that are persisted in a database and can be incorporated into any page layout. -The BlockBundle also provides a few commonly used standard blocks, including the -ability to edit them. See :doc:`types`. +The Symfony2 CMF BlockBundle also provides a few commonly used standard blocks, +including the ability to edit them. See :doc:`types`. Installation ------------ @@ -26,10 +26,10 @@ Usage ----- The default settings of a block are defined in the block service. If you use a -3rd party block you might want to alter these for your application. Use the +third party block, you might want to alter these for your application. Use the ``sonata_block`` key for this. You can define default settings for a block -service type or more specific for a block class. The later is usefull as a -block service can be used by multiple block classes and sometimes you only want +service type or more specific for a block class. The later is useful when you +are using the same block service for multiple block classes but you only want specific settings for one of the block classes. .. configuration-block:: @@ -45,7 +45,7 @@ specific settings for one of the block classes. blocks_by_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock: settings: - maxItems: 3 + maxItems: 5 .. code-block:: xml @@ -55,8 +55,11 @@ specific settings for one of the block classes. - 3 + 3 + + 5 + @@ -66,55 +69,48 @@ specific settings for one of the block classes. $container->loadFromExtension('sonata_block', array( 'blocks' => array( 'acme_main.block.rss' => array( - 'settings' => 3, + 'settings' => array( + 'maxItems' => 3, + ), + ), + ), + 'blocks_by_class' => array( + 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock' => array( + 'settings' => array( + 'maxItems' => 5, + ), ), ), )); -If you want to make the base fields (f.e. the TTL for caching) of your -block document based on ``BaseBlock`` editable, just use the existing -admin extension by adding the following lines to your sonata admin -configuration ``sonata_admin``. Admin extensions allow you to add or -change features of one or more Admin instances. Read more about -`Sonata Admin Extensions`_ for more details. - -.. configuration-block:: +.. tip:: - .. code-block:: yaml + You can also store settings in the single block objects themselves. This + allows to individually configure options per block instance. - # app/config/config.yml - sonata_admin: - extensions: - cmf.block.admin.base.extension: - extends: - - Symfony\Cmf\Bundle\BlockBundle\Document\BaseBlock + If you edit the blocks using the Sonata admin, there is also the + :ref:`Block Sonata Admin Extension ` + that adds editing of the ``BaseBlock`` general block options. - .. code-block:: xml +Updated SonataBlockBundle Defaults +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - +The BlockBundle *automatically* changes some defaults and adds configuration +to the `SonataBlockBundle`_ to make it work nicely. This is done using the +`prepended configuration`_ option of Symfony. The following defaults are +updated: - - - Symfony\Cmf\Bundle\BlockBundle\Document\BaseBlock - - - +* **templates.block_base** the cmf base template wraps the block output in + a div and dashifies the PHPCR path as id; The base template is + kept compatible with the Sonata base template for non-cmf blocks; +* **RssBlock configuration** adds the + :ref:`default RssBlock settings `. - .. code-block:: php +.. note:: - // app/config/config.php - $container->loadFromExtension('sonata_admin', array( - 'extensions' => array( - 'cmf.block.admin.base.extension' => array( - 'extends' => array( - 'Symfony\Cmf\Bundle\BlockBundle\Document\BaseBlock', - ), - ), - ), - )); + Settings are only prepended, meaning the default value is changed. You can + still change the values by setting the configuration values in your + application configuration file. .. _bundle-block-document: @@ -137,8 +133,8 @@ your block in the repository. You can do so with the following code snippet:: $documentManager->persist($myBlock); Note the ``sidebarBlock`` is the identifier we chose for the block. Together -with the parent document of the block, this makes the block unique. The other -properties are specific to +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``. The simple block is now ready to be rendered, see @@ -146,9 +142,9 @@ The simple block is now ready to be rendered, see .. note:: - Always make sure you implement the interface - ``Sonata\BlockBundle\Model\BlockInterface`` or an existing block document - like ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\AbstractBlock``. + Make sure to always have your blocks implement the interface + ``Sonata\BlockBundle\Model\BlockInterface`` or extend an existing block + document like ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\AbstractBlock``. Block Context ------------- @@ -156,7 +152,7 @@ Block Context The BlockContext contains all information and the block document needed to render the block. It aggregates and merges all settings from configuration, the block service, the block document and settings passed to the twig template -helper. Therefore use the BlockContext to get or alter a setting if needed. +helper. Therefore, use the BlockContext to get or alter a setting if needed. .. _bundle-block-service: @@ -176,13 +172,13 @@ A block service contains: * Javascript and stylesheet assets to be loaded; * A load method. -Take a look at the block services in ``Symfony\Cmf\Bundle\BlockBundle\Block`` -to see some examples. +The block services provided by the Symfony2 CMF BlockBundle are in the +namespace ``Symfony\Cmf\Bundle\BlockBundle\Block``. .. note:: Always make sure you implement the interface - ``Sonata\BlockBundle\Block\BlockServiceInterface`` or an existing block + ``Sonata\BlockBundle\Block\BlockServiceInterface`` or extend a block service like ``Sonata\BlockBundle\Block\BaseBlockService``. .. _bundle-block-execute: @@ -190,7 +186,7 @@ to see some examples. The Execute Method ~~~~~~~~~~~~~~~~~~ -This method contains ``controller`` logic:: +This method of a block service contains *controller* logic:: // ... if ($block->getEnabled()) { @@ -209,23 +205,23 @@ This method contains ``controller`` logic:: .. note:: - If you have much logic to be used, you can move that to a specific service - and inject it in the block service. Then use this specific service in the - execute method. + If you need complex logic to handle a block, it is recommended to move that + logic into a dedicated service and inject that service into the block + service and call it in the ``execute`` method. Default Settings ~~~~~~~~~~~~~~~~ The method ``setDefaultSettings`` specifies the default settings for a block. -Settings can be altered on multiple places afterwards, it cascades like this: +Settings can be altered in multiple places afterwards, cascading as follows: * Default settings are stored in the block service; * If you use a 3rd party bundle you might want to change them in the bundle configuration for your application see :ref:`bundle-block-configuration`; * Settings can be altered through template helpers (see example); * And settings can also be altered in a block document, the advantage is that - settings are stored in PHPCR and allows to implement a frontend or backend UI - to change some or all settings. + settings are stored in the database and are individual to the specific block + instead of all blocks of a type. Example of how settings can be specified through a template helper: @@ -262,7 +258,7 @@ Javascript and Stylesheets ~~~~~~~~~~~~~~~~~~~~~~~~~~ The methods ``getJavascripts`` and ``getStylesheets`` can be used to define -javascript and stylesheet assets. Use the twig helpers +javascript and stylesheet assets needed by a block. Use the twig helpers ``sonata_block_include_javascripts`` and ``sonata_block_include_stylesheets`` to render them: @@ -309,9 +305,9 @@ the following code to your Twig template: 'name' => '/cms/content/blocks/sidebarBlock', )) ?> -In this example we specify an absolute path, however, if the block is a child -of a content document, then you can simply specify the **name** of the block -as follows: +In this example, we specify an absolute path. However, if the block is the +child of a content document, then you can simply specify the **name** of the +block as follows: .. configuration-block:: @@ -325,63 +321,27 @@ as follows: 'name' => 'sidebarBlock', )) ?> -This will make the BlockBundle render the specified block on every page that -has a child block document named ``sidebarBlock``. Of course, the actual page -needs to be rendered by the template that contains the snippet above. +This will make the BlockBundle render the specified block if the main content +(as per the :ref:`routing `) maps a field named +``sidebarBlock``. If different main contents are rendered using different +templates, make sure all that should support this block actually include the +snippet above. -When a block is rendered the following things happen: +When a block being rendered, the following things happen: * The block document is loaded based on its name or absolute path; * If caching is configured, the cache is checked and content is returned if found; -* The ``execute`` method of the corresponding block service is called. +* Otherwise, the ``execute`` method of the corresponding block service is + called. -The execute method is the equivalent of a normal Symfony controller. It +The ``execute`` method is the equivalent of a normal Symfony controller. It receives the block object (equivalent to a Request object) and a ``Response`` object. The purpose of the ``execute`` method to set the content of the response object - typically by rendering a Twig template. -You can also :ref:`embed blocks in content ` using the -``cmf_embed_blocks`` filter. - -Block types ------------ - -The block bundle comes with a couple of predefined blocks. You may write -your own blocks, but often, the supplied implementations will be sufficient. -This is just a quick overview, more details on each block type can be found -in the :doc:`Block Types ` section. - -There are five general purpose blocks: - -* **StringBlock**: A block only containing a string that is rendered without - any decoration. Useful for page fragments; -* **SimpleBlock**: A simple block with nothing but a title and a field of - hypertext. This would usually be what an editor edits directly, for example - contact information; -* **ContainerBlock**: A block that contains zero, one or many child blocks; -* **ReferenceBlock**: A block that references a block stored somewhere else in - the content tree. For example you might want; to refer parts of the contact - information from the homepage -* **ActionBlock**: A block that calls a Symfony2 action. - -The BlockBundle also provides a couple of blocks for specific tasks, -integrating third party libraries. You should to read the :doc:`types` section -relevant to those blocks to figure out what third party libraries you need to -load into your project. - -* **RssBlock**: This block extends the ``ActionBlock``, the block document - saves the feed url and the controller action fetches the feed items. The - default implementation uses the `EkoFeedBundle - `_ to read the feed items. - -* **ImagineBlock**: A block containing an image child, the imagine filter name - and optional link url and title. - -* **SlideshowBlock**: A special case of a container block suitable for building - a slideshow of blocks. Note that this block doesn't provide any Javascript - code to make the slideshow work in the frontend. You can use your favourite - Javascript library to do the animation. +You can also :ref:`embed blocks in WYSIWYG content ` +using the ``cmf_embed_blocks`` filter. Examples -------- @@ -390,8 +350,15 @@ 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>`. +Read on +------- + +* :doc:`types` +* :doc:`create_your_own_blocks` +* :doc:`cache` +* :doc:`relation_to_sonata_block_bundle` + .. _`Packagist`: https://packagist.org/packages/symfony-cmf/block-bundle .. _`Symfony CMF Sandbox`: https://github.com/symfony-cmf/cmf-sandbox .. _`prepended configuration`: http://symfony.com/doc/current/components/dependency_injection/compilation.html#prepending-configuration-passed-to-the-extension .. _`SonataBlockBundle`: https://github.com/sonata-project/SonataBlockBundle -.. _`Sonata Admin Extensions`: http://sonata-project.org/bundles/admin/master/doc/reference/extensions.html diff --git a/bundles/block/relation_to_sonata_block_bundle.rst b/bundles/block/relation_to_sonata_block_bundle.rst index d7c5ae89..5cdffac8 100644 --- a/bundles/block/relation_to_sonata_block_bundle.rst +++ b/bundles/block/relation_to_sonata_block_bundle.rst @@ -1,15 +1,14 @@ Relation to Sonata Block Bundle =============================== -.. include:: ../_outdate-caution.rst.inc - -The BlockBundle is based on the `SonataBlockBundle`_. It replaces components -of the bundle where needed to be compatible with PHPCR. +The Symfony2 CMF BlockBundle is based on the `SonataBlockBundle`_. It replaces +components of the SonataBlockBundle where needed to be compatible with PHPCR. Classdiagram ------------ -The following picture shows where we use our own components (blue): +The following diagram shows the components the Symfony CMF BlockBundle replaces +in blue color: .. image:: ../../_images/bundles/classdiagram.jpg :align: center diff --git a/bundles/block/types.rst b/bundles/block/types.rst index c62ba39e..e1080ac4 100644 --- a/bundles/block/types.rst +++ b/bundles/block/types.rst @@ -1,13 +1,14 @@ Block Types =========== -.. include:: ../_outdate-caution.rst.inc - The BlockBundle provides a couple of default block types for general use cases. It also has a couple of more specific blocks that integrate third party libraries. Those can be handy for some use cases and also serve as examples to build your own blocks. +You can also :doc:`create your own blocks `, but +the provided block types should cover many standard cases. + Common Behaviour ---------------- @@ -23,23 +24,89 @@ The ``AbstractBlock`` implements the write interfaces for publishable and publis period, see the :ref:`publish workflow documentation ` for more information. +Sonata Admin +~~~~~~~~~~~~ + +All block types provided by the Symfony2 CMF BlockBundle come with a admin +classes for :doc:`../doctrine_phpcr_admin`. To activate the admin services, +it is enough to load the SonataDoctrinePhpcrAdminBundle in your application +kernel and configure the sonata dashboard as desired. + +.. _bundles-block-types-admin_extension: + +Sonata Admin Extension for Basic Block Settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This bundle also provides a sonata admin *extension* that you can activate. +It adds a tab to edit settings of basic block options like the time to life +(TTL, for caching purposes). + +Assuming your blocks extend the ``BaseBlock`` class (as all blocks provided by +the CMF BlockBundle do), you can add the following lines to your sonata admin +configuration. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + sonata_admin: + extensions: + cmf.block.admin.base.extension: + extends: + - Symfony\Cmf\Bundle\BlockBundle\Model\BaseBlock + + .. code-block:: xml + + + + + + + + Symfony\Cmf\Bundle\BlockBundle\Model\BaseBlock + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('sonata_admin', array( + 'extensions' => array( + 'cmf.block.admin.base.extension' => array( + 'extends' => array( + 'Symfony\Cmf\Bundle\BlockBundle\Model\BaseBlock', + ), + ), + ), + )); + +.. note:: + + Admin extensions are a way to configure editing of common features on several + ``Admin`` classes without needing them to extend each other. If you want to + learn more about them, please read on in `Sonata Admin Extensions`_ for more + details. + +.. _bundle-block-updated-sonata-defaults: + + StringBlock ----------- This is a very simple block that just provides one string field called ``body`` and the default template renders the content as ``raw`` to allow HTML in the field. The template outputs no HTML tags around the string -at all. +at all. This can be useful for editable page fragments. SimpleBlock ----------- Just a text block with a ``title`` and a ``body``. The default template -renders both title and content as ``raw``, meaning HTML is allowed in those -fields. - -This block also exists in a MultilangSimpleBlock variant that can be -translated. +renders both title and body with the twig ``raw`` filter, meaning HTML is +allowed in those fields. This block is useful to edit static text fragments and for example display it in several places using the ``ReferenceBlock``. @@ -48,7 +115,9 @@ ContainerBlock -------------- A container can hold a list of arbitrary child blocks (even other -``ContainerBlocks``) and just renders one child after the other. +``ContainerBlocks``) and just renders one child after the other. The list can +also be empty, in which case only the wrapping element of the container block +will be rendered. This block has the methods ``setChildren`` to overwrite the current children with a new list and ``addChild`` and ``removeChild`` to individually @@ -57,9 +126,9 @@ add resp. remove child blocks. ReferenceBlock -------------- -This block has no content of its own but points to a target block. -When rendered, this block renders the target node as if the target -node was directly used in that place. +This block has no content of its own, but points to a target block. +When rendered, this block renders the target block as if the target +block was directly used in that place. This block simply has the method ``setReferencedBlock`` that accepts any block mapped by the persistence layer as argument. If you set this to @@ -70,28 +139,29 @@ ActionBlock ----------- The action block allows to configure a controller action that will be called -in a subrequest when rendering the block. Instead of directly calling the -action from a template, your CMS users can define and parametrize their own -actions, and decide where to put this block. +in a `sub-request`_ when rendering the block. Instead of directly calling the +action from a template, your CMS users can define and parametrize what action +to call, and decide where they want to put this block. -This block is also a good base to implement specific actions if you need +This block is also a good base to implement specific actions, if you want something more user friendly. See the ``RssBlock`` below for an example. -As the ``ActionBlock`` does a subrequest, you may also need to control the -parameters that are passed to the subrequest. The block service calls +As the ``ActionBlock`` does a sub-request, you may also need to control the +parameters that are passed to the sub-request. The block service calls ``resolveRequestParams($request, $blockContext)`` to let the block decide -what needs to be passed to the subrequest. The ActionBlock implementation -lets you configure the fields with ``setRequestParams`` and persists them -in the database. It does not matter whether the field is found in the -request attributes or the request parameters, it is found in both by using +what needs to be passed to the sub-request. The ``ActionBlock`` lets you +configure the fields with ``setRequestParams`` and persists them in the +database. It does not matter whether the field is found in the request +attributes or the request parameters, it is found in both by using ``$request->get()``. The only request attribute propagated by default is the ``_locale``. RssBlock -------- -The RssBlock extends the ActionBlock and allows you to read feed items and -display them in a list. +The ``RssBlock`` extends the ``ActionBlock`` and allows you to read feed items and +display them in a list. It depends on the ``eko/feedbundle`` which you need to add +to your ``composer.json`` and instantiate in the ``AppKernel``. Create a document:: @@ -110,7 +180,7 @@ Create a document:: .. _bundle-block-rss-settings: -All available settings are: +The available settings are: * **url**: the url of the rss feed (*required*) * **title**: the title for the list (*default*: Insert the rss title) @@ -121,7 +191,7 @@ All available settings are: * **ItemClass**: the class used for the item objects that are passed to the template (*default*: ``Symfony\Cmf\Bundle\BlockBundle\Model\FeedItem``) -The controller to get the feed items can also be changed: +The controller used to fetch the feed items can also be changed: * Define a different class for the controller service in your configuration using the DI service parameter ``cmf_block.rss_controller_class`` @@ -129,18 +199,19 @@ The controller to get the feed items can also be changed: .. note:: - The `Symfony CMF Sandbox`_ contains an example of the RssBlock. + The `Symfony CMF Sandbox`_ contains an example of the ``RssBlock``. ImagineBlock ------------ The imagine block uses the `LiipImagineBundle`_ to display images directly out of PHPCR. The block has a child of type -``Symfony\Cmf\Bundle\MediaBundle\ImageInterface`` and fields for the name of -the imagine filter to use, an URL and an image caption. To use this block, you -need to add ``liip/imagine-bundle`` to your ``composer.json`` and define the -imagine filter you specify in the block. The default name is ``cmf_block``. The -filter must use the ``cmf_media_doctrine_phpcr`` driver: +``Symfony\Cmf\Bundle\MediaBundle\ImageInterface`` for the image, and fields for +the name of the imagine filter to use, an URL and an image caption. To use this +block, you need to add ``liip/imagine-bundle`` to your ``composer.json`` and +define the imagine filter you specify in the block. The default name is +``cmf_block``. The filter must use the ``cmf_media_doctrine_phpcr`` driver if +you use the PHPCR-ODM ``ImagineBlock``: .. configuration-block:: @@ -191,22 +262,22 @@ filter must use the ``cmf_media_doctrine_phpcr`` driver: ), )); -The ImagineBlock uses the template ``BlockBundle:Block:block_imagine.html.twig`` -template to render the layout. You may override this one if special markup is -needed. +The ``ImagineBlock`` uses the template ``BlockBundle:Block:block_imagine.html.twig`` +to render the layout. You may override this or configure a different template if +you need a specific markup. -Refer to the `LiipImagineBundle documentation`_ for further information. - -See the example below for how to create an ``ImagineBlock`` programmatically. +See also the example below for how to create an ``ImagineBlock`` programmatically. +Please refer to the `LiipImagineBundle documentation`_ for further information. SlideshowBlock -------------- -The ``SlideshowBlock`` is just a special kind of ``ContainerBlock``. It -can contain any kind of blocks that will be rendered with a wrapper div -to help a javascript slideshow library to slide them. +The ``SlideshowBlock`` is a special kind of ``ContainerBlock``. It can contain +any kind of blocks that will be rendered with a wrapper div to help a +javascript slideshow library to slide them. + The ``ImagineBlock`` is particularly suited if you want to do an image -slideshow but the ``SlideshowBlock`` can handle any kind of blocks, also mixed +slideshow, but the ``SlideshowBlock`` can handle any kind of blocks, also mixed types of blocks in the same slideshow. .. note:: @@ -218,9 +289,9 @@ types of blocks in the same slideshow. Create your first Slideshow ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Creating a slideshow consists of creating the container ``SlideshowBlock`` and -adding blocks to it. Those blocks can be anything, but an image makes a lot -of sense:: +Building a slideshow consists of creating the container ``SlideshowBlock`` and +adding blocks to it. Those blocks can be any kind of blocks, but the +``ImagineBlock`` makes a lot of sense:: use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock; use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock; @@ -247,9 +318,9 @@ of sense:: Render the slideshow ~~~~~~~~~~~~~~~~~~~~ -Rendering your slideshow is as easy as just rendering the according block -in your template. If your ``contentDocument`` has a field ``slideshow`` that -contains a ``SlideshowBlock`` object, you can simply render it with: +Rendering your slideshow simply means rendering the ``SlideshowBlock`` in your +template. If your ``contentDocument`` has a field ``slideshow`` that contains +a ``SlideshowBlock`` object, you can render it with: .. configuration-block:: @@ -269,17 +340,17 @@ Make the slideshow work in the frontend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since the BlockBundle doesn't contain anything to make the slideshow work -in the frontend, you need to do this yourself. Just use your favourite JS +in the frontend, you need to do this yourself. Use your favourite javascript library to make the slideshow interactive. If special markup is needed for -your slideshow code to work, just override -``BlockBundle:Block:block_slideshow.html.twig`` or the templates of the +your slideshow code to work, you can override +``BlockBundle:Block:block_slideshow.html.twig`` and/or the templates of the blocks you use as slideshow items and adapt them to your needs. Use the Sonata admin class ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The BlockBundle comes with an admin class for managing slideshow blocks. All -you need to do to administrate slideshows in your project is to add the +The BlockBundle comes with a sonata admin class for managing slideshow blocks. +All you need to do to administrate slideshows in your project is to add the following line to your sonata admin configuration: .. configuration-block:: @@ -333,5 +404,7 @@ for further information. .. _`Symfony CMF Sandbox`: https://github.com/symfony-cmf/cmf-sandbox .. _`Sonata Admin documentation`: http://sonata-project.org/bundles/admin/master/doc/reference/form_types.html +.. _`Sonata Admin Extensions`: http://sonata-project.org/bundles/admin/master/doc/reference/extensions.html .. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle .. _`LiipImagineBundle documentation`: https://github.com/liip/LiipImagineBundle/tree/master/Resources/doc +.. _`sub-request`: http://symfony.com/doc/current/book/internals.html#internal-requests \ No newline at end of file diff --git a/bundles/routing/dynamic.rst b/bundles/routing/dynamic.rst index a9dedcef..0ace7176 100644 --- a/bundles/routing/dynamic.rst +++ b/bundles/routing/dynamic.rst @@ -48,6 +48,8 @@ your own routers. ), )); +.. _bundle-routing-dynamic-match: + Match Process ~~~~~~~~~~~~~ diff --git a/cookbook/using_blockbundle_and_contentbundle.rst b/cookbook/using_blockbundle_and_contentbundle.rst index fa605821..8997043b 100644 --- a/cookbook/using_blockbundle_and_contentbundle.rst +++ b/cookbook/using_blockbundle_and_contentbundle.rst @@ -371,7 +371,7 @@ sample block, so create the ``LoadBlockWithCmfParent.php`` class:: use Symfony\Component\DependencyInjection\ContainerInterface; use PHPCR\Util\NodeHelper; use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock; - use Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent; + use Symfony\Cmf\Bundle\ContentBundle\Doctrine\Phpcr\StaticContent; class LoadBlockWithCmfParent extends AbstractFixture implements ContainerAwareInterface { @@ -389,7 +389,7 @@ sample block, so create the ``LoadBlockWithCmfParent.php`` class:: $document->setPath($basepath . '/blocks'); $manager->persist($document); - // Create a new SimpleBlock (see http://symfony.com/doc/master/cmf/bundles/block.html#block-types) + // Create a new SimpleBlock $myBlock = new SimpleBlock(); $myBlock->setParentDocument($document); $myBlock->setName('testBlock'); @@ -411,9 +411,9 @@ This class creates an example content page using the CMF ContentBundle. It then loads our example block as before, using the new content page as its parent. -By default, the base path for the content is ``/cms/content/static``. To show -how it can be configured to any path, add the following, optional entry to -your ``config.yml``: +By default, the base path for the content is ``/cms/content``. To show how it +can be configured to any path, add the following, optional entry to your +``config.yml``: .. configuration-block:: @@ -421,7 +421,7 @@ your ``config.yml``: # app/config/config.yml cmf_content: - static_basepath: /content + content_basepath: /content Now it should be possible to load in the above fixtures: diff --git a/reference/configuration/block.rst b/reference/configuration/block.rst index 505c7459..34030852 100644 --- a/reference/configuration/block.rst +++ b/reference/configuration/block.rst @@ -6,6 +6,11 @@ configured under the ``cmf_block`` key in your application configuration. When using XML, you can use the ``http://cmf.symfony.com/schema/dic/block`` namespace. +The BlockBundle *automatically* changes some defaults and adds configuration +to the SonataBlockBundle to make the integration work seamlessly. See the +:ref:`updated SonataBlockBundle defaults ` +for more information. + Configuration ------------- @@ -30,19 +35,19 @@ 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 - string_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock 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 - string_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin slideshow_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin imagine_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin @@ -57,19 +62,19 @@ is the following configuration: 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" - string-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock" 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" - string-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin" slideshow-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin" imagine-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin" /> @@ -86,19 +91,19 @@ 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', - 'string_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock', 'slideshow_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock', 'imagine_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock', - 'use_sonata_admin:' => 'auto', + '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', - 'string_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin', 'slideshow_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin', 'imagine_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin', ), @@ -178,40 +183,38 @@ retrieve the default manager. If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to the value of ``cmf_core.persistence.phpcr.manager_name``. +string_document_class +""""""""""""""""""""" + +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock`` + +The string block document class. + simple_document_class """"""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock`` The simple block document class. -If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in -``Resources/config/admin.xml``. - container_document_class """""""""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock`` The container block document class. -If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in -``Resources/config/admin.xml``. - reference_document_class """""""""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock`` The reference block document class. -If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in -``Resources/config/admin.xml``. - action_document_class """"""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock`` The action block document class. @@ -221,93 +224,81 @@ If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in slideshow_document_class """""""""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock`` The slideshow block document class. -If phpcr is enabled and ``use_imagine`` is enabled, the class value is set in -``Resources/config/admin-imagine.xml``. - imagine_document_class """""""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**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. -The imagine block document class. +use_sonata_admin +"""""""""""""""" -If phpcr is enabled, ``use_sonata_admin`` is enabled and ``use_imagine`` is -enabled, the class value is set in ``Resources/config/admin-imagine.xml``. +**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto`` + +If ``true``, the block classes and admin classes are activated. If set to +``auto``, they are activated only if the SonataPhpcrAdminBundle is present. + +If the :doc:`CoreBundle <../../bundles/core/index>` 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**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin`` The sonata admin class of the simple block. -If phpcr is enabled and ``use_sonata_admin`` is enabled, the class value is set -in ``Resources/config/admin.xml``. - container_admin_class """"""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin`` The sonata admin class of the container block. -If phpcr is enabled and ``use_sonata_admin`` is enabled, the class value is set -in ``Resources/config/admin.xml``. - reference_admin_class """"""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin`` The sonata admin class of the reference block. -If phpcr is enabled and ``use_sonata_admin`` is enabled, the class value is set -in ``Resources/config/admin.xml``. - action_admin_class """""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin`` The sonata admin class of the action block. -If phpcr is enabled and ``use_sonata_admin`` is enabled, the class value is set -in ``Resources/config/admin.xml``. - slideshow_admin_class """"""""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin`` The sonata admin class of the slideshow block. -If phpcr is enabled, ``use_sonata_admin`` is enabled and ``use_imagine`` is -enabled, the class value is set in ``Resources/config/admin-imagine.xml``. +This admin will only be loaded if ``use_imagine`` is enabled. imagine_admin_class """"""""""""""""""" -**type**: ``string`` **default**: ``null`` +**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin`` The sonata admin class of the imagine block. -If phpcr is enabled, ``use_sonata_admin`` is enabled and ``use_imagine`` is -enabled, the class value is set in ``Resources/config/admin-imagine.xml``. - -use_sonata_admin -"""""""""""""""" - -**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto`` - -If ``true``, the block classes and admin classes are activated. If set to -``auto``, they are activated only if the SonataPhpcrAdminBundle is present. - -If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to the value -of ``cmf_core.persistence.phpcr.use_sonata_admin``. +This admin will only be loaded if ``use_imagine`` is enabled. twig ~~~~