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


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 "
  } else if($item->type == 'bodycopy') {
    echo "
  } 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

  • New post: Version 3.0.135 of ProcessWire on the dev branch focuses on some .htaccess updates, adds clarity to debug mode, and improves upon the installer— More
    5 July 2019
  • ProcessWire 3.0.133 adds a useful new Page::meta() method for a new type of page-specific persistent data storage, adds the ability for users to create their own bookmarks in Lister, and has a handy and time saving update for the asmSelect input type— More
    14 June 2019
  • New post: This week we’ll take a look at 3 different WEBP image strategies that you can use in ProcessWire 3.0.132+. Then we’ll dive into a major update for the Google Client API module, and finish up by outlining some useful new updates in FormBuilder— More
    31 May 2019

Latest news

  • ProcessWire Weekly #270
    This week in the 270th issue of ProcessWire Weekly we're going to cover the SearchEngine module, feature some recent support forum highlights, and introduce a brand new site of the week. Read on! / 13 July 2019
  • ProcessWire 3.0.135 core updates
    Version 3.0.135 of ProcessWire on the dev branch focuses on .htaccess updates, adds additional layers of security, adds clarity to debug mode, and improves upon the installer.
    Blog / 3 July 2019
  • Subscribe to weekly ProcessWire news

“Indeed, if ProcessWire can be considered as a CMS in its own right, it also offers all the advantages of a CMF (Content Management Framework). Unlike other solutions, the programmer is not forced to follow the proposed model and can integrate his/her ways of doing things.” —Guy Verville, Spiria Digital Inc.