Installation¶

You can install this bundle with composer using the symfony-cmf/block-bundle package.

As the bundle is using the SonataBlockBundle, you need to instantiate some sonata bundles in addition to the CmfBlockBundle:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Sonata\BlockBundle\SonataBlockBundle(),
            new Sonata\CoreBundle\SonataCoreBundle(),
            new Symfony\Cmf\Bundle\BlockBundle\CmfBlockBundle(),
        );

        // ...
    }

    // ...
}

Usage¶

The BlockBundle needs a persistence layer to be configured. This can either be done globally with the Core Bundle or individually as follows:

The default settings of a block are defined in the block service. If you use a 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 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.

Block Document¶

Before you can render a block, you need to create a data object representing your block in the repository. You can do so with the following code snippet:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock;

// ...
/** @var $dm \Doctrine\ODM\PHPCR\DocumentManager */
$parentDocument = $dm->find(null, '/cms/content/home');

$myBlock = new SimpleBlock();
$myBlock->setParentDocument($parentDocument);
$myBlock->setName('sidebarBlock');
$myBlock->setTitle('My first block');
$myBlock->setBody('Hello block world!');

$dm->persist($myBlock);

Note the 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.

The simple block is now ready to be rendered, see Block rendering.

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.

Block Service¶

Internally, the block bundle uses a block service to work with each type of block. The service is configured to handle a type of block. The blocks themselves identify their type in the getType method.

When using the provided blocks, you do not need to worry about the block service. It is only relevant when creating your own blocks.

Block rendering¶

Rendering is handled by the SonataBlockBundle sonata_block_render Twig function. The block name is either an absolute PHPCR path or the name of the block relative to the cmfMainContent document.

To render the example from the Block Document section, just add the following code to your Twig template:

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:

This will make the BlockBundle render the specified block if the main content (as per the 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 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;
• Otherwise, the execute method of the corresponding block service is called.

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.

1
2
3

%embed-block|/absolute/path/to/block|end%

%embed-block|local-block|end%

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 BlockBundle and CoreBundle 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 CreateBundle.

Read on¶

• Block Types
• Create your own Blocks
• Cache
• Relation to Sonata Block Bundle
• Configuration Reference