What is ng-checkbox?

A checkbox Angular directive provides user selected data and its statistics. Any contributions are welcomed!

Demo

Installation

npm install --save ng-checkbox

Include the file in your html

<script src="node_modules/ng-checkbox/dist/ngCheckbox.js"></script>

Add ngCheckbox to your module's dependencies

angular.module('MyApp', ['ngCheckbox']);

Sample Usage

Inject the ngCheckboxStatistics factory into your controllers. Add callback(s) to ngCheckboxStatistics

angular.module('MyApp')
.controller('myController', function($scope, ngCheckboxStatistics) {
    var onCheckboxClick = function(stats){
        console.log('Stats object contain all the information everytime you select/unselect a checkbox: ',stats);
    }
    ngCheckboxStatistics.addListener(onCheckboxClick);
});

Use it in your templates, there are many variations depending on your needs (also check the Documentation, and Demo, when use right, it can be powerful), here is one small workable simple example:

        <ng-checkbox groups="['luxury','fast']" count="2" sum="200000" unit="USD">Car A</ng-checkbox>
        <ng-checkbox groups="['cheap','fast']" count="2" sum="200" unit="USD">Car B</ng-checkbox>
  ...

By default, if ng-model attribute is not defined, checkbox will have a value of true (the checkbox is checked). When the controller is first instantiated, onCheckboxClick will be invoked by ngCheckboxStatistics, and stats object will have a value as following:

{
    count: 4 // total count. if unset, default count is 1
    groups: {
        cheap:{
            count:2
            sumByUnits: [
                {
                    sum:400,
                    unit:'USD'
                }
            ]
        },
        fast:{
            count:4
            sumByUnits: [
                {
                    sum:400400,
                    unit:'USD'
                }
            ]
        },
        luxury:{
            count:2
            sumByUnits: [
                {
                    sum:400000,
                    unit:'USD'
                }
            ]
        },
    },
    selectedId: undefined,
    selectedIds: ['ngCb_luxury_fast_19','ngCb_cheap_fast_20'] // selected checkbox ids. The ids are autogenerated if id attribute is not defined
    sumByUnits: [
        {
            sum:400400,
            unit:'USD'
        }
    ],
    superGroup: "default", // 'default' if super-group attribute is not set
    unselectedId: undefined
}

If however you decided to later have a superGroup for each checkbox, e.g something like this:

        <ng-checkbox super-group='Car' groups="['luxury','fast']" count="2" sum="200000" unit="USD">Car A</ng-checkbox>
        <ng-checkbox super-group='Car' groups="['cheap','fast']" count="2" sum="200" unit="USD">Car B</ng-checkbox>
        
        <ng-checkbox super-group='Bike' groups="['luxury','fast']" count="2" sum="1000" unit="USD">Bike A</ng-checkbox>
        <ng-checkbox super-group='Bike' groups="['cheap','fast']" count="2" sum="10" unit="USD">Bike B</ng-checkbox>
  ...

Then you have to add listeners for each superGroup to be able to receive the statistics back (see more documentation for ngCheckboxStatistics.addListener)

ngCheckboxStatistics.addListener(onCheckboxClick, null,'Car'); // This will only be invoked whenever the user clicks on 'Car' checkbox(es)
ngCheckboxStatistics.addListener(this.onCheckboxClick2, this, 'Bike'); // if you pass in this.onCheckboxClick2 instead of just onCheckboxClick2, you must pass in the 'this' context object in the second parameter as well

Documentation

ng-checkbox directive attributes (All are optional)

• id (string, default: autogenerated id) - unique id for checkbox. Shown in 'selectedId' if checkbox is selected and 'unselectedId' if checkbox is unselected.
• super-group (string, default: 'defaut') - super-group that a checkbox belongs to
• groups (array, default: []) - group(s) that a checkbox belongs to
• head (boolean, default: false) - if checkbox has a head="true" then whenever it is clicked, other checkboxes under the same group(s) will have the same value with it
• ngModel (boolean, default: true) - value of checkbox. True if checkbox is checked and vice versa.
• sum (array/number, default: []) - checkbox sum value (the final sum, however, will be count*sum)
• count (number, default: 1) - checkbox count value
• unit (string, default: '') - unit for checkbox sum value

ngCheckboxStatistics

• ngCheckboxStatistics.addListener(callback,[thisArg,superGroupName]) - add a callback to listen to checkboxes selection in a super-group. So if you ngCheckboxStatistics.addListener(myCallback,null,"mySuperGroup"), myCallback will be invoked whenever a checkbox with super-group="mySuperGroup" is selected/unselected.

callback _(function) thisArg _(object,optional,default: null) _ callback will use thisArg as a reference for its context superGroupName _(string,optional,default: 'default')

• ngCheckboxStatistics.reset() - reset all checkboxes' states but not the callbacks which has been added by addListener.

• ngCheckboxStatistics.resetHard() - reset all checkboxes' states,and callbacks which has been added by addListener, usually called in controller 's $destroy event.

Want to contribute?

Anyone can help make this project better, fork it, do your changes and make a pull request! Also, see TODO file for some of my notes on what could be improved.