MAF Configuration Practices – Marking Fields as Required

About this task

In Graphite applications, there are several ways to mark fields as required to ensure data integrity and guide users to provide necessary information. This guide explains the different methods available for marking fields as required and provides examples for each approach, organized by common scenarios.

Scenarios

Marking fields required at the Datasource level

One of the most fundamental ways to mark a field as required in a Graphite application is through the datasource attribute’s required property. When an attribute in the datasource is marked as required, any UI field bound to that attribute will automatically be treated as required.

Datasource Configuration:

<datasource id="workOrderDS">
  <attribute name="description" required="true" />
  <attribute name="location" required="true" />
  <attribute name="priority" />
</datasource>

UI Field Binding:

<text-input id="descriptionField" label="Description" value="{datasource.description}" />
<text-input id="locationField" label="Location" value="{datasource.location}" />

What happens:

Fields bound to required attributes will automatically be treated as required
An asterisk appears next to the field label
Form submission is prevented if the field is empty
Validation is handled at the datasource level

When to use:

When the requirement is driven by the data model
For consistent enforcement of required fields across multiple pages
When the field should always be required regardless of UI context

Basic Required Fields

The simplest scenario is marking fields as permanently required using the required attribute in your XML.

XML Configuration:

<text-input id="description" label="Description" required="true" />
<number-input id="quantity" label="Quantity" required="true" />
<dropdown id="status" label="Status" required="true">
  <dropdown-item value="active" label="Active" />
  <dropdown-item value="inactive" label="Inactive" />
</dropdown>

What happens:

An asterisk appears next to the field label
Form submission is prevented if the field is empty
A default error message appears when validation fails

When to use:

For fields that are always required
When using the default validation behavior is sufficient
For simple forms with straightforward validation needs

Custom Error Messages

When you need to provide more specific guidance to users about required fields.

XML Configuration:

<text-input 
  id="assetId" 
  label="Asset ID" 
  required="true" 
  error-message="Please enter a valid Asset ID in the format ASSET-XXXXX" 
/>

<date-input 
  id="dueDate"

JavaScript for dynamic error messages:

/**
 * Get custom error message based on field and context
 * @param {string} fieldId - The field ID
 * @param {Object} context - Validation context
 * @returns {string} - The error message
 */
getErrorMessage(fieldId, context) {
  switch (fieldId) {
    case 'workOrderId':

When to use:

When default error messages aren’t descriptive enough
For fields with specific format requirements
When different error contexts need different messages

Conditionally Required Fields

For fields that should only be required based on certain conditions.

XML Configuration:

<checkbox id="emergency" label="Emergency" checked="{page.state.workOrder.emergency}" on-change="handleEmergencyChange" />

<textarea 
  id="notes" 
  label="Notes" 
  value="{page.state.workOrder.notes}" 
  required="{page.state.workOrder.emergency}"
  error="{page.state.validationErrors.notes}"
  on-change="handleNotesChange"

JavaScript Implementation:

/**
 * Handle emergency checkbox change
 * @param {boolean} checked - Whether emergency is checked
 */
handleEmergencyChange(checked) {
  this.page.state.workOrder.emergency = checked;
  
  // Update required fields based on emergency status
  this.updateRequiredFields();

When to use:

When fields should only be required in specific circumstances
For implementing business rules that affect field requirements
When creating dynamic forms that adapt to user input

Complex Validation Rules

For scenarios requiring more sophisticated validation beyond simple “required” checks.

JavaScript Implementation:

/**
 * Validate a specific field
 * @param {string} fieldId - The field to validate
 * @returns {boolean} - Whether the field is valid
 */
validateField(fieldId) {
  const workOrder = this.page.state.workOrder;
  const requiredFields = this.page.state.requiredFields;
  const errors = this.page.state.validationErrors || {};

When to use:

When validation goes beyond simple presence checks
For fields with format requirements (regex patterns)
When fields need to be validated against each other
For numeric fields with range requirements

Form-Level Validation

For validating multiple fields together or implementing cross-field validation.

JavaScript Implementation:

/**
 * Validate the entire form
 * @returns {boolean} - Whether the form is valid
 */
validateForm() {
  const workOrder = this.page.state.workOrder;
  const errors = {};
  let isValid = true;

When to use:

When fields need to be validated in relation to each other
For implementing business rules that span multiple fields
When validation depends on the overall form state

Complete Example

Here’s a complete example showing how to implement required fields with validation for a work order form:

Page XML:

<page id="workOrderForm">
  <state name="workOrder" type="object" default-value="{}" />
  <state name="validationErrors" type="object" default-value="{}" />
  <state name="requiredFields" type="object" default-value="{description: true, location: true}" />
  
  <page-header>
    <page-title>Create Work Order</page-title>
  </page-header>

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

Validation Timing: Consider when to validate - on submit, on blur, or as the user types.
Error Messages: Provide specific, actionable error messages rather than generic ones.
Accessibility: Ensure error states are accessible to screen readers and other assistive technologies.
Conditional Requirements: Clearly indicate when fields become required based on other selections.
Performance: For large forms, consider validating fields individually rather than all at once.
Default Values: Provide sensible default values where appropriate to reduce the burden on users.
Error Recovery: Make it easy for users to correct errors without losing other entered data.
Mobile Considerations: Ensure validation works well on mobile devices with appropriate error placement.
Testing: Test required field validation with various input scenarios, including edge cases.

Edit this page on GitHub

Simple configurations: Enabling persistent values

Complex configurations: Open links to external browser