README.md

ng-form-rules

Simple, powerful, and customizable rule engine library for Angular reactive forms.

Table of Contents

• Installation
• Dependencies
• What does ng-form-rules do?
• What does ng-form-rules NOT do?
• Getting Started
• Documentation
• Examples
• License

Installation

npm install ng-form-rules

Dependencies

ℹ️ If you are using Angular 6+ these are installed by default. In other words, you are good to go :)

• @angular/common version ^6.0.0
• @angular/core version ^6.0.0
• tslib version ^1.9.0

What does ng-form-rules do?

• Generate Angular reactive form controls (FormGroup, FormArray, and FormControl) based upon model setting configurations
  • Model settings have a collection of properties that have tests & rules dictating whether they are valid and/or editable
  • Model settings won't clutter your model classes and can be re-used as much as you'd like
• Rules can be as simple or complex as you want; you have full control
  • Rules can react to changes in other properties in the form, whether at the same level, nested, in an array item, or at a parent's level
  • Rules can be synchronous or asynchronous
  • All of the rules in your model settings will automatically be integrated seamlessly into your form
• You are never blocked! The form controls we generate are no different than what you already use in Angular. You can manipulate them, add controls, add validators from outside ng-form-rules, etc.

What does ng-form-rules NOT do?

• Anything to do with styling, display, etc.
• Provide a library of validation methods (e.g. MaxLength, Required, etc.)

Getting Started

⚡ View example in action ⚡

To use ng-form-rules in your app you need to import the FormRulesModule into one of your Angular modules (most likely the main AppModule).

import { FormRulesModule } from 'ng-form-rules';
// other imports...

@NgModule({
  imports: [
    BrowserModule,       // from Angular, but required to use reactive forms
    ReactiveFormsModule, // from Angular, but required to use reactive forms
    FormRulesModule      // HERE is the import from ng-form-rules
  ],
  // other module stuff...
})
export class AppModule { }

Now that Angular knows about ng-form-rules you can use its functionality in your app. For instance, you could create some simple model settings and a form to use in a component.

import { Component, OnInit } from '@angular/core';
import { FormGroup, AbstractControl } from "@angular/forms";
import { ReactiveFormsRuleService, AdhocModelSettings, ModelSettingsBuilder } from 'ng-form-rules';

// model representing form data
interface Person {
  name: string;
}

@Component({
  selector: 'my-app',
  templateUrl: './app.component.html',
  styleUrls: [ './app.component.css' ]
})
export class AppComponent implements OnInit  {
  form: FormGroup;

  // receive an instance of ReactiveFormsRuleService via dependency injection
  constructor(private svc: ReactiveFormsRuleService) {
  }

  ngOnInit(): void {
    // create model settings
    const settings = AdhocModelSettings.create<Person>((builder: ModelSettingsBuilder) => {
      // return an array of properties
      return [
        builder.property('name', prop => { // add a name property to the settings
          prop.valid.push( // add validation to the name property
            builder.validNamedTest( // add a test to the validation with a name, message, and rule
              'name-required-test',
              `Name is required.`,
              builder.rule(person => !!person.name)
            )
          );
        }),
      ];
    });

    // create form group based on the model settings
    this.form = this.svc.createFormGroup(settings);
  }
}

AppComponent receives an instance of ReactiveFormsRuleService in its constructor. ReactiveFormsRuleService is the primary service used from ng-form-rules and it will be your best friend. Within the component's ngOnInit() you use this service to create model settings and then a FormGroup based upon those settings.

The settings are created using the static create() function on AdhocModelSettings. create() receives as a parameter a function that takes an instance of ModelSettingsBuilder and returns an array of properties. ModelSettingsBuilder is a helper class that is used to create properties and their associated validations, tests, rules, etc.

Now you can use the FormGroup in a template.

<form [formGroup]="form">
  <div>
    <label for="name">Name: </label>
    <input type="text" id="name" formControlName="name" />
    <pre *ngIf="form.get('name').errors">{{ form.get('name').errors | json }}</pre>
  </div>
</form>

You did it! You successfully used ng-form-rules on your first form!

This was obviously a simple example and we know the real-world demands on forms are more complex. Please see our docs and examples to learn how you can use ng-form-rules to handle all your scenarios.

Documentation

Examples

Watch our "Let’s Build a Registration Form" video for a great walkthrough of several key features of the library.

We have links to pertinent examples throughout our documentation, or you can just pick from a list of our examples. We use StackBlitz for all our examples, which allows you to fully interact, fork, and edit them.

License