ngrx-forms

ngrx-forms

Proper integration of forms in Angular applications using ngrx.

Disclaimer: This library is not affiliated with the official ngrx library. I have created it mainly for my own use in one of my projects, but I thought others could profit as well.

Content

1 Overview
2 Installation
3 Design Principles
4 Open Points
5 Contributing

1 Overview

ngrx-forms brings the strengths of the redux state management model to the world of forms in applications that are using Angular and ngrx. The mechanisms that Angular provides for working with forms are inherently mutable, local, and hard to debug. This library offers a different model for working with forms. Instead of storing the state of form controls inside the components we put them in the ngrx store. We update the state with actions which allows easy debugging just like any other redux application. ngrx-forms also provides powerful mechanisms to update, validate and generally manage large complex forms. It contains APIs for synchronous and asynchronous validation, creating dynamic forms, integrating with custom form elements, and much more.

To get to know more you can either read the detailed user guide or visit the example application.

2 Installation

npm install ngrx-forms --save

This library has a peer dependency on versions >=4.0.0 of @angular/core, @angular/common, @angular/forms, @angular/platform-browser, and @ngrx/store.

3 Design Principles

This library is written to be as functional and as pure as possible. Most of the heavy lifting is done in pure reducer functions with the directives being only a thin layer to connect the form states to the DOM.

This library also tries to be as independent as possible from other libraries/modules. While there is of course a dependency on ngrx the touching points are small and it should be possible to adapt this library to any other redux library without too much effort. There is also a peer dependency on @angular/forms from which we re-use the ControlValueAccessor concept to allow easier integration with other libraries that provide custom form controls.

Conceptually this library borrows heavily from @angular/forms, specifically the concepts of form controls and form groups (see the User Guide for a more detailed description of these concepts).

4 Open Points

• add README section about Actions
• providing some global configuration options (e.g. enabling focus tracking globally)
• add isSomeChildFocused to groups to track whether any child is focused
• some more tests for directives
• tests for example application

5 Contributing

Any pull requests are welcome. If you want to work on this library locally you can use the commands shown below.

Testing

The following command runs all unit tests:

npm test

Building and Packaging

The following command:

npm run build

• starts TSLint with Codelyzer
• starts AoT compilation using ngc compiler
• creates dist folder with all the files of distribution

To test the npm package locally run:

npm run pack-lib

and install it in an app to test it with:

npm install [path]ngrx-forms-[version].tgz

License

MIT

Copyright © 2017 Jonathan Ziller

Changelog

2.0.0

Features

• add support for arrays of form controls (19d4e49)
• add support for asynchronous validation (see the documentation for more details) (f208e61)
• add value converter for object to JSON conversion (2ba37ee) (thanks @tbroadley)
• add support for error composition by extending validate update function to take a single validation function or an array of validation functions (ba976c5)
• add setErrors update function (ee25ca8)
• add reset update function (d380e67)
• add updateRecursive update function (see the documentation for a usage example) (31f9d5d)
• add common set of validation functions (40308d4)
• add support for user defined properties on form controls and groups (d9778d2)
• introduce concept of FormViewAdapter and rewrite all control value accessors from scratch as view adapters (see the documentation for more details)
• extend example application to contain multiple examples
• added overloads for many update functions that make casting the state unnecessary in certain situations
• added lots of inline comments to the API making it easier to understand what certain functions do right in your IDE

Breaking Changes

• remove support for last keydown code tracking on form controls (this feature has been superseded by user defined properties which allow associating any kind of metadata with a control)
• rename groupUpdateReducer to createFormGroupReducerWithUpdate in order to make it clearer that the function itself is not a reducer
• remove erroneously exposed function createChildState from public API
• change option element value bindings to work correctly for all primitive data types thereby removing the need for ngValue bindings
• trying to set an error with a key prefixed with $ will now throw an error since the $ prefix is used to mark async errors
• applying the ngrxFormControlState directive to a form element will now set the element's id attribute to the ID of the state (thereby overriding any already present id)
• the isDirty property for form controls is now not set automatically the first time the state's value changes, but instead it is set manually from the NgrxFormControlDirective the first time the underlying FormViewAdapter or ControlValueAccessor reports a new value; this means if you were e.g. using the setValue update function in your reducer before this will now not mark the state as dirty anymore
• rename addControl update function to addGroupControl
• rename AddControlAction to AddGroupControlAction (also renaming its type from ngrx/forms/ADD_CONTROL to ngrx/forms/ADD_GROUP_CONTROL)
• rename removeControl update function to removeGroupControl
• rename RemoveControlAction to RemoveGroupControlAction (also renaming its type from ngrx/forms/REMOVE_CONTROL to ngrx/forms/REMOVE_GROUP_CONTROL)

Bugfixes

• fix issue that caused bundled library to be larger than required due to external dependencies being included in the bundle (drastically reducing its size)

<a name="1.1.1"></a>