Documentation

6.3 Create a block with Integrated Block bundle

The IntegratedBlockbundle can be used to generate blocks in an application in two ways:

  • Added by the user on pages, using the IntegratedPageBundle
  • By using the twig function integrated_block($slug) to render a block from code

A block is composed with:

  • A block document, which contains the configurable fields
  • A block handler, which is very similar to a controller
  • A block view, which is the view for the block

To create a block with we assume that the IntegratedBlockBundle is available in the project and loaded in AppKernel.php.

Creating a block document

Create a new class in the folder Document or Document/Block . Give the class the following name: <Blocktype>Block.php . This class is a subclass of the class Block. This class is a description of a document and the properties for the ODM and Type Annotations need to be set.

In the BlockBundle there is a default TextBlock. Here is a simple version of it.

Integrated/Bundle/<BundleName>/Document/TextBlock.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<?php
 
namespace Integrated\Bundle\\Document;
 
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Integrated\Common\Form\Mapping\Annotations as Type;
 
use Integrated\Bundle\BlockBundle\Document\Block\Block;
 
/**
 * @ODM\Document
 * @Type\Document("Document name")
 */
class TextBlock extends Block
{
    /**
     * @var string
     * @ODM\String
     */
    protected $text;
 
    /**
     * @return string
     */
    public function getText()
    {
        return $this->text;
    }
 
    /**
     * @param string $text
     * @return $this
     */
    public function setText($text)
    {
        $this->text = $text;
        return $this;
    }
 
    /**
     * {@inheritdoc}
     */
    public function getType()
    {
        return 'text';
    }
}

Create a BlockHandler

To render the block on the site and handle the input of the block you need to create a BlockHandler. This should be placed in the map Block and the name should be <Blocktype>BlockHandler.php. This Block needs a method execute(BlockInterface $block). This method returns $this->render() with the parameter $block

$block is a instance of a block from the new type with the values of Integrated.If you need to chance any values this needs to be done here. If the services need to chance , these can be given to the constructor and saved.

The BlockHandler Class renders the template ‘default’ from the folder

/vendor/integrated/content-bundle/Resources/views/themes/default/blocks/<blocktype>

You can chance this with the method : setTemplate();

Example

Integrated/Bundle/<Bundlename>/Block/TextBlock.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php
 
namespace Integrated\Bundle\\Block;
 
use Integrated\Bundle\BlockBundle\Block\BlockHandler;
use Integrated\Common\Block\BlockInterface;
 
/**
 * @author firstname Lastname <firstname@e-active.nl>
 */
class ContactBlockHandler extends BlockHandler
{
    /**
     * {@inheritdoc}
     */
    public function execute(BlockInterface $block)
    {
        return $this->render([
            'block'  => $block,
        ]);
    }
}

Create a BlockHandler service

To make sure the block is created the right way the Blockhandler must be registered as a service. Its recommended to do this in ‘block.xml’ (or .yml). In the folder Resources/config. If this file does not exist it has to be included in <Bundlename>Extension.php.

Example

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?xml version="1.0" encoding="UTF-8" ?>
 
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
    <parameters>
 
        <parameter key="<bundlename>.block_handler.text.class">Integrated\Bundle\<BundleName>\Block\TextBlockHandler</parameter>
 
    </parameters>
 
    <services>
 
        <service id="<bundlename>.block_handler.text" class="%<bundlename>.block_handler.text.class%">
            <tag name="integrated.block" type="text" />
        </service>
 
    </services>
</container>

Important is that the type in purple is the same as the method getType();

Create a block view

To display the block you need to add a template. The standard template is called ‘default’ this file is located in the folder : views/themes/default/blocks/<blocktype>.

Example

Integrated/Bundle/<Bundlename>/Resources/views/themes/deault/blocks/TextBlock.html.twig

1
2
3
4
5
6
7
8
<div class="panel panel-default">
    <div class="panel-heading">
        {{ block.title }}
    </div>
    <div class="panel-body">
        {{ block.text }}
    </div>
</div>

Content-aware blocks

Sometimes blocks need to be related to the content item (for example Article). For example a related content block. The active content item is available in the blockmanager to support this kind of blocks.

If you have your own controller, you need to set the active document in your controller:

1
$this->blockManager->setDocument($article);

You can get the active content item in the block:

1
$this->blockManager->getDocument();