Block Structure

Complete breakdown of what makes a block - from basic properties to advanced features like actions, validations, and display conditions.

🧱

What is a Block?

A block is the fundamental building unit of your form. Each block represents a single UI component (like an input field, button, or card) with its own properties, behaviors, and interactions.

Complete Block Structure

json
{
  "id": "email-input",
  "blockType": "InputBlock",
  "metadata": {
    "label": "Email Address",
    "placeholder": "Enter your email",
    "contextPath": "user.email",
    "type": "email",
    "required": true,
    "description": "We'll use this to send you updates"
  },
  "className": "mb-4",
  "style": {
    "borderRadius": "8px"
  },
  "validations": [
    {
      "rule": "email",
      "message": "Please enter a valid email address"
    },
    {
      "rule": "charMinLength",
      "value": 1,
      "message": "Email is required"
    }
  ],
  "displayConditions": [
    {
      "matchType": "exact",
      "field": "user.accountType",
      "value": "premium"
    }
  ],
  "actions": [
    {
      "type": "callApi",
      "service": "validateEmail",
      "trigger": "onBlur"
    }
  ],
  "blocks": [
    // Nested blocks for complex components
  ]
}

Block Properties Breakdown

🔹 Core Properties

  • id: Unique identifier for the block
  • blockType: Component type (InputBlock, ButtonBlock, etc.)
  • metadata: Component-specific configuration

🎨 Styling & Layout

  • className: CSS classes for styling
  • style: Inline CSS properties
  • displayConditions: When to show/hide the block

✅ Validation & Rules

  • validations: Field validation rules
  • required: Whether field must be filled
  • conditions: Conditional validation logic

⚡ Actions & Behavior

  • actions: What happens when user interacts
  • triggers: When actions should fire
  • blocks: Nested child components

1. Core Properties

ID and Block Type

json
{
  "id": "unique-identifier",
  "blockType": "InputBlock"
}

ID Requirements:

  • • Must be unique within the form
  • • Used for targeting in actions and validations
  • • Should be descriptive (e.g., "first-name-input")

Metadata Object

The metadata object contains all the block-specific configuration. Each block type has different metadata properties:

json
{
  "metadata": {
    "label": "Email Address",
    "placeholder": "Enter your email",
    "contextPath": "user.email",
    "type": "email",
    "required": true,
    "description": "We'll use this to send you updates",
    "options": [
      { "label": "Option 1", "value": "opt1" },
      { "label": "Option 2", "value": "opt2" }
    ]
  }
}

2. Styling Properties

Class Name

json
{
  "className": "mb-4 p-4 border border-gray-300 rounded-lg"
}

Use Tailwind CSS classes for responsive design and consistent styling across your form.

Inline Styles

json
{
  "style": {
    "borderRadius": "8px",
    "boxShadow": "0 2px 4px rgba(0,0,0,0.1)",
    "backgroundColor": "#f9fafb"
  }
}

3. Display Conditions

Control when blocks are visible based on form state:

json
{
  "displayConditions": [
    {
      "matchType": "exact",
      "field": "user.accountType",
      "value": "premium"
    }
  ]
}

Condition Types:

  • exact: Field equals specific value
  • regex: Field matches pattern
  • notNull: Field has any value
  • arrayIncludes: Array contains value

Multiple Conditions (AND Logic)

json
{
  "displayConditions": [
    {
      "matchType": "exact",
      "field": "user.accountType",
      "value": "business"
    },
    {
      "matchType": "notNull",
      "field": "user.companyName"
    }
  ]
}

Condition Groups (OR Logic)

json
{
  "displayConditions": {
    "operator": "OR",
    "conditions": [
      {
        "matchType": "exact",
        "field": "user.status",
        "value": "active"
      },
      {
        "matchType": "exact",
        "field": "user.role",
        "value": "admin"
      }
    ]
  }
}

4. Validation Rules

Basic Validation

json
{
  "validations": [
    {
      "rule": "email",
      "message": "Please enter a valid email address"
    }
  ]
}

Validation with Parameters

json
{
  "validations": [
    {
      "rule": "charMinLength",
      "value": 8,
      "message": "Password must be at least 8 characters"
    },
    {
      "rule": "pattern",
      "value": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)",
      "message": "Password must contain uppercase, lowercase, and number"
    }
  ]
}

Conditional Validation

json
{
  "validations": [
    {
      "rule": "charMinLength",
      "value": 1,
      "message": "Company name is required",
      "conditions": [
        {
          "matchType": "exact",
          "field": "user.accountType",
          "value": "business"
        }
      ]
    }
  ]
}

Available Validation Rules:

String Validations:
  • • charMinLength, charMaxLength
  • • charExactLength, charMinMaxLength
  • • pattern (regex)
  • • email, url, phone, zipCode
Number Validations:
  • • numberMin, numberMax
  • • numberMinMax
  • • numberMinLength, numberMaxLength

5. Actions and Triggers

Action Types

Action TypeDescriptionExample
goToPageNavigate to another page"target": "confirmation"
callApiCall a service"service": "validateEmail"
assignContextUpdate form data"assign": {"user.name": "John"}
toastShow notification"message": "Saved!"

Trigger Events

json
{
  "actions": [
    {
      "type": "callApi",
      "service": "validateEmail",
      "trigger": "onBlur"
    },
    {
      "type": "goToPage",
      "target": "next",
      "trigger": "onClick"
    }
  ]
}

Available Triggers:

  • onClick: Button clicks, link clicks
  • onChange: Input value changes
  • onBlur: Input loses focus
  • onFocus: Input gains focus
  • onLoad: Block first renders
  • onSubmit: Form submission

Action Sequences

json
{
  "actions": [
    {
      "type": "callApi",
      "service": "validateEmail",
      "then": [
        {
          "type": "toast",
          "message": "Email validated!",
          "trigger": "onClick"
        }
      ],
      "else": [
        {
          "type": "toast",
          "message": "Please enter a valid email",
          "trigger": "onClick"
        }
      ]
    }
  ]
}

6. Nested Blocks

Complex blocks can contain other blocks to create rich layouts:

json
{
  "id": "contact-card",
  "blockType": "CardBlock",
  "metadata": {
    "title": "Contact Information"
  },
  "blocks": [
    {
      "id": "name-row",
      "blockType": "RowBlock",
      "blocks": [
        {
          "blockType": "InputBlock",
          "metadata": {
            "label": "First Name",
            "contextPath": "user.firstName"
          }
        },
        {
          "blockType": "InputBlock",
          "metadata": {
            "label": "Last Name",
            "contextPath": "user.lastName"
          }
        }
      ]
    },
    {
      "blockType": "InputBlock",
      "metadata": {
        "label": "Email",
        "contextPath": "user.email",
        "type": "email"
      }
    }
  ]
}

Block Type Categories

📝 Input Components

  • • InputBlock (text, email, password)
  • • TextareaBlock
  • • SelectBlock (dropdowns)
  • • CheckboxBlock
  • • RadioBlock

🎨 Layout Components

  • • CardBlock (containers)
  • • RowBlock (horizontal layout)
  • • ColumnBlock (vertical layout)
  • • PageBlock (page wrapper)
  • • SidebarBlock

⚡ Interactive Components

  • • ButtonBlock
  • • LinkBlock
  • • ConfirmationGroupBlock
  • • LoadingBlock
  • • NavigationBlock

Best Practices

✅ Organization Tips

  • • Use descriptive IDs that indicate purpose
  • • Group related blocks together logically
  • • Keep validation messages user-friendly
  • • Use consistent styling patterns

⚠️ Performance Considerations

  • • Avoid deeply nested block structures
  • • Use display conditions instead of many conditional blocks
  • • Minimize actions on frequently triggered events
  • • Cache expensive validations

🔧 Debugging Strategies

  • • Test blocks in isolation first
  • • Use browser dev tools to inspect block properties
  • • Check console for validation and action errors
  • • Verify context paths are correct

📚 Related Documentation