Graphite Dialog Components Guide

Table of Contents

1. Overview
2. Common Lifecycle Events
3. Common Properties
4. Programmatic Access
5. Dialog Component
6. Lookup Component
7. Lookup with Filter Component
8. Sliding Drawer Component
9. Best Practices
10. Troubleshooting

Overview

1. Dialog - A versatile modal window for displaying content with customizable action buttons and decorations. Perfect for confirmations, forms, and focused content presentation.

2. Lookup - A specialized modal for searching and selecting items from a datasource. Supports both mobile list views and desktop table views with advanced features like barcode scanning, filtering, and multi-select.

3. Lookup with Filter - An enhanced lookup component that provides a filter element for refining search results. This is driven by a datasource where an attribute is flagged as filterable. Also supports hierarchical data navigation for drill-down scenarios.

4. Sliding Drawer - A side-panel modal that slides in from the start or end of the screen. Provides a non-intrusive way to display supplementary content while maintaining context with the main view.

• They must be declared within a <dialogs> container element
• They support controller binding for advanced behavior and lifecycle management
• They provide event callbacks for open, close, and action events
• They can be opened programmatically via page.showDialog() or app.showDialog()
• They support validation callbacks to prevent closing with unsaved changes
• They integrate seamlessly with Graphite’s state management and datasource system

• Use Dialog when you need a general-purpose modal for confirmations, alerts, or custom forms
• Use Lookup when users need to search and select from a list of items with rich filtering and search capabilities
• Use Lookup with Filter when you need advanced filtering capabilities driven by datasource attributes, or when working with hierarchical data that requires drill-down navigation
• Use Sliding Drawer when you want to show supplementary content without completely blocking the main view

Common Lifecycle Events

Binding a Controller

<dialog id="myDialog" title="Sample Dialog" controller="MyDialogController">
  <!-- dialog content -->
</dialog>

<lookup id="myLookup" datasource="itemsDS" controller="MyLookupController">
  <!-- lookup configuration -->
</lookup>

<sliding-drawer id="myDrawer" header-text="Details" controller="MyDrawerController">
Copy to clipboardCopied!

// src/controllers/MyDialogController.js
export default class MyDialogController {
  // Implement lifecycle event handlers here
}
Copy to clipboardCopied!

Shared Lifecycle Events

1. on-open-action Event

• Initialize component state or load data when it opens
• Set focus on a specific field
• Log analytics events for views
• Perform setup that depends on the component being visible

onOpenAction(event) {
  // event contains the component context and any arguments passed via on-open-action-arg
}
Copy to clipboardCopied!

<dialog id="editDialog" 
        title="Edit Item" 
        controller="EditDialogController"
        on-open-action="loadItemData"
        on-open-action-arg="{item.id}">
  <field label="Name" value="{dialog.state.itemName}" />
</dialog>
Copy to clipboardCopied!

export default class EditDialogController {
  loadItemData(itemId) {
    // Fetch item details when dialog opens
    const datasource = this.dialog.findDatasource('itemDS');
    datasource.load({ id: itemId });
  }
}
Copy to clipboardCopied!

• Form initialization: Pre-populate form fields with existing data
• Dynamic content loading: Fetch data from an API when the component opens
• User tracking: Record that a user opened a specific component for analytics
• Focus management: Set initial focus to the first input field

2. on-close-action Event

• Clean up resources or state when the component closes
• Reset form fields to their default values
• Log analytics events for dismissals
• Perform cleanup operations

onCloseAction(event) {
  // event contains the component context and any arguments passed via on-close-action-arg
}
Copy to clipboardCopied!

<lookup id="itemLookup" 
        datasource="itemsDS"
        controller="ItemLookupController"
        on-close-action="cleanupSelection">
  <!-- lookup configuration -->
</lookup>
Copy to clipboardCopied!

export default class ItemLookupController {
  cleanupSelection() {
    // Reset temporary selection state
    this.lookup.state.tempSelection = null;
    console.log('Lookup closed, temporary state cleared');
  }
}
Copy to clipboardCopied!

• State cleanup: Clear temporary state that was only needed while the component was open
• Resource release: Cancel pending API requests or timers
• Analytics: Track how users exit components (close vs. save)
• Validation reset: Clear validation errors when the component closes

3. validate Event

• Validate form data before allowing the component to close
• Check for unsaved changes and prompt the user
• Ensure required fields are filled
• Perform complex validation logic

validate() {
  // Return false to prevent component from closing
  // Return true or undefined to allow closing
}
Copy to clipboardCopied!

<dialog id="formDialog" 
        title="User Registration" 
        controller="FormDialogController"
        validate="validateForm"
        primary-action-text="Register">
  <field label="Email" value="{dialog.state.email}" />
  <field label="Password" value="{dialog.state.password}" />
</dialog>
Copy to clipboardCopied!

export default class FormDialogController {
  validateForm() {
    const { email, password } = this.dialog.state;
    
    // Email validation
    if (!email || !email.includes('@')) {
      this.app.toast('Please enter a valid email address');
      return false;
    }
Copy to clipboardCopied!

• Form validation: Ensure all required fields are filled and valid
• Unsaved changes detection: Warn users before losing unsaved work
• Business rule validation: Enforce complex business rules before submission
• Async validation: Check with server before allowing close (return a Promise)

Common Properties

Universal Properties

Action Button Properties

Datasource Properties

Programmatic Access

Opening a Dialog Component

// From a page controller
export default class MyPageController {
  openEditDialog(item) {
    this.page.showDialog('editDialog', {
      item: item,
      mode: 'edit'
    });
  }
  
Copy to clipboardCopied!

page.showDialog(componentId, options, context)
app.showDialog(componentId, options, context)
Copy to clipboardCopied!

• componentId (string): The ID of the component to open
• options (object, optional): Options object passed to the component
• context (object, optional): Additional context information

export default class MyComponentController {
  onOpenAction(options) {
    // Access the options passed to showDialog
    const item = options.item;
    const mode = options.mode;
    
    // Use the options to initialize component state
    this.dialog.state.currentItem = item;
    this.dialog.state.editMode = mode;
Copy to clipboardCopied!

Closing a Dialog Component

export default class MyComponentController {
  cancelOperation() {
    // Close from within the controller
    // Works for dialog, lookup, and drawer
    this.dialog.closeDialog();
    // or
    this.lookup.closeDialog();
    // or
    this.drawer.closeDialog();
Copy to clipboardCopied!

import UserInteractionManager from '@maximo/graphite-framework/util/UserInteractionManager';

// Close a specific component by ID
UserInteractionManager.get().closeDialog('myComponentId');
Copy to clipboardCopied!

Finding a Dialog Component

export default class MyPageController {
  getComponentState() {
    // Find the component by ID
    const dialog = this.page.findDialog('editDialog');
    
    // Access component state
    const currentState = dialog.state;
    
    return currentState;
Copy to clipboardCopied!

State Management

<dialog id="myDialog" title="Sample Dialog">
  <states>
    <state name="userName" type="string" value="" />
    <state name="userAge" type="number" value="0" />
    <state name="isValid" type="boolean" value="false" />
  </states>
  
  <field label="Name" value="{dialog.state.userName}" />
  <field label="Age" value="{dialog.state.userAge}" />
Copy to clipboardCopied!

export default class MyComponentController {
  onOpenAction() {
    // Read state
    const currentName = this.dialog.state.userName;
    
    // Update state
    this.dialog.state.userName = 'John Doe';
    this.dialog.state.userAge = 30;
    this.dialog.state.isValid = true;
Copy to clipboardCopied!

Dialog Component

Component-Specific Lifecycle Events

on-primary-action Event

<dialog id="createDialog" 
        title="Create New Item" 
        controller="CreateDialogController"
        primary-action-text="Create"
        on-primary-action="createItem">
  <field label="Name" value="{dialog.state.newItemName}" required="true" />
</dialog>
Copy to clipboardCopied!

export default class CreateDialogController {
  async createItem() {
    if (!this.dialog.state.newItemName) {
      this.app.toast('Name is required');
      return false; // Prevent dialog from closing
    }

    const datasource = this.page.findDatasource('itemsDS');
    await datasource.addNew({ name: this.dialog.state.newItemName });
Copy to clipboardCopied!

on-secondary-action Event

on-tertiary-action Event

Component-Specific Properties

• header-buttons: Custom buttons to place in the dialog header
• ai: AI label component

<dialogs>
  <dialog id="confirmDelete" 
          title="Confirm Deletion" 
          sub-title="This action cannot be undone"
          size="sm"
          danger="true"
          primary-action-text="Delete"
          secondary-action-text="Cancel"
          controller="DeleteController"
Copy to clipboardCopied!

Lookup Component

Component-Specific Lifecycle Events

on-item-click Event

<lookup id="itemLookup"
        datasource="itemsDS"
        controller="ItemLookupController"
        on-item-click="handleItemSelection"
        on-item-click-arg="{item}">
</lookup>
Copy to clipboardCopied!

export default class ItemLookupController {
  handleItemSelection(item) {
    console.log('Selected item:', item);
    // Process the selected item
    this.page.state.selectedItem = item;
  }
}
Copy to clipboardCopied!

on-reset-action Event

on-empty-state-action Event

Component-Specific Properties

• actions: Action buttons for the title bar
• item: Custom item rendering in datalist
• selected-item: Custom selected item row rendering
• lookup-subheading: Custom sub header content
• lookup-description: Custom description content

<dialogs>
  <lookup id="assetLookup"
          datasource="assetsDS"
          lookup-heading="Select Asset"
          lookup-subheading="Choose from available assets"
          show-search="true"
          can-filter="true"
          can-sort="true"
          enable-barcode-scanner="true"
Copy to clipboardCopied!

Lookup with Filter Component

• Filter-driven search based on datasource attributes marked as filterable
• Hierarchical drill-down navigation
• Supports both flat and tree-structured data

Component-Specific Lifecycle Events

on-item-click Event

on-drill-in Event

• item: The current item being drilled into (null/undefined for root level)
• Access to datasource and component state through controller

• Loading hierarchical data dynamically
• Filtering child records based on parent selection
• Implementing lazy-loading for large datasets
• Building breadcrumb navigation

<lookup-with-filter id="locationLookup"
                    datasource="locationsDS"
                    hierarchy-drill-in="true"
                    controller="LocationLookupController"
                    on-drill-in="handleDrillIn"
                    on-drill-in-arg="{item}">
</lookup-with-filter>
Copy to clipboardCopied!

export default class LocationLookupController {
  handleDrillIn(item) {
    if (!item) {
      // Root level - load top-level locations
      this.loadRootLocations();
    } else {
      // Load children of the selected item
      this.loadChildLocations(item);
    }
Copy to clipboardCopied!

<attribute name="assetchildren" child-relationship="assetchildren" id="w7d2z"/>
Copy to clipboardCopied!

<lookup-with-filter [...]  lookup-attributes="{['assetnum', 'description']}" tree-label-attribute="assetnum" child-attribute="assetchildren"/>
Copy to clipboardCopied!

<list-item id="n2yd922">
  <box>
    <label label="{item.description}" id="rxnjp22"/>
  </box>
</list-item>
Copy to clipboardCopied!

  <lookup-with-filter id="locationLookup" datasource="locationsDS" hierarchy-drill-in="true" />
Copy to clipboardCopied!

<list-item id="maxlib_a3y42" tree-label-attribute="assetnum"/>
Copy to clipboardCopied!

<list-item child-attribute="assetchildren" id="n2yd922">
  <label label="{item.description}" id="rxnjp22"/>
</list-item>
Copy to clipboardCopied!

• hierarchy-drill-in: Must be set to true to enable drill-down functionality
• child-attribute: Specifies which attribute contains child records (for nested data)
• tree-label-attribute: Defines which attribute to display as the item label
• last-child-drill-in: Set to false to prevent drilling into leaf nodes (items with no children)
• has-filter: Enables filter button for combining search with drill-down

Component-Specific Properties

• actions: Action buttons for the title bar
• item: Custom item rendering

<dialogs>
  <lookup-with-filter id="hierarchyLookup"
                      datasource="hierarchyDS"
                      lookup-heading="Select Location"
                      hierarchy-drill-in="true"
                      has-filter="true"
                      tree-name="Location Tree"
                      tree-label-attribute="name"
                      child-attribute="children"
Copy to clipboardCopied!

Sliding Drawer Component

Component-Specific Properties

• header-button: Button for additional header functionality
• primary-button: Primary button at drawer end
• secondary-button: Secondary button at drawer end

<dialogs>
  <sliding-drawer id="detailsDrawer"
                  header-text="Item Details"
                  sub-title="View and edit item information"
                  align="end"
                  content-padding="true"
                  dock-on-expand="true"
                  controller="DetailsDrawerController"
                  on-open-action="loadDetails">
Copy to clipboardCopied!

Best Practices

1. Use Meaningful Component IDs

<!-- Good -->
<dialog id="confirmDeleteDialog" title="Confirm Deletion">
<lookup id="assetSelectionLookup" datasource="assetsDS">
<sliding-drawer id="itemDetailsDrawer" header-text="Details">

<!-- Avoid -->
<dialog id="dlg1" title="Dialog">
<lookup id="l" datasource="ds">
Copy to clipboardCopied!

2. Leverage State for Dynamic Content

// Good - Use state
this.dialog.state.errorMessage = 'Invalid input';
this.dialog.state.showError = true;

// Avoid - Direct DOM manipulation
document.getElementById('errorDiv').textContent = 'Invalid input';
Copy to clipboardCopied!

3. Implement Proper Validation

validate() {
  const requiredFields = ['name', 'email', 'phone'];
  
  for (const field of requiredFields) {
    if (!this.dialog.state[field]) {
      this.app.toast(`${field} is required`);
      return false;
    }
  }
Copy to clipboardCopied!

4. Handle Async Operations Properly

<dialog id="saveDialog" 
        async-primary-action="true"
        on-primary-action="saveData">
Copy to clipboardCopied!

async saveData() {
  try {
    const datasource = this.page.findDatasource('itemsDS');
    await datasource.save();
    this.app.toast('Saved successfully');
    return true;
  } catch (error) {
    this.app.toast('Save failed: ' + error.message);
    return false; // Keep dialog open on error
Copy to clipboardCopied!

5. Clean Up Resources

onCloseAction() {
  // Clear temporary state
  this.dialog.state.tempData = null;
  
  // Cancel pending operations
  if (this.pendingRequest) {
    this.pendingRequest.abort();
  }
  
Copy to clipboardCopied!

6. Choose the Right Component

• Use Dialog for simple confirmations and forms
• Use Lookup when users need to search and select from flat data
• Use Lookup with Filter for hierarchical data navigation
• Use Sliding Drawer for supplementary content that doesn’t require full focus

7. Provide Clear Action Labels

<!-- Good -->
<dialog primary-action-text="Save Changes" secondary-action-text="Cancel">
<lookup primary-action-text="Select Items" secondary-action-text="Cancel">

<!-- Avoid -->
<dialog primary-action-text="OK" secondary-action-text="No">
Copy to clipboardCopied!

8. Consider Mobile vs Desktop

<!-- Small dialog for simple confirmations -->
<dialog size="sm" title="Confirm">

<!-- Large lookup for complex selection -->
<lookup size="lg" datasource="itemsDS">

<!-- Drawer with proper padding -->
<sliding-drawer content-padding="true" header-text="Details">
Copy to clipboardCopied!

9. Use Controllers for Complex Logic

<!-- Good - Logic in controller -->
<dialog id="myDialog" 
        controller="MyDialogController"
        on-primary-action="handleSave">

<!-- Avoid - Inline logic -->
<dialog id="myDialog" 
        on-primary-action="{app.findDatasource('ds').save().then(() => app.toast('Saved'))}">
Copy to clipboardCopied!

10. Declare All Dialogs in the Dialogs Container

<application id="myApp">
  <dialogs>
    <dialog id="dialog1" title="Dialog 1" />
    <lookup id="lookup1" datasource="ds1" />
    <sliding-drawer id="drawer1" header-text="Drawer" />
  </dialogs>
  
  <page id="mainPage">
    <!-- page content -->
Copy to clipboardCopied!

Troubleshooting

Issue: Component Won’t Close After Primary Action

1. Validation returning false:

// Check your validate method
validate() {
  // Make sure this returns true when validation passes
  return this.isFormValid();
}
Copy to clipboardCopied!

2. Primary action handler returning false:

// Ensure your handler returns true or undefined
onPrimaryAction() {
  this.saveData();
  return true; // Explicitly return true to close
}
Copy to clipboardCopied!

3. Async operation not awaited:

<!-- Add async-primary-action attribute -->
<dialog async-primary-action="true" on-primary-action="saveData">
Copy to clipboardCopied!

Issue: Component State Not Updating UI

<!-- Correct - Use binding -->
<field value="{dialog.state.userName}" />

<!-- Incorrect - Static value -->
<field value="dialog.state.userName" />
Copy to clipboardCopied!

Issue: Controller Methods Not Being Called

1. Controller not properly bound:

<!-- Ensure controller attribute is set -->
<dialog id="myDialog" controller="MyDialogController">
Copy to clipboardCopied!

2. Method name mismatch:

// Method name must match the event name
// For on-open-action="loadData"
loadData() { // Correct
  // ...
}

onLoadData() { // Incorrect - won't be called
  // ...
}
Copy to clipboardCopied!

3. Controller file not exported:

// Ensure default export
export default class MyDialogController {
  // ...
}
Copy to clipboardCopied!

Issue: Component Opens But Content Is Empty

1. Missing datasource data:

onOpenAction() {
  // Ensure datasource is loaded
  const ds = this.page.findDatasource('itemsDS');
  if (!ds.state.hasData) {
    await ds.load();
  }
}
Copy to clipboardCopied!

2. Binding to undefined state:

<!-- Initialize state with default values -->
<states>
  <state name="userName" type="string" value="" />
</states>
Copy to clipboardCopied!

Issue: Lookup Not Showing Search Results

1. Datasource attributes not marked as searchable:

<json-datasource id="itemsDS">
  <schema>
    <attribute name="name" searchable="true" />
    <attribute name="description" searchable="true" />
  </schema>
</json-datasource>
Copy to clipboardCopied!

2. show-search not enabled:

<lookup id="myLookup" 
        datasource="itemsDS" 
        show-search="true">
Copy to clipboardCopied!

Issue: Sliding Drawer Not Docking Properly

<sliding-drawer id="myDrawer"
                dock-on-expand="true"
                header-text="Details">
Copy to clipboardCopied!

Issue: Multiple Components Interfering

<!-- Each component should have unique state -->
<dialog id="editDialog">
  <states>
    <state name="editUserName" type="string" />
  </states>
</dialog>

<dialog id="createDialog">
  <states>
Copy to clipboardCopied!

Issue: Validation Not Showing Error Messages

validate() {
  if (!this.dialog.state.email) {
    // Show toast or set error state
    this.app.toast('Email is required');
    this.dialog.state.emailError = 'Email is required';
    return false;
  }
  return true;
}
Copy to clipboardCopied!

Issue: Lookup Not Pre-selecting Items

// For single select
this.page.showDialog('myLookup', {
  preselectedValues: [itemId]
});

// For multi-select
this.page.showDialog('myLookup', {
  preselectedValues: [id1, id2, id3]
});
Copy to clipboardCopied!

Issue: Barcode Scanner Not Working

1. Scanner not enabled:

<lookup id="myLookup"
        enable-barcode-scanner="true"
        readers="{['QR', 'code_128_reader']}">
Copy to clipboardCopied!

2. Wrong reader type specified:

<!-- Use correct reader types -->
<lookup readers="{['QR', 'ean_reader', 'code_128_reader']}">
Copy to clipboardCopied!

Issue: Drill-Down Navigation Not Working

1. Missing child-attribute for nested data:

<!-- For pre-loaded nested data, specify the child attribute -->
<lookup-with-filter id="locationLookup"
                    datasource="locationsDS"
                    hierarchy-drill-in="true"
                    child-attribute="children"
                    tree-label-attribute="location">
</lookup-with-filter>
Copy to clipboardCopied!

2. on-drill-in handler not loading data:

// ❌ Wrong - not loading data
handleDrillIn(item) {
  console.log('Drilling into:', item);
  // Missing datasource load!
}

// ✅ Correct - loads child data
async handleDrillIn(item) {
  const datasource = this.app.findDatasource('hierarchyDS');
Copy to clipboardCopied!

3. Data structure doesn’t indicate children:

// ❌ Wrong - no way to know if item has children
{
  id: '1',
  name: 'Parent Item'
}

// ✅ Correct - includes child indicator
{
  id: '1',
Copy to clipboardCopied!