Block view templates #

This page is for designers who write or restyle the template of a layouts block. It answers: what a block template receives, how it draws its items, and how a container draws its children.

Contents #

1. Where block templates live
2. What a block template receives
3. A simple block
4. A list block with items
5. Containers and their children
6. Template blocks
7. Rules

Where block templates live #

explayouts/block/<definition identifier>.tpl, found through the design cascade. The extension's own copies are in extension/explayouts/design/standard/templates/explayouts/block/; a design replaces any of them by putting a file at the same path, as the media design does in design/media/templates/explayouts/block/.

What a block template receives #

A simple block #

The shipped title block (block/title.tpl), shortened:

<div class="slb slb-title" data-block-id="{$block.id|wash}">
    {if $block.values.title}
        {def $tag = cond( $block.values.tag|ne( '' ), $block.values.tag, concat( 'h', $block.values.level ) )}
        <{$tag} class="title">{$block.values.title|wash}</{$tag}>
        {undef $tag}
    {/if}
</div>

A list block with items #

Collection items of the shipped list block are nodes ($block.values.items):

<div class="slb slb-list" data-block-id="{$block.id|wash}">
    {if $block.name}<h2 class="block-title">{$block.name|wash}</h2>{/if}
    {if $block.values.items|count}
    <ul class="block-list">
        {foreach $block.values.items as $item}
        <li>{node_view_gui content_node=$item view='line'}</li>
        {/foreach}
    </ul>
    {else}
    <p class="block-empty">{'No items found.'|i18n( 'design/mytheme/block' )}</p>
    {/if}
</div>

Drawing each item with node_view_gui and a view mode (line, or one of your own such as card) reuses the line templates and overrides of your design (node_view_gui).

Containers and their children #

A container block draws the blocks whose parent_id is its id, by placeholder. From the shipped block/two_columns.tpl:

{foreach $zone.blocks as $child}
    {if and( is_set( $child.parent_id ), $child.parent_id|eq( $block.id ),
             is_set( $child.placeholder ), $child.placeholder|eq( 'left' ),
             is_set( $child.definition_identifier ), $child.definition_identifier|ne( '' ) )}
        {include uri=concat( 'design:explayouts/block/', $child.definition_identifier, '.tpl' )
                 block=$child zone=$zone module_result=$module_result}
    {/if}
{/foreach}

The zone templates draw only top-level blocks (parent_id 0); children are always drawn by their container.

Template blocks #

The tpl_block block names a template part (block_name parameter), drawn from explayouts/tpl_block/<name>.tpl. Designs use it for parts that belong to the page but should be placeable by editors: the media design has article_header.tpl, article_body.tpl, article_media.tpl; the starter design draws its header and footer this way.

Rules #

• Wash every value (|wash); block parameters are editor input.
• Keep the outer element with data-block-id: the layouts editor's preview uses it.
• No inline CSS or JavaScript; style by class (Styling layout blocks).
• A variable defined with {def} in an included template can clash with the includer's; {undef} what you define.

Related pages #

• Block definitions
• Styling layout blocks
• Layouts for designers
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.