Enabling Composer Editing for a Block Type

Any block type can be included in Concrete CMS's Page Type composer interface.

Block Appearing in the Page Type Edit Interface

HTML Block as It Appears in Composer

Composer Template File

Since composer view for a page is the same for adding a page and editing a page, there aren't separate add and edit templates. There's just one: composer.php. In order for your block type to be listed in the Block "Add Control" interface on the Page Type edit screen, a file named "composer.php" must be present in the block's directory.

touch application/blocks/your_block/composer.php

Composer template scope items

These are variables found in the composer.php template automatically that will be useful.

$label

This is a text representation of the composer control label. This label can be customized through the page type interface.

$description

This is the help description specified for this particular composer control. This description can be specified through the page type edit interface.

$view

This is an instance of the Concrete\Core\Block\View\BlockView class. The field() method on this class is how the composer templates output their form names.

Example

Here is the HTML block composer template:

<div class="control-group">
    <label class="control-label"><?=$label?></label>
    <? if($description): ?>
    <i class="fa fa-question-circle launch-tooltip" title="" data-original-title="<?=$description?>"></i>
    <? endif; ?>
    <div class="controls">
        <?
        print $form->textarea($view->field('content'), $content, array(
            'class' => $class,
            'style' => 'width: 580px; height: 380px'
        ));
        ?>
    </div>
</div>

Let's walk through the template. First, we notice the style of markup. This is done using Bootstrap 3. The $label parameter is either going to be "HTML" or the custom label set through Composer. Additionally, we use the Bootstrap tooltip library to provide access to the help text, if a user provided it through the interface. The composer template itself is responsible for rendering labels and help text, because we wanted to give developers maximum flexibility for how they displayed that information (or chose not to.)

Next, we see the only form element that the HTML block uses, the text area. This is very similar to the edit interface for the HTML block, with one very important difference. Instead of using "content" as the name of the text area input element, we make the name of the text area input element $view->field('content'). This transforms "content" into something like that looks like this ptComposer[36][content]. We do this because multiple blocks with the same parameters can exist in one composer form, so we can't just name our composer elements indiscriminately. Instead, we use $view->field('content') which takes care of ensuring our "content" parameter will be unique to this composer control instance, and automatically translates it back to "content" when saving the form. Note: $view->field() works in regular block edit and add templates as well, so it's a good idea to use it, rather than just hard-coding "content".

That's it! With this simple template we've added composer functionality to our block.