Grouping replicator sets in Statamic

Grouping replicator sets in Statamic

In our quest to build highly customizable websites for customers we stumble in a lot of roadblocks. Giving the client the power to edit the content without breaking the website is one of our goals at Lucky Media.

Luckily we discovered Statamic, which is a flat-file CMS that runs as a Laravel package and you can customize it in every way possible. It comes battery included, but you can always customize it to your own needs because it's built as a Laravel package.

Just recently, we had a client with a very complex website and with as many as 90+ pages. The client builds every page with the help of ready to use blocks that we made available from the CP. If you already use Statamic as a developer, you know the current limitation of the Replicator Field and large sets. If you include all the sets then you end up with a very large list of sets which is extremely difficult to navigate. In this post we will talk about how to group your sets in a replicator field.

Here is a quick picture of what we saw before using the new technique for grouping them:

In our project we had roughly 40+ sets and the above picture is a bit hard to read through.

So how can we group all of this? Natively Statamic doesn't support this yet although an idea was already submitted at the ideas repo . Until there is an official way to group sets, lets take a look at our solution.

To save some time, I will assume you already have a Statamic project running, in our case we use Tailwind CSS for styling but you are free to use anything you want.

In the page blueprint we have the following configuration:

title: Pages
sections:
  main:
    display: Main
    fields:
      -
        handle: title
        field:
          type: text
          required: true
          validate:
            - required
      -
        handle: blocks
        field:
          collapse: false
          sets:
          display: Blocks
          type: replicator
          icon: replicator
          listable: hidden
  sidebar:
    display: Sidebar
    fields:
      -
        handle: slug
        field:
          type: slug
          required: true
          localizable: true
          validate:
            - required

As you can see for now we only have one replicator field called blocks that we will add new sets into it.

We start by grouping our sets, as you saw on the picture, we have Header Sections, Featured Sections, etc.. and for now they are ordered as 1, 2, 3 etc. But, we will start by writing just the category name in our case it will be like this:

  • Header Section
  • CTA Section
  • Featured Section
  • Logo Cloud
  • Testimonial Section
  • Partner Section
  • Gallery Section

Here we have only 6 categories, and inside them we can have as many variations as we want. Usually you might have 2-3 variations for each block depending on the scale of your website. So how do we target each file in these sets? In our case we decided to go with button group but you are free to use select for a more compact view.

Here is a config for one of our sections, the CTA Section:

cta_section:
  display: "CTA Section"
  fields:
    - handle: version
      field:
        options:
          cta_section_1: "Version 1"
          cta_section_2: "Version 2"
          cta_section_3: "Version 3"
        display: "CTA Version"
        default: "cta_section_1"
        type: button_group
        icon: button_group
        instructions: "Select a CTA Style"
        listable: hidden
        validate:
          - required
    - handle: title
      field:
        input_type: text
        antlers: false
        display: Title
        type: text
        icon: text
        listable: hidden
        validate:
          - required
    - handle: description
      field:
        antlers: false
        display: Description
        type: textarea
        icon: textarea
        listable: hidden
    - handle: link
      field:
        display: Link
        type: link
        icon: link
        listable: hidden

As you can see for our CTA Section we have a button group for each version, the values of each option represents one file in our template. Basically cta_section_1 should be under partials/sets/cta_section/cta_section_1.antlers.html but we will touch on this a bit later. Note that there is a default value on our button group, this is to mitigate any error when used in a Live Preview window.

Also very important for your button group (or if you prefer select) to have a handle name of version as we will use this in the frontend. Our CTA Section has a title, description and a link field.

You can go into more detail and add more fields for each CTA field and then trigger their visibility by the version value but that is up to you.

Here is how we organize our files in the frontend, under resources/views/ we have a folder for sets. Under sets we have the following structure:

  • cta_section
    • cta_section_1.antlers.html
    • cta_section_2.antlers.html
    • cta_section_3.antlers.html
  • logo_cloud
    • logo_cloud_1.antlers.html
    • logo_cloud_2.antlers.html
    • logo_cloud_3.antlers.html

You can do this for all the block categories that you have and create different versions for each one of them.

Please note that the root folder is the name of the handle, and the file names should be based on the options that you provided under versions in the config above.

To display each set in our frontend, we have to go to resources/views/pages/show.antlers.html and add the following code:

{{ block }}
    {{ partial src="sets/{type}/{version}" }}
{{ /blocks }}

And now in our replicator for each section we only have the name of the category:

This is way cleaner and user-friendly than what we had before.

In our control panel every section is neatly displayed and you can select different versions for each section in a simple way. Here is how our CTA Section looks like with 3 versions:

If you want to check the code for this we have a basic example repo here.