A Complete Guide to Customizing Entities and Modules in Perfect Management Systems

2025-05-25

Entity Configuration and Dynamic Form System

This document outlines the structure and functionality of the Entity Configuration System in the Perfect Management Systems platform. It provides comprehensive guidance for administrator users configuring and adding new modules such as Appointments, Customer, Attendance, Expenses etc.

Purpose

The Entity Configuration Interface allows platform administrators to define the structure, display, and data behavior of each entity in the system. It directly drives how forms and lists are rendered dynamically within the app.

image

1. Core Components

Setting Description
ID Unique identifier (used internally and in the database). Lowercase, no spaces.
Name User-friendly label displayed throughout the UI.
Icon FontAwesome icon name (e.g., fa-calendar-alt).Refer to: FontAwesome Free Icons
Child Marks as a child entity. Used when embedding inside a parent.
Modal If enabled, opens this form in a modal popup instead of full screen.
Display Display style of the list view (List, Grid, Spreadsheet).

2. Fields Configuration

Each entity contains an ordered list of fields. These are editable in a drag-and-drop interface.

Field Properties:

image

  • Field Name: Identifier key for the field.
  • Field Type: Defines the input or behavior (see below).
  • Val: Default value or behavior config.
  • Required: Whether this must be filled before saving.
  • Search: Whether this field is used in search and filters.
  • Unique: Marks the field as a unique key. When a new or imported record has the same value as an existing one in this field, the system will detect it as a duplicate and prompt the user to switch to the existing record instead.
  • ShowDoc (for object/array): If true, clicking opens detailed view of embedded object.
  • Tooltip: Tooltip help text shown to end users.
  • Set Icon: Associates a UI icon with the field.
  • Delete Field: Deletes the field (only if not core).
  • Reorder Handle: Allows repositioning field order.

3. Field Types Reference

This table explains each field type, with descriptions and visual references.

Type Description Example / Visual Reference
input Single-line text box input
number Numeric input number
password Password-style input password
text Multiline text input text
date Date picker date
datetime-local Combined date and time picker datetime-local
checkbox Boolean toggle checkbox
select Dropdown select. Options are configured separately select
generate_id Automatically generates a unique ID using a prefix (defined in config), a date (DOB or current date), total count of existing records, and a small random number to avoid duplicates generate_id
signature Checkbox for signing, stores user ID when checked signature
image Image capture or upload field image
file File attachment upload file
comment Placeholder for threaded comment widgets comment
object Links to another entity via autocomplete (saves object ID) auto-complete
objectfilter Filtered object link based on another field object-filter
connectedobject Connects to another entity with a different label auto-complete
embeddedobject Embeds fields from another entity inline in this one auto-complete
objectfields On selecting an object, pre-fills several fields based on field name match  
array References an array of another entity (may show inline or linked view)  
spreadsheet Inline tabular form capturing multiple rows of data. Column headers are defined using a dynamic configuration editor. spreadsheet
arraytags Multi-select tags via autocomplete arraytags
arrayinput Allows selection of inputs from another entity using autocomplete. If the source objects include a parent-child structure, inputs will be grouped accordingly. Parent inputs are rendered with their children below them. Each child input is editable, and users can remove individual items as needed. Useful for panels (e.g., lab tests) or grouped form structures. arrayinput
form Embedded form entity  
page Renders another page inside this form  
inline_texteditor Embedded rich text HTML editor html_editor
texteditor Loads template-driven rich text input text-editor

4. Select and Spreadsheet Field Options

If a field is of type select or spreadsheet, a dynamic editor is shown in the footer to manage options or columns.

  • For select:

    • Option: The value saved in the database.

    • Description: What the user sees in the dropdown.

  • For spreadsheet:

    • Add column keys and labels that define each column of the spreadsheet.

    • Allows structured row-entry in form submissions.

5. Special Field Behaviors

_type: 'Store'

This is a hidden system field automatically set when a user creates a new store. Stores are a special type of entity that enable users to manage inventories across multiple outlets (e.g., pharmacy store, lab stock store, etc.).

  • This field is not visible in the Add Entity form.

  • It can be inspected or edited via the JSON editor.

  • Behavior tied to _type includes filtering records by store, stock management logic, and separating views per store type.

More technical notes on Store logic will be provided in a later section.

Autocomplete Field Prefill Behavior

For fields of type object, objectfilter, or connectedobject, when a user selects an entry via autocomplete, the system can automatically prefill related fields in the form if they follow a specific naming convention.

Prefill Logic:

  • If the selected object has fields like name, sex, or phone, and the current entity has fields named with the same structure - object_name, object_sex, object_phone, etc. these fields will be automatically populated.

  • This applies only when those fields are defined in the entity’s settings.

For example:

  • Selecting a customer will automatically fill:

    • customer_name → customer’s name

    • customer_sex → customer’s sex

    • customer_phone → customer’s phone

This improves user efficiency and reduces manual entry errors.

Duplicate Record Detection

If a field is marked as Unique, then when a user creates or imports a record with a value that already exists in the system for that field, a Duplicate Found alert will appear. This allows users to switch to the existing record or cancel the action.

duplicates

6. Generate ID Logic

Fields of type generate_id are designed to produce system-assigned IDs that are unique and structured. The logic is as follows:

  • Prefix: Defined by the user in the configuration form. If not provided, the system uses the uppercase first letter of the entity type.

  • Date Component: Uses the patient's date of birth (if available) or the current system date.

  • User Suffix: First 3 letters of the logged-in user's username are appended for traceability.

  • Entity Count: Retrieves the total number of existing records of that entity type.

  • Random Number: A small random 3-digit number is included to prevent ID duplication in concurrent user scenarios.

These elements are concatenated to produce an ID like:

7. Saving & Best Practices

  • Use the Submit button to save all changes to the entity.

  • Use tooltips to guide form users.

  • Avoid overuse of embedded objects to reduce complexity.

  • Prefer lowercase, underscore-separated field IDs.

  • Always test new fields in a dummy entry before production use.