@memberjunction/ng-base-forms

Base classes and components for creating entity forms in MemberJunction Angular applications, providing core functionality for form management, validation, and data handling.

Features

- Abstract base classes for forms, form sections, and record components
- Automatic field rendering components with type detection
- Encrypted field support with configurable visibility and blind edit modes
- Support for edit mode and validation
- Transaction management for saving related records
- Integration with MemberJunction metadata and entity framework
- Tab management and responsive design
- Permission checking and user authorization
- Support for favorites and record dependencies
- Form event handling and coordination
- Dynamic form section loading
- Linked record field components with search and dropdown capabilities

Installation

``bash
npm install @memberjunction/ng-base-forms
`

Core Components

$3

A powerful component that automatically generates UI for any field in a BaseEntity object:

`typescript
import { Component } from '@angular/core';
import { BaseEntity } from '@memberjunction/core';

@Component({
template:
[record]="myRecord"
[EditMode]="isEditing"
FieldName="FirstName"
Type="textbox"
[ShowLabel]="true"
(ValueChange)="onValueChange($event)"
>

})
export class MyComponent {
myRecord: BaseEntity;
isEditing: boolean = false;

onValueChange(newValue: any) {
console.log('Field value changed:', newValue);
}
}
`

#### MJFormField Input Properties

- record (BaseEntity, required): The entity record containing the field
- EditMode (boolean): Whether the field is editable
- FieldName (string, required): Name of the field to render
- Type (string): Control type - 'textbox' | 'textarea' | 'numerictextbox' | 'datepicker' | 'checkbox' | 'dropdownlist' | 'combobox' | 'code'
- LinkType (string): For linked fields - 'Email' | 'URL' | 'Record' | 'None'
- LinkComponentType (string): For record links - 'Search' | 'Dropdown'
- ShowLabel (boolean): Whether to show the field label (default: true)
- DisplayName (string): Override the default display name
- PossibleValues (string[]): Custom values for dropdown/combobox fields
- formContext (BaseFormContext): Form context for field filtering and state
- hideWhenEmptyInReadOnlyMode (boolean): Hide field when empty in read-only mode (default: true)

#### Encrypted Field Support

MJFormField automatically handles fields configured for encryption in the entity metadata. The component provides appropriate UI based on the field's encryption settings:

Read-Only Mode:
- AllowDecryptInAPI=true: Displays a masked value (••••••••) with a lock icon by default. Users can click the eye toggle button to reveal the actual decrypted value.
- AllowDecryptInAPI=false: Displays only the masked value with a lock icon. The value cannot be revealed as it's protected.
- Empty value: Displays nothing (no mask or icon).

Edit Mode:
- AllowDecryptInAPI=true: Shows a password-style text input with an eye toggle to show/hide the value being edited.
- AllowDecryptInAPI=false ("Blind Edit"): Shows the current value as locked/masked (cannot be viewed), with a separate empty text input for entering a new value. Users can use the eye toggle to verify what they're typing before submitting.

`typescript
// Entity field metadata configuration for encryption
// (Set via database or entity metadata, not in Angular component)
// - Encrypt: true // Field value is encrypted at rest
// - AllowDecryptInAPI: true // Decrypted value can be sent to API clients
// - SendEncryptedValue: false // Whether to send encrypted ciphertext when AllowDecryptInAPI=false
`

Example usage with encrypted field:
`html

[record]="userRecord"
[EditMode]="isEditing"
FieldName="SSN"
Type="textbox"
>
`

The encrypted field UI includes:
- Lock icon (fa-lock) indicating the field is encrypted
- Eye toggle buttons (fa-eye / fa-eye-slash) for showing/hiding values
- Hint text for blind edit mode explaining the behavior
- Password-style masking for sensitive data entry

$3

Specialized component for fields that link to other entity records:

`typescript
[record]="myRecord"
FieldName="CustomerID"
[RecordName]="customerName"
LinkComponentType="Search"
>
`

#### MJLinkField Input Properties

- record (BaseEntity, required): The entity record
- FieldName (string, required): The foreign key field name
- RecordName (string): Pre-populate with the linked record's name
- LinkComponentType ('Search' | 'Dropdown'): UI type for selecting records

$3

Dynamically loads form sections registered with the MemberJunction class factory:

`typescript
Entity="Customer"
Section="Details"
[record]="customerRecord"
[EditMode]="isEditing"
(LoadComplete)="onSectionLoaded()"
>
`

Base Classes

$3

The foundational class for all components that work with entity records:

`typescript
import { BaseRecordComponent } from '@memberjunction/ng-base-forms';

@Component({
// ...
})
export class YourComponent extends BaseRecordComponent {
// Inherited properties:
// - record: BaseEntity
// - EditMode: boolean
// - UserCanEdit: boolean
// - UserCanDelete: boolean
// - IsFavorite: boolean
}
`

$3

For creating reusable form sections that can be dynamically loaded:

`typescript
import { BaseFormSectionComponent } from '@memberjunction/ng-base-forms';
import { RegisterClass } from '@memberjunction/global';

@Component({
template:

`typescript
import { BaseFormComponent } from '@memberjunction/ng-base-forms';
import { RegisterClass } from '@memberjunction/global';

@Component({
template:

`typescript
// Start editing
this.StartEditMode();

// Save changes (true = stop edit mode after save)
await this.SaveRecord(true);

// Cancel editing and revert changes
this.CancelEdit();

// Check if in edit mode
if (this.EditMode) {
// Show save/cancel buttons
}
`

$3

`typescript
// Validate the entire form
const validationResult = this.Validate();
if (!validationResult.Success) {
console.log('Validation errors:', validationResult.Errors);
}

// Validate pending records
const pendingResults = this.ValidatePendingRecords();
`

$3

`typescript
// Check user permissions
if (this.UserCanEdit) {
this.StartEditMode();
}

if (this.UserCanDelete) {
// Show delete button
}

// Check field-level permissions
const canEditField = this.UserCanEditField('FieldName');
`

$3

`typescript
// Get view parameters for related entity
const viewParams = this.BuildRelationshipViewParamsByEntityName('Orders');

// Create new related record with pre-filled values
const newOrderValues = this.NewRecordValues('Orders');
newOrderValues.CustomerID = this.record.ID;

// Access pending records for transaction
const pendingOrders = this.PendingRecords.filter(r => r.Entity === 'Orders');
`

$3

`typescript
// Check active tab
if (this.IsCurrentTab('details')) {
// Load tab-specific data
}

// Handle tab selection
public onTabSelect(e: TabEvent) {
this.LoadTabData(e.title);
}

// Tab configuration
tabs = [
{ title: 'Details', selected: true },
{ title: 'Orders', selected: false },
{ title: 'History', selected: false }
];
`

$3

`typescript
// Check if record is favorited
if (this.IsFavorite) {
// Show filled star icon
}

// Toggle favorite status
if (this.IsFavorite) {
await this.RemoveFavorite();
} else {
await this.MakeFavorite();
}
`

$3

`typescript
// Check for dependencies before delete
const dependencies = await this.GetRecordDependencies();
if (dependencies.length > 0) {
// Show warning about dependent records
console.log(Cannot delete: ${dependencies.length} dependent records found);
}
`

Advanced Usage

$3

Override default field rendering by creating custom components:

`typescript
@Component({
selector: 'custom-field',
template:

`typescript
// In your module or component
import { RegisterClass } from '@memberjunction/global';

@RegisterClass(BaseFormSectionComponent, 'Product.Inventory')
export class ProductInventorySection extends BaseFormSectionComponent {
// Section implementation
}

// Usage in template
[record]="productRecord" [EditMode]="EditMode">

`

$3

Handle multiple related records in a single transaction:

`typescript
// Add records to pending transaction
this.AddPendingRecord(newOrderRecord, 'Orders');
this.AddPendingRecord(newOrderItemRecord, 'Order Items');

// Validate all pending records
const validationResults = this.ValidatePendingRecords();
if (validationResults.every(r => r.Success)) {
// Save all records in transaction
await this.SaveRecord(true);
}
`

Module Configuration

The BaseFormsModule includes all necessary imports:

`typescript
import { BaseFormsModule } from '@memberjunction/ng-base-forms';

@NgModule({
imports: [
BaseFormsModule,
// Other imports...
]
})
export class YourModule { }
`

Dependencies

- Angular Core: v18.0.2+
- @memberjunction/core: Core MJ functionality
- @memberjunction/global: Global utilities and class factory
- @memberjunction/ng-shared: Shared Angular services
- @memberjunction/ng-tabstrip: Tab management
- @memberjunction/ng-link-directives: Link handling
- @memberjunction/ng-container-directives: Container utilities
- @memberjunction/ng-record-changes: Change tracking
- @memberjunction/ng-code-editor: Code editing support
- @progress/kendo-angular-\*: UI components
- @memberjunction/ng-markdown: Markdown rendering
- rxjs: Reactive programming

Integration with MemberJunction

This package is designed to work seamlessly with the MemberJunction ecosystem:

- Entity Metadata: Automatically reads field definitions, relationships, and permissions
- Class Factory: Uses MJ's class factory for dynamic component loading
- Validation: Integrates with entity-level validation rules
- Permissions: Respects entity and field-level permissions
- Transactions: Supports MJ's transaction management for related records

Best Practices

1. Always use the class factory for registering custom form components
2. Leverage MJFormField for automatic field rendering when possible
3. Handle validation at both field and form levels
4. Check permissions before allowing user actions
5. Use transactions when saving multiple related records
6. Implement proper error handling for save operations
7. Follow Angular lifecycle hooks for initialization and cleanup

Building

This package uses Angular CLI for building:

`bash


Build the package

License

ISC