Blocks

Getting started

Blocks and Atoms

In order to use Blocks, you need to define some blocks.

A block is a logical grouping that content editors can create and populate. So a pull-quote quote could be a block, or a captioned image could be a block.

A block is made up of atoms. So, to go with the pull-quote example, a pull-quote would have a content field as one atom and a citation as another. A captioned image would have a file upload field as one atom, a caption as another atom, and maybe some alt-text as a third atom.

You will also probably want a simple content field as a block, which just includes a single atom with an Expresso, Wygwam, or other rich text field. This lets the content editors input text like they normally would when they don't need rich content.

To define blocks and atoms, go to the Modules screen in the Add-ons section and click on Blocks. There you can see all of the blocks you have defined already.

Create a field

Once you've defined some atoms – don't worry, you can go back and define more later – you can create a field in your channel for your content using the Blocks field type. When you create a field, select the blocks you want to include for that field.

Why not just define the blocks there? Blocks assumes you may have multiple channels with content areas, and you won't want to define the blocks each time.

Template

So you can get your content in just fine. Let's get it out.

{exp:channel:entries}

{!-- Whatever you called your field --}
{your_field_name}

  {!-- The name of your block --}
  {simple_content}
    {!-- The name of your atom --}
    {content}
  {/simple-content}

{/your_field_name}

{/exp:channel:entries}

Alright, starting out simple. When you set up your channel, you created a field. Since I don't know what you called it, I'm going to use {your_field_name}.

And you associated {your_field_name} with some blocks. One of those was simple_content. So, whenever Blocks comes across a simple_content block, it outputs whatever is inside here. In this case, output the single atom content directly.

Blocks really shines with rich content. So let's see that.

{your_field_name}

  {simple_content}
    {content}
  {/simple_content}

  {pull_quote}
  <blockquote>
    {quote_content}
    {if author}
    <cite>{author}</cite>
    {/if}
  </blockquote>
  {/pull_quote}

{/your_field_name}

Now, anytime Blocks comes across a pull_quote, it outputs it inside a <blockquote> element, an optionally outputs a <cite> tag, if necessary.

The best part is that you, the developer, completely control that output. You don't have to expect your content editors to know what a blockquote element even is, and you can even change the markup in the future.