angular-dynamic-forms-lite/README.md

Efficient dynamic and customizable Angular 7+ forms.

![Angular Dynamic Forms Lite](https://raw.githubusercontent.com/tom-schoener/angular-dynamic-forms-lite/master/github/assets/logo.png)

# 📃 Angular Dynamic Forms Lite (Pre-Alpha)

[![Build Status](https://travis-ci.org/tom-schoener/angular-dynamic-forms-lite.svg?branch=master)](https://travis-ci.org/tom-schoener/angular-dynamic-forms-lite)
[![npm version](https://badge.fury.io/js/angular-dynamic-forms-lite.svg)](https://badge.fury.io/js/angular-dynamic-forms-lite)

## ⚠⚠⚠ Pre-Alpha notice ⚠⚠⚠

Versions in the range 0.0.0 - 0.0.x are pre-alpha releases, mainly for internal testing and project setup. Currenlty it should not be used for any projects as the api will differ heavily between pre-alpha versions. Better documentation will follow soon.

## What is this about?

Creating dynamic forms in Angular is a basic requirement for many applications. This library simplifies dynamic forms tremendously, so you can focus on the layout and model of your form. It is basically a thin orchestration layer on top of your form model. Use your own form components or an external library like Angular Material – that’s up to you.

## Installation

```sh
npm install --save angular-dynamic-forms-lite
```

## How it works

This example uses the inline form definition model. For an advanced usecase see the [Github Wiki page](https://github.com/tom-schoener/angular-dynamic-forms-lite/wiki).

### Setup

Try it out: [Code Sandbox](https://codesandbox.io/s/qz44o0nzqj)

#### Add the module to your app module

We will use the concept of default components here. This is not required, but it is easier to start with. Add the module to your app module like so:

```ts
// library imports
import { DynamicFormsLiteModule } from "angular-dynamic-forms-lite";

@NgModule({
  imports: [BrowserModule, ReactiveFormsModule, DynamicFormsLiteModule.withDefaultComponents()]
})
export class AppModule {}
```

### Creating the model and form field settings

```ts
// library imports
import {
  FormFieldGroupComponent,
  DynamicFormsLiteService,
  FormRootDirective,
  DynamicFormType,
  FormContext
} from "angular-dynamic-forms-lite";

@Component({
  selector: "app-form",
  template: `
    <form-root></form-root>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormComponent implements OnInit, AfterViewInit, FormFieldGroupComponent {
  @ViewChild(FormRootDirective)
  public formRoot: FormRootDirective;

  private formContext: FormContext<any, FormGroup>;

  constructor(private dynamicFormsService: DynamicFormsLiteService) {}

  ngOnInit() {
    this.formContext = this.dynamicFormsService.createInline({
      name: [
        "Name",
        {
          first: ["First name", DynamicFormType.STRING],
          last: ["Last name", DynamicFormType.STRING]
        }
      ],
      hobbies: ["Hobbies", ["Hobby", DynamicFormType.STRING]]
    });
  }

  ngAfterViewInit() {
    // render the form at the predefined spot
    this.dynamicFormsService.render(this.formRoot, this.formContext);

    // log all form changes
    this.formContext.formControl.valueChanges.subscribe(form => console.log(form));
  }
}
```

### Custom form fields

#### Basic form control

```ts
// library imports
import { FormFieldComponent, FIELD_FORM_CONTROL } from "angular-dynamic-forms-lite";

@Component({
  selector: "app-text-field",
  template: `
    <input [formControl]="formControl" />
    <p>is valid: {{ formControl.valid }}</p>
  `
})
export class TextFieldComponent implements OnInit, FormFieldComponent {
  constructor(@Inject(FIELD_FORM_CONTROL) public formControl: FormControl) {}
}
```

#### Array form

```ts
// library imports
import {
  FormFieldArrayComponent,
  FormRootDirective,
  FIELD_DYNAMIC_CONTROLLER,
  DynamicArrayController
} from "angular-dynamic-forms-lite";

@Component({
  selector: "app-array",
  template: `
    <div class="border">
      <form-root></form-root>
    </div>
    <button (click)="addField()">Add Hobby</button>
  `,
  styles: [
    `
      .border {
        border: 2px solid grey;
        margin: 5px;
        padding: 5px;
      }
    `
  ]
})
export class ArrayComponent implements FormFieldArrayComponent {
  @ViewChild(FormRootDirective)
  public formRoot: FormRootDirective;

  constructor(
    @Inject(FIELD_DYNAMIC_CONTROLLER)
    public dynamicController: DynamicArrayController
  ) {}

  addField() {
    this.dynamicController.push("");
  }
}
```

#### Group form

```ts
// library imports
import { FormFieldGroupComponent, FormRootDirective } from "angular-dynamic-forms-lite";

@Component({
  selector: "app-group",
  template: `
    <div class="border"><form-root></form-root></div>
  `,
  styles: [
    `
      .border {
        border: 2px solid grey;
        margin: 5px;
        padding: 5px;
      }
    `
  ]
})
export class GroupComponent implements FormFieldGroupComponent {
  @ViewChild(FormRootDirective)
  public formRoot: FormRootDirective;

  constructor() {}
}
```

## For library maintainers

### Building the library

```sh
npm install
npm run build
```

The build artifacts will be stored in the `dist/` directory.

### Referencing a local build

Add this script to your package.json file and change the <...> parts accordingly.

```sh
cd <path-to-lib> && npm run build:pack && cd <path-to-app> && npm install <path-to-lib>/dist/angular-dynamic-forms-lite-<version>.tgz"
```

### Running unit tests

```sh
npm test
```

Executes the unit tests via [Karma](https://karma-runner.github.io).

### Version Release

```sh
npm version patch
```