Using Datagrids

Datagrids are one of the most powerful features in reBB's Standard Editor, allowing you to create dynamic, repeatable sections in your forms. This guide will help you understand and master datagrids to create more sophisticated forms.

What is a Datagrid?

A datagrid is a special component that allows users to add multiple rows of related information. Think of it as a mini-form within your form that can be repeated as many times as needed.

Common uses for datagrids include:

• Inventory or item lists
• Contact lists
• Team member rosters
• Order forms with multiple items
• Character skills or abilities
• Any collection of similar items

Creating Your First Datagrid

Adding a Datagrid to Your Form

1. In the Standard Editor, find the "Data Grid" component in the left panel
2. Drag it onto your form canvas
3. Give it a meaningful label (e.g., "Inventory Items")
4. Set a unique key (e.g., "inventory")

Adding Components Inside the Datagrid

After adding a datagrid:

1. Drag and drop a component into a datagrid
2. Configure the component as you normally would
3. Repeat for all fields needed in each row

For example, an inventory datagrid might contain:

• Text field for "Item Name"
• Number field for "Quantity"
• Textarea for "Description"

Configuring Datagrid Settings

Key settings to configure for your datagrid:

1. Label: What users see above the datagrid 2 Add Another Text: Customize the text on the "Add Another" button
2. Minimum/Maximum Values: Set limits on how many rows users can add
3. Initial Number of Values: How many empty rows to show initially

Using Datagrids in Templates

Datagrids require special wildcards in your templates to handle the repeating content.

Understanding Dataset Wildcards

For a datagrid with the key "inventory", you'll have two special wildcards:

• {@START_inventory@} - Marks where repeating content begins
• {@END_inventory@} - Marks where repeating content ends

Between these markers, you'll use the component keys from inside your datagrid.

Basic Datagrid Template Examples

Simple List Example:

[b]Inventory:[/b]
[list]
{@START_inventory@}[*]{itemName} (Quantity: {quantity}){@END_inventory@}
[/list]

When filled out, this might generate:

[b]Inventory:[/b]
[list]
[*]Healing Potion (Quantity: 5)
[*]Rope (Quantity: 1)
[*]Torch (Quantity: 3)
[/list]

Table Example:

[table]
[tr][th]Item[/th][th]Quantity[/th][th]Description[/th][/tr]
{@START_inventory@}[tr][td]{itemName}[/td][td]{quantity}[/td][td]{description}[/td][/tr]{@END_inventory@}
[/table]

Formatting Considerations

When working with datagrid templates:

1. Be careful with line breaks

   • Line breaks between {@START_key@} and {@END_key@} will be included in each iteration
   • This can affect how your output renders, especially with BBCode

2. Watch for spacing

   • Extra spaces may be included in your output
   • Test with multiple rows to see how formatting appears

3. Template placement

   • Place dataset markers precisely where repetition should occur
   • Everything between the markers repeats for each row

Advanced Datagrid Techniques

Conditional Formatting Based on Row Content

You can add conditional output by structuring your template to include different formats based on values:

[b]Team Members:[/b]
{@START_team@}
[*][b]{name}[/b] - {role} (You want to display the following based on javascript: experience >= 5 ? '(Senior)' : '(Junior)')
{@END_team@}

!! This requires using JavaScript with calculated values to prepare the fields properly. !!

Using JavaScript with Datagrids

Datagrids become even more powerful with JavaScript:

Calculating Row Totals

For a price calculator datagrid:

// In a "subtotal" field's Calculated Value
value = row.quantity * row.unitPrice;

Calculating Grand Totals

For a field outside the datagrid:

// In a "total" field's Calculated Value
var total = 0;
if (data.orderItems && Array.isArray(data.orderItems)) {
    // Note: In reBB datagrids, start from index 1 (index 0 is internal)
    for (var i = 1; i < data.orderItems.length; i++) {
        total += Number(data.orderItems[i].subtotal || 0);
    }
}
value = total;

Validating Across Rows

To prevent duplicates:

// In Custom Validation
var isDuplicate = false;
if (data.team && Array.isArray(data.team)) {
    for (var i = 1; i < data.team.length; i++) {
        // Skip comparing against current row
        if (i !== rowIndex && data.team[i].email === input) {
            isDuplicate = true;
            break;
        }
    }
}
valid = !isDuplicate;

Practical Examples

Example 1: Character Skills List

Datagrid Components:

• Text field for "Skill Name"
• Select for "Skill Level" (Novice, Adept, Expert, Master)
• Text Area for "Description"

Template:

[b]Skills:[/b]
{@START_skills@}
[*][b]{skillName}[/b] - [i]{skillLevel}[/i]
   {description}
{@END_skills@}

Example 2: Order Form

Datagrid Components:

• Select for "Product"
• Number for "Quantity"
• Calculated field for "Subtotal"

JavaScript for Subtotal:

// Using a custom price lookup based on product selection
var prices = {
    'product1': 10.99,
    'product2': 24.99,
    'product3': 5.50
};
value = (prices[row.product] || 0) * row.quantity;

Template:

[b]Order Summary:[/b]
[table]
[tr][th]Product[/th][th]Quantity[/th][th]Price[/th][/tr]
{@START_orderItems@}[tr][td]{product}[/td][td]{quantity}[/td][td]${subtotal}[/td][/tr]{@END_orderItems@}
[/table]

[b]Total:[/b] ${orderTotal}

Troubleshooting Datagrids

Common Issues and Solutions

1. Dataset wildcards not working

   • Ensure both {@START_key@} and {@END_key@} wildcards are in your template
   • Verify the key matches your datagrid's key exactly
   • Check that the wildcards are properly formatted with @ symbols

2. Missing data in output

   • Confirm users have added at least one row of data
   • Check field keys inside the datagrid match your template
   • Verify no JavaScript errors are occurring

3. Strange formatting in output

   • Check for extra line breaks or spaces between dataset wildcards
   • Ensure your BBCode or HTML is properly structured
   • Test with different numbers of rows

4. Calculation errors

   • Ensure numeric fields are properly converted to numbers in JavaScript
   • Check for missing or null values with default fallbacks
   • Verify calculations work with different input values

Datagrid Limitations and Workarounds

Current Limitations

As of reBB v1.3:

• You cannot add required fields inside datagrids
• Datagrid validation is limited to individual rows
• Nested datagrids aren't directly supported

Workarounds

1. For required fields:

   • Add a calculated validation field outside the datagrid
   • Use JavaScript to check if important fields are filled

2. For validation across rows:

   • Create a hidden calculated field to perform cross-row validation
   • Display custom error messages based on validation results

3. For complex nested structures:

   • Use careful template design with consistent indentation
   • Consider breaking complex forms into multiple steps

Best Practices for Datagrids

By mastering datagrids, you can create sophisticated, dynamic forms that handle complex data collection scenarios while producing perfectly formatted output.