Nitrogen Pumpkin Mulch

    angular-input-modified

    2.4.2 • Public • Published

    Angular Input Modified

    angular-input-modified

    Bower version npm version

    This Angular module adds additional properties and methods to the ngModel and ngForm controllers, as well as CSS classes to the underlying form elements to provide end-user with facilities to detect and indicate changes in form data.

    This extra functionality allows you to provide better usability with forms. For example, you can add decorations to the form elements that are actually changed. That way, user will see what values has changed since last edit.

    Also, you can reset an entire form or just a single field to it's initial state (cancel all user edits) with just a single call to the reset() method or lock new values (preserve new state) just by calling overloaded $setPristine() method.

    Demos and examples

    Please see the demos hosted on our GitHub Pages or open them locally.

    Also, feel free to play with our Plunk!

    Decorations and animation

    This module adds ng-modified and ng-not-modified CSS classes (names are customizable) to the input fields to indicate their state. Use them in your CSS to decorate input fields. You can combine multiple classes in the same selector. For example, use this convenient CSS selector to decorate modified elements as valid:

    /** Decorating only modified inputs as valid */
    input.ng-valid.ng-modified {
        border-color: green;
    }

    This way end user will see what elements were actually changed.

    This module also supports animations if ngAnimate module is available.

    Installation

    Install library with yarn

    yarn add -D angular-input-modified

    Install library with npm

    npm i -D angular-input-modified

    Add library to your page

    <script src="/node_modules/angular-input-modified/dist/angular-input-modified.js"></script>

    You should use minified version (angular-input-modified.min.js) in production.

    Add dependency in your application's module definition

    var application = angular.module('application', [
      // ...
      'ngInputModified'
    ]);

    Usage

    Please see our demos and examples as well as API documentation.

    Form initialization

    Starting from version 2.0.0 form must be synchronously initialized during controller execution. If you need some data to be fetched prior to form initialization — the best approach is to resolve this data using your router.

    However, if you really need to re-initialize form after controller execution — please use the approach shown in this demo: Delayed Initialization.

    Excluding some fields

    Input modified module provides you with the ability to control which input elements will exhibit modifiable behavior and which will not.

    By default all form fields in your application will support modifiable behavior, after input modified module is added to the application. You can control this via enableGlobally() and disableGlobally() methods of the inputModifiedConfigProvider. This gives you the overall top-level switch to control modifiable behavior.

    Also, we provide you with special directive called bsModifiable that allows you to control which fields will support the behavior. It gives you are more granular control over your forms. This directive works in a recursive manner and can be applied to any HTML element. For example, you can apply it to an entire form: <form name="myForm" bs-modifiable="true"> in order to enable modifiable behavior on all it's fields.

    bs-modifiable attribute can be set to true or to false, depending on what you are trying to achieve.

    You can exercise the exclusion policy by excluding only specific fields or you can exercise the inclusion policy by disabling the behavior globally and then adding modifiable behavior only to the required forms or form fields. It's all up to you!

    Please see the special demo.

    Listening for form changes

    When a form is modified, it fires the inputModified.formChanged event. Parent scopes can listen to this event. Modification flag and reference to the form controller are passed to event listener. Following is an example of parent scope listening to this event.

    /**
     * @param {object}  event 
     * @param {boolean} modified 
     * @param {object}  formCtrl 
     */
    $scope.$on('inputModified.formChanged', function (event, modified, formCtrl) {
      // Process the modified event,
      // use formCtrl.$name to get the form name.
    });

    API

    inputModifiedConfigProvider

    Use this provider to configure behavior of this module. Every setter of this provider supports methods chaining. See example:

    angular.module('Application', ['ngInputModified'])
      .config(function(inputModifiedConfigProvider) {
        inputModifiedConfigProvider
          .disableGlobally()
          .setModifiedClassName('my-changed')
          .setNotModifiedClassName('my-clear')
        ;
      })
    ;
    Method Description
    enableGlobally() Enables modifiable behavior globally for all form elements (this is default)
    disableGlobally() Disables modifiable behavior globally for all form elements
    setModifiedClassName({string} className) Provides CSS class name that will be added to modified elements. ng-modified is the default one
    setNotModifiedClassName({string} className) Provides CSS class name that will be added to unmodified elements. ng-not-modified is the default one

    ngModel

    Property Type Description
    masterValue mixed Initial value of the form field
    modified boolean Flag that indicates whether the form field was modified
    Method Description
    reset() Resets input value to it's initial state
    $setPristine() Makes form field pristine by preserving current value as a new master value

    ngForm

    Property Type Description
    modified boolean Flag that indicates whether the form is modified
    modifiedCount integer The number of modified form fields
    modifiedModels array The list of modified model controllers
    modifiedChildFormsCount integer The number of modified child forms
    modifiedChildForms array The list of modified child form controllers
    Method Description
    reset() Resets all input fields of the form to their initial states
    $setPristine() Makes form pristine by making all child forms and form fields pristine
    Event Listener Attributes Description
    inputModified.formChanged event, modified, formCtrl Fired up through the scope chain when form is changed

    bsModifiable

    This directive can be applied to any element on the page. All descendant form fields (recursively) will respect it.

    Attribute Type Description
    bs-modifiable string Either "true" or "false", see "excluding some fields" chapter

    Changelog

    Please see the complete changelog for list of changes.

    Feedback

    If you have found a bug or have another issue with the library — please create an issue.

    If you have a question regarding the library or it's integration with your project — consider asking a question at StackOverflow and sending me a link via E-Mail. I will be glad to help.

    Have any ideas or propositions? Feel free to contact me by E-Mail.

    Cheers!

    FAQ

    How do I access demos locally?

    Node.js must be installed in your OS.

    • clone the repo
    • npm i && bower install to initialize the project
    • install Gulp by running npm i -g gulp
    • run gulp demo in the repo's root directory
    • open http://localhost:8888/

    Developer guide

    Fork, clone, create a feature branch, commit, create a PR.

    Run:

    • yarn install && bower install to initialize the project
    • gulp build to re-build the dist files
    • gulp demo to run local webserver with demos on port 8888
    • gulp demo-deploy to deploy GitHub Pages

    Do not add dist files to the PR itself. We will re-compile the module manually each time before releasing.

    Support

    If you like this library consider to add star on GitHub repository.

    Thank you!

    License

    The MIT License (MIT)

    Copyright (c) 2014 - 2017 Slava Fomin II, BETTER SOLUTIONS

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Install

    npm i angular-input-modified

    DownloadsWeekly Downloads

    678

    Version

    2.4.2

    License

    MIT

    Last publish

    Collaborators

    • sfomin