Customizing UI & Foreign Keys
Relevant source files
The following files were used as context for generating this wiki page:
The IT Management System implements a strict set of guardrails for User Interface (UI) customization and the handling of Foreign Keys (FK). The primary goal is to ensure that technical database identifiers (numeric IDs) are never exposed to end-users in place of human-readable labels. This architecture supports multi-tenancy by scoping lookups to specific companies while maintaining legacy support through fallback mechanisms.
System-wide UI behaviors, such as table actions, button positioning, and sidebar preferences, are managed through a centralized configuration hub. This ensures consistency across the standard CRUD Modules and provides a seamless experience for administrators managing multiple tenants.
Sources: wiki/Foreign-Keys.md:3-9, wiki/Modules.md:46-56, modules/settings/AGENT_NOTES.md:4-8
Foreign Key Display Logic
The core principle of the system's data presentation is to render meaningful labels (e.g., hostname, name, username) instead of raw FK numeric IDs in all list and detail screens. This is achieved through heuristic metadata lookups that identify the most appropriate label column for a given referenced table.
Tenant-Safe Lookup Strategy
To maintain data isolation in a multi-tenant environment, the system follows a specific priority order when resolving labels for foreign keys:
- Company-Scoped Lookup: Queries are first executed with a filter for the current
company_id. - ID-Only Fallback: If a company-scoped row is missing, the system falls back to a global ID lookup to preserve legacy data or shared reference rows.
Sources: wiki/Foreign-Keys.md:12-16, modules/it_locations/index.php:127-142
Label Resolution Heuristics
The system uses the cr_fk_metadata function to automatically determine which column should represent a foreign entity. It searches for candidates in a specific order of preference.
| Preference Order | Candidate Column Names |
|---|---|
| 1 | name, display_name, title |
| 2 | username, code, color_name |
| 3 | type, port_number |
Sources: modules/floor_designer_points/index.php:111-125, modules/it_locations/index.php:107-118
UI Configuration & Customization
The system allows for extensive per-company UI customization managed via the ui_configuration table. These settings control the layout and functional elements of module index pages and forms.
Configuration Scope
- Button Positioning: Control the alignment of "+ New" and "Save" buttons (e.g.,
left,right, orleft_right). - Pagination: Defines the number of records displayed per page via
itm_resolve_records_per_page. - Sidebar Preferences: Users can manage the visibility and order of sidebar items, stored in
user_sidebar_preferences.
Sources: modules/settings/AGENT_NOTES.md:10-14, modules/it_locations/index.php:484-489, wiki/Modules.md:48-52
Data Flow for UI Settings
The following diagram illustrates how UI configurations are resolved and applied to a module's view:
The application of these settings ensures that the UI dynamically adapts to the specific needs of a company or user while maintaining the core architectural standards.
Sources: modules/settings/AGENT_NOTES.md:4-14, modules/it_locations/index.php:484-498
Dropdown & Form Consistency
Form inputs for foreign keys must remain consistent even if the referenced data is not strictly scoped to the current tenant. A common challenge occurs when a saved FK value exists in the database but is not returned by a tenant-scoped query (e.g., legacy or shared data).
Persisting Selected Values
When loading edit forms, the system implements cr_fk_ensure_selected_option. This function ensures that if a persisted FK value is missing from the standard dropdown options, it is explicitly loaded and appended to the list to prevent the form from defaulting to "-- Select --".
Sources: wiki/Foreign-Keys.md:25-27, modules/it_locations/index.php:76-105
User Reference Fields
Special rules apply to fields such as created_by, updated_by, or approved_by:
- Format: Preference is given to
first_name + last_name. - Fallback: The
usernameis used only if the full name is empty. - Input Type: These fields must always use dropdowns with human-readable labels rather than free-text numeric inputs.
Sources: wiki/Foreign-Keys.md:31-38
API & Import Integration
The customization and FK rules extend to the JSON API and Excel/CSV import endpoints. The itm_handle_json_table_import function facilitates bulk data entry while respecting FK relationships.
Import Resolution Process
- The API receives a JSON payload containing rows of data.
- The system maps human-readable headers to database columns using
cr_humanize_fieldlogic. - For FK columns, the system performs a lookup to resolve the provided label (e.g., Department Name) into the corresponding numeric ID.
- If a label cannot be resolved, it may fallback to checking if the provided value is already a numeric ID.
Sources: scripts/api.php:143-155, modules/it_locations/index.php:501-576
This sequence ensures that imports remain user-friendly by allowing labels instead of requiring internal database IDs.
Sources: modules/it_locations/index.php:538-555, scripts/api.php:178-185
Conclusion
Customizing the UI and managing Foreign Keys in this system is a disciplined process centered on user clarity and data integrity. By utilizing heuristic label resolution and tenant-aware fallbacks, the system provides a robust multi-tenant environment where technical implementation details remain hidden. Developers must adhere to these guardrails—particularly the synchronization of index.php and view.php renderers—to maintain a consistent and professional interface.
Sources: wiki/Foreign-Keys.md:44-55, modules/settings/AGENT_NOTES.md:34-36