dijit/_WidgetBase.js

• Provides:

  • dijit._WidgetBase

• Requires:

  • dijit._base.manager in common
  • dojo.Stateful in common

• dijit._WidgetBase

  • type

    Function

  • chains:
    • dojo.Stateful: (prototype)
    • dojo.Stateful: (call)
  • parameters:
    • params: (typeof Object)
    • srcNodeRef: (typeof DomNode|String)
  • summary

    Future base class for all Dijit widgets.
    _Widget extends this class adding support for various features needed by desktop.

  • tags:

• dijit._WidgetBase.id

  • tags: const
  • type

    String

  • summary

    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.

• dijit._WidgetBase.lang

  • tags: const
  • type

    String

  • summary

    Rarely used.  Overrides the default Dojo locale used to render this widget,
    as defined by the [HTML LANG](http://www.w3.org/TR/html401/struct/dirlang.html#adef-lang) attribute.
    Value must be among the list of locales specified during by the Dojo bootstrap,
    formatted according to [RFC 3066](http://www.ietf.org/rfc/rfc3066.txt) (like en-us).

• dijit._WidgetBase.dir

  • tags: const
  • type

    String

  • summary

    Bi-directional support, as defined by the [HTML DIR](http://www.w3.org/TR/html401/struct/dirlang.html#adef-dir)
    attribute. Either left-to-right "ltr" or right-to-left "rtl".  If undefined, widgets renders in page's
    default direction.

• dijit._WidgetBase.class

  • type

    String

  • summary

    HTML class attribute

• dijit._WidgetBase.style

  • type

    String||Object

  • summary

    HTML style attributes as cssText string or name/value hash

• dijit._WidgetBase.title

  • type

    String

  • summary

    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.

• dijit._WidgetBase.tooltip

  • type

    String

  • summary

    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.

• dijit._WidgetBase.baseClass

  • tags:
  • type

    String

  • summary

    Root CSS class of the widget (ex: dijitTextBox), used to construct CSS classes to indicate
    widget state.

• dijit._WidgetBase.srcNodeRef

  • tags: readonly
  • type

    DomNode

  • summary

    pointer to original DOM node

• dijit._WidgetBase.domNode

  • tags: readonly
  • type

    DomNode

  • summary

    This is our visible representation of the widget! Other DOM
    Nodes may by assigned to other properties, usually through the
    template system's dojoAttachPoint syntax, but the domNode
    property is the canonical "top level" node in widget UI.

• dijit._WidgetBase.containerNode

  • tags: readonly
  • type

    DomNode

  • summary

    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 dojoType=myWidget>
    		<b> here's a plain DOM node
    		<span dojoType=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 dojoType=subWidget>and a widget</span>
    		<i> and another plain DOM node </i>
    
    In templated widgets, "containerNode" is set via a
    dojoAttachPoint 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.

• dijit._WidgetBase._started

  • type

    Boolean

  • summary

    startup() has completed.

• dijit._WidgetBase.attributeMap

  • tags:
  • type

    Object

  • summary

    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:
    - string --> { node: string, type: "attribute" }, for example:
    	"focusNode" ---> { node: "focusNode", type: "attribute" }
    - "" --> { node: "domNode", type: "attribute" }

• dijit._WidgetBase.attributeMap.id

  • type

    String

• dijit._WidgetBase.attributeMap.dir

  • type

    String

• dijit._WidgetBase.attributeMap.lang

  • type

    String

• dijit._WidgetBase.attributeMap.class

  • type

    String

• dijit._WidgetBase.attributeMap.style

  • type

    String

• dijit._WidgetBase.attributeMap.title

  • type

    String

• dijit._WidgetBase._blankGif

  • tags:
  • type

    String

  • summary

    Path to a blank 1x1 image.
    Used by <img> nodes in templates that really get their image via CSS background-image.

• dijit._WidgetBase.postscript

  • constructor - postscript
  • type

    Function

  • parameters:
    • params: (typeof Object)
    • srcNodeRef: (typeof DomNode|String)
  • summary

    Kicks off widget instantiation.  See create() for details.

  • tags:

• dijit._WidgetBase.create

  • parameters:
    • params: (typeof Object)

      Hash of initialization parameters for widget, including
      scalar values (like title, duration etc.) and functions,
      typically callbacks like onClick.

    • srcNodeRef: (typeof DomNode|String)

      If a srcNodeRef (DOM node) is specified:
      - use srcNodeRef.innerHTML as my contents
      - if this is a behavioral widget then apply behavior
      to that srcNodeRef
      - otherwise, replace srcNodeRef with my generated DOM
      tree

  • summary

    Kick off the life-cycle of a widget

  • description

    Create calls a number of widget methods (postMixInProperties, buildRendering, postCreate,
    etc.), some of which of you'll want to override. See http://docs.dojocampus.org/dijit/_Widget
    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.

  • tags:
  • type

    Function

• dijit._WidgetBase._connects

  • type

    Array

• dijit._WidgetBase._subscribes

  • type

    Array

• dijit._WidgetBase.params

• dijit._WidgetBase._created

  • type

    Object

• dijit._WidgetBase.create.srcNodeRef

  • type

    If

  • summary

    a srcNodeRef (DOM node) is specified:
    - use srcNodeRef.innerHTML as my contents
    - if this is a behavioral widget then apply behavior
    to that srcNodeRef
    - otherwise, replace srcNodeRef with my generated DOM
    tree

• dijit._WidgetBase.create.params

  • type

    Hash

  • summary

    of initialization parameters for widget, including
    scalar values (like title, duration etc.) and functions,
    typically callbacks like onClick.

• dijit._WidgetBase._applyAttributes

  • summary

    Step during widget creation to copy all widget attributes to the
    DOM as per attributeMap and _setXXXAttr functions.

  • description

    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.
    
    It processes the attributes in the attribute map first, and then
    it goes through and processes the attributes for the _setXXXAttr
    functions that have been specified

  • tags:
  • type

    Function

• dijit._WidgetBase._getSetterAttributes

  • returns

    String[]

  • summary

    Returns list of attributes with custom setters for this widget

  • type

    Function

• dijit._WidgetBase.constructor

• dijit._WidgetBase.constructor._setterAttrs

  • type

    Array

• dijit._WidgetBase.constructor.prototype

• dijit._WidgetBase.postMixInProperties

  • summary

    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.

  • tags:
  • type

    Function

• dijit._WidgetBase.buildRendering

  • summary

    Construct the UI for this widget, setting this.domNode

  • description

    Most widgets will mixin `dijit._Templated`, which implements this
    method.

  • tags:
  • type

    Function

• dijit._WidgetBase.postCreate

  • summary

    Processing after the DOM fragment is created

  • description

    Called after the DOM fragment has been created, but not necessarily
    added to the document.  Do not include any operations which rely on
    node dimensions or placement.

  • tags:
  • type

    Function

• dijit._WidgetBase.startup

  • summary

    Processing after the DOM fragment is added to the document

  • description

    Called after a widget and its children have been created and added to the page,
    and all related widgets have finished their create() cycle, up through postCreate().
    This is useful for composite widgets that need to control or layout sub-widgets.
    Many layout widgets can use this as a wiring phase.

  • type

    Function

• dijit._WidgetBase.destroyRecursive

  • parameters:
    • preserveDom: (typeof Boolean)

      If true, this method will leave the original DOM structure
      alone of descendant Widgets. Note: This will NOT work with
      dijit._Templated widgets.

  • summary

    Destroy this widget and its descendants

  • description

    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.

  • type

    Function

• dijit._WidgetBase._beingDestroyed

  • type

    Object

• dijit._WidgetBase.destroy

  • parameters:
    • preserveDom: (typeof Boolean)

      If true, this method will leave the original DOM structure alone.
      Note: This will not yet work with _Templated widgets

  • summary

    Destroy this widget, but not its descendants.
    This method will, however, destroy internal widgets such as those used within a template.

  • type

    Function

• dijit._WidgetBase._destroyed

  • type

    Object

• dijit._WidgetBase.destroyRendering

  • parameters:
    • preserveDom: (typeof Boolean)

      If true, this method will leave the original DOM structure alone
      during tear-down. Note: this will not work with _Templated
      widgets yet.

  • summary

    Destroys the DOM nodes associated with this widget

  • tags:
  • type

    Function

• dijit._WidgetBase.destroyDescendants

  • parameters:
    • preserveDom: (typeof Boolean)

      If true, the preserveDom attribute is passed to all descendant
      widget's .destroy() method. Not for use with _Templated
      widgets.

  • summary

    Recursively destroy the children of this widget and their
    descendants.

  • type

    Function

• dijit._WidgetBase.uninitialize

  • summary

    Stub function. Override to implement custom widget tear-down
    behavior.

  • tags:
  • type

    Function

• dijit._WidgetBase._setClassAttr

  • parameters:
    • value: (typeof String)
  • summary

    Custom setter for the CSS "class" attribute

  • tags:
  • type

    Function

• dijit._WidgetBase._setStyleAttr

  • parameters:
    • value: (typeof String||Object)
  • summary

    Sets the style attribute of the widget according to value,
    which is either a hash like {height: "5px", width: "3px"}
    or a plain string

  • description

    Determines which node to set the style on based on style setting
    in attributeMap.

  • tags:
  • type

    Function

• dijit._WidgetBase._attrToDom

  • parameters:
    • attr: (typeof String)
    • value: (typeof String)
  • summary

    Reflect a widget attribute (title, tabIndex, duration etc.) to
    the widget DOM, as specified in attributeMap.
    Note some attributes like "type"
    cannot be processed this way as they are not mutable.

  • tags:
  • type

    Function

• dijit._WidgetBase.get

  • parameters:
    • name: (typeof The)

      property to get.

  • summary

    Get a property from a widget.

  • description

    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 a properties "foo"
    and "bar" and a method named "_getFooAttr", calling:
    	myWidget.get("foo");
    would be equivalent to writing:
    	widget._getFooAttr();
    and:
    	myWidget.get("bar");
    would be equivalent to writing:
    	widget.bar;

  • type

    Function

• dijit._WidgetBase.set

  • parameters:
    • name: (typeof The)

      property to set.

    • value: (typeof The)

      value to set in the property.

  • summary

    Set a property on a widget

  • description

    Sets named properties on a widget which may potentially be handled by a
    setter in the widget.
    For example, if the widget has a properties "foo"
    and "bar" and a method named "_setFooAttr", calling:
    	myWidget.set("foo", "Howdy!");
    would be equivalent to writing:
    	widget._setFooAttr("Howdy!");
    and:
    	myWidget.set("bar", 3);
    would be equivalent to writing:
    	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)

  • type

    Function

• dijit._WidgetBase._attrPairNames

  • type

    Object

• dijit._WidgetBase._getAttrNames

  • parameters:
    • name
  • summary

    Helper function for get() and set().
    Caches attribute name values so we don't do the string ops every time.

  • tags:
  • type

    Function

• dijit._WidgetBase._set

  • parameters:
    • name: (typeof String)
    • value: (typeof anything)
  • summary

    Helper function to set new value for specified attribute, and call handlers
    registered with watch() if the value has changed.

  • type

    Function

• dijit._WidgetBase.toString

  • returns

    String

  • summary

    Returns a string that represents the widget

  • description

    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.

  • type

    Function

• dijit._WidgetBase.getDescendants

  • returns

    dijit._Widget[]

  • summary

    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.

  • type

    Function

• dijit._WidgetBase.getChildren

  • returns

    dijit._Widget[]

  • summary

    Returns all the widgets contained by this, i.e., all widgets underneath this.containerNode.
    Does not return nested widgets, nor widgets that are part of this widget's template.

  • type

    Function

• dijit._WidgetBase.connect

  • parameters:
    • obj: (typeof Object|null)
    • event: (typeof String|Function)
    • method: (typeof String|Function)
  • returns

    _Widget.Handle

  • summary

    Connects specified obj/event to specified method of this object
    and registers for disconnect() on widget destroy.

  • description

    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.

  • return_summary

    A handle that can be passed to `disconnect` in order to disconnect before
    the widget is destroyed.

  • example

    	var btn = new dijit.form.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());
    	});

  • tags:
  • type

    Function

• dijit._WidgetBase.disconnect

  • parameters:
    • handles: (typeof _Widget.Handle)
  • summary

    Disconnects handle created by <code>connect</code>.
    Also removes handle from this widget's list of connects.

  • tags:
  • type

    Function

• dijit._WidgetBase.subscribe

  • parameters:
    • topic: (typeof String)
    • method: (typeof String|Function)
  • summary

    Subscribes to the specified topic and calls the specified method
    of this object and registers for unsubscribe() on widget destroy.

  • description

    Provide widget-specific analog to dojo.subscribe, except with the
    implicit use of this widget as the target object.

  • example

    	var btn = new dijit.form.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);
    	});

  • type

    Function

• dijit._WidgetBase.unsubscribe

  • parameters:
    • handle: (typeof Object)
  • summary

    Unsubscribes handle created by this.subscribe.
    Also removes handle from this widget's list of subscriptions

  • type

    Function

• dijit._WidgetBase.isLeftToRight

  • returns

    Boolean

  • summary

    Return this widget's explicit or implicit orientation (true for LTR, false for RTL)

  • tags:
  • type

    Function

• dijit._WidgetBase.placeAt

  • parameters:
    • reference: (typeof String|DomNode|_Widget)

      The String id of a domNode, a domNode reference, or a reference to a Widget posessing
      an addChild method.

    • position: (typeof String|Int)

      If passed a string or domNode reference, the position argument
      accepts a string just as dojo.place does, one of: "first", "last",
      "before", or "after".
      
      If passed a _Widget reference, and that widget reference has an ".addChild" method,
      it will be called passing this widget instance into that method, supplying the optional
      position index passed.

  • summary

    Place this widget's domNode reference somewhere in the DOM based
    on standard dojo.place conventions, or passing a Widget reference that
    contains and addChild member.

  • description

    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.

  • return_summary

    dijit._Widget
    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.

  • example

     	// create a Button with no srcNodeRef, and place it in the body:
     	var button = new dijit.form.Button({ label:"click" }).placeAt(dojo.body());
     	// now, 'button' is still the widget reference to the newly created button
     	dojo.connect(button, "onClick", function(e){ console.log('click'); });

  • example

    	// create a button out of a node with id="src" and append it to id="wrapper":
     	var button = new dijit.form.Button({},"src").placeAt("wrapper");

  • example

    	// place a new button as the first element of some div
    	var button = new dijit.form.Button({ label:"click" }).placeAt("wrapper","first");

  • example

    	// create a contentpane and add it to a TabContainer
    	var tc = dijit.byId("myTabs");
    	new dijit.layout.ContentPane({ href:"foo.html", title:"Wow!" }).placeAt(tc)

  • type

    Function

• dijit

  • type

    Object