dynamic forms module doc

7 months ago · ddc486fef6
1 changed files with 816 additions and 0 deletions
--- a/docs/en/framework/ui/angular/dynamic-form-module.md
+++ b/docs/en/framework/ui/angular/dynamic-form-module.md
@ -0,0 +1,816 @@
+```json
+//[doc-seo]
+{
+    "Description": "Learn how to use the ABP Dynamic Form Module to create dynamic, configurable forms with validation, conditional logic, and custom components in Angular applications."
+}
+```
+
+# Dynamic Form Module
+
+The ABP Dynamic Form Module is a powerful component that allows you to create dynamic, configurable forms without writing extensive HTML templates. It provides a declarative way to define form fields with validation, conditional logic, grid layout, and custom components.
+
+## Installation
+
+The Dynamic Form Module is part of the `@abp/ng.components` package. If you haven't installed it yet, install it via npm:
+
+```bash
+npm install @abp/ng.components
+```
+
+## Usage
+
+Import the `DynamicFormComponent` in your component:
+
+```ts
+import { DynamicFormComponent } from '@abp/ng.components/dynamic-form';
+
+@Component({
+  selector: 'app-my-component',
+  imports: [DynamicFormComponent],
+  templateUrl: './my-component.component.html',
+})
+export class MyComponent {}
+```
+
+## Basic Example
+
+Here's a simple example of how to use the dynamic form:
+
+```ts
+import { Component } from '@angular/core';
+import { DynamicFormComponent } from '@abp/ng.components/dynamic-form';
+import { FormFieldConfig } from '@abp/ng.components/dynamic-form';
+
+@Component({
+  selector: 'app-user-form',
+  imports: [DynamicFormComponent],
+  template: `
+    <abp-dynamic-form
+      [fields]="formFields"
+      [submitButtonText]="'Submit'"
+      [showCancelButton]="true"
+      (onSubmit)="handleSubmit($event)"
+      (formCancel)="handleCancel()">
+    </abp-dynamic-form>
+  `,
+})
+export class UserFormComponent {
+  formFields: FormFieldConfig[] = [
+    {
+      key: 'firstName',
+      type: 'text',
+      label: 'First Name',
+      placeholder: 'Enter your first name',
+      required: true,
+      order: 1,
+    },
+    {
+      key: 'lastName',
+      type: 'text',
+      label: 'Last Name',
+      placeholder: 'Enter your last name',
+      required: true,
+      order: 2,
+    },
+    {
+      key: 'email',
+      type: 'email',
+      label: 'Email',
+      placeholder: 'Enter your email',
+      required: true,
+      order: 3,
+    },
+  ];
+
+  handleSubmit(formValue: any) {
+    console.log('Form submitted:', formValue);
+    // Handle form submission
+  }
+
+  handleCancel() {
+    console.log('Form cancelled');
+    // Handle form cancellation
+  }
+}
+```
+
+## Component Inputs
+
+The `DynamicFormComponent` accepts the following inputs:
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `fields` | `FormFieldConfig[]` | `[]` | Array of field configurations |
+| `values` | `Record<string, any>` | `undefined` | Initial values for the form |
+| `submitButtonText` | `string` | `'Submit'` | Text for the submit button |
+| `submitInProgress` | `boolean` | `false` | Whether form submission is in progress |
+| `showCancelButton` | `boolean` | `false` | Whether to show the cancel button |
+
+## Component Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `onSubmit` | `EventEmitter<any>` | Emitted when the form is submitted with valid data |
+| `formCancel` | `EventEmitter<void>` | Emitted when the cancel button is clicked |
+
+## FormFieldConfig Properties
+
+The `FormFieldConfig` interface defines the structure of each field in the form:
+
+```ts
+interface FormFieldConfig {
+  key: string;                    // Unique identifier for the field
+  type: FieldType;                // Type of the field
+  label: string;                  // Label text for the field
+  value?: any;                    // Initial value
+  placeholder?: string;           // Placeholder text
+  required?: boolean;             // Whether the field is required
+  disabled?: boolean;             // Whether the field is disabled
+  options?: OptionProps;          // Options for select fields
+  validators?: ValidatorConfig[]; // Array of validator configurations
+  conditionalLogic?: ConditionalRule[]; // Array of conditional rules
+  order?: number;                 // Display order (ascending)
+  gridSize?: number;              // Bootstrap grid size (1-12)
+  component?: Type<ControlValueAccessor>; // Custom component
+}
+```
+
+### Field Types
+
+The following field types are supported:
+
+- `text` - Text input
+- `email` - Email input
+- `number` - Number input
+- `select` - Dropdown select
+- `checkbox` - Checkbox
+- `date` - Date picker
+- `textarea` - Textarea
+
+## Validators
+
+You can add validators to your form fields using the `validators` property:
+
+```ts
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'username',
+    type: 'text',
+    label: 'Username',
+    validators: [
+      {
+        type: 'required',
+        message: 'Username is required',
+      },
+      {
+        type: 'minLength',
+        value: 3,
+        message: 'Username must be at least 3 characters',
+      },
+      {
+        type: 'maxLength',
+        value: 20,
+        message: 'Username must not exceed 20 characters',
+      },
+    ],
+  },
+  {
+    key: 'age',
+    type: 'number',
+    label: 'Age',
+    validators: [
+      {
+        type: 'min',
+        value: 18,
+        message: 'You must be at least 18 years old',
+      },
+      {
+        type: 'max',
+        value: 100,
+        message: 'Age must not exceed 100',
+      },
+    ],
+  },
+];
+```
+
+### Available Validator Types
+
+| Type | Description | Requires Value |
+|------|-------------|----------------|
+| `required` | Field is required | No |
+| `email` | Must be a valid email | No |
+| `minLength` | Minimum string length | Yes |
+| `maxLength` | Maximum string length | Yes |
+| `min` | Minimum numeric value | Yes |
+| `max` | Maximum numeric value | Yes |
+| `pattern` | Regular expression pattern | Yes |
+| `requiredTrue` | Must be true (for checkboxes) | No |
+
+## Select Fields with Options
+
+You can create dropdown select fields with static or dynamic options:
+
+### Static Options
+
+```ts
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'country',
+    type: 'select',
+    label: 'Country',
+    options: {
+      defaultValues: [
+        { key: 'us', value: 'United States' },
+        { key: 'uk', value: 'United Kingdom' },
+        { key: 'ca', value: 'Canada' },
+      ],
+      valueProp: 'key',
+      labelProp: 'value',
+    },
+  },
+];
+```
+
+### Dynamic Options from API
+
+```ts
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'department',
+    type: 'select',
+    label: 'Department',
+    options: {
+      url: '/api/departments',
+      apiName: 'MyApi',
+      valueProp: 'id',
+      labelProp: 'name',
+    },
+  },
+];
+```
+
+### OptionProps Interface
+
+```ts
+interface OptionProps<T = any> {
+  defaultValues?: T[];           // Static array of options
+  url?: string;                  // API endpoint URL
+  disabled?: (option: T) => boolean; // Function to disable specific options
+  labelProp?: string;            // Property name for label
+  valueProp?: string;            // Property name for value
+  apiName?: string;              // API name for RestService
+}
+```
+
+## Conditional Logic
+
+The Dynamic Form Module supports conditional logic to show/hide or enable/disable fields based on other field values:
+
+```ts
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'hasLicense',
+    type: 'checkbox',
+    label: 'Do you have a driver\'s license?',
+    order: 1,
+  },
+  {
+    key: 'licenseNumber',
+    type: 'text',
+    label: 'License Number',
+    placeholder: 'Enter your license number',
+    order: 2,
+    conditionalLogic: [
+      {
+        dependsOn: 'hasLicense',
+        condition: 'equals',
+        value: true,
+        action: 'show',
+      },
+    ],
+  },
+  {
+    key: 'age',
+    type: 'number',
+    label: 'Age',
+    order: 3,
+  },
+  {
+    key: 'parentConsent',
+    type: 'checkbox',
+    label: 'Parent Consent Required',
+    order: 4,
+    conditionalLogic: [
+      {
+        dependsOn: 'age',
+        condition: 'lessThan',
+        value: 18,
+        action: 'show',
+      },
+    ],
+  },
+];
+```
+
+### Conditional Rule Interface
+
+```ts
+interface ConditionalRule {
+  dependsOn: string;    // Key of the field to watch
+  condition: string;    // Condition type
+  value: any;          // Value to compare against
+  action: string;      // Action to perform
+}
+```
+
+### Available Conditions
+
+- `equals` - Field value equals the specified value
+- `notEquals` - Field value does not equal the specified value
+- `contains` - Field value contains the specified value (for strings/arrays)
+- `greaterThan` - Field value is greater than the specified value (for numbers)
+- `lessThan` - Field value is less than the specified value (for numbers)
+
+### Available Actions
+
+- `show` - Show the field when condition is met
+- `hide` - Hide the field when condition is met
+- `enable` - Enable the field when condition is met
+- `disable` - Disable the field when condition is met
+
+## Grid Layout
+
+You can use the `gridSize` property to control the Bootstrap grid layout:
+
+```ts
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'firstName',
+    type: 'text',
+    label: 'First Name',
+    gridSize: 6, // Half width
+    order: 1,
+  },
+  {
+    key: 'lastName',
+    type: 'text',
+    label: 'Last Name',
+    gridSize: 6, // Half width
+    order: 2,
+  },
+  {
+    key: 'address',
+    type: 'textarea',
+    label: 'Address',
+    gridSize: 12, // Full width
+    order: 3,
+  },
+];
+```
+
+The `gridSize` property uses Bootstrap's 12-column grid system. If not specified, it defaults to 12 (full width).
+
+## Custom Components
+
+You can use custom components for specific fields by providing a component that implements `ControlValueAccessor`:
+
+```ts
+// custom-rating.component.ts
+import { Component, forwardRef } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+@Component({
+  selector: 'app-custom-rating',
+  template: `
+    <div class="rating">
+      @for (star of [1,2,3,4,5]; track star) {
+        <span
+          class="star"
+          [class.filled]="star <= value"
+          (click)="setValue(star)">
+          ★
+        </span>
+      }
+    </div>
+  `,
+  styles: [`
+    .star { cursor: pointer; font-size: 24px; color: #ccc; }
+    .star.filled { color: #ffc107; }
+  `],
+  providers: [{
+    provide: NG_VALUE_ACCESSOR,
+    useExisting: forwardRef(() => CustomRatingComponent),
+    multi: true
+  }]
+})
+export class CustomRatingComponent implements ControlValueAccessor {
+  value = 0;
+  onChange: any = () => {};
+  onTouched: any = () => {};
+
+  setValue(rating: number) {
+    this.value = rating;
+    this.onChange(rating);
+    this.onTouched();
+  }
+
+  writeValue(value: any): void {
+    this.value = value || 0;
+  }
+
+  registerOnChange(fn: any): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: any): void {
+    this.onTouched = fn;
+  }
+}
+```
+
+Then use it in your form configuration:
+
+```ts
+import { CustomRatingComponent } from './custom-rating.component';
+
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'rating',
+    type: 'text', // Type is ignored when using custom component
+    label: 'Rating',
+    component: CustomRatingComponent,
+    value: 3,
+  },
+];
+```
+
+## Setting Initial Values
+
+You can set initial values for the form fields in two ways:
+
+### 1. Using the `value` property in FormFieldConfig
+
+```ts
+const formFields: FormFieldConfig[] = [
+  {
+    key: 'firstName',
+    type: 'text',
+    label: 'First Name',
+    value: 'John',
+  },
+];
+```
+
+### 2. Using the `values` input
+
+```ts
+@Component({
+  template: `
+    <abp-dynamic-form
+      [fields]="formFields"
+      [values]="initialValues"
+      (onSubmit)="handleSubmit($event)">
+    </abp-dynamic-form>
+  `,
+})
+export class MyComponent {
+  formFields: FormFieldConfig[] = [
+    {
+      key: 'firstName',
+      type: 'text',
+      label: 'First Name',
+    },
+    {
+      key: 'lastName',
+      type: 'text',
+      label: 'Last Name',
+    },
+  ];
+
+  initialValues = {
+    firstName: 'John',
+    lastName: 'Doe',
+  };
+
+  handleSubmit(formValue: any) {
+    console.log(formValue);
+  }
+}
+```
+
+## Programmatic Form Control
+
+You can access the form instance using the `exportAs` property and template reference variable:
+
+```ts
+@Component({
+  template: `
+    <abp-dynamic-form
+      #myForm="abpDynamicForm"
+      [fields]="formFields"
+      (onSubmit)="handleSubmit($event)">
+    </abp-dynamic-form>
+
+    <button (click)="myForm.resetForm()">Reset Form</button>
+  `,
+})
+export class MyComponent {
+  formFields: FormFieldConfig[] = [
+    // ... field configurations
+  ];
+
+  handleSubmit(formValue: any) {
+    console.log(formValue);
+  }
+}
+```
+
+### Available Methods
+
+- `resetForm()` - Resets the form to its initial state
+- `submit()` - Programmatically submit the form
+
+## Custom Action Buttons
+
+You can customize the action buttons by projecting your own content:
+
+```ts
+@Component({
+  template: `
+    <abp-dynamic-form
+      [fields]="formFields"
+      (onSubmit)="handleSubmit($event)">
+
+      <div actions class="form-actions">
+        <button type="button" class="btn btn-secondary" (click)="handleCancel()">
+          Cancel
+        </button>
+        <button type="submit" class="btn btn-success">
+          Save Changes
+        </button>
+        <button type="button" class="btn btn-info" (click)="handleDraft()">
+          Save as Draft
+        </button>
+      </div>
+    </abp-dynamic-form>
+  `,
+})
+export class MyComponent {
+  formFields: FormFieldConfig[] = [
+    // ... field configurations
+  ];
+
+  handleSubmit(formValue: any) {
+    console.log('Form submitted:', formValue);
+  }
+
+  handleCancel() {
+    console.log('Cancelled');
+  }
+
+  handleDraft() {
+    console.log('Saved as draft');
+  }
+}
+```
+
+## Complete Example
+
+Here's a complete example demonstrating various features:
+
+```ts
+import { Component } from '@angular/core';
+import { DynamicFormComponent } from '@abp/ng.components/dynamic-form';
+import { FormFieldConfig } from '@abp/ng.components/dynamic-form';
+
+@Component({
+  selector: 'app-employee-form',
+  imports: [DynamicFormComponent],
+  template: `
+    <div class="container">
+      <h2>Employee Registration</h2>
+      <abp-dynamic-form
+        #employeeForm="abpDynamicForm"
+        [fields]="formFields"
+        [submitButtonText]="'Register Employee'"
+        [showCancelButton]="true"
+        [submitInProgress]="isSubmitting"
+        (onSubmit)="handleSubmit($event)"
+        (formCancel)="handleCancel()">
+      </abp-dynamic-form>
+    </div>
+  `,
+})
+export class EmployeeFormComponent {
+  isSubmitting = false;
+
+  formFields: FormFieldConfig[] = [
+    // Personal Information
+    {
+      key: 'firstName',
+      type: 'text',
+      label: 'First Name',
+      placeholder: 'Enter first name',
+      required: true,
+      gridSize: 6,
+      order: 1,
+      validators: [
+        { type: 'required', message: 'First name is required' },
+        { type: 'minLength', value: 2, message: 'First name must be at least 2 characters' },
+      ],
+    },
+    {
+      key: 'lastName',
+      type: 'text',
+      label: 'Last Name',
+      placeholder: 'Enter last name',
+      required: true,
+      gridSize: 6,
+      order: 2,
+      validators: [
+        { type: 'required', message: 'Last name is required' },
+        { type: 'minLength', value: 2, message: 'Last name must be at least 2 characters' },
+      ],
+    },
+    {
+      key: 'email',
+      type: 'email',
+      label: 'Email',
+      placeholder: 'Enter email address',
+      required: true,
+      gridSize: 6,
+      order: 3,
+      validators: [
+        { type: 'required', message: 'Email is required' },
+        { type: 'email', message: 'Please enter a valid email address' },
+      ],
+    },
+    {
+      key: 'phoneNumber',
+      type: 'text',
+      label: 'Phone Number',
+      placeholder: 'Enter phone number',
+      gridSize: 6,
+      order: 4,
+    },
+
+    // Employment Details
+    {
+      key: 'department',
+      type: 'select',
+      label: 'Department',
+      required: true,
+      gridSize: 6,
+      order: 5,
+      options: {
+        defaultValues: [
+          { id: 1, name: 'Engineering' },
+          { id: 2, name: 'Marketing' },
+          { id: 3, name: 'Sales' },
+          { id: 4, name: 'Human Resources' },
+        ],
+        valueProp: 'id',
+        labelProp: 'name',
+      },
+      validators: [
+        { type: 'required', message: 'Department is required' },
+      ],
+    },
+    {
+      key: 'position',
+      type: 'text',
+      label: 'Position',
+      placeholder: 'Enter position',
+      required: true,
+      gridSize: 6,
+      order: 6,
+      validators: [
+        { type: 'required', message: 'Position is required' },
+      ],
+    },
+    {
+      key: 'startDate',
+      type: 'date',
+      label: 'Start Date',
+      required: true,
+      gridSize: 6,
+      order: 7,
+      validators: [
+        { type: 'required', message: 'Start date is required' },
+      ],
+    },
+
+    // Conditional Fields
+    {
+      key: 'isManager',
+      type: 'checkbox',
+      label: 'Is this person a manager?',
+      gridSize: 12,
+      order: 8,
+    },
+    {
+      key: 'teamSize',
+      type: 'number',
+      label: 'Team Size',
+      placeholder: 'Number of team members',
+      gridSize: 6,
+      order: 9,
+      conditionalLogic: [
+        {
+          dependsOn: 'isManager',
+          condition: 'equals',
+          value: true,
+          action: 'show',
+        },
+      ],
+      validators: [
+        { type: 'min', value: 1, message: 'Team size must be at least 1' },
+      ],
+    },
+    {
+      key: 'managementExperience',
+      type: 'textarea',
+      label: 'Management Experience',
+      placeholder: 'Describe your management experience',
+      gridSize: 12,
+      order: 10,
+      conditionalLogic: [
+        {
+          dependsOn: 'isManager',
+          condition: 'equals',
+          value: true,
+          action: 'show',
+        },
+      ],
+    },
+
+    // Additional Information
+    {
+      key: 'notes',
+      type: 'textarea',
+      label: 'Additional Notes',
+      placeholder: 'Any additional information',
+      gridSize: 12,
+      order: 11,
+    },
+  ];
+
+  handleSubmit(formValue: any) {
+    this.isSubmitting = true;
+
+    console.log('Employee Data:', formValue);
+
+    // Simulate API call
+    setTimeout(() => {
+      this.isSubmitting = false;
+      alert('Employee registered successfully!');
+    }, 2000);
+  }
+
+  handleCancel() {
+    if (confirm('Are you sure you want to cancel?')) {
+      // Navigate back or reset form
+      console.log('Form cancelled');
+    }
+  }
+}
+```
+
+## API Reference
+
+### DynamicFormComponent
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dynamicForm` | `FormGroup` | The underlying Angular FormGroup instance |
+| `fieldVisibility` | `{ [key: string]: boolean }` | Object tracking field visibility state |
+
+#### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `submit()` | - | `void` | Submits the form if valid |
+| `onCancel()` | - | `void` | Emits the formCancel event |
+| `resetForm()` | - | `void` | Resets the form to initial values |
+| `isFieldVisible(field)` | `FormFieldConfig` | `boolean` | Checks if a field is currently visible |
+
+### DynamicFormService
+
+The `DynamicFormService` provides utility methods for form management:
+
+#### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `createFormGroup(fields)` | `FormFieldConfig[]` | `FormGroup` | Creates a FormGroup from field configurations |
+| `getInitialValues(fields)` | `FormFieldConfig[]` | `any` | Extracts initial values from field configurations |
+| `getOptions(url, apiName?)` | `string, string?` | `Observable<any[]>` | Fetches options from an API endpoint |
+
+## See Also
+
+- [Form Validation](./form-validation.md)
+- [Form Input Component](./form-input-component.md)
+- [Dynamic Form Extensions](./dynamic-form-extensions.md)