Replicator

The Replicator fieldtype allows you to define sets of fields that you can dynamically piece together in the Control Panel to create a freeform content area.

It’s similar to the Grid in that you can create an infinite amount of re-orderable content, but with Replicator, each ‘row’ can contain different fields.

It’s a perfect way to give your client the flexibility of creating the document flow they need without sacrificing the structure you want.

Setting up sets

A single replicator field is made up of multiple sets containing one or more fields. Within each set, you’d insert fields just like you would anywhere else.

Here’s an example fieldset containing a Replicator field with 3 sets – basic content, a quote, and an image:

fields:

  my_replicator_field:
    type: replicator
    instructions: |
      Replicate a new set for each piece of content you need.

    sets:

      content_set:
        display: Content
        instructions: A basic block of text
        fields:
          text:
            display: Text
            type: markitup

      quote_set:
        display: Quote
        instructions: A lovely pullquote
        fields:
          quote:
            type: textarea
            height: 40
            instructions: What was said?
          cite:
            type: text
            instructions: Who said it?

      image_set:
        display: Image
        instructions: Showcase your adventures in a gallery
        fields:
          photo:
            type: file
            allowed: [png, jpg, gif]
            destination: assets/img/
          caption:
            type: text
            instructions: Describe the photo

note You can name your sets whatever you want. The names will be what you use in your templates. We’ve appended _set here just to make it clearer.

Each set can have its own set of instructions. They will be visible in the set itself, and when you hover over the add buttons.

Using Replicator

You will be presented with a button for each set you’ve defined. Clicking one will replicate an empty set. You can replicate a single set type as many times as you like as well as dragging and dropping them to adjust their order.

Outputting in your templates

Once you’ve populated your field, you’ll need a way to output it.

Replicator stores your data as an array, with the set name as type, so you just need to use the tag pair syntax with an if else statement. Simple!

{{ my_replicator_field }}

  {{ if type == "content_set" }}

    <div class="text">
      {{ text|markdown }}
    </div>

  {{ elseif type == "quote_set" }}

    <setquote>{{ quote }}</setquote>
    <p>&mdash; {{ cite }}</p>

  {{ elseif type == "image_set" }}

    <figure>
      <img src="{{ photo }}" alt="{{ caption }}" />
      <figcaption>{{ caption }}</figcaption>
    </figure>

  {{ endif }}

{{ /my_replicator_field }}

Nesting

Grids can go inside Grids, can you put a Replicator inside a Replicator? No, you can’t do that.
Let us know if you think you have a valid use case for needing to do this.

However, you can definitely put a Grid inside a Replicator set. You can even put a Grid inside that Grid. Hey, while you’re at it, put another Grid in that Grid. Xzibit would be proud.