dijit/_editor/RichText is the core of dijit.Editor, which provides basic WYSIWYG editing features.
dijit/_editor/RichText is the core of dijit.Editor, which provides basic WYSIWYG editing features. It also encapsulates the differences of different js engines for various browsers. Do not use this widget with an HTML <TEXTAREA> tag, since the browser unescapes XML escape characters, like <. This can have unexpected behavior and lead to security issues such as scripting attacks.
Parameter | Type | Description |
---|---|---|
params | Object | null | Initial settings for any of the widget attributes, except readonly attributes. |
srcNodeRef | DOMNode | The widget replaces the specified DOMNode. |
Path to a blank 1x1 image.
Used by <img>
nodes in templates that really get their image via CSS background-image.
USed to separate name from content. Just a colon isn't safe.
Used to concat contents from multiple editors into a single string,
so they can be saved into a single <textarea>
node. See "name" attribute.
True if mouse was pressed while over this widget, and hasn't been released yet
Deprecated. Instead of attributeMap, widget should have a _setXXXAttr attribute for each XXX attribute to be mapped to the DOM.
attributeMap sets up a "binding" between attributes (aka properties) of the widget and the widget's DOM. Changes to widget attributes listed in attributeMap will be reflected into the DOM.
For example, calling set('title', 'hello') on a TitlePane will automatically cause the TitlePane's DOM to update with the new title.
attributeMap is a hash where the key is an attribute of the widget, and the value reflects a binding to a:
DOM node attribute
focus: {node: "focusNode", type: "attribute"} Maps this.focus to this.focusNode.focus
DOM node innerHTML
title: { node: "titleNode", type: "innerHTML" } Maps this.title to this.titleNode.innerHTML
DOM node innerText
title: { node: "titleNode", type: "innerText" } Maps this.title to this.titleNode.innerText
DOM node CSS class
myClass: { node: "domNode", type: "class" } Maps this.myClass to this.domNode.className
If the value is an array, then each element in the array matches one of the formats of the above list.
There are also some shorthands for backwards compatibility:
"focusNode" ---> { node: "focusNode", type: "attribute" }
Events which should be connected to the underlying editing area, events in this array will be addListener with capture=true.
Designates where children of the source DOM node will be placed. "Children" in this case refers to both DOM nodes and widgets. For example, for myWidget:
<div data-dojo-type=myWidget> <b> here's a plain DOM node <span data-dojo-type=subWidget>and a widget</span> <i> and another plain DOM node </i> </div>
containerNode would point to:
<b> here's a plain DOM node <span data-dojo-type=subWidget>and a widget</span> <i> and another plain DOM node </i>
In templated widgets, "containerNode" is set via a data-dojo-attach-point assignment.
containerNode must be defined for any widget that accepts innerHTML (like ContentPane or BorderContainer or even Button), and conversely is null for widgets that don't, like TextBox.
Subclasses may define a cssStateNodes property that lists sub-nodes within the widget that need CSS classes applied on mouse hover/press and focus.
Each entry in this optional hash is a an attach-point name (like "upArrowButton") mapped to a CSS class name (like "dijitUpArrowButton"). Example:
{ "upArrowButton": "dijitUpArrowButton", "downArrowButton": "dijitDownArrowButton" }
The above will set the CSS class dijitUpArrowButton to the this.upArrowButton DOMNode when it
is hovered, etc.
Bi-directional support, as defined by the HTML DIR attribute. Either left-to-right "ltr" or right-to-left "rtl". If undefined, widgets renders in page's default direction.
When true, disables the browser's native spell checking, if supported. Works only in Firefox.
This is our visible representation of the widget! Other DOM Nodes may by assigned to other properties, usually through the template system's data-dojo-attach-point syntax, but the domNode property is the canonical "top level" node in widget UI.
events which should be connected to the underlying editing area
This widget or a widget it contains has focus, or is "active" because it was recently clicked.
Set height to fix the editor at a specific height, with scrolling. By default, this is 300px. If you want to have the editor always resizes to accommodate the content, use AlwaysShowToolbar plugin and set height="". If this editor is used within a layout widget, set height="100%".
A unique, opaque ID string that can be assigned by users or by the system. If the developer passes an ID which is known not to be unique, the specified ID is ignored and the system-generated ID is used instead.
whether to inherit the parent's width or simply use 100%
Make tab key and shift-tab indent and outdent rather than navigating. Caution: sing this makes web pages inaccessible to users unable to use a mouse.
Specifies the name of a (hidden) <textarea>
node on the page that's used to save
the editor content on page leave. Used to restore editor contents after navigating
to a new page and then hitting the back button.
Deferred which is fired when the editor finishes loading. Call myEditor.onLoadDeferred.then(callback) it to be informed when the rich-text area initialization is finalized.
The document this widget belongs to. If not specified to constructor, will default to srcNodeRef.ownerDocument, or if no sourceRef specified, then to the document global
semicolon (";") separated list of css files for the editing area
HTML title attribute.
For form widgets this specifies a tooltip to display when hovering over the widget (just like the native HTML title attribute).
For TitlePane or for when this widget is a child of a TabContainer, AccordionContainer, etc., it's used to specify the tab label, accordion pane title, etc. In this case it's interpreted as HTML.
When this widget's title attribute is used to for a tab label, accordion pane title, etc., this specifies the tooltip to appear when the mouse is hovered over that text.
Function to handle IE's quirkiness regarding how it handles format commands on a word. This involves a lit of node splitting and format cloning.
Parameter | Type | Description |
---|---|---|
command | undefined | The format command, needed to check if the desired command is true or not. |
This function handles normalizing the IE list behavior as much as possible.
Parameter | Type | Description |
---|---|---|
command | undefined | The list command to execute. |
argument | undefined | Any additional argument. |
Function to adapt the IE range by removing leading 'newlines' Needed to fix issue with bold/italics/underline not working if range included leading 'newlines'. In IE, if a user starts a selection at the very end of a line, then the native browser commands will fail to execute correctly. To work around the issue, we can remove all empty nodes from the start of the range selection.
In the case there are multiple text nodes in a row the offset may not be within the node. If the offset is larger than the node length, it will attempt to find the next text sibling until it locates the text node in which the offset refers to
Parameter | Type | Description |
---|---|---|
node | DomNode | The node to check. |
offset | Int | The position to find within the text node |
Step during widget creation to copy widget attributes to the DOM according to attributeMap and _setXXXAttr objects, and also to call custom _setXXXAttr() methods.
Skips over blank/false attribute values, unless they were explicitly specified as parameters to the widget, since those are the default anyway, and setting tabIndex="" is different than not setting tabIndex at all.
For backwards-compatibility reasons attributeMap overrides _setXXXAttr when _setXXXAttr is a hash/string/array, but _setXXXAttr as a functions override attributeMap.
Reflect a widget attribute (title, tabIndex, duration etc.) to the widget DOM, as specified by commands parameter. If commands isn't specified then it's looked up from attributeMap. Note some attributes like "type" cannot be processed this way as they are not mutable.
Parameter | Type | Description |
---|---|---|
attr | String | Name of member variable (ex: "focusNode" maps to this.focusNode) pointing to DOMNode inside the widget, or alternately pointing to a subwidget |
value | String | |
commands | Object |
Optional
|
This function implements the backcolor command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements an over-ride of the bold command.
Parameter | Type | Description |
---|---|---|
argument | undefined | Not used, operates by selection. |
Implementation to call to the native queryCommandEnabled of the browser.
Parameter | Type | Description |
---|---|---|
command | undefined | The command to check. |
Internal helper for directly changing an attribute value.
Directly change the value of an attribute on an object, bypassing any accessor setter. Also handles the calling of watch and emitting events. It is designed to be used by descendant class when there are two values of attributes that are linked, but calling .set() is not appropriate.
Parameter | Type | Description |
---|---|---|
name | String | The property to set. |
value | Mixed | The value to set in the property. |
Internal helper for directly changing an attribute value.
This function implements the test for if the copy command should be enabled or not.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the test for if the create link command should be enabled or not.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
Handler for CSS event on this.domNode. Sets hovering and active properties depending on mouse state, which triggers _setStateClass() to set appropriate CSS classes for this.domNode.
Parameter | Type | Description |
---|---|---|
event | Event |
This function implements the test for if the cut command should be enabled or not.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the fontname command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the fontsize command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the forecolor command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
Helper function to get value for specified property stored by this._set(), i.e. for properties with custom setters. Used mainly by custom getters.
For example, CheckBox._getValueAttr() calls this._get("value").
Parameter | Type | Description |
---|---|---|
name | String |
Helper function for get() and set(). Caches attribute name values so we don't do the string ops every time.
Parameter | Type | Description |
---|---|---|
name | undefined |
Generates the boilerplate text of the document inside the iframe (ie, <html><head>...</head><body/></html>
).
Editor content (if not blank) should be added afterwards.
An internal function for computing the cumulative height of all child nodes of 'node'
Parameter | Type | Description |
---|---|---|
node | undefined | The node to process the children of; |
This function handles applying text color as best it is able to do so when the selection is collapsed, making the behavior cross-browser consistent. It also handles the name and size for IE.
Parameter | Type | Description |
---|---|---|
command | undefined | The command. |
argument | undefined | Any additional arguments. |
This function implements the hilitecolor command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the insertion of HTML 'HR' tags. into a point on the page. IE doesn't to it right, so we have to use an alternate form
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the insertion of HTML content into a point on the page.
Parameter | Type | Description |
---|---|---|
argument | undefined | The content to insert, if any. |
This function implements the insertorderedlist command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the test for if the inserttable command should be enabled or not.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the insertunorderedlist command
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
Collect metadata about this widget (only once per class, not once per instance):
- list of attributes with custom setters, storing in this.constructor._setterAttrs - generate this.constructor._onMap, mapping names like "mousedown" to functions like onMouseDown
Function to test if a node is devoid of real content.
Parameter | Type | Description |
---|---|---|
node | undefined | The node to check. |
startOffset | undefined |
This function implements an over-ride of the italic command.
Parameter | Type | Description |
---|---|---|
argument | undefined | Not used, operates by selection. |
When IE is running in a non-English locale, the API actually changes, so that we have to say (for example) danraku instead of p (for paragraph). Handle that here.
Used as the advice function to map our normalized set of commands to those supported by the target browser.
Parameter | Type | Description |
---|---|---|
cmd | String | |
argument | Anything |
Optional
|
Convert 'strong' and 'em' to 'b' and 'i'.
Moz can not handle strong/em tags correctly, so to help mozilla and also to normalize output, convert them to 'b' and 'i'.
Note the IE generates 'strong' and 'em' rather than 'b' and 'i'
Parameter | Type | Description |
---|---|---|
html | String |
c This function implements the test for if the paste command should be enabled or not.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
filter the output after getting the content of the editing area
post-filtering allows plug-ins and users to specify any number of transforms over the editor's content, enabling many common use-cases such as transforming absolute to relative URLs (and vice-versa), ensuring conformance with a particular DTD, etc. The filters are registered in the contentDomPostFilters and contentPostFilters arrays. Each item in the contentDomPostFilters array is a function which takes a DOM Node or array of nodes as its only argument and returns the same. It is then passed down the chain for further filtering. The contentPostFilters array behaves the same way, except each member operates on strings. Together, the DOM and string-based filtering allow the full range of post-processing that should be necessaray to enable even the most agressive of post-editing conversions to take place.
If nonDestructive is set to "true", the nodes are cloned before filtering proceeds to avoid potentially destructive transforms to the content which may still needed to be edited further. Once DOM filtering has taken place, the serialized version of the DOM which is passed is run through each of the contentPostFilters functions.
Parameter | Type | Description |
---|---|---|
dom | DomNode | DomNode[] | String |
Optional a node, set of nodes, which to filter using each of the current members of the contentDomPostFilters and contentPostFilters arrays. |
nonDestructive | Boolean |
Optional defaults to "false". If true, ensures that filtering happens on a clone of the passed-in content and not the actual node itself. |
filter the input's live DOM. All filter operations should be considered to be "live" and operating on the DOM that the user will be interacting with in their editing session.
Parameter | Type | Description |
---|---|---|
dom | DomNode |
Filter the input before setting the content of the editing area. DOM pre-filtering may happen after this string-based filtering takes place but as of 1.2, this is not guaranteed for operations such as the inserthtml command.
Parameter | Type | Description |
---|---|---|
html | String |
Pre-filter to do fixing to href attributes on <a>
and <img>
tags
Parameter | Type | Description |
---|---|---|
html | String |
See queryCommandAvailable().
Parameter | Type | Description |
---|---|---|
command | String |
Post filter to remove unwanted HTML attributes generated by mozilla
Parameter | Type | Description |
---|---|---|
html | String |
Function to adjust selection range by removing the current start node.
Parameter | Type | Description |
---|---|---|
node | undefined | The node to remove from the starting range. |
range | undefined | The range to adapt. |
The range to adapt.
Post filter to remove unwanted HTML attributes generated by webkit
Parameter | Type | Description |
---|---|---|
html | String |
Saves the content in an onunload event if the editor has not been closed
Deprecated, remove for 2.0. New code should access this.selection directly. Run the named method of dijit/selection over the current editor instance's window, with the passed args.
Parameter | Type | Description |
---|---|---|
name | undefined | |
args | undefined |
Helper function to set new value for specified property, and call handlers registered with watch() if the value has changed.
Parameter | Type | Description |
---|---|---|
name | String | |
value | anything |
Parameter | Type | Description |
---|---|---|
disabled | Boolean |
Update the visual state of the widget by setting the css classes on this.domNode (or this.stateNode if defined) by combining this.baseClass with various suffixes that represent the current widget state(s).
In the case where a widget has multiple states, it sets the class based on all possible combinations. For example, an invalid form widget that is being hovered will be "dijitInput dijitInputInvalid dijitInputHover dijitInputInvalidHover".
The widget may have one or more of the following states, determined by this.state, this.checked, this.valid, and this.selected:
In addition, it may have one or more of the following states, based on this.disabled and flags set in _onMouse (this.active, this.hovering) and from focus manager (this.focused):
Sets the style attribute of the widget according to value, which is either a hash like {height: "5px", width: "3px"} or a plain string
Determines which node to set the style on based on style setting in attributeMap.
Parameter | Type | Description |
---|---|---|
value | String | Object |
Sets textDir attribute. Sets direction of editNode accordingly.
Parameter | Type | Description |
---|---|---|
value | String |
Registers that attr("value", foo) should call setValue(foo)
Parameter | Type | Description |
---|---|---|
value | String |
This function implements an over-ride of the strikethrough command.
Parameter | Type | Description |
---|---|---|
argument | undefined | Not used, operates by selection. |
Function for stripping out the breaker spans inserted by the formatting command. Registered as a filter for IE, handles the breaker spans needed to fix up How bold/italic/etc, work when selection is collapsed (single cursor).
Parameter | Type | Description |
---|---|---|
node | DOMNode |
Function for stripping trailing nodes without any text, excluding trailing nodes like or
, even though they don't have text either.Parameter | Type | Description |
---|---|---|
node | DOMNode |
Handler for hover/active mouse event on widget's subnode
Parameter | Type | Description |
---|---|---|
node | undefined | |
clazz | undefined | |
evt | undefined |
This function implements an over-ride of the superscript command.
Parameter | Type | Description |
---|---|---|
argument | undefined | Not used, operates by selection. |
This function implements an over-ride of the superscript command.
Parameter | Type | Description |
---|---|---|
argument | undefined | Not used, operates by selection. |
Function to return the tab names that are associated with a particular style.
Parameter | Type | Description |
---|---|---|
command | String | The command to return tags for. |
Track mouse/focus events on specified node and set CSS class on that node to indicate current state. Usually not called directly, but via cssStateNodes attribute.
Given class=foo, will set the following CSS class on the node
Note that it won't set any classes if the widget is disabled.
Parameter | Type | Description |
---|---|---|
node | DomNode | Should be a sub-node of the widget, not the top node (this.domNode), since the top node is handled specially and automatically just by mixing in this class. |
clazz | String | CSS class name (ex: dijitSliderUpArrow) |
This function implements an over-ride of the underline command.
Parameter | Type | Description |
---|---|---|
argument | undefined | Not used, operates by selection. |
This function implements the test for if the unlink command should be enabled or not.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
This function implements the unlink of an 'a' tag.
Parameter | Type | Description |
---|---|---|
argument | undefined | arguments to the exec command, if any. |
Add a handler for a keyboard shortcut
Parameter | Type | Description |
---|---|---|
key | String | Number | |
ctrl | Boolean | |
shift | Boolean | |
handler | Function |
add an external stylesheet for the editing area
Parameter | Type | Description |
---|---|---|
uri | dojo/_base/url | Url of the external css file |
This method is deprecated, use get() or set() directly.
Parameter | Type | Description |
---|---|---|
name | String | Object | The property to get or set. If an object is passed here and not a string, its keys are used as names of attributes to be set and the value of the object as values to set in the widget. |
value | Object |
Optional Optional. If provided, attr() operates as a setter. If omitted, the current value of the named property is returned. |
Construct the UI for this widget, setting this.domNode.
Most widgets will mixin dijit._TemplatedMixin
, which implements this method.
Kills the editor and optionally writes back the modified contents to the element from which it originated.
Parameter | Type | Description |
---|---|---|
save | Boolean |
Optional Whether or not to save the changes. If false, the changes are discarded. |
Deprecated, will be removed in 2.0, use this.own(on(...)) or this.own(aspect.after(...)) instead.
Connects specified obj/event to specified method of this object and registers for disconnect() on widget destroy.
Provide widget-specific analog to dojo.connect, except with the
implicit use of this widget as the target object.
Events connected with this.connect
are disconnected upon
destruction.
Parameter | Type | Description |
---|---|---|
obj | Object | null | |
event | String | Function | |
method | String | Function |
A handle that can be passed to disconnect
in order to disconnect before
the widget is destroyed.
var btn = new Button(); // when foo.bar() is called, call the listener we're going to // provide in the scope of btn btn.connect(foo, "bar", function(){ console.debug(this.toString()); });
Kick off the life-cycle of a widget
Create calls a number of widget methods (postMixInProperties, buildRendering, postCreate, etc.), some of which of you'll want to override. See http://dojotoolkit.org/reference-guide/dijit/_WidgetBase.html for a discussion of the widget creation lifecycle.
Of course, adventurous developers could override create entirely, but this should only be done as a last resort.
Parameter | Type | Description |
---|---|---|
params | Object | null | Hash of initialization parameters for widget, including scalar values (like title, duration etc.) and functions, typically callbacks like onClick. The hash can contain any of the widget's properties, excluding read-only properties. |
srcNodeRef | DOMNode | String |
Optional If a srcNodeRef (DOM node) is specified:
|
Wrapper to setTimeout to avoid deferred functions executing after the originating widget has been destroyed. Returns an object handle with a remove method (that returns null) (replaces clearTimeout).
Parameter | Type | Description |
---|---|---|
fcn | Function | Function reference. |
delay | Number |
Optional Delay, defaults to 0. |
Recursively destroy the children of this widget and their descendants.
Parameter | Type | Description |
---|---|---|
preserveDom | Boolean |
Optional If true, the preserveDom attribute is passed to all descendant widget's .destroy() method. Not for use with _Templated widgets. |
Destroy this widget and its descendants
This is the generic "destructor" function that all widget users should call to cleanly discard with a widget. Once a widget is destroyed, it is removed from the manager object.
Parameter | Type | Description |
---|---|---|
preserveDom | Boolean |
Optional If true, this method will leave the original DOM structure alone of descendant Widgets. Note: This will NOT work with dijit._TemplatedMixin widgets. |
Destroys the DOM nodes associated with this widget.
Parameter | Type | Description |
---|---|---|
preserveDom | Boolean |
Optional If true, this method will leave the original DOM structure alone during tear-down. Note: this will not work with _Templated widgets yet. |
Deprecated, will be removed in 2.0, use handle.remove() instead.
Disconnects handle created by connect
.
Parameter | Type | Description |
---|---|---|
handle | undefined |
Used by widgets to signal that a synthetic event occurred, ex:
myWidget.emit("attrmodified-selectedChildWidget", {}).
Emits an event on this.domNode named type.toLowerCase(), based on eventObj. Also calls onType() method, if present, and returns value from that method. By default passes eventObj to callback, but will pass callbackArgs instead, if specified. Modifies eventObj by adding missing parameters (bubbles, cancelable, widget).
Parameter | Type | Description |
---|---|---|
type | String | |
eventObj | Object |
Optional
|
callbackArgs | Array |
Optional
|
Adds escape sequences for special characters in XML. Optionally skips escapes for single quotes
Parameter | Type | Description |
---|---|---|
str | String | |
noSingleQuotes | Boolean |
Executes a command in the Rich Text area
Parameter | Type | Description |
---|---|---|
command | String | The command to execute |
argument | undefined | An optional argument to the command |
Get a property from a widget.
Get a named property from a widget. The property may potentially be retrieved via a getter method. If no getter is defined, this just retrieves the object's property.
For example, if the widget has properties foo
and bar
and a method named _getFooAttr()
, calling:
myWidget.get("foo")
would be equivalent to calling
widget._getFooAttr()
and myWidget.get("bar")
would be equivalent to the expression
widget.bar2
Parameter | Type | Description |
---|---|---|
name | undefined | The property to get. |
Returns all direct children of this widget, i.e. all widgets underneath this.containerNode whose parent is this widget. Note that it does not return all descendants, but rather just direct children. Analogous to Node.childNodes, except containing widgets rather than DOMNodes.
The result intentionally excludes internally created widgets (a.k.a. supporting widgets) outside of this.containerNode.
Note that the array returned is a simple array. Application code should not assume existence of methods like forEach().
Returns all the widgets contained by this, i.e., all widgets underneath this.containerNode. This method should generally be avoided as it returns widgets declared in templates, which are supposed to be internal/hidden, but it's left here for back-compat reasons.
A function for obtaining the height of the footer node
A function for obtaining the height of the header node
Deprecated. Use dijit/_editor/html::getChildrenHtml() instead.
Parameter | Type | Description |
---|---|---|
dom | DomNode |
Deprecated. Use dijit/_editor/html::_getNodeHtml() instead.
Parameter | Type | Description |
---|---|---|
node | DomNode |
Return the current content of the editing area (post filters are applied). Users should call get('value') instead.
Parameter | Type | Description |
---|---|---|
nonDestructive | Boolean |
Optional defaults to false. Should the post-filtering be run over a copy of the live DOM? Most users should pass "true" here unless they really know that none of the installed filters are going to mess up the editing session. |
Return true if this widget can currently be focused and false if not
Return this widget's explicit or implicit orientation (true for LTR, false for RTL)
Parameter | Type | Description |
---|---|---|
type | String | Function | protected |
func | Function |
Transforms the node referenced in this.domNode into a rich text editing node.
Sets up the editing area asynchronously. This will result in the creation and replacement with an iframe.
Parameter | Type | Description |
---|---|---|
element | DomNode |
Optional
|
Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.
The array of specified handles, so you can do for example:
var handle = this.own(on(...))[0];
Place this widget somewhere in the DOM based on standard domConstruct.place() conventions.
A convenience function provided in all _Widgets, providing a simple shorthand mechanism to put an existing (or newly created) Widget somewhere in the dom, and allow chaining.
Parameter | Type | Description |
---|---|---|
reference | String | DomNode | DocumentFragment | dijit/_WidgetBase | Widget, DOMNode, DocumentFragment, or id of widget or DOMNode |
position | String | Int |
Optional If reference is a widget (or id of widget), and that widget has an ".addChild" method, it will be called passing this widget instance into that method, supplying the optional position index passed. In this case position (if specified) should be an integer. If reference is a DOMNode (or id matching a DOMNode but not a widget), the position argument can be a numeric index or a string "first", "last", "before", or "after", same as dojo/dom-construct::place(). |
Provides a useful return of the newly created dijit._Widget instance so you can "chain" this function by instantiating, placing, then saving the return value to a variable.
// create a Button with no srcNodeRef, and place it in the body: var button = new Button({ label:"click" }).placeAt(win.body()); // now, 'button' is still the widget reference to the newly created button button.on("click", function(e){ console.log('click'); }));
// create a button out of a node with id="src" and append it to id="wrapper": var button = new Button({},"src").placeAt("wrapper");
// place a new button as the first element of some div var button = new Button({ label:"click" }).placeAt("wrapper","first");
// create a contentpane and add it to a TabContainer var tc = dijit.byId("myTabs"); new ContentPane({ href:"foo.html", title:"Wow!" }).placeAt(tc)
Place the cursor at the end of the editing area.
Place the cursor at the start of the editing area.
Called after the parameters to the widget have been read-in, but before the widget template is instantiated. Especially useful to set properties that are referenced in the widget template.
Kicks off widget instantiation. See create() for details.
Parameter | Type | Description |
---|---|---|
params | Object |
Optional
|
srcNodeRef | DomNode | String |
Tests whether a command is supported by the host. Clients SHOULD check whether a command is supported before attempting to use it, behaviour for unsupported commands is undefined.
Parameter | Type | Description |
---|---|---|
command | String | The command to test for |
Check whether a command is enabled or not.
Parameter | Type | Description |
---|---|---|
command | String | The command to execute |
Check the state of a given command and returns true or false.
Parameter | Type | Description |
---|---|---|
command | undefined |
Check the value of a given command. This matters most for custom selections and complex values like font value setting.
Parameter | Type | Description |
---|---|---|
command | undefined |
remove an external stylesheet for the editing area
Parameter | Type | Description |
---|---|---|
uri | dojo/_base/url |
This function set the content while trying to maintain the undo stack (now only works fine with Moz, this is identical to setValue in all other browsers)
Parameter | Type | Description |
---|---|---|
html | String |
Set a property on a widget
Sets named properties on a widget which may potentially be handled by a setter in the widget.
For example, if the widget has properties foo
and bar
and a method named _setFooAttr()
, calling
myWidget.set("foo", "Howdy!")
would be equivalent to calling
widget._setFooAttr("Howdy!")
and myWidget.set("bar", 3)
would be equivalent to the statement widget.bar = 3;
set() may also be called with a hash of name/value pairs, ex:
myWidget.set({ foo: "Howdy", bar: 3 });
This is equivalent to calling set(foo, "Howdy")
and set(bar, 3)
Parameter | Type | Description |
---|---|---|
name | undefined | The property to set. |
value | undefined | The value to set in the property. |
Set a property on a widget
Deprecated. Use set() instead.
Parameter | Type | Description |
---|---|---|
attr | String | |
value | anything |
Deprecated, use set('disabled', ...) instead.
Parameter | Type | Description |
---|---|---|
disabled | Boolean |
Add some default key handlers
Overwrite this to setup your own handlers. The default implementation does not use Editor commands, but directly executes the builtin commands within the underlying browser support.
This function sets the content. No undo history is preserved. Users should use set('value', ...) instead.
Parameter | Type | Description |
---|---|---|
html | String |
Deprecated, will be removed in 2.0, use this.own(topic.subscribe()) instead.
Subscribes to the specified topic and calls the specified method of this object and registers for unsubscribe() on widget destroy.
Provide widget-specific analog to dojo.subscribe, except with the implicit use of this widget as the target object.
Parameter | Type | Description |
---|---|---|
t | String | The topic |
method | Function | The callback |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Returns a string that represents the widget.
When a widget is cast to a string, this method will be used to generate the output. Currently, it does not implement any sort of reversible serialization.
Deprecated. Override destroy() instead to implement custom widget tear-down behavior.
Deprecated, will be removed in 2.0, use handle.remove() instead.
Unsubscribes handle created by this.subscribe. Also removes handle from this widget's list of subscriptions
Parameter | Type | Description |
---|---|---|
handle | Object |
Watches a property for changes
Parameter | Type | Description |
---|---|---|
name | String |
Optional Indicates the property to watch. This is optional (the callback may be the only parameter), and if omitted, all the properties will be watched |
callback | Function | The function to execute when the property changes. This will be called after the property has been changed. The callback will be called with the |this| set to the instance, the first argument as the name of the property, the second argument as the old value and the third argument as the new value. |
An object handle for the watch. The unwatch method of this object can be used to discontinue watching this property:
var watchHandle = obj.watch("foo", callback); watchHandle.unwatch(); // callback won't be called now
Called from focus manager when focus has moved away from this editor
Parameter | Type | Description |
---|---|---|
e | undefined |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Called from focus manager when focus has moved into this editor
Parameter | Type | Description |
---|---|---|
e | Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
IE only to prevent 2 clicks to focus
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Maps on() type parameter (ex: "mousemove") to method name (ex: "onMouseMove"). If type is a synthetic event like touch.press then returns undefined.
Parameter | Type | Description |
---|---|---|
type | String | Function |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Internal method called when this widget is made visible.
See onShow
for details.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Called when the widget stops being "active" because focus moved to something outside of it, or the user clicked somewhere outside of it, or the widget was hidden.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
This is fired if and only if the editor loses focus and the content is changed.
Parameter | Type | Description |
---|---|---|
newContent | undefined |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Handler for when the user clicks.
Parameter | Type | Description |
---|---|---|
e | Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Called when this widget is being displayed as a popup (ex: a Calendar popped up from a DateTextBox), and it is hidden. This is called from the dijit.popup code, and should not be called directly.
Also used as a parameter for children of dijit/layout/StackContainer or subclasses. Callback if a user tries to close the child. Child will be closed if this function returns true.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of mouse double click events.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
This event will be fired every time the display context changes and the result needs to be reflected in the UI.
If you don't want to have update too often, onNormalizedDisplayChanged should be used instead
Parameter | Type | Description |
---|---|---|
e | Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Called when another widget becomes the selected pane in a dijit/layout/TabContainer, dijit/layout/StackContainer, dijit/layout/AccordionContainer, etc.
Also called to indicate hide of a dijit.Dialog
, dijit.TooltipDialog
, or dijit.TitlePane
.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Handler for keydown event
Parameter | Type | Description |
---|---|---|
e | Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of printable keys being typed.
Parameter | Type | Description |
---|---|---|
event | undefined | key Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Handler for after the user has pressed a key, and the display has been updated. (Runs on a timer so that it runs after the display is updated)
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Handler for onkeyup event
Parameter | Type | Description |
---|---|---|
e | undefined |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Handler after the iframe finishes loading.
Parameter | Type | Description |
---|---|---|
html | String | Editor contents should be set to this value |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse button is pressed down.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse moves onto this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse moves off of this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse moves over nodes contained within this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse moves off of nodes contained within this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse moves onto nodes contained within this widget.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Connect to this function to receive notifications of when the mouse button is released.
Parameter | Type | Description |
---|---|---|
event | undefined | mouse Event |
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
This event is fired every updateInterval ms or more
If something needs to happen immediately after a user change, please use onDisplayChanged instead.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });
Called when this widget becomes the selected pane in a dijit/layout/TabContainer, dijit/layout/StackContainer, dijit/layout/AccordionContainer, etc.
Also called to indicate display of a dijit.Dialog
, dijit.TooltipDialog
, or dijit.TitlePane
.
var btn = new Button(); // when /my/topic is published, this button changes its label to // be the parameter of the topic. btn.subscribe("/my/topic", function(v){ this.set("label", v); });