This week is all about repeaters, something that we didn't cover on the roadmap last week, and maybe should have. But we always like to save a few surprises so you still have a reason to come and read these blog posts!
This week we have ProcessWire 3.0.4 which brings a major refactoring of the Repeaters Fieldtype/Inputfield to the core. Not to mention several other unrelated tweaks and bug fixes. But we'll focus on the repeaters here. The latest version of Repeaters included with the ProcessWire core adds these new features…
The "Add New Item" action now uses AJAX to add items, replacing the previous "ready items" (more on that below).
New configuration options for whether items are collapsed or open by default.
Control over repeater labels, which can new be fully customized and also include values from the repeater item/page.
Ability to control the published/unpublished state of individual repeater items with a toggle.
Repeaters using regular CKEditor fields are now sortable. Previously it caused CKEditor to freeze when you tried to sort since CKEditor doesn't like to be moved around in the DOM.
We now support "show if" dependencies in repeaters.
The "Add New Item" action text is now customizable–make it say whatever you want.
Numerous other bug fixes and tweaks.
Introduction of several new bugs (Just kidding! Hopefully not! But like the rest of PW3 you should consider it very much beta and please report any issues you find).
Repeaters no longer have to maintain "ready pages", which were one or more pages that it would keep (per your settings) ready-to-edit, hidden in the background. This was undesirable overhead, as it might keep several unused pages for each repeater, on each page. If you had more items to add than you had "ready pages", then you would get a non-editable item labeled with "this item will become editable after you save."
All this was was necessary when repeaters were originally developed because not all core Inputfields could be dynamically inserted into a document, especially those with heavy Javascript components like rich text editors, image fields, and the like. ProcessWire 2.7 largely corrected that, as the core now supports AJAX/dynamic loaded fields in the page editor. That means that Repeaters can now take advantage of it too, and in the latest version, they do. What this means is that the latest repeaters version is significantly more efficient and has a nicer admin UI for the editors.
It's possible there may still be some instance where you've got an Inputfield module that doesn't work well being inserted from Javascript (AJAX). For those cases, a new configuration setting has been added that enables you to disable the AJAX-add mode, reverting back to the "this item will be editable after you save" method. Though our hope is that the instances where you might need that will be rare.
The following screenshot shows a repeaters field that I setup for managing events. I've configured my repeater to keep the items collapsed by default (requiring a click to open and edit). The collapsed mode makes repeater items easier to keep track of and easier to sort. Note the third item there, which demonstrates an unpublished item–you can now maintain unpublished items in your repeater. To publish or unpublish, you just click the little toggle next to the trash can in the item header.
Next we have the same repeater as above, but with the last item open for editing. Note the "Add New Event" action at the bottom, which is now configurable with the repeater, making it much more context friendly. Previously all repeaters had the same "Add Item" action text.
In this next screenshot below, you'll see the field edit screen for the repeater field shown in the previous two screenshots. If you've used repeaters before, it probably looks pretty familiar, but with several new customization options, and no more field to configure "ready items."
One of the items in last week's roadmap was mention of a new ProFields module. Since we're on the topic of repeaters, I thought it made sense to give you a preview of the new Repeater Matrix field. This new field will part of our ProFields package and available for download in our ProFields support board in the near future. If you've already purchased ProFields and have an active ProFields support plan then ProFields Matrix will be free for you to download and use. It fills a gap in the current ProFields modules, providing a new flexible content type that we think you will find useful.
The Repeater Matrix field is a lot like a regular Repeater field, except that it lets you maintain multiple types of repeater items in the same repeater field. So while it may share some similarities with repeaters, it's also an entirely different animal that opens up a whole lot of new flexibility and possibilities for content management. Below are a few screenshots that help to communicate what it does.
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.
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, but we'll cover more on that next time, as it leads into yet another new feature coming to PW3 that we're saving as a surprise. Hope that you all have a great weekend and week ahead and thanks for reading! Remember to read the ProcessWire Weekly this Saturday!
In this post we take a look at all that is planned for ProcessWire in 2016. This includes plans for the core (3.x and 2.x), plans for the Pro modules, and big picture goals for the entire ProcessWire project! More
In ProcessWire 3.0.5, you can nest repeater fields and use dynamic/AJAX loading for all items. Plus we've got the first test version of Repeater Matrix released, and new support for field templates… More
“…building with ProcessWire was a breeze, I really love all the flexibility the system provides. I can’t imagine using any other CMS in the future.” —Thomas Aull
Tom
- 8 years ago
- 101
★★★★★"We now support "show if" dependencies in repeaters." - I love you so much!
Also this Matrix field is looking amazing! I must say, I've always liked the PageTable field, but it wasn't always exactly what I was looking for because of the required title field - in those cases, the Matrix field is exactly what I was looking for :-)!
Reply
Tom
"another new feature coming to PW3 that we're saving as a surprise" - This sounds incredibly exciting! :D
Reply
Mike Rockett
It does indeed! Hmmm, maybe something along the lines of provisional template files.
Reply
ryan
Tom, glad you like what you see! The show-if dependencies do now work, but note that required-if dependencies aren't supported just yet – though it now gives you a warning about it when you configure one so that hopefully nobody will get tripped up by it.
With PageTable, the "title" field doesn't have to be required. Enable $config->advanced=true; in your /site/config.php, then go to edit your template(s) used by your PageTable, click on the "System" tab and check the box to override the "global" field requirement.
Reply
Charles Stevens
- 8 years ago
- 40
★★★★★Very nice additions
Reply
Nikolaus Rademacher
Thanks, Ryan! We'll think about this.
Reply
Peter
I've said it before and I'll say it again. You're a damn fine man and a bloody good mind reader too. Thanks Ryan :-)
Reply
ryan
Admittedly I'm not familiar with the matrix type in Craft, but looking at those screenshots in the article it looks like exactly the same thing as our Repeater Matrix. Worth nothing is that PW has already supported this in PageTable for quite some time, but it takes more effort to configure relative to Repeater Matrix. Doing this in PageTable also takes a little more effort for editors, as items are edited individually in a modal rather than in the same page editor (which can be a drawback or a benefit, depending on the situation).
Reply
Nikolaus Rademacher
Thanks, Ryan! We'll think about this.
Reply
Martijn Geerts
You didn't mentioned that GUI wise the new repeaters and matrix fields take less space, making them more beautiful and even more practical. I love it.
Reply
ryan
Can, whether it's pages or some other data type, 20 repeater fields multiplied by 20 items is still 400 items. It may sound like a lot of items, but it isn't to PW. The benefit of pages is that they scale very well, they load their fields on demand (and don't load fields that aren't asked for from the API), they accept any kind of data (by way of Fieldtype modules) and input (by way of Inputfield modules), and the entire PW API is built around working with pages. That means they are highly flexible, efficient, searchable, accessible. Not to mention, really easy to use for the site developers.
A repeater that doesn't use pages could certainly exist (and does: ProFields Table), but such a field must manage all its own types and inputs, rather than benefitting from existing Fieldtype and Inputfield modules. It's limited to only those types and inputs it provides, rather than accepting modules/plugins for these (as Repeater does). There are of course benefits and drawbacks to each approach. But when it comes to Repeaters and Repeater Matrix, we want people to be able to use native PW fields rather than something limited and proprietary to a Fieldtype. Since Repeaters are in the core, we also want them to be able to work with their data in the same way they do with anything else in PW. I see fields like ProFields Table as being ideal for specific use cases, whereas Repeaters are better for general purpose cases. We've got several upgrades coming to ProFields Table too, btw.
Reply
Can
- 8 years ago
- 00
★★★★★You're right (of cause). Just want to mention that I know that you know what you're doing hehe ;-)
Just want to understand reasons.
Should have thought my question a little more through^^
Sure, doesn't matter, in the end the data has to be stored in the db. I thought it could be more cleaner without giving each item an id and url (I know they're not reachable).
Would be nice if mysql would allow non int columns to be auto incremental, or allow int fields to hold a prefix. So repeaters could have their own id "namespace" (I'm just dreaming^^)
I think I have to loose my thinking a little. In general I really love the way PW handles things.
1000 points for repeater matrix ;-)
Saludos
Can
Reply
diogo
Oh boy! Oh boy! Oh boy!!!
Reply
ryan
There are a lot of similarities between PageTable and Repeaters, but also a lot of differences, especially when it comes to the way they handle input. Both are equally powerful, though repeaters are a lot more turn-key, both for configuration and for input. If you've already standardized on PageTable, I would suggest sticking with it. The new repeaters require PW 3.x, which is currently a development version, whereas PageTable is already stable and in our stable PW 2.7.x version. You could always switch over to Repeaters or Repeater Matrix in the future. In terms of permissions, Repeaters pages inherit the permission from the page being edited.
Reply
Chris
so, will ProFields Repeteater Matrix Field be available for PW 2.7 ?
Reply
Joss
- 8 years ago
- 60
★★★★★Oh, this is going to make complex page construction a joy!
Reply
Pete
Agreed - max items would be a nice option and I suspect not too difficult to add :)
Reply
John Faulds
The matrix addition is excellent and means PW will now be able to handle long form content more elegantly like CraftCMS and others: http://alistapart.com/blog/post/longform-content-with-craft-matrix
Reply
SiNNuT
- 8 years ago
- 50
★★★★★Great stuff Ryan! I'm sure this will come in handy for lots of people.
Reply
thetuningspoon
FANTASTIC!!!
Reply
ryan
Thanks for all the feedback guys, glad you like the updates!
Reply
Can
- 8 years ago
- 00
★★★★★That's amazing!
The repeater matrix is still using pages for each repeater item under the hood?
I don't really understand why this is, somehow I guess it gives more flexibility, but wouldn't it be possible without pages too and have less overhead? Because when you got 20 pages (that's not much) and each is using, let's say 20-30 repeater items, that's at least 400 pages (right?)
I'm not naging and am still learning basic things in php/mysql, but therefore im interested in the reasons for this.
If there are already any comments on this, I would be happy about links as I couldn't find anything specific..
Reply
Cerulean
- 8 years ago
- 10
★★★★★Repeater Matrix: very, very nice.
Reply
Nikolaus Rademacher
- 8 years ago
- 00
★★★★★As always: Great stuff! :)
From a UI point of view the new Repeater is a clear improvement to the PageTable (at least in my use case). But except from this: What's the difference between PageTables and Pro-Repeaters? Both are using pages to store data, right? What's about editing permissions? Will repeater pages inherit the permissions from the repeater field that is creating them?
I'm just wondering if we'll reschedule our intranet launch to use the new Repeater instead of PageTables. Keep up the good work! :-)
Reply
Chris
- 8 years ago
- 10
★★★★★This branch is moving along nicely which is great to see. I love repeaters and have never come across the need to use PageTable due to performance. I would still love the opportunity to limit the number of repeaters. If my design has 3 calls to action on a homepage I only want there to be the possibility of 3. If I was to set this up for the home page with fields I may have:
Title 1
Image 1
Link 1
Title 2
Image 2
Link 2
Title 3
Image 3
Link 3
9 fields to achieve this. With repeaters it could just be 3 fields set to a limit of 3:
Title
Image
Link
This is the only thing I have ever missed from ProcessWire, its such a great framework.
Reply
Pete
- 8 years ago
- 10
★★★★★Awesome work Ryan!
For some reason I never really got on well with the old repeaters (always used to store too much data in them) and used PageTable instead, but this will likely lure me back to repeaters again.
I know you've mentioned AJAX, but will repeater fields be paginated too? Just thinking of use cases with a lot of repeaters. If they could be collapsed and opening them loads the contents via AJAX I guess that would give more scalability, but some sort of lister-style pagination would be very welcome.
Reply
Dion
- 8 years ago
- 00
★★★★★You are my hero.
This is exactly what I needed on one of my last projects and will surely use the new features in an upcoming one!
Reply
Manlio
- 8 years ago
- 00
★★★★★Excellent improvements and great new features. Profield Repeater Matrix seems really handy
Thanks!
Reply
robotpapier
- 8 years ago
- 00
★★★★★Hi,it can serve as a templatebuilder I guess. I think it would be even more flexible if we could add logic blocks where you can select fields of other pages in addition to the local custom fields of the matrix. For example instead of uploading images in a photogallery block again, just refer to a page that contains images and use a selector to include all the images of a specific page.
You would also be able to refer to all fields of a given page that would be inserted in line.
And you could even be able to insert block that list children, children that could also contain a repeater matrix and so on...
In other words make it kind of fractal.
In the API, the repeaters matrix field would be convertible to a pageArray of pageArrays and so we can compose a structure in the repeater matrix field by adding blocks and then gets it's pagearray and loop through it to render the composed structure.
This way we can also think of using this for newsletter building by selecting existing pages or any other type of data structure that mixes data from existing pages and from custom user data.
Don't know if I made myself clear, what do you think?
Reply