Reusable Accessible Mapping Platform

API Docs for: 5.0.0
Show:

File: src\js\RAMP\Utils\checkboxGroup.js

  1. /* global define, console, $ */
  2.  
  3. /**
  4. * @module Utils
  5. */
  6.  
  7. /**
  8. * Creates a Checkbox group bound from the supplied JArray of input nodes. Optionally, the group is bound to the supplied master input node
  9. * which acts as a global toggle for the group.
  10. *
  11. *
  12. * @class CheckboxGroup
  13. * @constructor
  14. * @uses dojo/Evented
  15. * @uses dojo/_base/declare
  16. * @uses dojo/_base/lang
  17. * @uses dojo/_base/array
  18. * @uses Checkbox
  19. *
  20. * @param {JArray} nodes a jQuery object representing the checkboxes to be grouped
  21. * @param {Object} [options] Additional options
  22. * @param {String} [options.nodeIdAttr] Name of the "data-*" attribute set on the checkbox node to be treated as the checkbox id. If no appropriate "data-*" attribute found,
  23. * `nodeIdAttr` is used directly, failing that, regular `id` is used.
  24. * @param {Object} [options.cssClass] `active`, `focus`, and `check` CSS class to be applied to the Checkbox correspondingly.
  25. * @param {Object} [options.cssClass.active] CSS class to be set when the Checkbox is `active`.
  26. * @param {Object} [options.cssClass.focus] CSS class to be set when the Checkbox is `focused`.
  27. * @param {Object} [options.cssClass.check] CSS class to be set when the Checkbox is `checked`.
  28. * @param {Object} [options.label] `check` and `uncheck` label texts to be applied to the Checkbox labels.
  29. * @param {Object} [options.label.check] A text to be set as a label when the Checkbox is `checked`
  30. * @param {Object} [options.label.uncheck] A text to be set as a label when the Checkbox is `unchecked`
  31. * @param {Function} [options.onChnage] A function to be called when the state of the Checkbox changes.
  32. * @param {Object} [options.master] Additional options applied to the master Checkbox.
  33. * @param {Object} [options.master.node] An `input` node to serve as the master Checkbox for the group.
  34. * @param {Object} [options.master.cssClass] `active`, `focus`, and `check` CSS class to be applied to the master Checkbox correspondingly.
  35. * @param {Object} [options.master.cssClass.active] CSS class to be set when the Checkbox is `active`.
  36. * @param {Object} [options.master.cssClass.focus] CSS class to be set when the master Checkbox is `focused`.
  37. * @param {Object} [options.master.cssClass.check] CSS class to be set when the master Checkbox is `checked`.
  38. * @param {Object} [options.master.label] `check` and `uncheck` label texts to be applied to the master Checkbox labels.
  39. * @param {Object} [options.master.label.check] A text to be set as a label when the master Checkbox is `checked`
  40. * @param {Object} [options.master.label.uncheck] A text to be set as a label when the master Checkbox is `unchecked`
  41. * @param {Function} [options.master.onChnage] A function to be called when the state of the master Checkbox changes.
  42. *
  43. * @return {CheckboxGroup} A control objects allowing to toggle individual checkboxes in a group as well as the group as a whole.
  44. */
  45.  
  46. define(["dojo/Evented", "dojo/_base/declare", "dojo/_base/lang", "dojo/_base/array",
  47.  
  48.         "utils/checkbox", "utils/array"],
  49.     function (Evented, declare, lang, dojoArray,
  50.             Checkbox, Array) {
  51.         "use strict";
  52.  
  53.         var CheckboxGroup;
  54.  
  55.         CheckboxGroup = declare([Evented], {
  56.             constructor: function (nodes, options) {
  57.                 var that = this,
  58.                     masterCheckboxOptions;
  59.  
  60.                 // declare individual properties inside the constructor: http://dojotoolkit.org/reference-guide/1.9/dojo/_base/declare.html#id6
  61.                 lang.mixin(this,
  62.                     {
  63.                         /**
  64.                          * Nodes of the checkbox nodes originally supplied to the CheckboxGroup.
  65.                          *
  66.                          * @property nodes
  67.                          * @type JArray
  68.                          * @default []
  69.                          */
  70.                         nodes: [],
  71.  
  72.                         /**
  73.                          * Name of the "data-*" attribute set on the checkbox node to be treated as the checkbox id.
  74.                          *
  75.                          * @property nodeIdAttr
  76.                          * @type String
  77.                          * @default "id"
  78.                          */
  79.                         nodeIdAttr: "id",
  80.  
  81.                         /**
  82.                          * An array of the Checkbox object belonging to the body of the group.
  83.                          *
  84.                          * @property nodes
  85.                          * @type Array
  86.                          * @default []
  87.                          */
  88.                         checkboxes: [],
  89.  
  90.                         /**
  91.                          * `active`, `focus`, and `check` CSS class to be applied to the Checkbox correspondingly.
  92.                          *
  93.                          * @property cssClass
  94.                          * @type {Object}
  95.                          * @default
  96.                          * @example
  97.                          *      cssClass: {
  98.                          *          active: "active",
  99.                          *          focus: "focused",
  100.                          *          check: "checked"
  101.                          *      }
  102.                          */
  103.                         cssClass: {
  104.                             active: "active",
  105.                             focus: "focused",
  106.                             check: "checked"
  107.                         },
  108.  
  109.                         /**
  110.                          * `check` and `uncheck` label texts to be applied to the Checkbox labels.
  111.                          *
  112.                          * @property label
  113.                          * @type {Object}
  114.                          * @default
  115.                          * @example
  116.                          *      label: {
  117.                          *          check: "check",
  118.                          *          uncheck: "unchecked"
  119.                          *      }
  120.                          */
  121.                         label: {
  122.                             check: "checked",
  123.                             uncheck: "unchecked"
  124.                         },
  125.  
  126.                         /**
  127.                          * A function to be called when the state of the Checkbox changes.
  128.                          *
  129.                          * @property onChnage
  130.                          * @type Function
  131.                          * @default
  132.                          * @example     function () { }
  133.                          */
  134.                         onChange: function () { },
  135.  
  136.                         /**
  137.                          * Options for the master Checkbox.
  138.                          *
  139.                          * @property master
  140.                          * @type Object
  141.                          * @default
  142.                          * @example
  143.                          *      master: {
  144.                          *          node: null,
  145.                          *          checkbox: null,
  146.                          *          nodeIdAttr: null,
  147.                          *
  148.                          *          cssClass: {
  149.                          *              active: "active",
  150.                          *              focus: "focused",
  151.                          *              check: "checked"
  152.                          *          },
  153.                          *
  154.                          *          label: {
  155.                          *              check: "checked",
  156.                          *              uncheck: "unchecked"
  157.                          *          },
  158.                          *
  159.                          *          onChange: function () { }
  160.                          *      }
  161.                          *
  162.                          */
  163.                         master: {
  164.                             node: null,
  165.                             checkbox: null,
  166.                             nodeIdAttr: null,
  167.  
  168.                             cssClass: {
  169.                                 active: "active",
  170.                                 focus: "focused",
  171.                                 check: "checked"
  172.                             },
  173.                             label: {
  174.                                 check: "checked",
  175.                                 uncheck: "unchecked"
  176.                             },
  177.  
  178.                             onChange: function () { }
  179.                         }
  180.                     },
  181.                     options,
  182.                     {
  183.                         nodes: nodes
  184.                     }
  185.                 );
  186.                 
  187.                 masterCheckboxOptions = {
  188.                     nodeIdAttr: this.nodeIdAttr,
  189.                     cssClass: this.cssClass,
  190.                     label: this.label,
  191.                     onChange: this.onChange
  192.                 };
  193.                 
  194.                 if (this.master.node) {
  195.                     this.master.checkbox = new Checkbox(
  196.                         this.master.node,
  197.                         lang.mixin(masterCheckboxOptions, this.master)
  198.                     );
  199.  
  200.                     this.master.checkbox.on(Checkbox.event.TOGGLE, function (evt) {
  201.                         // re-emit individual checkbox's toggle event as groups;
  202.                         console.log("CheckboxGroup Master ->", evt.checkbox.id, "set by", evt.agency, "to", evt.checkbox.state);
  203.  
  204.                         that.emit(CheckboxGroup.event.MASTER_TOGGLE, evt);
  205.  
  206.                         if (evt.agency === Checkbox.agency.USER) {
  207.                             that.setState(evt.checkbox.state);
  208.                         }
  209.                     });
  210.                 } else {
  211.                     this.master = null;
  212.                 }
  213.  
  214.                 this.addCheckbox(this.nodes);
  215.             },
  216.  
  217.             addCheckbox: function (nodes) {
  218.                 var that = this,
  219.                     checkbox,
  220.                     checkboxOptions = {
  221.                         nodeIdAttr: this.nodeIdAttr,
  222.                         cssClass: this.cssClass,
  223.                         label: this.label,
  224.                         onChange: this.onChange
  225.                     },
  226.                     cbIndex;
  227.  
  228.                 // Create individual Checkboxes
  229.                 nodes.each(function (index, node) {
  230.                     node = $(node);
  231.  
  232.                     cbIndex = Array.indexOf(that.checkboxes, function (cb) {
  233.                         return cb.node.is(node);
  234.                     });
  235.  
  236.                     if (cbIndex === -1) {
  237.  
  238.                         checkbox = new Checkbox(node, checkboxOptions);
  239.                         that.checkboxes.push(checkbox);
  240.  
  241.                         checkbox.on(Checkbox.event.TOGGLE, function (evt) {
  242.                             // re-emit individual checkbox's toggle event as groups;
  243.                             //console.log("CheckboxGroup ->", evt.checkbox.id, "set by", evt.agency, "to", evt.checkbox.state);
  244.  
  245.                             that.emit(CheckboxGroup.event.MEMBER_TOGGLE, evt);
  246.  
  247.                             if (evt.agency === Checkbox.agency.USER) {
  248.                                 that._checkMaster();
  249.                             }
  250.                         });
  251.                     } else {
  252.                         // reset the checkbox, just in case
  253.                         that.checkboxes[cbIndex].reset();
  254.                     }
  255.                 });
  256.  
  257.                 this._checkMaster();
  258.             },
  259.  
  260.             /**
  261.              * Synchronizes the state of the master Checkbox with the state of the group.
  262.              * All group members checked -> master checked
  263.              * Any of the group members unchecked -> master unchecked
  264.              *
  265.              * @method _checkMaster
  266.              * @private
  267.              */
  268.             _checkMaster: function () {
  269.                 var allChecked;
  270.  
  271.                 allChecked = dojoArray.every(this.checkboxes, function (checkbox) {
  272.                     // "INVALID" state is parsed as "true" so it's counted in, but is ignored otherwise
  273.                     return checkbox
  274.                             .validate()
  275.                             .state;
  276.                 });
  277.  
  278.                 // set state to the master checkbox only if you have one
  279.                 if (this.master) {
  280.                     this.master.checkbox.setState(allChecked);
  281.                 }
  282.             },
  283.  
  284.             /**
  285.             * Toggles the state of the specified Checkbox. If checkboxId is not supplied, toggles the whole group.
  286.             *
  287.             * @method setState
  288.             * @param {Boolean} state Specifies the state of the checkbox: true, false
  289.             * @param {String} [checkboxId] Specifies the checkbox to toggle.
  290.             * @return CheckboxGroup
  291.             * @chainable
  292.             */
  293.             setState: function (state, checkboxId) {
  294.                 var checkbox,
  295.                     masterCheckboxId = this.master.checkbox ? this.master.checkbox.id : undefined;
  296.  
  297.                 if (!checkboxId || masterCheckboxId === checkboxId) {
  298.                     this.master.checkbox.setState(state);
  299.  
  300.                     this.checkboxes.forEach(function (checkbox) {
  301.                         checkbox.setState(state);
  302.                     });
  303.                 } else {
  304.                     // use for loop because you can't break out of forEach loop
  305.                     for (var i = 0; i < this.checkboxes.length; i++) {
  306.                         checkbox = this.checkboxes[i];
  307.                         if (checkbox.id === checkboxId) {
  308.                             break;
  309.                         }
  310.                     }
  311.  
  312.                     checkbox.setState(state);
  313.  
  314.                     this._checkMaster();
  315.                 }
  316.  
  317.                 return this;
  318.             },
  319.  
  320.             /**
  321.             * Toggle all the checkboxes based on the return value of the given function.
  322.             *
  323.             * @param {Function} fcn a function that takes a checkbox as an argument and returns
  324.             * true if the given checkbox should be toggled on, false if it should be toggled off
  325.             * @method setEachState
  326.             * @chainable
  327.             */
  328.             setEachState: function (fcn) {
  329.                 this.checkboxes.forEach(function (checkbox) {
  330.                     checkbox.setState(fcn(checkbox));
  331.                 });
  332.                 this._checkMaster();
  333.                 return this;
  334.             },
  335.  
  336.             _purgeInvalid: function () {
  337.                 var i,
  338.                     checkbox;
  339.  
  340.                 for (i = this.checkboxes.length - 1; i >= 0; i--) {
  341.                     checkbox = this.checkboxes[i];
  342.                     if (checkbox.state === Checkbox.state.INVALID) {
  343.                         Array.remove(this.checkboxes, i);
  344.                     }
  345.                 }
  346.             }
  347.         });
  348.  
  349.         lang.mixin(CheckboxGroup,
  350.             {
  351.                 /**
  352.                 * Event names published by the Checkbox
  353.                 *
  354.                 * @private
  355.                 * @property event
  356.                 * @type Object
  357.                 * @default null
  358.                 * @example
  359.                 *      {
  360.                 *          MEMBER_TOGGLE: "checkbox/toggled",
  361.                 *          MASTER_TOGGLE: "checkbox/toggled"
  362.                 *      }
  363.                 */
  364.                 event: {
  365.                     /**
  366.                     * This event is not published by CheckboxGroup. __Ignore this.__
  367.                     *
  368.                     * @event TOGGLE
  369.                     * @private
  370.                     */
  371.  
  372.                     /**
  373.                     * Published whenever a Checkbox get toggled.
  374.                     *
  375.                     * @event MEMBER_TOGGLE
  376.                     * @param event {Object}
  377.                     * @param event.checkbox {Checkbox} Checkbox object that has been toggled
  378.                     * @param event.agency {String} Agency that toggled the Checkbox
  379.                     */
  380.                     MEMBER_TOGGLE: "checkbox/member-toggle",
  381.  
  382.                     /**
  383.                     * Published whenever the master Checkbox get toggled.
  384.                     *
  385.                     * @event MASTER_TOGGLE
  386.                     * @param event {Object}
  387.                     * @param event.checkbox {Checkbox} master Checkbox object that has been toggled
  388.                     * @param event.agency {String} Agency that toggled the Checkbox
  389.                     */
  390.                     MASTER_TOGGLE: "checkbox/master-toggle"
  391.                 }
  392.             }
  393.         );
  394.  
  395.         return CheckboxGroup;
  396.     });
  397.