ProcessWire 3.0.44

Repeater and Repeater Matrix updates

This week I started with a small tweak to our Repeater field and ended up doing a whole bunch of upgrades. That's how it often goes. Once you start making small updates to something, the thought “wouldn't it be cool if…” appears, so you find yourself working towards that. Then “oh wait, why not make it do this too…” appears, and so that gets done, and on and on… The week is over in seemingly a day, but there's lots to share.

As you probably gathered from above, the majority of the updates this week were focused on Repeaters (and resultantly Repeater Matrix). Most of these updates were either things that people asked for, or proposed at some point. So I can't take credit for any of the ideas. Here's a list of what's been added to Repeater and Repeater Matrix fields:

  • Support for repeater item depth, enabling you to establish a hierarchy within repeater items. We'll cover this in detail further down.

  • A new repeater item clone feature. Click the clone link for any repeater item, and it makes a duplicate copy of it, ready for you to edit.

  • Support for a maximum and minimum quantity of repeater items.

  • Support for a new “accordion mode” which keeps just one item open at a time.

  • Support for a “delete all” option, which works the same way as with the same option on image fields (double-click trash can to mark all for deletion).

  • Confirmation dialogs for the clone and delete-all options.

  • The rather extensive javascript code for repeaters has been completely refactored and improved in many ways. With all the new features, I needed to rewrite a lot in order to make it more maintainable.

  • Power-user shortcut to open all/collapse all. Double click the on/off toggle icon to use. Consider this a hidden/undocumented feature for now, as we think it may be problematic at larger scale, so more testing is needed.

  • Improvements to repeater item display to fix the wrapping labels and overlapping action icons with labels that could sometimes occur in previous versions.

Below we'll cover some more details on the first item about repeater depth.


Screenshot demonstrating an overly basic example of using repeater depth.

Repeater depth

One of my favorite additions this week is something that Jonathan Lahijani came up with a few months ago: repeater items with depth. We've stuck pretty closely to his original proposal here. He even made mocked up the functionality and made a video demonstrating it.

The result that we ended up with in this week's ProcessWire version is essentially the same as what Jonathan proposed, except that rather than clicking buttons (as in the video) you set item depth the same way that you sort repeater items, by dragging them where you want them to go. We also added a depth configuration property so that you can set the maximum depth that items are allowed to have.

Once you've got repeater items with depth, you might be wondering how you work with that on the front-end. It's very simple. All Repeater Page items have a depth property that you can access as $item->depth or $item->getDepth(). It returns a number from 0 to your max-depth setting, where 0 represents the default depth of repeater items (which is no depth). Lets say you wanted to use the depth setting to output an large nested unordered list of repeater items having a "title" field:

$depth = -1;
foreach($page->repeater_items as $item) {
  if($item->depth > $depth) {
    echo "<ul>";
  } else if($item->depth < $depth) {
    echo "</ul>";
  }
  echo "<li>$item->title";
  $depth = $item->depth;
}
while($depth--) echo "</ul>";

The code above is what we used to output the Repeater shown in the screenshot earlier above. Here's the result below. Please pardon our </ul> margins–that's the site's stylesheet.

  • About
    • Welcome
    • FAQ
    • Testimonials
    • Contact
  • Resources
    • Articles
      • Categories
    • Interviews
    • Videos
  • Products
    • Engines
      • Steam powered engines
      • Diesel powered engines
      • Electric engines
    • Turbines
    • BBQ supplies
      • Barbecue sauce
      • Barbecue tools

Probably the simplest use case for something like this is as a menu builder. You don't really need such a thing in ProcessWire often, since the page tree serves that purpose. But I mention it just because it's probably the simplest way to introduce the concept. See the screenshot at the beginning of this section for an example of what it looks like as a repeater.

While a menu builder is a simple way to describe the concept of depth in a repeater, it barely scratches the surface on what's possible. In fact, it boggles my mind all the things that could be made possible when you consider that repeater items can have any ProcessWire fields present, rather than just the contrived title and URL of the menu builder example. Going further, consider where you can take this with Repeater Matrix fields, where you can have different kinds of repeater items in the same list. I'm looking forward to seeing how people use this feature.

To get started with using depth in a Repeater or Repeater Matrix field, simply edit the field settings and specify the maximum depth you will allow (near the bottom of the details tab). Once a depth is specified, it is enabled for the Repeater. Go and edit any page using that Repeater field and you can now drag items to have depth in the same way that you an drag them to sort them.

Below is a screenshot from the Repeater field edit screen, showing a few of the new configuration options.

Hope that you all have a great weekend and enjoy reading the ProcessWire Weekly!


Comments

  • Gideon So

    Gideon So 10 months ago 20

    This is amazing. Any plan to make pagination Repeater and Repeater matrix possible??

  • Joe Regan

    Joe Regan 10 months ago 40

    This is awesome!

    One request is to make export fields and export templates support exporting repeaters!

  • Sebastian

    Sebastian 10 months ago 41

    Yippiee! I waited long for the minimum and maximum of items in repeaters. Very usefull! Thank you, Ryan :)

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.