Repeater

The Repeater field allows for the dynamic addition of a list of items, each comprising multiple fields. It's particularly useful for cases where a variable number of entries, each with the same structure, is needed. Below is a detailed guide on its configuration and capabilities.

Configuration

The Repeater field is defined as follows:

{
  "name": "test",
  "label": "Repeater Test",
  "group": "Global Changes",
  "type": "repeater",
  "value": [],
  "maxCount": 10,
  "translations": {
    "addItem": "Add Item",
    "duplicateItem": "Duplicate Item",
    "emptyState": "Click the button to add the first item",
    "removeItem": "Remove Item"
  },
  "hasEmptyState": true,
  "hideLabels": false,
  "structure": [
    {
      "name": "field1",
      "label": "Field 1",
      "type": "text",
      "placeholder": "Fill it",
      "spellcheck": true,
      "value": "",
      "width": 25,
      "dependencies": [
        {
          "field": "use_global_setting",
          "type": "pluginOption",
          "value": "yes"
        }
      ]
    },
    {
      "name": "field2",
      "label": "Field 2",
      "type": "number",
      "placeholder": "Fill it",
      "spellcheck": true,
      "value": 0,
      "width": 25
    },
    {
      "name": "field3",
      "label": "Field 3",
      "type": "textarea",
      "placeholder": "Fill it",
      "spellcheck": true,
      "value": "",
      "width": 50,
      "dependencies": [
        {
          "field": "field1",
          "type": "option",
          "value": "specific value"
        }
      ]
    }
  ]
}

Field Properties

Below is a comprehensive breakdown of the field properties available within the repeater configuration. These properties are critical for defining the structure and behavior of each field in the repeater. They cover everything from the basic setup, such as naming and labeling fields, to more advanced configurations, like input placeholders, default values, and conditional dependencies.

structure: Defines the structure of the fields within each repeater item. Supports the following properties:
- name: Field name.
- label: Field label for display.
- type: Field type. Supported types include text, number, textarea, dropdown, checkbox, radio, posts-dropdown, tags-dropdown, authors-dropdown, colorpicker.
- options: Array of objects { label: X, value: Y } for dropdown or radio types.
- placeholder: Text placeholder for text, number, email, url, and textarea.
- spellcheck: Enables spell check.
- multiple: Enables multiple selections for dropdowns related to posts, tags, authors.
- rows: Number of rows for textarea.
- min, max, step: Attributes for number and range types.
- allowed-post-status: Filters posts by status for posts-dropdown.
- width: Field width as a percentage.
- outputFormat: Format for the colorpicker.
- value: Default value.
maxCount: Maximum number of items allowed. Default is -1 for unlimited.
translations: Custom translations for UI elements like add, duplicate, remove buttons.
hasEmptyState: Displays an empty state message when no items are present.
hideLabels: Option to hide field labels for all but the first item row.

Dependencies in Repeater Field

The Repeater field supports dependencies, enabling the dynamic display or hiding of fields based on the values of other fields within the same repeater item or global theme options. This functionality enhances the interactivity and adaptability of the form elements, providing a tailored user experience based on input. There are two types of dependencies:

External Option Dependency (externalOption): This dependency type allows a field within a repeater to depend on a external option value. If the condition set by the pluginOption dependency is met, the field becomes visible or hidden according to the specified logic.
Option Dependency: This refers to dependencies between fields within the same repeater item. Unlike the externalOption type, this does not specify a dependency type, implying it's an intra-repeater dependency. It allows for the showing or hiding of fields based on the values of other fields within the same item.

Example Configuration

To illustrate, consider the following JSON configuration snippet that demonstrates both types of dependencies:

{
  "name": "use_in_text",
  "label": "Use in post text",
  "type": "checkbox",
  "value": true,
  "width": 33,
  "dependencies": [
    {
      "field": "wrapper",
      "type": "externalOption",
      "value": "custom"
    }
  ]
},
{
  "name": "use_in_title",
  "label": "Use in post title",
  "type": "checkbox",
  "value": false,
  "width": 33,
  "dependencies": [
    {
      "field": "use_in_text",
      "type": "option",
      "value": "true"
    }
  ]
}

Dependency Logic Explained

External Option Dependency: The field use_in_text is visible only if the external option wrapper is set to custom. This demonstrates how a field within a repeater can depend on an external setting.
Intra-Repeater Dependency: The visibility of use_in_title is contingent upon the use_in_text checkbox being checked (true). This showcases the dependency of one field on another within the same repeater item.

Implementing in Theme

After configuring the repeater field within your theme settings, the next step is to render the added items on your website. This section explains how to display the content of a repeater field named "test" within a Publii theme using Handlebars templating.

Rendering Repeater Field Content

To display each item from the repeater in your theme, you will utilize the Handlebars each loop. This method iterates over the items in the repeater field, allowing you to access and render the individual fields' values.

Below is a sample code snippet that demonstrates how to loop through the items in the "test" repeater field and display the content of field1, field2, and field3 within your theme, e.g. in index.hbs file:

{{#each @config.custom.test}}
  <div class="custom-repeater-item">
    <div class="field">
      <span class="label">Field 1:</span>
      <span class="value">{{field1}}</span>
    </div>
    <div class="field">
      <span class="label">Field 2:</span>
      <span class="value">{{field2}}</span>
    </div>
    <div class="field">
      <span class="label">Field 3:</span>
      <p class="value">{{field3}}</p>
    </div>
  </div>
{{/each}}

Key Points:

Iteration: {{#each @config.custom.test}} iterates over the repeater items, allowing access to each item's fields.
Field Access: Inside the loop, {{field1}}, {{field2}}, {{field3}} are used to insert the values of the corresponding fields.
HTML Structure: The sample uses div and span tags to structure the output, which can be customized based on your theme's design requirements.