2.48.0 â€ĸ Published 4 months ago

@memberjunction/ng-form-toolbar v2.48.0

Weekly downloads
-
License
ISC
Repository
-
Last release
4 months ago

@memberjunction/ng-form-toolbar

The @memberjunction/ng-form-toolbar package provides a consistent, feature-rich toolbar component for forms in MemberJunction Explorer applications. It handles standard form operations like editing, saving, and deleting records, while providing advanced functionality such as favorites management, record history viewing, AI-powered chat integration, and list management.

Features

  • Context-aware button display - Dynamically shows/hides buttons based on form state (view/edit mode)
  • Save with real-time feedback - Visual status updates during save operations with elapsed time tracking
  • Smart delete functionality - Dependency checking before deletion with confirmation dialog
  • Record history tracking - View change history for entities with tracking enabled
  • Skip AI chat integration - Discuss records with AI assistant directly from the toolbar
  • Favorites management - Mark frequently accessed records as favorites for quick access
  • List management - Add records to existing lists for organization
  • Permission-based visibility - Buttons respect user permissions (edit, delete, etc.)
  • Server update notifications - Real-time status updates from server during long operations
  • Consistent UX - Unified toolbar experience across all MemberJunction forms

Installation

npm install @memberjunction/ng-form-toolbar

Requirements

  • Angular 18+
  • @memberjunction/global ^2.43.0
  • @memberjunction/core ^2.43.0
  • @memberjunction/ng-shared ^2.43.0
  • @memberjunction/ng-base-forms ^2.43.0
  • @memberjunction/ng-ask-skip ^2.43.0
  • @memberjunction/ng-record-changes ^2.43.0
  • @memberjunction/ng-container-directives ^2.43.0
  • @progress/kendo-angular-buttons ^16.2.0
  • @progress/kendo-angular-dialog ^16.2.0
  • ngx-markdown ^18.0.0

Usage

Basic Setup

First, import the FormToolbarModule in your Angular module:

import { FormToolbarModule } from '@memberjunction/ng-form-toolbar';

@NgModule({
  imports: [
    CommonModule,
    FormsModule,
    // ... other imports
    FormToolbarModule
  ],
  // ... rest of module configuration
})
export class YourModule { }

Adding the Toolbar to a Form

The toolbar is designed to work seamlessly with forms that extend BaseFormComponent. Add it to your form template:

<!-- Basic usage -->
<mj-form-toolbar [form]="this"></mj-form-toolbar>

<!-- Your form content -->
<form>
  <!-- Form fields and controls -->
</form>

Example component implementation:

import { Component } from '@angular/core';
import { BaseFormComponent } from '@memberjunction/ng-base-forms';
import { UserEntity } from '@memberjunction/core-entities';

@Component({
  selector: 'app-user-form',
  templateUrl: './user-form.component.html',
  styleUrls: ['./user-form.component.css']
})
export class UserFormComponent extends BaseFormComponent {
  public record!: UserEntity;
  
  public async ngOnInit() {
    await super.ngOnInit();
    // Additional initialization logic
  }
  
  // Override BaseFormComponent methods as needed
}

Customizing the Toolbar

Control which features are displayed:

<!-- Hide Skip chat button -->
<mj-form-toolbar 
  [form]="this"
  [ShowSkipChatButton]="false">
</mj-form-toolbar>

<!-- Disable toolbar programmatically -->
<mj-form-toolbar 
  [form]="this"
  [Disabled]="isProcessing">
</mj-form-toolbar>

API Reference

FormToolbarComponent

Inputs

NameTypeDefaultDescription
formBaseFormComponentRequiredThe form component instance that this toolbar controls
ShowSkipChatButtonbooleantrueControls visibility of the Skip AI chat button

Properties

NameTypeDescription
DisabledbooleanGlobal setting to enable/disable the entire toolbar
CurrentlyDisabledbooleanRead-only property indicating if toolbar is currently disabled
listDialogVisiblebooleanControls visibility of the add-to-list dialog
showListDialogLoaderbooleanShows loading indicator in list dialog
availableListsListEntity[]Lists available for adding the current record
selectedListsListEntity[]Currently selected lists in the dialog

Methods

NameParametersReturn TypeDescription
saveExistingRecordevent: MouseEventPromise<void>Saves the current record with visual feedback and progress tracking
ShowSkipChatNonevoidToggles the Skip AI chat dialog for the current record
toggleDeleteDialogshow: booleanvoidShows or hides the delete confirmation dialog
toggleListDialogshow: booleanPromise<void>Shows or hides the add-to-list dialog and loads available lists
addRecordToListlist: ListEntityPromise<void>Adds the current record to the specified list
deleteRecordNonePromise<void>Deletes the current record after dependency check and confirmation

Toolbar States and Behavior

View Mode

When the form is in view mode (form.EditMode === false), the toolbar displays:

  • Edit button đŸ–Šī¸ - Visible if user has edit permission (form.UserCanEdit)
  • Delete button đŸ—‘ī¸ - Visible if user has delete permission (form.UserCanDelete)
  • Favorite/Unfavorite toggle ⭐ - Toggle between filled/outlined star based on favorite status
  • History button 🕐 - Visible only if entity tracks changes (EntityInfo.TrackRecordChanges)
  • Skip chat button đŸ’Ŧ - Visible if ShowSkipChatButton is true
  • Add to list button ➕ - Always visible in view mode

Edit Mode

When the form is in edit mode (form.EditMode === true), the toolbar displays:

  • Save button 💾 - Always visible with "Save" label
  • Cancel button â†Šī¸ - Only visible for existing records (not new records)
  • Changes button 📋 - Only visible when record has unsaved changes (record.Dirty)

Save Operation Features

During save operations, the toolbar provides enhanced user feedback:

  1. Visual Feedback: Form opacity reduced to 75% and interactions disabled
  2. Progress Tracking: Real-time elapsed time counter (updates every 100ms)
  3. Server Updates: Displays server status messages via MJGlobal event system
  4. Automatic Cleanup: Restores form state after save completion

Example save feedback display:

Saving... (3 secs)
Processing entity relationships...

Styling and Customization

CSS Classes

The component provides several CSS classes for customization:

/* Main container */
.toolbar-container {
  border-bottom: solid 1px lightgray;
  padding-bottom: 10px;
  margin-bottom: 5px;
}

/* Button spacing */
.toolbar-container button {
  margin-right: 7px;
}

/* Text spacing in buttons */
.toolbar-container .button-text {
  margin-left: 7px;
}

/* Disabled state */
.toolbar-container.disabled {
  pointer-events: none;
  opacity: 0.8;
}

/* Save status message */
.form-toolbar-status-message {
  background: #f0f0f0;
  padding: 15px;
  border-radius: 5px;
  box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
  color: #1d7032;
  font-weight: bold;
  text-align: center;
}

/* List dialog items */
.list-item {
  display: flex;
  justify-content: space-between;
  padding-bottom: 5px;
  align-items: center;
}

Icons

The toolbar uses Font Awesome icons for consistent visual language:

  • Edit: fa-pen-to-square
  • Delete: fa-trash-can
  • Favorite (filled): fa-solid fa-star
  • Favorite (outline): fa-regular fa-star
  • Save: fa-floppy-disk
  • Cancel: fa-rotate-left
  • Changes: fa-clipboard-list
  • History: fa-business-time
  • Chat: fa-comment-dots
  • Add: fa-plus

Integration with MemberJunction Services

Event System Integration

The toolbar integrates with MJGlobal event system for:

  • Server status updates: Listens for EventCodes.PushStatusUpdates during save operations
  • Tab management: Raises EventCodes.CloseCurrentTab after successful deletion

Skip Chat Integration

When Skip chat is enabled, the toolbar embeds the mj-skip-chat-with-record-window component:

<mj-skip-chat-with-record-window
  [LinkedEntityID]="form.EntityInfo.ID"
  [LinkedEntityPrimaryKey]="LinkedEntityPrimaryKey"
  [WindowOpened]="_skipChatDialogVisible"
  (WindowClosed)="ShowSkipChat()">
</mj-skip-chat-with-record-window>

Record Changes Integration

For entities with change tracking enabled:

<mj-record-changes 
  [record]="form.record" 
  (dialogClosed)="form.handleHistoryDialog()">
</mj-record-changes>

Advanced Usage Examples

Custom Toolbar with Conditional Features

@Component({
  template: `
    <mj-form-toolbar 
      [form]="this"
      [ShowSkipChatButton]="shouldShowChat">
    </mj-form-toolbar>
  `
})
export class CustomFormComponent extends BaseFormComponent {
  get shouldShowChat(): boolean {
    // Show chat only for certain record types or user roles
    return this.record?.Status === 'Active' && 
           this.currentUser.hasRole('Manager');
  }
}

Handling Toolbar Events

export class FormWithToolbarComponent extends BaseFormComponent {
  async ngOnInit() {
    await super.ngOnInit();
    
    // Listen for toolbar-related events
    MJGlobal.Instance.GetEventListener(false).subscribe((event: MJEvent) => {
      if (event.eventCode === EventCodes.CloseCurrentTab) {
        // Handle tab closure after deletion
        this.handleTabClosure();
      }
    });
  }
}

Programmatic Toolbar Control

export class AdvancedFormComponent extends BaseFormComponent {
  @ViewChild(FormToolbarComponent) toolbar!: FormToolbarComponent;
  
  async performBulkOperation() {
    // Disable toolbar during bulk operations
    this.toolbar.Disabled = true;
    
    try {
      await this.processBulkData();
    } finally {
      this.toolbar.Disabled = false;
    }
  }
  
  // Programmatically show Skip chat
  openAIAssistant() {
    this.toolbar.ShowSkipChat();
  }
}

Error Handling

The toolbar implements comprehensive error handling:

  • Save errors: Displays error notifications with server messages when available
  • Delete errors: Shows appropriate messages for dependency conflicts
  • List operations: Notifies users of success/failure when adding to lists
  • Network errors: Gracefully handles connection issues with user-friendly messages

Best Practices

  1. Always pass the form reference: The toolbar requires a valid BaseFormComponent instance
  2. Handle permissions properly: Ensure your form correctly implements permission checks
  3. Test save operations: Verify your entity's save logic works with the toolbar's feedback system
  4. Consider mobile responsiveness: The toolbar works on mobile but may need custom styling
  5. Use consistent icons: Follow MemberJunction's icon conventions when extending

Troubleshooting

Common Issues

  1. Buttons not appearing: Check that your form properly extends BaseFormComponent and implements required properties
  2. Save feedback not showing: Ensure your form's parent element is properly structured
  3. Skip chat not working: Verify @memberjunction/ng-ask-skip is properly installed and configured
  4. History not available: Confirm the entity has TrackRecordChanges enabled in metadata

Debug Mode

Enable debug logging by adding to your component:

ngOnInit() {
  // Log toolbar state changes
  console.log('Toolbar disabled:', this.toolbar.CurrentlyDisabled);
  console.log('Form edit mode:', this.form.EditMode);
  console.log('User permissions:', {
    canEdit: this.form.UserCanEdit,
    canDelete: this.form.UserCanDelete
  });
}

Version History

  • 2.43.0 - Current version with full feature set
  • 2.42.0 - Added server status update integration
  • 2.41.0 - Introduced real-time save progress tracking
  • 2.40.0 - Added list management functionality

Contributing

When contributing to this package:

  1. Follow the MemberJunction coding standards
  2. Ensure all buttons use appropriate Font Awesome icons
  3. Test with various entity types and permissions
  4. Update this README with any new features
  5. Add unit tests for new functionality

License

ISC

Support

For issues or questions:

2.27.1

8 months ago

2.23.2

8 months ago

2.46.0

4 months ago

2.23.1

8 months ago

2.27.0

8 months ago

2.34.0

6 months ago

2.30.0

7 months ago

2.19.4

9 months ago

2.19.5

9 months ago

2.19.2

9 months ago

2.19.3

9 months ago

2.19.0

9 months ago

2.19.1

9 months ago

2.15.2

9 months ago

2.34.2

6 months ago

2.34.1

6 months ago

2.15.1

9 months ago

2.38.0

5 months ago

2.45.0

4 months ago

2.22.1

8 months ago

2.22.0

8 months ago

2.41.0

5 months ago

2.22.2

8 months ago

2.26.1

8 months ago

2.26.0

8 months ago

2.33.0

6 months ago

2.18.3

9 months ago

2.18.1

9 months ago

2.18.2

9 months ago

2.18.0

9 months ago

2.37.1

5 months ago

2.37.0

5 months ago

2.14.0

9 months ago

2.21.0

8 months ago

2.44.0

5 months ago

2.40.0

5 months ago

2.29.0

7 months ago

2.29.2

7 months ago

2.29.1

7 months ago

2.25.0

8 months ago

2.48.0

4 months ago

2.32.0

7 months ago

2.32.2

7 months ago

2.32.1

7 months ago

2.17.0

9 months ago

2.13.4

10 months ago

2.36.0

6 months ago

2.13.2

11 months ago

2.13.3

10 months ago

2.13.0

11 months ago

2.36.1

6 months ago

2.13.1

11 months ago

2.43.0

5 months ago

2.20.2

9 months ago

2.20.3

8 months ago

2.20.0

9 months ago

2.20.1

9 months ago

2.28.0

8 months ago

2.47.0

4 months ago

2.24.1

8 months ago

2.24.0

8 months ago

2.31.0

7 months ago

2.12.0

12 months ago

2.39.0

5 months ago

2.16.1

9 months ago

2.35.1

6 months ago

2.35.0

6 months ago

2.16.0

9 months ago

2.42.1

5 months ago

2.42.0

5 months ago

2.23.0

8 months ago

2.11.0

12 months ago

2.10.0

12 months ago

2.9.0

12 months ago

2.8.0

1 year ago

2.7.0

1 year ago

2.6.1

1 year ago

2.5.2

1 year ago

2.6.0

1 year ago

2.7.1

1 year ago

2.5.1

1 year ago

2.5.0

1 year ago

2.4.1

1 year ago

2.4.0

1 year ago

2.3.3

1 year ago

2.3.2

1 year ago

2.3.1

1 year ago

2.3.0

1 year ago

2.2.1

1 year ago

2.2.0

1 year ago

2.1.5

1 year ago

2.1.4

1 year ago

2.1.3

1 year ago

2.1.2

1 year ago

2.1.1

1 year ago

2.0.0

1 year ago

1.8.1

1 year ago

1.8.0

1 year ago

1.7.1

1 year ago

1.7.0

1 year ago

1.6.1

1 year ago

1.6.0

1 year ago

1.5.3

1 year ago

1.5.2

1 year ago

1.5.1

1 year ago

1.5.0

1 year ago

1.4.1

1 year ago