lib/dijit/_editor/_Plugin.js.uncompressed.js

   1 define("dijit/_editor/_Plugin", [
   2         "dojo/_base/connect", // connect.connect
   3         "dojo/_base/declare", // declare
   4         "dojo/_base/lang", // lang.mixin, lang.hitch
   5         "../form/Button"
   6 ], function(connect, declare, lang, Button){
   7
   8 // module:
   9 //              dijit/_editor/_Plugin
  10 // summary:
  11 //              Base class for a "plugin" to the editor, which is usually
  12 //              a single button on the Toolbar and some associated code
  13
  14
  15 var _Plugin = declare("dijit._editor._Plugin", null, {
  16         // summary:
  17         //              Base class for a "plugin" to the editor, which is usually
  18         //              a single button on the Toolbar and some associated code
  19
  20         constructor: function(/*Object?*/args){
  21                 this.params = args || {};
  22                 lang.mixin(this, this.params);
  23                 this._connects=[];
  24                 this._attrPairNames = {};
  25         },
  26
  27         // editor: [const] dijit.Editor
  28         //              Points to the parent editor
  29         editor: null,
  30
  31         // iconClassPrefix: [const] String
  32         //              The CSS class name for the button node is formed from `iconClassPrefix` and `command`
  33         iconClassPrefix: "dijitEditorIcon",
  34
  35         // button: dijit._Widget?
  36         //              Pointer to `dijit.form.Button` or other widget (ex: `dijit.form.FilteringSelect`)
  37         //              that is added to the toolbar to control this plugin.
  38         //              If not specified, will be created on initialization according to `buttonClass`
  39         button: null,
  40
  41         // command: String
  42         //              String like "insertUnorderedList", "outdent", "justifyCenter", etc. that represents an editor command.
  43         //              Passed to editor.execCommand() if `useDefaultCommand` is true.
  44         command: "",
  45
  46         // useDefaultCommand: Boolean
  47         //              If true, this plugin executes by calling Editor.execCommand() with the argument specified in `command`.
  48         useDefaultCommand: true,
  49
  50         // buttonClass: Widget Class
  51         //              Class of widget (ex: dijit.form.Button or dijit.form.FilteringSelect)
  52         //              that is added to the toolbar to control this plugin.
  53         //              This is used to instantiate the button, unless `button` itself is specified directly.
  54         buttonClass: Button,
  55
  56         // disabled: Boolean
  57         //              Flag to indicate if this plugin has been disabled and should do nothing
  58         //              helps control button state, among other things.  Set via the setter api.
  59         disabled: false,
  60
  61         getLabel: function(/*String*/key){
  62                 // summary:
  63                 //              Returns the label to use for the button
  64                 // tags:
  65                 //              private
  66                 return this.editor.commands[key];               // String
  67         },
  68
  69         _initButton: function(){
  70                 // summary:
  71                 //              Initialize the button or other widget that will control this plugin.
  72                 //              This code only works for plugins controlling built-in commands in the editor.
  73                 // tags:
  74                 //              protected extension
  75                 if(this.command.length){
  76                         var label = this.getLabel(this.command),
  77                                 editor = this.editor,
  78                                 className = this.iconClassPrefix+" "+this.iconClassPrefix + this.command.charAt(0).toUpperCase() + this.command.substr(1);
  79                         if(!this.button){
  80                                 var props = lang.mixin({
  81                                         label: label,
  82                                         dir: editor.dir,
  83                                         lang: editor.lang,
  84                                         showLabel: false,
  85                                         iconClass: className,
  86                                         dropDown: this.dropDown,
  87                                         tabIndex: "-1"
  88                                 }, this.params || {});
  89                                 this.button = new this.buttonClass(props);
  90                         }
  91                 }
  92                 if(this.get("disabled") && this.button){
  93                         this.button.set("disabled", this.get("disabled"));
  94                 }
  95         },
  96
  97         destroy: function(){
  98                 // summary:
  99                 //              Destroy this plugin
 100
 101                 var h;
 102                 while(h = this._connects.pop()){ h.remove(); }
 103                 if(this.dropDown){
 104                         this.dropDown.destroyRecursive();
 105                 }
 106         },
 107
 108         connect: function(o, f, tf){
 109                 // summary:
 110                 //              Make a connect.connect() that is automatically disconnected when this plugin is destroyed.
 111                 //              Similar to `dijit._Widget.connect`.
 112                 // tags:
 113                 //              protected
 114                 this._connects.push(connect.connect(o, f, this, tf));
 115         },
 116
 117         updateState: function(){
 118                 // summary:
 119                 //              Change state of the plugin to respond to events in the editor.
 120                 // description:
 121                 //              This is called on meaningful events in the editor, such as change of selection
 122                 //              or caret position (but not simple typing of alphanumeric keys).   It gives the
 123                 //              plugin a chance to update the CSS of its button.
 124                 //
 125                 //              For example, the "bold" plugin will highlight/unhighlight the bold button depending on whether the
 126                 //              characters next to the caret are bold or not.
 127                 //
 128                 //              Only makes sense when `useDefaultCommand` is true, as it calls Editor.queryCommandEnabled(`command`).
 129                 var e = this.editor,
 130                         c = this.command,
 131                         checked, enabled;
 132                 if(!e || !e.isLoaded || !c.length){ return; }
 133                 var disabled = this.get("disabled");
 134                 if(this.button){
 135                         try{
 136                                 enabled = !disabled && e.queryCommandEnabled(c);
 137                                 if(this.enabled !== enabled){
 138                                         this.enabled = enabled;
 139                                         this.button.set('disabled', !enabled);
 140                                 }
 141                                 if(typeof this.button.checked == 'boolean'){
 142                                         checked = e.queryCommandState(c);
 143                                         if(this.checked !== checked){
 144                                                 this.checked = checked;
 145                                                 this.button.set('checked', e.queryCommandState(c));
 146                                         }
 147                                 }
 148                         }catch(e){
 149                                 console.log(e); // FIXME: we shouldn't have debug statements in our code.  Log as an error?
 150                         }
 151                 }
 152         },
 153
 154         setEditor: function(/*dijit.Editor*/ editor){
 155                 // summary:
 156                 //              Tell the plugin which Editor it is associated with.
 157
 158                 // TODO: refactor code to just pass editor to constructor.
 159
 160                 // FIXME: detach from previous editor!!
 161                 this.editor = editor;
 162
 163                 // FIXME: prevent creating this if we don't need to (i.e., editor can't handle our command)
 164                 this._initButton();
 165
 166                 // Processing for buttons that execute by calling editor.execCommand()
 167                 if(this.button && this.useDefaultCommand){
 168                         if(this.editor.queryCommandAvailable(this.command)){
 169                                 this.connect(this.button, "onClick",
 170                                         lang.hitch(this.editor, "execCommand", this.command, this.commandArg)
 171                                 );
 172                         }else{
 173                                 // hide button because editor doesn't support command (due to browser limitations)
 174                                 this.button.domNode.style.display = "none";
 175                         }
 176                 }
 177
 178                 this.connect(this.editor, "onNormalizedDisplayChanged", "updateState");
 179         },
 180
 181         setToolbar: function(/*dijit.Toolbar*/ toolbar){
 182                 // summary:
 183                 //              Tell the plugin to add it's controller widget (often a button)
 184                 //              to the toolbar.  Does nothing if there is no controller widget.
 185
 186                 // TODO: refactor code to just pass toolbar to constructor.
 187
 188                 if(this.button){
 189                         toolbar.addChild(this.button);
 190                 }
 191                 // console.debug("adding", this.button, "to:", toolbar);
 192         },
 193
 194         set: function(/* attribute */ name, /* anything */ value){
 195                 // summary:
 196                 //              Set a property on a plugin
 197                 //      name:
 198                 //              The property to set.
 199                 //      value:
 200                 //              The value to set in the property.
 201                 // description:
 202                 //              Sets named properties on a plugin which may potentially be handled by a
 203                 //              setter in the plugin.
 204                 //              For example, if the plugin has a properties "foo"
 205                 //              and "bar" and a method named "_setFooAttr", calling:
 206                 //      |       plugin.set("foo", "Howdy!");
 207                 //              would be equivalent to writing:
 208                 //      |       plugin._setFooAttr("Howdy!");
 209                 //              and:
 210                 //      |       plugin.set("bar", 3);
 211                 //              would be equivalent to writing:
 212                 //      |       plugin.bar = 3;
 213                 //
 214                 //      set() may also be called with a hash of name/value pairs, ex:
 215                 //      |       plugin.set({
 216                 //      |               foo: "Howdy",
 217                 //      |               bar: 3
 218                 //      |       })
 219                 //      This is equivalent to calling set(foo, "Howdy") and set(bar, 3)
 220                 if(typeof name === "object"){
 221                         for(var x in name){
 222                                 this.set(x, name[x]);
 223         }
 224                         return this;
 225                 }
 226                 var names = this._getAttrNames(name);
 227                 if(this[names.s]){
 228                         // use the explicit setter
 229                         var result = this[names.s].apply(this, Array.prototype.slice.call(arguments, 1));
 230                 }else{
 231                         this._set(name, value);
 232                 }
 233                 return result || this;
 234         },
 235
 236         get: function(name){
 237                 // summary:
 238                 //              Get a property from a plugin.
 239                 //      name:
 240                 //              The property to get.
 241                 // description:
 242                 //              Get a named property from a plugin. The property may
 243                 //              potentially be retrieved via a getter method. If no getter is defined, this
 244                 //              just retrieves the object's property.
 245                 //              For example, if the plugin has a properties "foo"
 246                 //              and "bar" and a method named "_getFooAttr", calling:
 247                 //      |       plugin.get("foo");
 248                 //              would be equivalent to writing:
 249                 //      |       plugin._getFooAttr();
 250                 //              and:
 251                 //      |       plugin.get("bar");
 252                 //              would be equivalent to writing:
 253                 //      |       plugin.bar;
 254                 var names = this._getAttrNames(name);
 255                 return this[names.g] ? this[names.g]() : this[name];
 256         },
 257
 258         _setDisabledAttr: function(disabled){
 259                 // summary:
 260                 //              Function to set the plugin state and call updateState to make sure the
 261                 //              button is updated appropriately.
 262                 this.disabled = disabled;
 263                 this.updateState();
 264         },
 265
 266         _getAttrNames: function(name){
 267                 // summary:
 268                 //              Helper function for get() and set().
 269                 //              Caches attribute name values so we don't do the string ops every time.
 270                 // tags:
 271                 //              private
 272
 273                 var apn = this._attrPairNames;
 274                 if(apn[name]){ return apn[name]; }
 275                 var uc = name.charAt(0).toUpperCase() + name.substr(1);
 276                 return (apn[name] = {
 277                         s: "_set"+uc+"Attr",
 278                         g: "_get"+uc+"Attr"
 279                 });
 280         },
 281
 282         _set: function(/*String*/ name, /*anything*/ value){
 283                 // summary:
 284                 //              Helper function to set new value for specified attribute
 285                 this[name] = value;
 286         }
 287 });
 288
 289 // Hash mapping plugin name to factory, used for registering plugins
 290 _Plugin.registry = {};
 291
 292 return _Plugin;
 293
 294 });