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:
||The entire blocked section should be inside this pair.|
||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>
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
<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: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.
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>
perch:block tag pair then just contains normal template code, including content tags, repeaters and markup. (Each individual block does not have a
after section, but they do have an index within the blocked group.) You can use the
divider-after attributes to give the edit form more structure.
perch:block opening tag has two required attributes.
type describes the block to the templating system, and
label describes it to your users.
|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|
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
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="true" attribute on the
To prevent ID clashes, the items from outside the blocks become
parent.originalID within the blocks. So a field that is
outside the blocks would be
id="parent.title" when brought into scope within the blocks.
A block can be represented by an icon. The available icons are listed below.