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:

Tag Description
<perch:blocks></perch:blocks> The entire blocked section should be inside this pair.
<perch:block></perch:block> An individual block, defining the start and end of that micro-template

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.

Attribute Value
type An ID-like reference used to refer to the block in templates
label A short, human-readable description of the block type
icon The name of an icon to use to represent the block in the user interface

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.

Icon Name
address-book
alarm-alt
anchor
bed
bell
book
bookmark
burger
calculator
calendar-add
calendar
camera-alt
cart
chart-pie
chat
circle-add
clock
cloud
code
coffee-togo
compass
contacts
dashboard
database
document
download
edit
flag
folder
heart
home
keyboard
keynote
lightbulb
link
list
location
mail
megaphone
menu
microphone
music
newspaper
notepad
paint-roller
paintbrush
paper-airplane
paperclip
pencil-paintbrush-pen
pencil
phone
photo
photos
plane
popsicle
pulse-wave
puzzle
question
quote
redirect
signs
tag
theater-masks
truck
tv
umbrella
user-female
user
users
utensils
video
weather
wine
world
wrench
yin-yang