Skip to main content

Collection Configs

Collection Configs allow you to define dynamic form models for your iXR Database collections. With this feature, you can create user-friendly forms that automatically generate documents in your collections with proper validation and structure.

🎯 Overview​

Collection Configs provide a visual form builder that lets you:

  • Define form fields with various input types (text, number, date, select, checkboxes, etc.)
  • Create multi-step forms to organize complex data entry
  • Set up field relationships (conditional visibility, dependencies, validation rules)
  • Generate JSON Schema automatically for validation
  • Create documents through user-friendly forms instead of raw JSON editing

📑 Page Layout​

The Collection Configs page displays a table with all available configurations:

  • Name: The display name of the configuration
  • Collection Name: The target iXR Database collection where documents will be stored
  • Steps: Number of form steps defined
  • Fields: Total number of form fields
  • Actions: Edit, Delete, and Generate Form options

➕ Creating a Collection Config​

Step 1: Basic Information​

  1. Navigate to Collection Configs page
  2. Click the + button to create a new configuration
  3. Fill in:
    • Configuration Name: A descriptive name for your form (e.g., "User Registration Form")
    • Collection Name: The iXR Database collection name where documents will be stored

Step 2: Define Steps​

Steps organize your form into logical sections:

  • Click + Step to add a new step
  • Set the Step Title (e.g., "Personal Information", "Preferences")
  • Optionally add a Description to guide users
  • Reorder steps using drag handles
  • Delete steps using the trash icon

Step 3: Add Fields​

For each step, add fields:

  1. Click + Field within a step

  2. Configure the field:

    • Name: Internal field name (used in JSON, must be unique)
    • Label: Display label shown to users
    • Type: Input type (see Field Types below)
    • Placeholder: Hint text shown in empty inputs
    • Help Text: Additional guidance displayed below the field
    • Default Value: Pre-filled value (optional)
    • Order: Display order within the step

  3. Configure Validation:

    • Required: Mark field as mandatory
    • Min/Max: For numbers and ranges
    • Min Length/Max Length: For text fields

  4. Add Values (for SELECT, RADIO, CHECKBOX_LIST):

    • Click + Value
    • Enter Label (displayed) and Value (stored in JSON)

  5. Set up Relations (optional):

    • Visibility: Show/hide field based on other field values
    • Dependency: Enable/disable field based on conditions
    • Validation: Cross-field validation rules

🎨 Field Types​

Text Inputs​

  • TEXT: Single-line text input
  • TEXTAREA: Multi-line text input
  • EMAIL: Email address with format validation
  • URL: URL with format validation
  • PASSWORD: Password input (masked)

Numeric Inputs​

  • NUMBER: Numeric input with min/max validation
  • RANGE: Single-value slider (min-max range)
  • RANGE_SELECTOR: Dual-value slider for selecting a range (e.g., age range 25-65)

Selection Inputs​

  • SELECT: Dropdown menu (single selection)
  • RADIO: Radio button group (single selection)
  • CHECKBOX: Single checkbox (boolean)
  • CHECKBOX_LIST: Multiple checkboxes (array of selected values)

Date/Time Inputs​

  • DATE: Date picker (YYYY-MM-DD format)
  • TIME: Time picker (HH:mm:ss format)
  • DATETIME: Date and time picker (ISO 8601 format)

🔗 Field Relations​

Field relations allow you to create dynamic, conditional forms:

Visibility Relations​

Control when fields are shown:

  • Action: Hide or show the field
  • Conditions: Define when the action applies
    • Field: Select the field to watch
    • Operator: equals, not equals, greater than, less than, contains
    • Value: The value to compare against

Example: Show "Emergency Contact" field only when "Has Emergency Contact" checkbox is checked.

Dependency Relations​

Control field state:

  • Action: Enable or disable the field
  • Conditions: Same as visibility relations

Example: Disable "Spouse Name" field when "Marital Status" is "Single".

Validation Relations​

Cross-field validation:

  • Define custom validation rules based on other field values
  • Useful for complex business logic (e.g., "End Date must be after Start Date")

📝 Generating Forms​

Once your configuration is saved:

  1. From the Collection Configs list, click Create (play icon) next to a configuration
  2. The form generator page opens with:
    • Stepper at the top showing progress through steps
    • Form fields rendered based on your configuration
    • Navigation buttons: Back, Next, and Submit

Form Features​

  • Live Validation: Fields are validated as you type
  • Step Navigation: Move between steps using Next/Back buttons
  • Error Display: Validation errors shown inline and in an alert banner
  • Responsive Layout: Fields arranged in two columns on larger screens
  • Conditional Fields: Fields appear/disappear based on relations

Submitting Forms​

  1. Fill in all required fields
  2. Navigate through all steps
  3. Click Submit on the final step
  4. The document is created in the specified collection
  5. You're redirected back to the Collection Configs list

✅ Validation​

Frontend Validation​

  • Real-time validation as users type
  • Required field checks
  • Format validation (email, URL, date, time)
  • Range validation (min/max for numbers)
  • Cross-field validation via relations

Backend Validation​

When documents are created, the backend:

  1. Generates JSON Schema from your configuration
  2. Validates the submitted data against the schema
  3. Returns detailed error messages if validation fails
  4. Only creates the document if validation passes

🔄 Workflow​

💡 Best Practices​

📌 Plan Your Form Structure

Before creating fields, sketch out your form structure. Group related fields into logical steps for better user experience.

🎯 Use Appropriate Field Types

Choose field types that match your data:

  • Use SELECT or RADIO for limited choices
  • Use CHECKBOX_LIST for multiple selections
  • Use RANGE_SELECTOR for min-max selections (e.g., age range)
  • Use DATE/TIME/DATETIME for temporal data
✅ Set Validation Rules

Always set validation rules:

  • Mark required fields
  • Set min/max for numeric fields
  • Set min/max length for text fields
🔗 Leverage Field Relations

Use relations to create smart forms:

  • Hide irrelevant fields to reduce clutter
  • Disable fields when not applicable
  • Guide users through conditional workflows
📝 Use Clear Labels
  • Use descriptive labels that users understand
  • Add help text for complex fields
  • Use placeholders to show expected format
🔄 Test Your Forms

After creating a configuration:

  1. Generate a form and test all fields
  2. Verify validation works correctly
  3. Test conditional fields (relations)
  4. Submit a test document and verify it's created correctly

🚨 Common Issues​

Fields Not Updating After Config Edit​

Issue: After updating a collection config, the form still shows old fields.

Solution: The schema cache is automatically cleared when you update a config. If you still see old fields, refresh the form generator page.

Validation Errors on Submit​

Issue: Form submits but backend returns validation errors.

Solution:

  • Check that all required fields are filled
  • Verify field formats match expectations (e.g., email format, date format)
  • Ensure numeric values are within min/max ranges
  • Check that array fields (checkbox lists) contain valid enum values

Checkbox List Not Rendering​

Issue: Checkbox list shows label but no checkboxes.

Solution: Ensure you've added values to the field. Each value needs both a Label (displayed) and Value (stored).

Time Field Validation Error​

Issue: Time field shows "must match format 'time'" error.

Solution: The time format expects HH:mm:ss (e.g., 14:30:00). Ensure your time picker outputs this format.

💼 Business Case​

Business Case — Dynamic Content Management

Imagine you're building a VR training platform where trainers need to create scenarios without coding knowledge.

Without Collection Configs:

  • Trainers must write JSON manually
  • High error rate from invalid JSON
  • Requires technical knowledge
  • Slow content creation

With Collection Configs:

  • Trainers use a visual form builder
  • Forms guide them through scenario creation
  • Validation prevents errors
  • Fast, user-friendly content creation

Example Scenario Form:

  • Step 1: Basic Info (Name, Description, Difficulty)
  • Step 2: Timing (Duration, Start Time, End Time)
  • Step 3: Safety (Dangerous Items checklist, Safety Level)
  • Step 4: Resources (URLs, Attachments)

When a trainer submits the form, a properly structured document is created in the scenarios collection, ready to be used by the VR application.

🚧 Planned Features​

The following features are planned for future releases:

Default Collection Documents​

When creating a collection config, you will be able to create a default document that serves as a template for new documents. This default document:

  • Contains pre-filled values for all fields
  • Can be used as a starting point when generating new documents
  • Ensures consistency across documents in the collection
  • Can be updated at any time to reflect changes in the collection structure

Use Case: For a "User Preferences" collection, you could set default values like theme: "light", language: "en", notifications: true so every new user starts with sensible defaults.

Document Assignment to End Users​

You will be able to assign specific documents to end users or reset them to the default document. This feature enables:

  • Personalization: Assign custom documents to individual end users
  • Default Reset: Reset a user's document back to the collection's default document
  • User-Specific Data: Maintain user-specific configurations while keeping defaults available

Use Case: In a VR training platform, you could assign a specific training scenario document to a user, or reset their progress back to the default training scenario.

Not Yet Implemented

These features are currently in planning and not yet available in the system.

🔧 Technical Details​

JSON Schema Generation​

When you save a collection config, the system:

  1. Converts your field definitions into JSON Schema
  2. Generates UI Schema for form rendering
  3. Handles field relations using JSON Schema if/then conditions
  4. Validates the schema before saving

Document Creation​

When a form is submitted:

  1. Frontend validates data using the same JSON Schema
  2. Data is sent to /projects/:projectId/collections/:collectionName
  3. Backend validates against the generated schema using Ajv
  4. If valid, document is created in the iXR Database collection
  5. If invalid, detailed error messages are returned

Schema Caching​

  • Schemas are cached by configuration ID for performance
  • Cache is automatically cleared when a config is updated
  • Forms always use the latest schema version

📚 Related Documentation​

  • Database - Learn about iXR Database collections and documents
  • Permissions - Understand access control for collection configs