Block Types

1.3 version
Maintained Unmaintained

Block Types

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 create your own blocks, but the provided block types should cover many standard cases.

Common Behavior

There is an AbstractBlock base class that defines common behavior for all blocks provided by this bundle. It also implements handling for locales, even though only those block that actually contain string content implement the TranslatableInterface.

Publish Workflow Interfaces

The AbstractBlock implements the write interfaces for publishable and publish time period, see the publish workflow documentation for more information.

Sonata Admin

Each block type provided by the CmfBlockBundle is supported with an admin service in CmfSonataPhpcrAdminIntegrationBundle

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

ContainerBlock

A container can hold a list of arbitrary child blocks (even 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 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 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 something that is not a valid block, the problem is only detected when rendering the block.

ActionBlock

The action block allows to configure a controller action that will be called 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 want something more user friendly. See the RssBlock below for an example.

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 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. It depends on the eko/feedbundle which you need to add to your composer.json and instantiate in the AppKernel.

Create a document:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock;

// ...

$myRssBlock = new RssBlock();
$myRssBlock->setParentDocument($parentPage);
$myRssBlock->setName('rssBlock');
$myRssBlock->setSetting('title', 'Symfony CMF news');
$myRssBlock->setSetting('url', 'http://cmf.symfony.com/news.rss');
$myRssBlock->setSetting('maxItems', 3);

$documentManager->persist($myRssBlock);

The available settings are:

  • url: the url of the rss feed (required)
  • title: the title for the list (default: Insert the rss title)
  • maxItems: the maximum amount of items to return to the template (default: 10)
  • template: the template to render the feed items (default: CmfBlockBundle:Block:block_rss.html.twig)
  • ItemClass: the class used for the item objects that are passed to the template (default: Symfony\Cmf\Bundle\BlockBundle\Model\FeedItem)

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
  • or set the actionName of your RssBlock document

Note

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 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:

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    # app/config/config.yml
    liip_imagine:
        # ...
        filter_sets:
            cmf_block:
                data_loader: cmf_media_doctrine_phpcr
                quality: 85
                filters:
                    thumbnail: { size: [616, 419], mode: outbound }
            # ...
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services">
        <config xmlns="http://example.org/dic/schema/liip_imagine">
            <!-- ... -->
            <filter-set name="cmf_block" data-loader="cmf_media_doctrine_phpcr" quality="85">
                <filter name="thumbnail" size="616,419" mode="outbound"/>
            </filter-set>
            <!-- ... -->
        </config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    // app/config/config.php
    $container->loadFromExtension('liip_imagine', array(
        // ...
        'filter_sets' => array(
            'cmf_block' => array(
                'data_loader' => 'cmf_media_doctrine_phpcr',
                'quality'     => 85,
                'filters'     => array(
                    'thumbnail' => array(
                        'size' => array(616, 419),
                        'mode' => 'outbound',
                    ),
                ),
            ),
            // ...
        ),
    ));
    

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.

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 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 types of blocks in the same slideshow.

Note

This bundle does not attempt to provide a JavaScript library for animating the slideshow. Chose your preferred library that plays well with the rest of your site and hook it on the slideshows. (See also below).

Create your first Slideshow

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. Make sure to have configured the imagine filter as explained above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock;
use Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock;
use Symfony\Cmf\Bundle\MediaBundle\Doctrine\Phpcr\Image;

// create slideshow
$mySlideshow = new SlideshowBlock();
$mySlideshow->setName('slideshow');
$mySlideshow->setParentDocument($parentPage);
$mySlideshow->setTitle('My first Slideshow');
$documentManager->persist($mySlideshow);

// add first slide to slideshow
$mySlideshowItem = new ImagineBlock();
$mySlideshowItem->setName('first_item');
$mySlideshowItem->setLabel('label of first item');
$mySlideshowItem->setParentDocument($mySlideshow);
$manager->persist($mySlideshowItem);

$image = new Image();
$image->setFileContentFromFilesystem('path/to/my/image.jpg');
$mySlideshowItem->setImage($image);

Render the slideshow

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:

  • Twig
    1
    2
    3
    {{ sonata_block_render({
        'name': 'slideshow'
    }) }}
    
  • PHP
    1
    2
    3
    <?php echo $view['blocks']->render(array(
        'name' => 'slideshow',
    )) ?>
    

Make the Slideshow Work in the Front-End

Since the BlockBundle doesn't contain anything to make the slideshow work in the front-end, you need to do this yourself. Use your favorite JavaScript library to make the slideshow interactive. If special markup is needed for 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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.