Repeater Matrix fields

ProcessWire ProFields now includes the new Repeater Matrix, perhaps the most powerful ProField yet! Repeater Matrix fields enable flexible content types and open the door to all kinds of great content management possibilities.

• About Repeater Matrix
• Repeater Matrix details and screenshots
• Repeater Matrix from the API

Please note: Repeater Matrix requires ProcessWire 3.0 or newer.

About Repeater Matrix

Repeater Matrix is an extension of Repeaters that enables you to have repeater items of different types in the same repeater. You define what fields accompany each item type. You can have any number of items of any type that you define. Repeater Matrix fields are very similar to regular ProcessWire repeater fields, except that in regular repeater fields, you can only have one type. Repeater Matrix fields enable flexible content types and open the door to all kinds of great content management possibilities.

Repeater Matrix details and screenshots

Here's what a Repeater Matrix looks like in your page editor when all the items are collapsed. It looks a lot like a regular repeater field here, but the "Add New" actions at the bottom hint at what's different. The types that you see there are configured with the field, and you can create as many different types as you want. Likewise, in your page editor, you can add any quantity or order of items of varying types that you want.

One use case for a Repeater Matrix is as an alternative to a rich text editor for those cases where you want more fine-grained developer control. For example, you might setup separate headline, body, blockquote, photo and video types, for starters. Because they are all independent fields rather than a big block of HTML, you as the developer have a lot more control over the output.

Below is what the same field looks like with a few of the items open. The "Links" field that you see is actually a ProFields Table field that I added to my Repeater Matrix. Like with regular repeaters, you can maintain unpublished items too–see the last Bodycopy item there as an example. By the way, the labels that you see for each item, like "Blockquote", "Photo gallery", etc., are fully configurable just like with the new repeaters, or they can be auto-generated to reflect just the type (as in these screenshots).

Next we have a screenshot showing you the Field editor (Setup > Fields) where you create and/or configure your Repeater Matrix field. The configuration is very similar to regular repeater fields except that you can add as many different repeater types as you'd like. Something to note is that Repeater Matrix fields are incredibly easy to configure, just as regular repeaters are. You can accomplish some similar things with a PageTable field, but it takes a lot more effort.

Repeater Matrix from the API

From the API side, your Repeater Matrix is just a PageArray accessed in the same way as any other Page field in ProcessWire, and each of the individual items are just Page objects. Meaning, you likely already know how to use this field from the API side. And you'll likewise already know how to $pages->find() items from it with selectors.

When it comes to outputting values, the main difference is that you'll want to check a type property for each item that you foreach (iterate), since you can have any number of different types in your PageArray value. That type property will indicate what type of item you are dealing with. For instance, the field configured in my screenshots above has types identified by: blockquote, bodycopy, gallery, links and highlights. Depending on the item type, you would use different code to output the values on the front-end. For example:

foreach($page->test_matrix as $item) {
  if($item->type == 'blockquote') {
    echo "
      <blockquote>
         <p>$item->quote</p>
         <cite>$item->quote_cite</cite>
      </blockquote>
      ";
  } else if($item->type == 'bodycopy') {
    echo "
      <h2>$item->title</h2>
      $item->body
      ";
  } else if($item->type == 'gallery') {
    // and so on...
  }
}

We also have an alternative option available where you can specify PHP files that render the output markup for each type, not unlike baby template files. More details are available in the Repeater Matrix documentation.