Page Layouts

Overview

Page Layouts control how records appear across OptiCRM. Every create form, detail page, and list view is rendered from a layout configuration — not hardcoded UI. This means admins can customize exactly which fields appear, how they're grouped into sections, and who sees which layout.

OptiCRM supports 41 entities (18 standard + 23 dynamic), and every one of them can have custom layouts.

The layout system follows the Salesforce/Oracle enterprise CRM model:

• Layouts are JSON configurations stored in the database
• A visual designer lets you drag-and-drop sections and widgets
• Layout assignments control which layout a user sees based on their role, group, or profile type
• A resolution engine picks the best layout for each user with caching

Layout Types

Most entities ship with default Form and Detail layouts. You can create additional layouts per type and assign them to specific audiences.

Layout Manager

Navigate to Settings → Presentation — Design → Record Layouts to manage all layouts.

What You See

The Layout Manager shows all layouts grouped by entity, with:

• Stats bar — Total layouts, entities covered, layouts with assignments, default count
• Search — Find layouts by name or entity
• Filters — Filter by section (Core, Operations, Finance, Admin), entity, or layout type
• Collapsible groups — Each entity is a collapsible section showing its layouts in a table

Layout Table Columns

Creating a Layout

1. Click New Layout in the top-right
2. Select Entity — Searchable dropdown grouped by section (Core, Operations, Finance, Admin). Shows all 41 registered entities.
3. Choose Layout Type — Form, Detail, List, Dashboard, or Portal
4. Name — Auto-suggested based on entity + type (e.g., "Vehicle Form"). You can customize it.
5. Click Create Layout — opens in the visual designer

Cloning a Layout

To create a variant of an existing layout:

1. Click the ... menu on any layout row
2. Select Clone
3. A copy is created with "(Copy)" suffix and the same configuration
4. Edit the clone in the designer to customize it

Setting Defaults

Each entity + layout type combination can have one default layout. The default is used when no specific assignment matches the current user.

• Click the star icon on a layout row to toggle default status
• A filled yellow star means it's the current default
• Only one default per entity + type — setting a new default doesn't automatically unset the old one, so manage this carefully

Deleting Layouts

• Click the ... menu → Delete
• Default layouts cannot be deleted — remove the default flag first
• Layouts with active assignments will warn before deletion

Layout Designer

Click Edit (pencil icon) on any layout to open the visual designer at /settings/layouts/{id}/edit.

Layout Structure

A layout is made of sections, and each section contains widgets:

Layout
├── Section: "Personal Information" (2 columns)
│   └── Widget: FIELD_GROUP ["firstName", "lastName", "dob", "gender"]
├── Section: "Academic Details" (2 columns, collapsible)
│   └── Widget: FIELD_GROUP ["className", "sectionName", "rollNumber"]
├── Section: "Attachments" (1 column)
│   └── Widget: ATTACHMENTS
└── Section: "Notes" (1 column)
    └── Widget: NOTES

Section Properties

Widget Types

Field Configuration

Within a FIELD_GROUP widget, you specify which fields to display by their API names. The rendering engine automatically:

• Shows the correct input type (text, select, date, etc.)
• Applies required/readonly rules from the field definition
• Renders lookup fields with search
• Shows validation errors inline

Layout Assignments

Navigate to Settings → Presentation — Assignments → Record Layout Assignments to control who sees which layout.

Assignment Priority

When a user opens a record, the system resolves the best layout in this order:

1. User — Exact match for this specific user (highest priority)
2. Group — User belongs to a group with an assigned layout
3. Role — User's role definition matches
4. Profile Type — User's profile type matches (Student, Parent, Staff, Admin, Super Admin)
5. Default — The layout marked as default for this entity + type
6. Fallback — If nothing matches, the system shows all non-readonly fields in a single section

Creating an Assignment

1. Click Assign Layout in the top-right
2. Select Entity — Searchable dropdown with all 41 entities
3. Layout Type — Choose which type (Form, Detail, etc.)
4. Layout — Select from layouts that exist for this entity + type
5. Assignment Type — Choose one:
   • Profile Type → Student, Parent, Staff, Admin, or Super Admin
   • Role → A specific role definition (e.g., "Finance Officer")
   • Group → A user group
   • User → A specific individual user
6. Click Assign

Quick Assignments from Layout Manager

You can also assign layouts directly from the Layout Manager page:

• In the "Assigned To" column, click + Assign on any layout
• Existing assignments appear as badges — hover and click × to remove

Duplicate Prevention

Only one assignment is allowed per entity + layout type + assignment type + target. For example, you can't assign two different Detail layouts to the same role for the Student entity. Delete the existing assignment first.

Viewing Assignments

The Layout Assignments page shows:

• Stats — Total assignments, entities covered, entities without assignments
• Search + filters — Search by layout name, entity, role, or group name
• Grouped by entity — Each entity shows its assignments in a table with layout name, type, assigned to, and assignment level

Resolution Cache

Layout resolution results are cached in Redis for 5 minutes to avoid repeated database lookups.

• Cache key format: layout_resolve:{institutionId}:{entity}:{layoutType}:{userId}
• Cache is automatically invalidated when assignments are created or deleted
• NONE results (no layout found) are never cached — so newly created assignments take effect immediately

Default Layouts

OptiCRM ships with multi-section default layouts for all entities. These are created during institution setup and can be regenerated.

Regenerating Better Defaults

If your institution was created before the improved layouts were available, an admin can regenerate them:

POST /api/admin/seed-better-layouts

This replaces single-section field dumps with properly grouped layouts. For example, the Vehicle form gets 4 sections:

• Vehicle Information (registration, type, make, model, capacity)
• Personnel (driver, conductor)
• Compliance & Expiry (insurance, fitness, permit, PUC dates)
• Tracking (GPS device, active status)

Every entity gets a thoughtful section grouping based on the domain.

What Gets Updated

• Existing default Form layouts are updated with the new multi-section config
• Existing default Detail layouts are updated similarly
• If a default layout doesn't exist, it's created
• Non-default layouts (custom ones you created) are never touched

Which Forms Use the Layout System?

The layout system drives all create and edit forms across OptiCRM. When you change a layout in Settings > Layouts, the form updates immediately for all users — no code deployment needed.

Fully Layout-Driven Forms

These entities render their create/edit forms entirely from the layout configuration. Admins can add fields, remove fields, reorder them, create sections, and assign different layouts per role.

Dynamic Objects (19) — accessed via /o/[apiName]:

Standard Entities with Layout-Driven Forms (12):

Custom UI Forms (Not Layout-Driven)

Some entities have specialized UIs that can't be represented as a flat field layout. These use purpose-built forms:

How It Works

When a layout-driven form opens, it:

1. Fetches the entity's field definitions from /api/settings/entity-fields?entity={name}
2. Resolves the best matching layout from /api/settings/layouts/resolve?entity={name}&type=LT_FORM based on the current user's role, group, or profile type
3. Renders form fields according to the layout's sections and widgets
4. If no layout is found, falls back to showing all non-readonly fields in a 2-column grid
5. On submit, sends the form data to the entity's API endpoint

This means:

• Adding a field to a layout immediately shows it in the form
• Removing a field hides it (the data is still in the database, just not shown)
• Reordering fields changes the form order
• Adding sections groups fields with headers
• Assigning layouts per role means Finance Officers can see different fields than Teachers

Entities Covered

All 41 registered entities support layouts:

Core (9): Student, Enquiry, Contact, Guardian, Attendance, Staff, Invoice, User, Institution

Finance (7): Fee Head, Fee Plan, Payment, Receipt, Expense, Scholarship, Concession

Calendar (2): Staff Attendance, Holiday

Transport (4): Vehicle, Transport Route, Route Stop, Student Transport

Library (6): Library Category, Library Item, Library Copy, Library Member, Library Issue, Library Reservation

Health (5): Health Profile, Health Screening, Sick Bay Visit, Vaccination, Medication

Hostel (4): Hostel Room, Hostel Allotment, Gate Pass, Hostel Visitor

Academics (4): Subject, Department, Event, Announcement

Tips

• Start with defaults — The seeded layouts work out of the box. Customize only when roles need different views.
• Use sections — Group related fields together (e.g., "Personal Info", "Financial Details", "Emergency Contact"). This is much better than one long form.
• Two columns for short fields — Use 2-column sections for fields like name, email, phone. Use 1-column for textareas and notes.
• Collapsible for secondary info — Make sections like "System Fields" or "Audit Trail" collapsible so they don't clutter the main view.
• Clone before editing — If you want to customize a default layout, clone it first. Assign the clone to a specific role and keep the original as the fallback default.
• Profile Type vs Role — Profile Type is broader (all staff), Role is specific (only Finance Officers). Use Profile Type for general differences, Role for specialized views.