$blocks

What are blocks?

When you want to work with the content of a Blocks field, you would use the toBlocks field method to convert it to a Blocks collection - a collection of Kirby\Cms\Block objects. The Blocks collection makes it easy to render the entire set of blocks or loop through blocks and create individual HTML for them.

Blocks in your templates

If you don't want to care about the HTML for each individual block, you can echo the entire blocks collection to render all blocks.

<?= $page->myBlocksField()->toBlocks() ?>

Block snippets

The HTML for each individual block is stored in its own block snippet. All our default block types bring their own snippets and can be overwritten. Block snippets are stored in /site/snippets/blocks

As an example, if you want to overwrite the snippet for our heading block, you would create a snippet file called /site/snippets/blocks/heading.php

The default heading snippet

<<?= $level = $block->level()->or('h2') ?>>
  <?= $block->text() ?>
</<?= $level ?>>

Your customized version

/site/snippets/blocks/heading.php

<<?= $level = $block->level()->or('h2') ?> id="<?= $block->customId()->or($block->id()) ?>">
  <?= $block->text() ?>
</<?= $level ?>>

Looping through blocks

Looping through blocks to control their HTML can be very powerful. You can assign custom CSS classes, IDs for links and more.

You don't need to render the HTML for each individual block in the loop though. You can wrap the block with your custom HTML and then echo the $block object to render the matching block snippet.

<?php foreach ($page->myBlocksField()->toBlocks() as $block): ?>
<div id="<?= $block->id() ?>" class="block block-type-<?= $block->type() ?>">
  <?= $block ?>
</div>
<?php endforeach ?>

Manually loading snippets

Sometimes you might wish to customize the way block snippets are loaded. Maybe you want to inject more snippet variables.

<?php foreach ($page->myBlocksField()->toBlocks() as $block): ?>
<div id="<?= $block->id() ?>" class="block block-type-<?= $block->type() ?>">
  <?php snippet('blocks/' . $block->type(), [
    'block' => $block,
    'theme' => 'dark'
  ]) ?>
</div>
<?php endforeach ?>

… or load snippets from a different location …

<?php foreach ($page->myBlocksField()->toBlocks() as $block): ?>
<div id="<?= $block->id() ?>" class="block block-type-<?= $block->type() ?>">
  <?php snippet('blocks/custom/' . $block->type(), [
    'block' => $block,
    'theme' => 'dark'
  ]) ?>
</div>
<?php endforeach ?>

new Blocks()

$blocks->add()

$blocks->append()

$blocks->callMethod()

$blocks->chunk()

$blocks->clone()

$blocks->count()

$blocks->current()

$blocks->data()

$blocks->empty()

$blocks->excerpt()

$blocks->extend()

Blocks::factory()

$blocks->filter()

$blocks->filterBy()

$blocks->find()

$blocks->findBy()

$blocks->findByKey()

$blocks->first()

$blocks->flip()

$blocks->get()

$blocks->getAttribute()

$blocks->getIterator()

$blocks->group()

$blocks->groupBy()

$blocks->has()

$blocks->hasMethod()

$blocks->indexOf()

$blocks->intersection()

$blocks->intersects()

$blocks->isEmpty()

$blocks->isEven()

$blocks->isNotEmpty()

$blocks->isOdd()

$blocks->key()

$blocks->keyOf()

$blocks->keys()

$blocks->last()

$blocks->limit()

$blocks->map()

$blocks->next()

$blocks->not()

$blocks->nth()

$blocks->offset()

$blocks->paginate()

$blocks->pagination()

$blocks->parent()

Blocks::parse()

$blocks->pluck()

$blocks->prepend()

$blocks->prev()

$blocks->query()

$blocks->remove()

$blocks->rewind()

$blocks->search()

$blocks->set()

$blocks->shuffle()

$blocks->slice()

$blocks->sort()

Blocks::sortArgs()

$blocks->sortBy()

$blocks->toArray()

$blocks->toHtml()

$blocks->toJson()

$blocks->toString()

$blocks->valid()

$blocks->values()

$blocks->when()

$blocks->without()