Repeater Fields

Welcome to the Repeater Fields guide! This article explains how to let your users add multiple entries for the same information—like products in an order form, expenses in a budget, or tasks in a to-do list.

What is a Repeater Field?

A Repeater Field is a special form element that allows users to click an Add button to create more entries of the same set of fields. This is handy when you need flexibility—such as adding multiple line items on an invoice or recording various items in a single form.

Benefits of Using Repeater Fields

• Save Time: Users can add multiple items without filling separate forms.
• Stay Flexible: Set minimum or maximum limits for how many items can be added.
• Automatic Calculations: Easily calculate totals, averages, or other formulas as new items are added.

Setting Up a Repeater Field

1. Add the Repeater Element: In your form builder, select the Repeater element.
2. Name the Repeater: For example, "Order Items" or "Expenses." This name will be used in your formulas.
3. Description (Optional): Provide a brief instruction for users (e.g., "Add each product you want to purchase").
4. Item Labels & Limits: You can set a custom label (e.g., "Item," "Expense"), as well as minimum and maximum items allowed.

Adding Fields Inside the Repeater

Within a repeater, you can include:

• Number fields (price, quantity, hours)
• Text fields (description, item name)
• Dropdowns (category, product type)
• Date fields (purchase date, deadline)
• Checkboxes (mark items as completed or optional)

Tips:

• Add placeholder text for clarity (e.g., "Enter unit price").
• Use validation rules (e.g., ensure quantity is a number).
• Pre-fill default values if it makes sense (e.g., set quantity to 1).

Calculations with Repeater Fields

1. Calculating for Each Entry

When you need to compute something for every item (like price × quantity), you’ll typically use Repeater Context Variables.

Repeater Context Variables

A Repeater Context Variable automatically applies a formula to every entry in the repeater. This is how you get per-item calculations (e.g., a line total) in each row.

How to Set It Up

1. Create a new variable in your form.
2. Turn on "Use in Repeater Context" in the variable’s settings.
3. Select the specific repeater you want to link it with.

Getting Field Values in Each Item

Use getCurrentValue("fieldName") inside the repeater context:

getCurrentValue("price") * getCurrentValue("quantity")

This formula calculates a line total for each item.

2. Calculating Across All Entries

To aggregate data across all items (e.g., summing every line total in a list of products), you can use functions available in Standard Mode:

repeaterSum("orderItems", "amount")

This adds up the "amount" field for all items in the orderItems repeater.

For more complex calculations (like multiplying fields before summation):

repeaterExpressionSum("orders", "@price * @quantity")

3. Using JavaScript Mode (Advanced)

If you prefer a coding approach or need custom logic, you can switch to JavaScript Mode. Keep in mind that standard repeater functions (like repeaterSum) are not available in JavaScript Mode.

Example:

// Get the current entry
const item = getCurrentItem();
return item.price * item.quantity;

Or, to work with all entries:

const items = orderItems; // 'orderItems' is your repeater’s name
return items[0].price; // Access the price of the first item

Note: If you’re not comfortable with JavaScript, standard mode should cover most use cases.

Standard Repeater Functions

Basic Functions

• repeaterSum("repeaterName", "fieldName") Sums the specified field across all entries.
• repeaterCount("repeaterName") Counts the number of items in the repeater.
• repeaterAverage("repeaterName", "fieldName") Calculates the average value of a specified field.
• repeaterGet("repeaterName", "fieldName", index) Retrieves a field value from a specific item (index starts at 1).

Text Functions

• repeaterJoin("repeaterName", "fieldName", ", ") Combines the text from a field across all items, separated by the character(s) you choose.

Advanced Functions

• repeaterExpressionSum("repeaterName", "@field1 * @field2") Performs complex calculations across all entries.
• repeaterCountNotEmpty("repeaterName", "fieldName") Counts how many entries have a given field filled.

Example Scenarios

1. Simple Order Form

• Fields: Item description, Quantity, Price
• Line Total (per item): getCurrentValue("price") * getCurrentValue("quantity")
• Total Amount (all items): repeaterSum("orderItems", "lineTotal")

2. Expense Tracker

• Fields: Date, Category, Amount
• Total Expenses: repeaterSum("expenses", "amount")

3. Invoice Generator

• Fields: Service Description, Hours, Rate
• Per-Item Total: getCurrentValue("hours") * getCurrentValue("rate")
• Invoice Total: repeaterSum("invoiceItems", "lineAmount")

Tips for a Great User Experience

1. Clear Labels: Make fields obvious (e.g., "Item Price," "Select Category").
2. Helpful Defaults: If a field often has the same value, pre-fill it (e.g., default Quantity = 1).
3. Set Reasonable Limits: Prevent confusion by capping the maximum number of entries if needed.
4. Consistent Layouts: Group related fields (price, quantity, etc.) together.

Frequently Asked Questions

Q: How many items can users add? A: You decide by setting minimum and maximum values in the repeater settings.

Q: Can I nest repeaters? A: No, you currently cannot place a repeater inside another repeater.

Q: How do I format numbers (e.g., currency)? A: In field settings, you can choose the number of decimals, add currency symbols, or enable thousand separators.

Troubleshooting

• Calculations Not Working?

  • Make sure your field names match exactly (case-sensitive).
  • Verify you’re using the right function (e.g., repeaterSum instead of SumRepeater).
  • Test with simple data to isolate the issue.

• Add Button Not Appearing or Not Working?

  • Confirm you haven’t reached the maximum allowed entries.
  • Check if you’re in preview mode, which may limit functionality.
  • Ensure no required fields are blocking progress.

Next Steps

Try adding a Repeater Field to one of your forms and see how much easier it is to handle multiple entries. If you need advanced calculations, explore the standard functions—or dive into JavaScript mode if you’re comfortable coding. Don’t forget to test everything thoroughly!

That’s it! You should now have all you need to start using Repeater Fields effectively. Happy building!