@cisco-msx/forms NPM

@cisco-msx/forms

Form builder classes, renderer, and Angular upgrades for MSX form field components.

Usage

import { NgModule } from '@angular/core';
import { MsxFormsModule } from '@cisco-msx/forms';

@NgModule({
  imports: [
    MsxFormsModule
  ]
})
export class MyModule {}

Testing

If you are testing your component using Angular's TestBed, import the MsxFormsTestingModule in your testing module instead of MsxFormsModule to have @cisco-msx/forms's components and directives mocked.

import {
  async,
  ComponentFixture,
  TestBed
} from '@angular/core/testing';
import { MsxFormsTestingModule } from '@cisco-msx/forms/testing';
import { MyComponent } from './my.component';

describe('MyComponent', () => {
  let component: MyComponent;
  let fixture: ComponentFixture<MyComponent>;

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      imports: [
        MsxFormsTestingModule
      ],
      declarations: [MyComponent]
    });
    fixture = TestBed.createComponent(MyComponent);
    component = fixture.componentInstance;
  }));
});

Form Fields

The upgraded form inputs that can be used are also included in the MsxFormModule. You can find the upgraded components here.

Form Builder/Renderer

This package contains the Form and FormGroup classes that are the basis for being a structure for your form. It also contains the DynamicFormComponent that takes instances of the Form and FormGroup to automatically render and handle the change lifecycle of the fields within them.

Note: If fields are added to a Form and a FormGroup you must render 2 dynamic form components as fields are encapsulated into the instance of where they are added even if all values are available in the top level form

The following is an example of how to use the dynamic forms using a Form and a FormGroup. This example uses Angular 8 but you can build forms (without the dynamic rendering) with any (or no) framework.

@Component({
    selector: 'my-component',
    template: `
    <div>
        <div>
            <h1>Name Information</h1>
            <msx-form [form]="nameForm"></msx-form>
        </div>
        <div>
            <h1>Location Information</h1>
            <!--Without passing the locationFormGroup, the address and postal code fields would never show  -->
            <msx-form [form]="locationFormGroup"></msx-form>
        </div>
    </div>
`
})
class MyComponent {

    nameForm = new Form();
    locationFormGroup = new FormGroup('locationGroup');

    ngOnInit() {
        this.nameForm.setFields([
            {
                name: "firstName",
                initialValue: "",
                properties: {
                    label: "First Name",
                    required: true,
                    placeholder: "Johny"
                }
            },
            {
                name: "lastName",
                initialValue: "",
                properties: {
                    label: "Last Name",
                    required: true,
                    placeholder: "Bravo"
                }
            }
        ]);

        this.locationGroup.setFields([
            {
                name: "address",
                initialValue: "",
                properties: {
                    required: true,
                    label: "Address",
                    placeholder: "123 Somewhere Lane"
                }
            },
            {
                name: "postalCode",
                initialValue: "",
                properties: {
                    label: "Postal Code",
                    required: true,
                    placeholder: "K0F K8A"
                }
            }
        ]);


        this.nameForm.setFormGroup(this.locationGroup);
    }
}

The example above would render a section header Name Information with 2 fields (firstName, lastName) and another section header Location Information with the 2 fields (address and postal code). Note that 2 msx-form components where used, one for the Form and one for the FormGroup. This is because fields are encapsulated where they are added. However, the Form will still know when a field from a child FormGroup changes.