Blocks Tags

Blocks offer the ability to structure an item with a choice of mixed content. Within each item (such as an item in a multiple item region, or a Collection item in Perch Runway) the template can define a perch:blocks section containing a choice of blocks to add.

Blocks defines the following template tags:

Each block is like a micro-template. It can include the usual mix of field types, Repeaters and markup.

<perch:blocks>
  <perch:block type="text" label="Text">
    ...
  </perch:block>
  <perch:block type="quote" label="Pull quote">
    ...
  </perch:block>
  <perch:block type="image" label="Feature image">
    ...
  </perch:block>
</perch:blocks>

The perch:blocks tag pair

All blocks must exist within a perch:blocks tag pair. This defines the ’blocked’ section of the template.

A template using blocks can contain other content outside of the blocks. The order of the fields and the blocked section can be controlled with the order attribute.

<perch:content type="smarttext" id="heading" order="1">
<perch:content type="date" id="date" order="3">
<perch:blocks order="2">
  …
</perch:blocks>

The blocked section can use perch:before and perch:after sections in order to display markup around the blocks. These do not show if no blocks are selected.

The blocks are output in a group, so perch:every acts across the blocks, and each block has its own perch_item_index and friends.

The perch:block tag pair

Block tags appear within a perch:blocks tag pair. They define each block than can be chosen by the content editor.

<perch:block type="image" label="Feature image">
  <figure>
      <img src="<perch:content id="image" type="image" width="1600" label="Image">">
      <figcaption>
        <perch:content id="caption" type="smarttext" label="Caption">
      </figcaption>
    </figure>
</perch:block>

A perch:block tag pair then just contains normal template code, including content tags, repeaters and markup. (Each individual block does not have a before or after section, but they do have an index within the blocked group.) You can use the divider-before and divider-after attributes to give the edit form more structure.

The perch:block opening tag has two required attributes. type describes the block to the templating system, and label describes it to your users.

The label attribute is used in the editing interface to describe the block.

A blocked section can include as many blocks as needed. A template can only contain one perch:blocks section.

Using template includes

It is perfectly fine to use template includes to make your code more modular.

<perch:blocks>
  <perch:block type="image" label="Feature image">
    <perch:template path="content/blocks/image.html">
  </perch:block>
</perch:blocks>

You can even make sets of common blocks and add special cases as needed:

<perch:blocks>
  <perch:template path="blocks/article_blocks.html">
  <perch:block type="image" label="Feature image">
    <perch:template path="content/blocks/image.html">
  </perch:block>
</perch:blocks>

Accessing content outside the blocks

By default, blocks operate as a silo – like a region within the template. They have their own content scope, and the template engine treats them as a distinct zone with its own before and after properties and new item counts.

Content from outside the perch:blocks tag is out of scope. You can bring it into scope for all blocks using the scope-parent attribute on the perch:blocks tag.

To prevent ID clashes, the items from outside the blocks become parent.originalID within the blocks. So a field that is id="title" outside the blocks would be id="parent.title" when brought into scope within the blocks.

Icons

A block can be represented by an icon. The available icons are listed below.