MAF Configuration Practices – Making Fields Read-Only

About this task

In Graphite applications, there are often scenarios where you need to make certain fields read-only based on business rules, user permissions, or workflow states. This guide presents common scenarios for making fields read-only and provides step-by-step implementation instructions for each approach.

Scenarios and Implementation

Scenario 1: Always Read-Only Fields

When to use: Use this approach when a field should always be displayed as read-only for all users in all contexts.

Application behavior: The field will be visible but not editable under any circumstances. Users can see the value but cannot modify it.

Implementation Steps:

Open your page XML file
Add the readonly="true" attribute to the field component
Save and deploy your changes

Example:

<text-input id="wonum" label="Work Order" value="{item.wonum}" readonly="true" />

Scenario 2: Status-Based Read-Only Fields

When to use: Use this approach when fields should become read-only based on the status of the record (e.g., making all fields read-only when a work order is completed).

Application behavior: Fields will be editable when the record is in certain statuses and become read-only when the status changes to a specified value.

Implementation Steps:

Open your page XML file
Add a conditional expression to the readonly attribute that checks the status
Save and deploy your changes

Example:

<text-input id="description" label="Description" value="{item.description}" 
            readonly="{item.status === 'COMPLETED' || item.status === 'CLOSED'}" />

For multiple fields affected by the same status condition:

/**
 * Set fields as read-only based on status
 * @param {Object} page - The page object
 * @param {Object} item - The current record
 */
setStatusBasedReadOnly(page, item) {
  const isReadOnly = ['COMPLETED', 'CLOSED'].includes(item.status);
  
  // Get references to field components

Call this method when the page initializes and when the status changes:

/**
 * Handle status change
 * @param {string} newStatus - The new status value
 */
handleStatusChange(newStatus) {
  const currentItem = this.page.datasources.workorderds.currentItem;
  if (currentItem) {
    this.setStatusBasedReadOnly(this.page, currentItem);
  }

Scenario 3: Dependent Field Relationships

When to use: Use this approach when the editability of one field depends on the value of another field (e.g., making Location read-only when an Asset is selected).

Application behavior: When the user selects or enters a value in one field, related fields will automatically become read-only or editable based on the defined relationship.

Implementation Steps:

Create a controller method to determine the read-only state
Bind the field’s readonly attribute to this method
Set up event listeners to update the state when dependent fields change

Example:

<text-input id="locationField" label="Location" value="{item.location}" 
            readonly="{controller.isLocationReadOnly(item)}" />

In your controller:

/**
 * Determine if location field should be read-only
 * @param {Object} item - The current record
 * @returns {boolean} True if the field should be read-only
 */
isLocationReadOnly(item) {
  // Location becomes read-only when an asset is selected
  return item && item.assetnum ? true : false;
}

Complete Example

Here’s a complete example showing how to implement read-only fields for multiple scenarios:

Page XML:

<page id="workorderdetails">
  <page-header>
    <page-title>Work Order Details</page-title>
  </page-header>
  
  <container>
    <!-- Scenario 1: Always read-only -->
    <text-input id="wonum" label="Work Order" value="{item.wonum}" readonly="true" />

AppCustomizations.js:

import {Application} from '@maximo/maximo-js-api';

class AppCustomizations {
  /**
   * Initialize page references when the page is initialized
   * @param {Object} page - The page object
   * @param {Object} app - The application object
   */
  async pageInitialized(page, app) {

Best Practices and Considerations

Visual Feedback: Provide clear visual indication that fields are read-only to improve user experience.
Error Messages: Display helpful messages explaining why fields cannot be edited when applicable.
Performance: Minimize the number of DOM manipulations when changing readonly states dynamically.
Server-Side Validation: Always implement server-side validation as well, since client-side readonly attributes can be bypassed.
Consistency: Apply read-only rules consistently across similar fields and pages.
Testing: Test read-only behavior across different user roles and scenarios.
Accessibility: Ensure read-only fields meet accessibility standards with proper ARIA attributes.
Mobile Considerations: Test read-only behavior on mobile devices where touch interactions differ.
Documentation: Document the business rules that determine when fields should be read-only.
Graceful Degradation: Ensure your application works correctly even if JavaScript is disabled or errors occur.

Edit this page on GitHub

Simple configurations: Marking Fields as Required

Complex configurations: Open links to external browser