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.

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).

matrix-pageedit-open.png

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.

matrix-config.png

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.

Twitter updates

  • Today a new version of FormBuilder has been released in the FormBuilder support board (our 50th version) and it has a lot of interesting new features, which we’ll take a closer look at in this post— More
    11 June 2021
  • ProcessWire 3.0.179 adds great new admin theme customization tools that put you in full control over the Uikit admin styles— More
    28 May 2021
  • ProcessWire updates for week of 21 May 2021— More
    22 May 2021

Latest news

  • ProcessWire Weekly #369
    In the 369th issue of ProcessWire Weekly we're going to check out the latest core updates, showcase some recent forum highlights and tutorials, and more. Read on!
    Weekly.pw / 5 June 2021
  • ProcessWire FormBuilder v50 updates
    Today a new version of FormBuilder has been released in the FormBuilder support board (our 50th version) and it has a lot of interesting new features, which we'll take a closer look at in this post.
    Blog / 11 June 2021
  • Subscribe to weekly ProcessWire news

“ProcessWire is like a breath of fresh air. So powerful yet simple to build with and customise, and web editors love it too.” —Margaret Chatwin, Web developer