Skip to main content

View Metadata

Where it lives
JSON Pointer: /views
JSONPath: $.views
Parent: Root of the metadata file

Overview​

Views define UI presentation of models and automatically generate:

  • List Views: Tabular display with search, filter, pagination
  • Form Views: Input forms for create/edit operations
  • Kanban Views: Card-based display with drag-and-drop

How to read this page: Each code sample below is preceded by a short explanation of what the snippet configures and how it affects the generated UI.

Example: Fee Portal List/Form Views​

What this shows: A combined example of a list view and a form view for an Institute model inside a Fees Portal module. The list section demonstrates pagination, search and row actions. The form section demonstrates the hierarchical layout (sheet → notebook → page → row → column → field) and how to attach a form handler.

View Schema (List + Form)

{ // List View for Institute Model
  "name": "institute-list-view",
  "displayName": "Institute",
  "type": "list",
  "context": "{}",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "institute",
  "layout": {
    "type": "list",
    "attrs": {
      "pagination": true,
      "pageSizeOptions": [10, 25, 50],
      "enableGlobalSearch": true,
      "create": true,
      "edit": true,
      "delete": true,
      "rowButtons": [
        {
          "attrs": {
            "className": "",
            "label": "Enable",
            "action": "ActivatePortal",
            "icon": "pi",
            "actionInContextMenu": false,
            "customComponentIsSystem": true,
            "openInPopup": true,
            "closable": true
          }
        }
      ],
      "configureViewActions": {
        "import": { "roles": ["Admin", "Mswipe Admin"] }
      },
      "children": [
        {
          "type": "field",
          "attrs": {
            "name": "id",
            "sortable": true,
            "filterable": true,
            "isSearchable": true
          }
        }
      ]
    }
  }
},
{ // Form View for Institute Model
  "name": "institute-form-view",
  "displayName": "Institute",
  "type": "form",
  "context": "{}",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "institute",
  "layout": {
    "type": "form",
    "attrs": {
      "name": "form-1",
      "label": "Institute",
      "className": "grid",
      "formButtons": [
        {
          "attrs": {
            "className": "",
            "label": "Preview",
            "action": "PreviewPortal",
            "icon": "pi",
            "actionInContextMenu": true,
            "openInPopup": true,
            "customComponentIsSystem": true,
            "closable": true
          }
        }
      ]
    },
    "onFormLayoutLoad": "instituteEditHandler",
    "children": [
      {
        "type": "sheet",
        "attrs": { "name": "sheet-1" },
        "children": [
          {
            "type": "notebook",
            "attrs": { "name": "notebook-1" },
            "children": [
              {
                "type": "page",
                "attrs": { "name": "page-1", "label": "Institutes" },
                "children": [
                  {
                    "type": "row",
                    "attrs": { "name": "sheet-1" },
                    "children": [
                      {
                        "type": "column",
                        "attrs": {
                          "name": "group-1",
                          "label": "Institutes Basic",
                          "className": "col-6"
                        },
                        "children": [
                          { "type": "field", "attrs": { "name": "instituteName" } }
                        ]
                      },
                      {
                        "type": "column",
                        "attrs": {
                          "name": "group-1",
                          "label": "Institutes Contact",
                          "className": "col-6"
                        },
                        "children": [
                          {
                            "type": "field",
                            "attrs": {
                              "name": "instituteAddress",
                              "disabled": false
                            }
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

View Configurations​

List View

List views display records in tabular format with advanced features like search, filtering, and pagination.

1) Basic List View Structure​

What this shows: The minimal configuration for a list view. Connect to a module/model and define a layout with attrs (behavior) and children (columns).

List View Structure

{
  "name": "institute-list-view",
  "displayName": "Institute",
  "type": "list",
  "context": "{}",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "institute",
  "layout": {
    "type": "list",
    "attrs": {
      // List view attributes
    },
    "children": [
      // Field configurations
    ]
  }
}

2) List View Attributes​

What this shows: How to toggle pagination and CRUD actions from the list, and how to restrict actions to specific roles.

List View Attributes

"attrs": {
  "pagination": true,
  "pageSizeOptions": [10, 25, 50],
  "enableGlobalSearch": true,
  "create": true,
  "edit": true,
  "delete": true,
  "import": { "roles": ["Admin"] },
  "showArchived": { "roles": ["Admin"] },
  "export": { "roles": ["Admin", "Institute Admin"] },
  "customizeLayout": { "roles": ["Admin"] },
  "saveCustomFilter": { "roles": ["Admin"] }
}

3) List View Field Configuration​

What this shows: Each item in children is a column. Control sort, filter and search participation; viewWidget customizes how the value renders.

Field Configuration

"children": [
  {
    "type": "field",
    "attrs": {
      "name": "instituteName",
      "sortable": true,
      "filterable": true,
      "isSearchable": true
    }
  },
  {
    "type": "field",
    "attrs": {
      "name": "logo",
      "sortable": true,
      "filterable": true,
      "isSearchable": true
    }
  },
  {
    "type": "field",
    "attrs": {
      "name": "paymentGatewayAccessSecret",
      "viewWidget": "maskedShortTextList",
      "sortable": true,
      "filterable": true,
      "isSearchable": true
    }
  }
]

Form View

Form views handle data entry and editing with complex layout structures using sheets, notebooks, and pages.

1) Basic Form View Structure​

What this shows: A form view with a base layout and optional onFormLayoutLoad handler. children will hold sheets/notebooks/pages/rows/columns/fields.

Form View Structure

{
  "name": "institute-form-view",
  "displayName": "Institute",
  "type": "form",
  "context": "{}",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "institute",
  "layout": {
    "type": "form",
    "attrs": {
      // Form view attributes
    },
    "onFormLayoutLoad": "instituteEditHandler",
    "children": [
      // Layout components (sheets, notebooks, etc.)
    ]
  }
}

2) Form View Attributes​

What this shows: Configure visual details and attach custom buttons that trigger actions or popups.

Form View Attributes

"attrs": {
  "name": "form-1",
  "label": "Institute",
  "className": "grid",
  "formButtons": [
    {
      "attrs": {
        "className": "",
        "label": "Preview",
        "action": "PreviewPortal",
        "icon": "pi",
        "actionInContextMenu": true,
        "openInPopup": true,
        "customComponentIsSystem": true,
        "closable": true
      }
    }
  ]
}

3) Form Layout Components Hierarchy​

What this shows: How layout blocks nest to build rich, organized forms.

Form
└── Sheet (top-level container)
    └── Notebook (tab container)
        └── Page (individual tab)
            └── Row (horizontal layout)
                └── Column (vertical container)
                    └── Field (input component)

Sheet Component​

What this shows: A top-level container for your form sections.

Sheet Component

{
  "type": "sheet",
  "attrs": { "name": "sheet-1" },
  "children": [
    // Notebook or Row components
  ]
}

Notebook Component (Tabs)​

What this shows: A tab container that groups multiple pages.

Notebook Component

{
  "type": "notebook",
  "attrs": { "name": "notebook-1" },
  "children": [
    // Page components (tabs)
  ]
}

Page Component (Individual Tab)​

What this shows: A single tab with its own content.

Page Component

{
  "type": "page",
  "attrs": { "name": "page-1", "label": "Institutes" },
  "children": [
    // Row components
  ]
}

Row Component (Horizontal Layout)​

What this shows: A horizontal group of columns.

Row Component

{
  "type": "row",
  "attrs": { "name": "row-1" },
  "children": [
    // Column components
  ]
}

Column Component (Vertical Container)​

What this shows: A vertical container with optional label and grid classes.

Column Component

{
  "type": "column",
  "attrs": {
    "name": "column-1",
    "label": "Institutes Basic",
    "className": "col-6"
  },
  "children": [
    // Field components
  ]
}

Field Component (Form Input)​

What this shows: A single form input with view/edit widget overrides.

Field Component

{
  "type": "field",
  "attrs": {
    "name": "instituteName",
    "disabled": false,
    "showLabel": true,
    "viewWidget": "default",
    "editWidget": "default"
  }
}

Complete Form Layout Example​

What this shows: A full, multi-tab form bringing together all components.

Complete Form Layout Example

{
  "type": "form",
  "attrs": {
    "name": "form-1",
    "label": "Institute",
    "className": "grid"
  },
  "onFormLayoutLoad": "instituteEditHandler",
  "children": [
    {
      "type": "sheet",
      "attrs": { "name": "sheet-1" },
      "children": [
        {
          "type": "notebook",
          "attrs": { "name": "notebook-1" },
          "children": [
            {
              "type": "page",
              "attrs": { "name": "page-1", "label": "Institutes" },
              "children": [
                {
                  "type": "row",
                  "attrs": { "name": "row-1" },
                  "children": [
                    {
                      "type": "column",
                      "attrs": {
                        "name": "column-1",
                        "label": "Institutes Basic",
                        "className": "col-6"
                      },
                      "children": [
                        { "type": "field", "attrs": { "name": "instituteName" } },
                        { "type": "field", "attrs": { "name": "description" } }
                      ]
                    },
                    {
                      "type": "column",
                      "attrs": {
                        "name": "column-2",
                        "label": "Institutes Contact",
                        "className": "col-6"
                      },
                      "children": [
                        { "type": "field", "attrs": { "name": "instituteAddress", "disabled": false } }
                      ]
                    }
                  ]
                }
              ]
            },
            {
              "type": "page",
              "attrs": { "name": "page-2", "label": "Payment Gateway Details" },
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

Kanban View

Kanban views display records as cards with drag-and-drop functionality.

1) Basic Kanban View Structure​

What this shows: Declares a kanban view and the places where swimlane and card configuration live.

Kanban View Structure

{
  "name": "task-kanban-view",
  "displayName": "Task Board",
  "type": "kanban",
  "context": "{}",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "task",
  "layout": {
    "type": "kanban",
    "attrs": {
      // Kanban view attributes
    },
    "children": [
      // Card template configuration
    ]
  }
}

2) Kanban View Attributes​

What this shows: Controls lane count, records per lane, the grouping field, and drag-and-drop.

Kanban View Attributes

"attrs": {
  "swimlanesCount": 10,
  "recordsInSwimlane": 5,
  "enableGlobalSearch": true,
  "create": true,
  "edit": true,
  "delete": true,
  "groupBy": "status",
  "draggable": true,
  "allowedViews": ["list", "kanban"]
}

3) Kanban Card Template​

What this shows: Maps model fields to parts of the card: header, content, badges.

Kanban Card Template

"children": [
  {
    "type": "cardTemplate",
    "attrs": { "name": "task-card" },
    "children": [
      { "type": "field", "attrs": { "name": "title", "displayType": "header" } },
      { "type": "field", "attrs": { "name": "description", "displayType": "content" } },
      { "type": "field", "attrs": { "name": "priority", "displayType": "badge" } }
    ]
  }
]

View RBAC​

Views support role-based access control (RBAC) to restrict actions and field-level permissions based on user roles.

Role-Based View Actions

What this shows: Limit visibility of list-level actions (import/export/layout customization) to specific roles.

View Actions

"configureViewActions": {
  "import": { "roles": ["Admin", "Manager"] },
  "export": { "roles": ["Admin", "Manager", "User"] },
  "customizeLayout": { "roles": ["Admin"] },
  "saveCustomFilter": { "roles": ["Admin", "Manager"] }
}

Field-Level Permissions in Views

What this shows: Hide or show sensitive fields per role.

Field-Level Permissions

{
  "type": "field",
  "attrs": {
    "name": "salary",
    "roles": ["Admin", "HR"]
  }
}

View Widgets

Views support custom widgets to enhance field display and editing experiences. List view supports viewWidget and form views support viewWidget (view mode) and editWidget (edit mode).

What this shows: Override default rendering/editing of a field using specific named widgets.

Custom View Widgets

{
  "type": "field",
  "attrs": {
    "name": "password",
    "viewWidget": "maskedShortTextList",
    "editWidget": "maskedShortTextEdit"
  }
}

Further Reference​

View Event Handlers (TODO)

What this shows: Hook into lifecycle events to preprocess layout/data or react to user input.

  • onFormLayoutLoad: Executed when form loads
  • onFormDataLoad: Executed after form data is loaded
  • onFieldChange: Triggered on field value changes
  • onFieldBlur: Executed when a field loses focus
  • onCustomWidgetRender: Called when a custom widget is rendered

Further reference: Event Handlers Documentation

View Layout Responsive Design

CSS Grid Classes​

What this shows: Use grid utility classes to control width across breakpoints.

CSS Grid Classes

{
  "type": "column",
  "attrs": { "className": "col-12 col-md-6 col-lg-4" }
}

Layout Breakpoints​

  • col-12: Full width on all screens
  • col-md-6: Half width on medium screens and up
  • col-lg-4: Third width on large screens and up

View Metadata Attributes​

name (string, required, unique)​

Name of the view (used for referencing).
Default: N/A

displayName (string, required)​

Display name of the view (shown in the UI).
Default: N/A

type (string, required)​

Type of view. Supported types:

  • list: List view for displaying multiple records in a tabular format.
  • form: Form view for creating/editing a single record.
  • kanban: Kanban view for visualizing records as cards in columns. Default: N/A

context (JSON, optional)​

JSON object defining context-specific parameters for the view.
Default: N/A

layout (JSON, required)​

Defines the layout and structure of the view. Controls how fields, widgets, buttons, and other UI elements are organized.
Default: N/A

Further Reference​

Info

Each view type has its own expected layout schema. Use the links above to understand required keys, optional properties, and usage examples.

moduleUserKey (string, optional)​

User key of the module this view belongs to.
Default: N/A

modelUserKey (string, optional)​

User key of the model this view is associated with.
Default: N/A

Best Practices​

Layout Organization

  • Use logical grouping: Group related fields in columns with descriptive labels
  • Progressive disclosure: Use tabs (notebooks) for complex forms
  • Responsive design: Use appropriate grid classes for different screen sizes
  • Field ordering: Place important fields first, follow logical workflow

Security Considerations

  • Role-based access: Configure view actions based on user roles
  • Field-level security: Hide sensitive fields from unauthorized users
  • Audit trails: Enable audit tracking for sensitive operations

Performance Optimization

  • Pagination: Always enable pagination for large datasets
  • Field selection: Only display necessary fields in list views