The repeater fieldtype enables you to create a group of fields and make it repeatable in any quantity on your page.

This opens many new possibilities with how you might manage and structure data. 

Repeatable fields are also referred to as matrix fields in some other platforms. We refer to them as repeatable fields or repeaters, but they are all the same thing. Below is a video that demonstratates how to create and use a repeater field. I suggest viewing the video full screen to see the higher resolution version. 

When to use repeaters

Repeaters are ideal for managing simple-to-complex groups of information in smaller known or unknown quantities. Things like rate tables, locations, product variations, staff directories, photo galleries with meta data, and so on might be a good fit with repeaters. The sky is the limit. 

Choose repeaters when they will represent a good long term, and short-term, solution to a problem. If you know the quantity of repeated items will stay at a reasonable size on the given pages despite time and scale, repeaters are a good solution to consider.

When not to use repeaters

Repeaters aren't infinitely scalable in quantity, so avoid repeaters for quantities of items that you think may need to be infinitely scalable. When you edit a repeater field in your page, you edit all items at once. As a result, you probably don't want to use a repeater if you expect hundreds of items, as that may slow your editing experience. It's better to use pages without repeaters when dealing with huge quantities of items. 

You also don't want to use repeaters for items of content that you want to have their own URL. Individual repeater items don't have individual URLs, so repeaters are better for items that you will be showing as a group on one page. However, there's nothing preventing you from attaching repeater items to URL segments or GET variables (for example), but consider whether you would be better off just using regular pages. 

How to use repeaters

How to create a repeatable field

The repeaters fieldtype is not installed by default. To install, login to your ProcessWire admin and click to Modules. Locate the Fieldtype section and click the Install button for the Repeater fieldtype. 

Next create the individual fields that will live in your repeater. Create these fields like you would any other, from Setup > Fields > Add New Field. Lets say that I wanted to create fields to hold data for skyscrapers. I might plan to re-use the built-in title field for my building name, and then create these 3 new fields:

  • feet_high
  • num_floors
  • year_built

Once you've created the fields you want to use with your repeater, you can go on to create the actual repeater field. Click Setup > Fields > Add New Field, and choose "Repeater" as the field type. Continuing the example above, I might name my field "buildings". Click Save and the repeater field will be created. 

Now you want to add the title, feet_high, num_floors and year_built fields to your repeater. Click the details tab while editing your repeater field. Select those fields to add them. Drag them to the order you want. Then click Save.

After saving, you may want to customize the title field so that it has a label of "Building Name" rather than "Title". While still in the details tab, click the name "title" in your list of fields. It will pop open a modal window enabling you to change the context of the title field when used in this buildings repeater field. Change the label to "Building Name" and click Save. Now click Save again in the field editor. 

Next you want to add your buildings repeater field to a template. Go to Setup > Templates and click an existing template to edit. In my case, I'm editing my "home" template. In the field selection box, select the field "buildings" (or whatever you named your repeater field) to add it to the template. Then click Save.

Now you can edit or create any pages using that template and they will have the repeater field available. All you need to do to add a repeater is click "add new", populate your content and Save your page. 

What are ready items?

When you create or edit a repeater field in Setup > Fields, you'll see an option that refers to "ready items". This represents the quantity of items that will be kept cached in the system, ready for edits. In the page editor, you'll see an "add item" link and every time you click that, you'll get one of those ready-to-edit items. If there aren't any ready items, then you'll instead get a notice that says you must save the page before the item will be ready to edit. 

It is most efficient to have 0 ready items, but it's more convenient to have at least 1 ready item. That way you don't have to save the page before adding every item. If you routinely add lots of items at a time, you may want to increase this number to 3 or more. But don't set the number any higher than you need it, as ready items do take up space in the system. 

Outputting repeatable fields

The individual items contained in a repeater field are technically pages in ProcessWire. The value of a repeater field is a PageArray. As a result, you may interact with them exactly like you would any other group of pages in ProcessWire. You might iterate through and output the group of items like this (using the fictional buildings repeater, created in the previous section): 

foreach($page->buildings as $building) {
    echo "<h2>{$building->title}</h2><p>";   
    echo "Height: {$building->feet_high} feet, ";
    echo "Floors: {$building->num_floors}, ";
    echo "Year built: {$building->year_built} </p>";
} 

That's all there is to it. Everything that you know about outputting any other pages in ProcessWire applies to outputting repeaters. 

Testing for an empty value

Like with any other PageArray, you can tell how many items there are by using count(): 

if(count($page->buildings)) {
    echo "<p>There are " . count($page->buildings) . " buildings.</p>";
} else {
    echo "<p>There are no buildings.</p>";
}  

Finding pages by repeater value (using selectors)

Use selector subfields to locate pages by a value in a repeater field. Subfields are those that are split with a period, like "field.subfield". This is best demonstrated by examples, again continuing with our buildings field, we will locate pages that have a buildings repeater field by properties of the individual buildings within that repeater field: 

// find all pages that have at least one building with a height > 500 feet
$buildings = $pages->find("buildings.height>500"); 

// find all pages that have a building made in 1940 with at least 20 floors
$buildings = $pages->find("buildings.year_built=1940, buildings.num_floors>=20");

// find all pages using the basic-page template with at least 1 building
$buildings = $pages->find("template=basic-page, buildings.count>0")     

Using the API to add or remove repeater items

Unlike other pages in ProcessWire, new repeater items must be created by ProcessWire rather than you. As a result, a helper method is provided called getNew(). You may call getNew() on any repeater field to get a new item. The item that it returns is ready to populate and has already been added to the repeater. Once populated, you simply save the page that the repeater field is on. 

$building = $page->buildings->getNew();
$building->title = 'One Atlantic Center';
$building->feet_high = 880;
$building->num_floors = 50;
$building->year_built = 1997;
$building->save();
$page->buildings->add($building);
$page->save();      

Remove a repeater item in exactly the same way you remove an item from any other PageArray: 

$building = $page->buildings->first(); // or whatever item you want to remove
$page->buildings->remove($building);
$page->save();   

Implementing templates for repeater fields

While not commonly done, you can actually implement template files for your repeater fields, if you want to.

If you want to implement a template file for your repeater, you create a file in your /site/templates/ named "repeater_[field name].php", i.e. in the case of the buildings field, it would be "repeater_buildings.php". That template file will receive a $page variable that is represents one 'buildings' record. So you could do something like this:

/site/templates/repeater_buildings.php

echo "<h2>{$page->building_name}</h2>"; 
echo "<p>{$page->floors} floors, {$page->height} feet</p>";

The template used by your page with a 'buildings' field could then do this:

/site/template/basic-page.php

foreach($page->buildings as $building) {
    echo $building->render();
}

See Also

Repeater forum thread

Comments

  • Lars282

    Lars282 5 years ago 21

    It seems that when using the API to add repeater items, you need to save the page after calling getNew(). It does not seem to be the case that "The item that it returns is ready to populate and has already been added to the repeater."

    When not saving first, it returns an error when I try to add an image to the repeater item.

    Lars

  • MarionRaven

    MarionRaven 5 years ago 11

    It should be noted that a search will not yield any hits from repeater fields. I guess that is because the content actually belongs to a hidden page.

  • Gertrud Schrenk

    Gertrud Schrenk 4 years ago 31

    Gorgious. Großartig. Unbelievable. Brillant. Frábært.

    How long would you have to strive in second best CSM modX to achieve this... and other things...

    Thank you.

  • jwaldeck

    jwaldeck 4 years ago 11

    Hi Ryan - this module is amazing, but I noticed the same issue that "MarionRaven" mentioned.. When you search for an item created as a repeater, the search result doesn't "see" these elements and they are not displayed.

    Is there any workaround this?

    Tks!

  • Arjen

    Arjen 4 years ago 11

    Marionraven,

    Nik posted a solution to search within repeaters. See http://processwire.com/talk/topic/1869-searching-and-repeaters/?p=17497

  • Steve

    Steve 3 years ago 11

    Is there a way to limit the number of repeater items. For example, I'd like to allow a user to add only 3 repeater items and not more.

    • Ryan

      Ryan 3 years ago 21

      Currently there is not such a setting available for repeaters, but perhaps we can add it in a future version.

  • Batyr

    Batyr 3 years ago 11

    Hi, Thank you for descriptive tutorial on how to use repeaters. I have problem which I couldn't resolve. I have a huge gallery of picture on my website and I use repeater, but when I wanted to add more than 140 pictures processwire doesn't save them. Is there any way to fix this?

    • Ryan

      Ryan 3 years ago 21

      Chances are you are running up against PHP's max_input_vars limit. This is something that can be changed in the php.ini: http://www.php.net/manual/en/info.configuration.php#ini.max-input-vars

      You might also consider using PageTable, which shouldn't be affected by PHP's max_input_vars setting.

Post a Comment

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