dijit/_HasDropDown¶
Author: | Colin Snover |
---|---|
Project owner: | Bill Keese |
since: | 1.4 |
Contents
Introduction¶
dijit/_HasDropDown is a dijit widget mixin that provides drop-down menu functionality. Widgets like dijit/form/Select, dijit/form/ComboBox, dijit/form/DropDownButton, and dijit/form/DateTextBox all use dijit/_HasDropDown to implement their drop-down functionality.
Usage¶
First, mixin dijit/_HasDropDown when you create your widget:
define([ "dojo/_base/declare", "dijit/_HasDropDown" ],
function(declare, _HasDropDown){
return declare(_HasDropDown, {
...
});
});
Then, either set the value of :ref:HasDropDown.dropDown
to an existing widget:
require([ "dijit/registry", "my/CustomDropDown", "dojo/domReady!" ], function(registry, CustomDropDown){
var customDropDown = new CustomDropDown({
dropDown: registry.byId("dropDownMenuWidget")
}, "myDropDownWidget");
});
Or, override the :ref:HasDropDown.loadDropDown
and :ref:HasDropDown.isLoaded
functions to allow for lazy instantiation of the drop-down (see Dynamic & lazy-loading drop-downs, below).
Optional node properties¶
Note
All of these properties can only be set before :ref:Widget.buildRendering
is called.
_buttonNode¶
By default, dijit/_HasDropDown will use either focusNode
or domNode
as the element to click to display the drop-down.
If you want to use a specific element to click to display the drop-down instead, attach that element to :ref:buttonNode
.
_arrowWrapperNode¶
When a dijit/_HasDropDown is instantiated, a CSS class dijit(Up|Down|Right|Left)ArrowButton
is added to specify which direction the pop-up appears by default relative to the widget.
By default, these classes are set on :ref:buttonNode
.
Attaching an element to :ref:arrowWrapperNode
will cause these classes to be applied to that element instead.
_popupStateNode¶
When a drop-down is opened, a CSS class dijitHasDropDownOpen
and a popupActive
attribute are added to indicate that the drop-down is open.
By default, these changes apply to focusNode
, or :ref:buttonNode
if there is no focusNode
.
Attaching an element to :ref:popupStateNode
will cause these changes to occur on that element instead.
_aroundNode¶
When the drop-down is opened, it is positioned based on the location of domNode
.
Attaching an element to :ref:aroundNode
will cause the drop-down to be positioned relative to that element instead.
Dynamic & lazy-loading drop-downs¶
By default, _HasDropDown assumes that a dijit widget has been created and assigned to :ref:HasDropDown.dropDown
before the widget starts up.
This works well for drop-downs that always contain the same content and are available immediately,
but it may reduce startup performance and it makes it impossible to create dynamically populated/asynchronous drop-downs.
In order to work around these limitations, more advanced drop-down widgets can implement
:ref:HasDropDown.loadDropDown
and :ref:HasDropDown.isLoaded
instead:
define([ "dojo/_base/declare", "dijit/form/Button", "dijit/_HasDropDown" ],
function(declare, Button, _HasDropDown){
return declare([Button, _HasDropDown], {
isLoaded: function(){
// Returns whether or not we are loaded - if our dropdown has an href,
// then we want to check that.
var dropDown = this.dropDown;
return (!!dropDown && (!dropDown.href || dropDown.isLoaded));
},
loadDropDown: function(callback){
// Loads our dropdown
var dropDown = this.dropDown;
if(!dropDown){ return; }
if(!this.isLoaded()){
var handler = dropDown.on("load", this, function(){
handler.remove();
callback();
});
dropDown.refresh();
}else{
callback();
}
}
});
});