Embedded Table Field Type

Description:
The embedded_table field type is used to create structured data entry within a table format. It allows users to add, edit, and manage multiple rows of related data in a tabular interface. This field type is essential for capturing structured information like line items, inventory lists, or any data that benefits from a table format.

Elasticsearch Mapping: object with nested properties

YAML Definition 

- name: line_items
  type: entity
  display: embedded_table
  display_name: "Line Items"
  default_value: []
  required: false
  readonly: false
  hidden: false
  guidance: "Add line items for this order"
  fields:
    - name: "product_name"
      type: "string"
      display: "text"
      display_name: "Product Name"
      required: true
      guidance: "Enter the product name"
    - name: "quantity"
      type: "number"
      display: "number"
      display_name: "Quantity"
      default_value: 1
      required: true
      guidance: "Enter the quantity"
    - name: "unit_price"
      type: "number"
      display: "currency"
      display_name: "Unit Price"
      symbol: "£"
      precision: 2
      required: true
      guidance: "Enter the unit price"
    - name: "notes"
      type: "string"
      display: "text"
      display_name: "Notes"
      required: false
      guidance: "Additional notes for this line item"

Attributes

  • name (string): Required.
    The unique identifier for the field.

  • type (string): Required.
    Must be set to entity for embedded table fields.

  • display (string): Required.
    Must be set to embedded_table for embedded table display.

  • display_name (string): Optional.
    The label displayed in the user interface. If not provided, a formatted version of name is used.

  • guidance (string): Optional.
    Help text or instructions for the field, assisting users in understanding how to use the table.

  • required (boolean): Optional.
    If true, at least one row must be added before submission. Default: false.

  • readonly (boolean): Optional.
    If true, the table is read-only and cannot be edited by the user. Default: false.

  • hidden (boolean): Optional.
    If true, the field is hidden from the user interface. Default: false.

  • default_value (array): Optional.
    The default rows displayed when the form is first loaded.

  • fields (array): Required.
    Array of field definitions for each column in the table.

Examples

Basic Embedded Table:

- name: line_items
  type: entity
  display: embedded_table
  display_name: "Line Items"
  guidance: "Add line items for this order"
  fields:
    - name: "product_name"
      type: "string"
      display: "text"
      display_name: "Product Name"
      required: true
    - name: "quantity"
      type: "number"
      display: "number"
      display_name: "Quantity"
      default_value: 1
      required: true
    - name: "unit_price"
      type: "number"
      display: "currency"
      display_name: "Unit Price"
      symbol: "£"
      precision: 2
      required: true

Complex Embedded Table:

- name: project_tasks
  type: entity
  display: embedded_table
  display_name: "Project Tasks"
  guidance: "Add tasks for this project"
  fields:
    - name: "task_name"
      type: "string"
      display: "text"
      display_name: "Task Name"
      required: true
    - name: "assigned_to"
      type: "string"
      display: "select"
      display_name: "Assigned To"
      options: ["John", "Jane", "Mike", "Sarah"]
      required: true
    - name: "priority"
      type: "string"
      display: "select"
      display_name: "Priority"
      options: ["Low", "Medium", "High", "Critical"]
      default_value: "Medium"
      required: true
    - name: "due_date"
      type: "date"
      display: "date"
      display_name: "Due Date"
      required: true
    - name: "status"
      type: "string"
      display: "select"
      display_name: "Status"
      options: ["Not Started", "In Progress", "Completed"]
      default_value: "Not Started"
      required: true
    - name: "notes"
      type: "string"
      display: "text"
      display_name: "Notes"
      required: false

Readonly Embedded Table:

- name: completed_tasks
  type: entity
  display: embedded_table
  display_name: "Completed Tasks"
  readonly: true
  guidance: "This table shows completed tasks"
  fields:
    - name: "task_name"
      type: "string"
      display: "text"
      display_name: "Task Name"
      readonly: true
    - name: "completion_date"
      type: "date"
      display: "date"
      display_name: "Completion Date"
      readonly: true
    - name: "completed_by"
      type: "string"
      display: "text"
      display_name: "Completed By"
      readonly: true

Usage Notes

  • Table Structure:
    • The embedded table creates a dynamic table interface.
    • Users can add, edit, and remove rows as needed.
    • Each row represents a data entry with multiple columns.
  • Field Definitions:
    • Use the fields array to define the columns in the table.
    • Each field in the array follows the standard field definition format.
    • Supported field types include: string, number, date, boolean, select, etc.
  • Row Management:
    • Users can add new rows using an “Add Row” button.
    • Existing rows can be edited inline or in a modal.
    • Rows can be deleted individually or in bulk.
  • Data Validation:
    • Each field within a row can have its own validation rules.
    • Required fields within rows must be filled before the row is saved.
    • Table-level validation can ensure minimum/maximum number of rows.
  • Default Values:
    • Use default_value to pre-populate the table with existing data.
    • Each row in the default value should match the field structure.
  • Required Tables:
    • Set required: true to ensure at least one row is added.
    • Useful for essential data that must be captured.
  • Readonly Tables:
    • Use readonly for displaying data that shouldn’t be modified.
    • Common for historical data or system-generated information.
  • Use Cases:
    • Order Management: Line items for orders and invoices.
    • Project Management: Task lists and project deliverables.
    • Inventory: Product lists and stock management.
    • Time Tracking: Time entries and work logs.
    • Survey Responses: Multiple choice responses and ratings.
  • Data Structure:
    • Table data is stored as an array of objects.
    • Each object represents a row with properties matching the field definitions.
    • Supports complex nested data structures.
  • User Experience:
    • Provide clear guidance on how to use the table.
    • Consider the number of columns - too many can make the table unwieldy.
    • Use appropriate field types for each column to improve data entry.
  • Performance Considerations:
    • Large tables may impact form performance.
    • Consider pagination or limiting the number of rows for very large datasets.
    • Optimize field types and validation for better performance.
  • Accessibility:
    • Ensure that table interfaces are keyboard accessible.
    • Provide clear labels for table actions (add, edit, delete).
    • Support screen readers for table navigation and data entry.

By incorporating the embedded_table field type into your schema, you provide users with a powerful and flexible way to manage structured data in a familiar table format, enhancing the data collection and organization capabilities of your application.

Copyright © 2025 Caseblocks Limited.