Reusable Accessible Mapping Platform

API Docs for: 3.0.0
Show:

File: src\js\RAMP\Tools\baseTool.js

  1. /* global define, tmpl, i18n, require, console, $ */
  2.  
  3. /**
  4. * @module Tools
  5. */
  6.  
  7. /**
  8. * BaseTool provides essential functionality for Tools including handling of the activate toggle, setting `busy` state, injecting output float into the page,
  9. * and templating the output. It's not required to mixin BaseTool, but it's really helpful; and of course any of the BaseTool methods/properties can be overwritten
  10. * after mixining it in.
  11. *
  12. * Call `initToggle` to initialize the tool.
  13. *
  14. * @class BaseTool
  15. * @static
  16. * @constructor
  17. * @uses dojo/Evented
  18. * @uses dojo/_base/lang
  19. * @uses dojo/Deferred
  20. * @uses dojo/text!./templates/tools_template.json
  21. * @uses GlobalStorage
  22. * @uses TmplHelper
  23. * @uses PopupManager
  24. * @uses Util
  25. */
  26.  
  27. define([
  28. // Dojo
  29.         "dojo/Evented", "dojo/_base/lang", "dojo/Deferred",
  30. // Text
  31.         "dojo/text!./templates/tools_template.json",
  32. // Ramp
  33.         "ramp/globalStorage",
  34. // Utils
  35.         "utils/tmplHelper", "utils/popupManager", "utils/util"
  36. ],
  37.     function (
  38. // Dojo
  39.         Evented, dojoLang, Deferred,
  40. // Text
  41.         tools_template_json,
  42. // Ramp
  43.         GlobalStorage,
  44. // Utils
  45.         TmplHelper, PopupManager, Util
  46.     ) {
  47.         "use strict";
  48.  
  49.         // mixin the Evented functions (on, emit) into the BaseTool
  50.         return dojoLang.mixin(new Evented(),
  51.             {
  52.                 /**
  53.                  * Stored options passed to the BaseTool.
  54.                  *
  55.                  * @property options
  56.                  * @type Object
  57.                  * @default null
  58.                  * @private
  59.                  */
  60.                 options: null,
  61.  
  62.                 /**
  63.                  * Handle (popup handle) that triggers opening/closing of the tool.
  64.                  *
  65.                  * @property handle
  66.                  * @type JObject
  67.                  * @default null
  68.                  *
  69.                  */
  70.                 handle: null,
  71.  
  72.                 /**
  73.                  * Node (button) the handle is attached too.
  74.                  * 
  75.                  * @property node
  76.                  * @type JObject
  77.                  * @default null
  78.                  */
  79.                 node: null,
  80.  
  81.                 /**
  82.                  * Node representing the tool output float container.
  83.                  *
  84.                  * @property outputFloat
  85.                  * @type JObject
  86.                  * @default templates/tools_template.json:base_tool_float
  87.                  * @example
  88.                  *      <div class='advanced-output-section-container'>
  89.                  *          <div class='advanced-output-section'>
  90.                  *              <section class='float-content'></section>
  91.                  *              <button class='button button-none float-default-button' >
  92.                  *                  <i class='fa fa-trash-o'></i><span class='on-right'>{%= o.clearMapButton %}</span>
  93.                  *              </button>
  94.                  *              <div class='clear'></div>
  95.                  *          </div>
  96.                  *      </div>
  97.                  */
  98.                 outputFloat: null,
  99.  
  100.                 /**
  101.                  * Template string representing `working` label shown when the tool is in `busy` state.
  102.                  *
  103.                  * @property workingLabel
  104.                  * @type String
  105.                  * @default templates/tools_template.json:working_label
  106.                  * @example     <span class='tool-tooltip'><i class='fa fa-cog fa-spin'></i>{%= o.workingLabel %}</span>
  107.                  */
  108.                 workingLabel: null,
  109.  
  110.                 /**
  111.                  * Tooltip node that appears by the mouse cursor when tools is activated.
  112.                  *
  113.                  * @property tooltip
  114.                  * @type JObject
  115.                  * @default $("#mainMap.map > .tooltip")
  116.                  *
  117.                  */
  118.                 tooltip: null,
  119.  
  120.                 /**
  121.                  * Stringified and parsed templates
  122.                  *
  123.                  * @property template
  124.                  * @type Object
  125.                  * @default templates/tools_template.json
  126.                  *
  127.                  */
  128.                 templates: null,
  129.  
  130.                 /**
  131.                 * Event names published by the BaseTool
  132.                 *
  133.                 * @property event
  134.                 * @type Object
  135.                 * @default null
  136.                 * @example
  137.                 *      {
  138.                 *          ACTIVATE: "basetool-activate",
  139.                 *          DEACTIVATE: "basetool-deactivate"
  140.                 *      }
  141.                 */
  142.                 event: {
  143.                     /**
  144.                     * Published whenever a Tool is activated.
  145.                     *
  146.                     * @event ACTIVATE
  147.                     * @param event {Object}
  148.                     * @param event.tool {BaseTool} Tool that was activated
  149.                     */
  150.                     ACTIVATE: "basetool-activate",
  151.  
  152.                     /**
  153.                     * Published whenever a Tool is deactivated.
  154.                     *
  155.                     * @event DEACTIVATE
  156.                     * @param event {Object}
  157.                     * @param event.tool {BaseTool} Tool that was deactivated
  158.                     */
  159.                     DEACTIVATE: "basetool-deactivate"
  160.                 },
  161.  
  162.                 ns: "tools/",
  163.  
  164.                 /**
  165.                  * Name of the tool so AdvancedToolbar can distinguish between them.
  166.                  *
  167.                  * @property name
  168.                  * @type String
  169.                  * @default BaseTool
  170.                  */
  171.                 name: "BaseTool",
  172.  
  173.                 /**
  174.                  * Initializes the tool and sets up popup to handle activating/deactivating of the tool. Tools should call this function on `init`,
  175.                  * unless they employ a different workflow and then need to handle all function activation/deactivation/working themselves.
  176.                  *
  177.                  * @method initToggle
  178.                  * @param {JObject} selector a target selector that serves as a toggle for the tool
  179.                  * @param {JObject} d a Deferred object to be resolved after tool initiates
  180.                  * @param {Object} [options] Additional options
  181.                  * @param {JObject} [options.target] Target where the tool's float should be appended to
  182.                  * @param {String} [options.outputFloatTemplate] Template name to generate the float container with
  183.                  * @param {Object} [options.outputFloatData] Data payload to be passed to the template engine when generate the float container
  184.                  * @param {String} [options.workingLabelTemplate] Template name to generate the `busy` label
  185.                  * @param {Object} [options.workingLabelData] Data payload to be passed to the template engine when generate the `busy` label
  186.                  * @param {Function} [options.activate] an activate function to be called when the toggle is clicked
  187.                  * @param {Function} [options.deactivate] a deactivate function to be called when the toggle is clicked
  188.                  * @param {Function} [options.defaultAction] Function to be executed when the `float-default-button` is clicked
  189.                  * @chainable
  190.                  * @return this tool
  191.                  */
  192.                 initToggle: function (selector, d, options) {
  193.                     var that = this,
  194.                         toolTemplate,
  195.                         deferrList = [
  196.                             new Deferred(),
  197.                             new Deferred()
  198.                         ];
  199.  
  200.                     // wait for translation and template to load
  201.                     Util.afterAll(deferrList,
  202.                         function () {
  203.                             tmpl.cache = {};
  204.                             // mixin base tools template with individual tool's template
  205.                             tmpl.templates = that.templates = dojoLang.mixin(
  206.                                 JSON.parse(TmplHelper.stringifyTemplate(tools_template_json)),
  207.                                 JSON.parse(TmplHelper.stringifyTemplate(toolTemplate)));
  208.  
  209.                             // create tool button, outputfloat, and working label
  210.                             this.node = $(tmpl(this.options.toolButtonTemplate, this.options.toolButtonData));
  211.                             // creating the float to display output on
  212.                             this.outputFloat = $(tmpl(this.options.outputFloatTemplate, this.options.outputFloatData));
  213.                             this.workingLabel = tmpl(this.options.workingLabelTemplate, this.options.workingLabelData);
  214.  
  215.                             // initializing tools' toggle button
  216.                             this.handle = PopupManager.registerPopup(this.node.find(selector), "click",
  217.                                 function (d) {
  218.                                     that.emit(that.event.ACTIVATE, {
  219.                                         tool: that
  220.                                     });
  221.  
  222.                                     console.log(that.name, ": tool opens");
  223.  
  224.                                     that.options.activate.call(that);
  225.                                     that.options.target.append(that.outputFloat);
  226.  
  227.                                     that.outputFloat.on("click", ".float-default-button", that.options.defaultAction);
  228.  
  229.                                     that.tooltip = $("#mainMap.map > .tooltip")
  230.                                         .wrapInner("<span class='esri-tooltip'></span")
  231.                                         .append(that.workingLabel);
  232.  
  233.                                     d.resolve();
  234.                                 }, {
  235.                                     closeHandler: function (d) {
  236.                                         that.emit(that.event.DEACTIVATE, {
  237.                                             tool: that
  238.                                         });
  239.  
  240.                                         console.log(that.name, ": tool closes");
  241.  
  242.                                         that.options.deactivate.call(that);
  243.                                         that.outputFloat.detach();
  244.  
  245.                                         that.outputFloat.off("click", ".float-default-button", that.options.defaultAction);
  246.  
  247.                                         d.resolve();
  248.                                     },
  249.  
  250.                                     activeClass: "button-pressed",
  251.                                     useAria: false
  252.                                 }
  253.                             );
  254.  
  255.                             d.resolve(this);
  256.                         },
  257.                         this);
  258.  
  259.                     // load tool's i18n namespace
  260.                     that.ns += that.name;
  261.                     i18n.loadNamespace(that.ns, function () {
  262.                         console.log(that.name, ": translation is loaded");
  263.                         deferrList[0].resolve();
  264.                     });
  265.  
  266.                     // load toll's template
  267.                     require(["dojo/text!tools/templates/" + that.name + ".json"], function (tt) {
  268.                         console.log(that.name, ": template is loaded");
  269.                         toolTemplate = tt;
  270.  
  271.                         deferrList[1].resolve();
  272.                     });
  273.  
  274.                     // BaseTool default options
  275.                     this.options = dojoLang.mixin(
  276.                         {
  277.                             target: $("#mainMap"),
  278.  
  279.                             outputFloatTemplate: "base_tool_float",
  280.                             outputFloatData: {
  281.                                 clearMapButton: i18n.t("tools.basetool.clearmap")
  282.                             },
  283.  
  284.                             workingLabelTemplate: "working_label",
  285.                             workingLabelData: {
  286.                                 workingLabel: i18n.t("tools.basetool.working")
  287.                             },
  288.  
  289.                             toolButtonTemplate: "base_tool_button",
  290.                             toolButtonData: {
  291.                                 ns: that.ns
  292.                             },
  293.  
  294.                             toolOutputTemplate: "base_tool_output",
  295.  
  296.                             activate: function () { console.log('activate action'); },
  297.                             deactivate: function () { console.log('deactivate action'); },
  298.                             defaultAction: function () { console.log('default action'); }
  299.                         },
  300.                         options);
  301.  
  302.                     return this;
  303.                 },
  304.  
  305.                 /**
  306.                  * Generates output to be injected into the tool's float given a template's name and data object.
  307.                  *
  308.                  * @method displayTemplateOutput
  309.                  * @param {Object} templateData data to be put inside the specified template
  310.                  * @param {String} [templateName] template name to be completed with provided data; if not supplied, "toolOutputTemplate" property of the options object will be used
  311.                  * @chainable
  312.                  * @return this tool
  313.                  */
  314.                 displayTemplateOutput: function (templateData, templateName) {
  315.                     var output;
  316.  
  317.                     templateName = templateName || this.options.toolOutputTemplate;
  318.  
  319.                     tmpl.cache = {};
  320.                     tmpl.templates = this.templates;
  321.  
  322.                     output = tmpl(templateName, templateData);
  323.  
  324.                     this.displayOutput(output);
  325.  
  326.                     return this;
  327.                 },
  328.  
  329.                 /**
  330.                  * Injects given tool output into the tool's float.
  331.                  *
  332.                  * @method displayOutput
  333.                  * @param {String | JObject} output String or node collection to be injected into the tool output float.
  334.                  * @chainable
  335.                  * @return this tool
  336.                  */
  337.                 displayOutput: function (output) {
  338.                     this.outputFloat.find(".float-content")
  339.                         .empty()
  340.                         .append(output);
  341.  
  342.                     return this;
  343.                 },
  344.  
  345.                 /**
  346.                 * Sets the tool into a specified state; if the tool is `working`, a `working` label is placed beside the cursor and injected into the tool output float.
  347.                 *
  348.                 * @method working
  349.                 * @param {Boolean} state indicates the state of the tool: working, idle
  350.                 * @chainable
  351.                 * @return This tool
  352.                 */
  353.                 working: function (state) {
  354.                     if (state) {
  355.                         this.tooltip.addClass("working");
  356.                         this.outputFloat
  357.                             .find(".working-placeholder")
  358.                             .replaceWith(this.workingLabel);
  359.                     } else {
  360.                         this.tooltip.removeClass("working");
  361.                         this.outputFloat
  362.                             .find(".working-placeholder").empty();
  363.                     }
  364.  
  365.                     return this;
  366.                 },
  367.  
  368.                 /**
  369.                 * Activate the tool by triggering `open` method on the tool's popup handle.
  370.                 * @method activate
  371.                 * @chainable
  372.                 * @return This tool
  373.                 */
  374.                 activate: function () {
  375.                     //console.log("base activate; nothing to see here;");
  376.                     if (this.handle) {
  377.                         this.handle.open();
  378.                     }
  379.  
  380.                     return this;
  381.                 },
  382.  
  383.                 /**
  384.                 * Deactivate the tool by triggering `close` method on the tool's popup handle.
  385.                 * @method deactivate
  386.                 * @chainable
  387.                 * @return This tool
  388.                 */
  389.                 deactivate: function () {
  390.                     //console.log("base deactivate; nothing to see here;");
  391.                     if (this.handle && this.handle.isOpen()) {
  392.                         this.handle.close();
  393.                     }
  394.  
  395.                     return this;
  396.                 }
  397.             }
  398.         );
  399.     }
  400. );
  401.