Initializer
.ojMenu(options)
option()
.
Parameters:
Name | Type | Argument | Description |
---|---|---|---|
options |
Object |
<optional> |
a map of option-value pairs to set on the component |
- Source:
- ojmenu/ojmenu.js, line 19
Examples
Initialize the menu with no options specified:
$( ".selector" ).ojMenu();
Initialize the menu with some options and callbacks specified:
$( ".selector" ).ojMenu( { "disabled": true, "create": function( event, ui ) {} } );
Initialize the menu via the JET ojComponent
binding:
<ul id="menu" data-bind="ojComponent: { component: 'ojMenu',
disabled: true,
select: menuItemSelect }">
Options
-
#contextMenu :Object
-
JQ selector identifying the JET Menu that the component should launch as a context menu on right-click or Shift-F10. If specified, the browser's native context menu will be replaced by the specified JET Menu.
To specify a JET context menu on a DOM element that is not a JET component, see the
ojContextMenu
binding.To make the page semantically accurate from the outset, applications are encouraged to specify the context menu via the standard HTML5 syntax shown in the below example. When the component is initialized, the context menu thus specified will be set on the component.
The JET Menu should be initialized before any component using it as a context menu.
- Default Value:
null
- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 51
Examples
Initialize a JET component with a context menu:
// via recommended HTML5 syntax: <div id="myComponent" contextmenu="myMenu" data-bind="ojComponent: { ... }> // via JET initializer (less preferred) : $( ".selector" ).ojFoo({ "contextMenu": "#myMenu" });
Get or set the
contextMenu
option, after initialization:// getter var menu = $( ".selector" ).ojFoo( "option", "contextMenu" ); // setter $( ".selector" ).ojFoo( "option", "contextMenu", ".my-marker-class" );
Set a JET context menu on an ordinary HTML element:
<a href="#" id="myAnchor" contextmenu="myMenu" data-bind="ojContextMenu: {}">Some text
-
#disabled :boolean
-
Disables the menu if set to
true
.- Default Value:
false
- Source:
- ojmenu/ojmenu.js, line 248
Examples
Initialize the menu with the
disabled
option specified:$( ".selector" ).ojMenu( { "disabled": true } );
Get or set the
disabled
option, after initialization:// getter var disabled = $( ".selector" ).ojMenu( "option", "disabled" ); // setter $( ".selector" ).ojMenu( "option", "disabled", true );
-
#menuPosition :Object
-
Identifies the position of this menu when launched via the
show()
method or via menu button or context menu functionality.By default, the menu is positioned relative to the launching event if that event is a right-click mouse event, and the launcher element otherwise. Both of those items are passed to the
show()
method. This behavior is appropriate for context menus and menu buttons. If a value is set on theof
field, then the menu is positioned relative to that element or position instead.Please refer to the jQuery UI Position utility for more details about the various choices.
See also
show()
for more details.- Default Value:
{ "my": "left top", "at": "left bottom" }
- Source:
- ojmenu/ojmenu.js, line 299
Examples
Initialize the menu with the
menuPosition
option specified:$( ".selector" ).ojMenu({ menuPosition: { "my": "left top", "at": "right-5 top+5" } });
Get or set the
menuPosition
option, after initialization:// getter var position = $( ".selector" ).ojMenu( "option", "menuPosition" ); // setter $( ".selector" ).ojMenu( "option", "menuPosition", { "my": "left top", "at": "right-5 top+5" } );
-
#menuSelector :string
-
Selector for the elements that serve as the menu container, including submenus.
Note: The
menuSelector
option should not be changed after initialization. Existing submenus will not be updated.- Default Value:
"ul"
- Source:
- ojmenu/ojmenu.js, line 324
Examples
Initialize the menu with the
menuSelector
option specified:$( ".selector" ).ojMenu({ menuSelector: "div" });
Get the
menuSelector
option, after initialization:// getter var menuSelector = $( ".selector" ).ojMenu( "option", "menuSelector" );
-
#rootAttributes :Object|undefined
-
Attributes specified here will be set on the component's root DOM element at creation time. This is particularly useful for components like Dialog that wrap themselves in a root element at creation time.
The specified
class
andstyle
are appended to the current class and style, respectively. All other attributes overwrite any existing value.Setting this option after component creation has no effect.
- Default Value:
undefined
- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 77
Example
Initialize a JET component, specifying a set of attributes to be set on the component's root DOM element:
$( ".selector" ).ojFoo({ "rootAttributes": { 'id': 'myId', 'style': 'max-width:100%; color:blue;', 'class': 'my-class' }});
-
#submenuPosition :Object
-
Identifies the position of submenus. By default, the submenu is positioned relative to the parent menu item, but if a value is set on the
of
field, then the submenu is positioned relative to that element or position instead.Please refer to the jQuery UI Position utility for more details about the various choices.
- Default Value:
{ "my": "left top", "at": "right top" }
- Source:
- ojmenu/ojmenu.js, line 348
Examples
Initialize the menu with the
submenuPosition
option specified:$( ".selector" ).ojMenu({ submenuPosition: { "my": "left top", "at": "right-5 top+5" } });
Get or set the
submenuPosition
option, after initialization:// getter var position = $( ".selector" ).ojMenu( "option", "submenuPosition" ); // setter $( ".selector" ).ojMenu( "option", "submenuPosition", { "my": "left top", "at": "right-5 top+5" } );
Events
-
#beforeShow
-
Triggered before this menu is launched via the
show()
method or via menu button or context menu functionality. The launch can be cancelled by callingevent.preventDefault()
.- Source:
- ojmenu/ojmenu.js, line 377
Properties:
Name Type Description event
Event jQuery
event objectui
Object Parameters Properties
Name Type Description launcher
jQuery the launcher element that was passed to the show()
method.Examples
Initialize the menu with the
beforeShow
callback specified:$( ".selector" ).ojMenu({ "beforeShow": function( event, ui ) {} });
Bind an event listener to the
ojbeforeshow
event:$( ".selector" ).on( "ojbeforeshow", function( event, ui ) {} );
-
#blur
-
Triggered when a menu item loses focus.
- Source:
- ojmenu/ojmenu.js, line 398
Properties:
Name Type Description event
Event jQuery
event objectui
Object Parameters Properties
Name Type Description item
jQuery the currently active menu item Examples
Initialize the menu with the
blur
callback specified:$( ".selector" ).ojMenu({ "blur": function( event, ui ) {} });
Bind an event listener to the
ojblur
event:$( ".selector" ).on( "ojblur", function( event, ui ) {} );
-
#create
-
Triggered when the menu is created.
- Source:
- ojmenu/ojmenu.js, line 400
Properties:
Name Type Description event
Event jQuery
event objectui
Object Empty object included for consistency with other events Examples
Initialize the menu with the
create
callback specified:$( ".selector" ).ojMenu({ "create": function( event, ui ) {} });
Bind an event listener to the
ojcreate
event:$( ".selector" ).on( "ojcreate", function( event, ui ) {} );
-
#focus
-
Triggered when a menu gains focus or a menu item becomes active.
- Source:
- ojmenu/ojmenu.js, line 439
Properties:
Name Type Description event
Event jQuery
event objectui
Object Parameters Properties
Name Type Description item
jQuery the currently active menu item Examples
Initialize the menu with the
focus
callback specified:$( ".selector" ).ojMenu({ "focus": function( event, ui ) {} });
Bind an event listener to the
ojfocus
event:$( ".selector" ).on( "ojfocus", function( event, ui ) {} );
-
#select
-
Triggered when a menu item is selected. Applications should listen for this event, not the
click
event, to detect when a menu item has been selected.- Source:
- ojmenu/ojmenu.js, line 461
Properties:
Name Type Description event
Event jQuery
event objectui
Object Parameters Properties
Name Type Description item
jQuery the currently active menu item Examples
Initialize the menu with the
select
callback specified:$( ".selector" ).ojMenu({ "select": function( event, ui ) {} });
Bind an event listener to the
ojselect
event:$( ".selector" ).on( "ojselect", function( event, ui ) {} );
Methods
-
#blur(event)
-
Removes focus from the active menu item, if any. Does not affect whether the menu itself has browser focus. Resets any active element styles and triggers the menu's
blur
event.Parameters:
Name Type Argument Description event
Event <optional>
What triggered the menu item to blur. May be null
or omitted.- Source:
- ojmenu/ojmenu.js, line 994
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
blur
method:$( ".selector" ).ojMenu( "blur" ) );
-
#collapse(event)
-
Closes the currently active submenu.
Parameters:
Name Type Argument Description event
Event <optional>
What triggered the menu to collapse. May be null
or omitted.- Source:
- ojmenu/ojmenu.js, line 1260
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
collapse
method:$( ".selector" ).ojMenu( "collapse" );
-
#collapseAll(event, all)
-
Closes some or all open submenus.
Parameters:
Name Type Argument Description event
Event <optional>
What triggered the menu to collapse. May be null
. May be omitted if theall
parameter is omitted.all
boolean <optional>
Indicates whether all submenus should be closed or only submenus below and including the menu that is or contains the target of the triggering event. Defaults to false
.- Source:
- ojmenu/ojmenu.js, line 1195
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
collapseAll
method:$( ".selector" ).ojMenu( "collapseAll ", null, true );
-
#destroy()
-
Removes the menu functionality completely. This will return the element back to its pre-init state.
This method does not accept any arguments.
- Source:
- ojmenu/ojmenu.js, line 1416
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
destroy
method:$( ".selector" ).ojMenu( "destroy" );
-
#expand(event)
-
Opens the submenu below the currently active item, if one exists.
Parameters:
Name Type Argument Description event
Event <optional>
What triggered the menu to expand. May be null
or omitted.- Source:
- ojmenu/ojmenu.js, line 1280
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
expand
method:$( ".selector" ).ojMenu( "expand" );
-
#focus(event, item)
-
Activates the specified menu item and triggers the menu's
focus
event.Parameters:
Name Type Description event
Event What triggered the menu item to gain focus. May be null
, but may not be omitted.item
jQuery The menu item to focus/activate. Its containing submenu, if any, must already be expanded. - Source:
- ojmenu/ojmenu.js, line 946
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
focus
method:$( ".selector" ).ojMenu( "focus", null, menu.find( ".oj-menu-item:last" ) );
-
#getNodeBySubId(locator) → {Element|null}
-
Return the subcomponent node represented by the documented locator attribute values.
Parameters:
Name Type Description locator
Object An Object containing at minimum a subId property whose value is a string, documented by the component, that allows the component to look up the subcomponent associated with that string. It contains: component: optional component name - in the future there may be more than one component contained within a page element
subId: the string, documented by the component, that the component expects in getNodeBySubId to locate a particular subcomponent.
- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 526
Returns:
the subcomponent located by the subId string passed in locator, if found.- Type
- Element | null
-
#getSubIdByNode(node) → {string|null}
-
Return the subId string for the given child DOM node
Parameters:
Name Type Description node
Element child DOM node - Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 548
Returns:
- the subId for the DOM node or null when none is found- Type
- string | null
-
#next(event)
-
Moves active state to next menu item.
Parameters:
Name Type Argument Description event
Event <optional>
What triggered the focus to move. May be null
or omitted.- Source:
- ojmenu/ojmenu.js, line 1308
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
next
method:$( ".selector" ).ojMenu( "next" );
-
#option(optionName, value) → {Object|undefined}
-
This method has several overloads, which gets and set component options.
The first overload accepts a single
optionName
param as a string, and returns the current value of that option.The second overload accepts two params, an
optionName
string and a new value to which that option will be set.The third overload accepts no params, and returns a map of key/value pairs representing all the component options and their values.
The fourth overload accepts a single map of option-value pairs to set on the component.
Parameters:
Name Type Argument Description optionName
string | Object <optional>
the option name (string, first two overloads), or the map (Object, last overload). Omitted in the third overload. value
Object <optional>
a value to set for the option. Second overload only. - Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 600
Returns:
The getter overloads return the retrieved value(s). When called via the public jQuery syntax, the setter overloads return the object on which they were called, to facilitate method chaining.- Type
- Object | undefined
Examples
First overload: get one option:
var isDisabled = $( ".selector" ).ojFoo( "option", "disabled" ); // Foo is Button, Menu, etc.
Second overload: set one option:
$( ".selector" ).ojFoo( "option", "disabled", true ); // Foo is Button, Menu, etc.
Third overload: get all options:
var options = $( ".selector" ).ojFoo( "option" ); // Foo is Button, Menu, etc.
Fourth overload: set one or more options:
$( ".selector" ).ojFoo( "option", { disabled: true } ); // Foo is Button, Menu, etc.
-
#previous(event)
-
Moves active state to previous menu item.
Parameters:
Name Type Argument Description event
Event <optional>
What triggered the focus to move. May be null
or omitted.- Source:
- ojmenu/ojmenu.js, line 1323
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
previous
method:$( ".selector" ).ojMenu( "previous" );
-
#refresh()
-
Refreshes the visual state of the menu. JET components require a
refresh()
after the DOM is programmatically changed underneath the component. For Menu, this includes:- After menu items or submenus are added or removed.
- After a change to a menu item's disabled status (which is set by applying or removing the
oj-disabled
class from the menu item). - After the reading direction (LTR vs. RTL) changes.
This method does not accept any arguments.
- Source:
- ojmenu/ojmenu.js, line 839
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
refresh
method:$( ".selector" ).ojMenu( "refresh" );
-
#select(event)
-
Selects the currently active menu item, collapses all submenus and triggers the menu's
select
event.Parameters:
Name Type Argument Description event
Event <optional>
What triggered the selection. May be null
or omitted.- Source:
- ojmenu/ojmenu.js, line 1374
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
select
method:$( ".selector" ).ojMenu( "select" );
-
#show(event, params)
-
Launches this menu as a popup, after firing the
beforeShow
event. Listeners to that event can cancel the launch viaevent.preventDefault()
, and can tweak menu configuration as needed, such asmenuPosition
.Parameters:
Name Type Description event
Event What triggered the menu launch. May be null
, but may not be omitted.params
Object.<string, string> Map including one or more of the following keys: "launcher"
: Required. The DOM element (which may or may not be a JET component) that launched the popup menu. Focus is returned to this node upon menu dismissal. Can be thestring
id of the DOM node, or ajQuery
object containing the node."focus"
: Optional; defaults to"firstItem"
. Values are the followingstring
s:"none"
: Leaves focus where it is, e.g. on the launching component (e.g. WAI-ARIA MenuButton Space/Enter behavior). Use this value if setting focus in thebeforeShow
listener."menu"
: Focuses the menu itself with no menu item focused (e.g. typical Context Menu behavior)."firstItem"
: Focuses the first menu item (e.g. WAI-ARIA MenuButton DownArrow behavior).
- Source:
- ojmenu/ojmenu.js, line 1068
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.Example
Invoke the
show
method:$( ".selector" ).ojMenu( "show", myEvent, {launcher: "myElement"} );
-
#widget() → {jQuery}
-
Returns a
jQuery
object containing the menu.This method does not accept any arguments.
- Source:
- ojmenu/ojmenu.js, line 1414
Returns:
the menu- Type
- jQuery
Example
Invoke the
widget
method:var widget = $( ".selector" ).ojMenu( "widget" );
Non-public Methods
Note: Extending JET components is not currently supported. Thus, non-public methods are for internal use only.
-
<protected> #_AfterCreate()
-
This method is called after
_ComponentCreate
. The JET base component does tasks here that must happen after the component (subclass) has created itself in its override of_ComponentCreate
. Notably, the base component handles therootAttributes
andcontextMenu
options here, since those options operate on the component root node, which for some components is created in their override of_ComponentCreate
.Subclasses should override this method only if they have tasks that must happen after a superclass's implementation of this method, e.g. tasks that must happen after the context menu is set on the component.
Overrides of this method should call
this._super
first.- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 292
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining. -
<protected> #_ComponentCreate()
-
All component create-time initialization lives in this method, except the logic that specifically needs to live in
_InitOptions
or_AfterCreate
, per the documentation for those methods. All DOM creation must happen here, since the intent of_AfterCreate
is to contain superclass logic that must run after that DOM is created.Overrides of this method should call
this._super
first.- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 266
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining. -
<protected> #_GetReadingDirection() → {string}
-
Determines whether the component is LTR or RTL.
Component responsibilities:
- All components must determine directionality exclusively by calling this protected superclass method. (So that any future updates to the logic can be made in this one place.)
- Components that need to know the directionality must call this method from
_create()
andrefresh()
, and cache the value. - Components should not call this at other times, and should instead use the cached value. (This avoids constant DOM queries, and avoids any future issues if directional islands and component reparenting (e.g. popups) should coexist.)
App responsibilities:
- The app specifies directionality by setting the HTML
"dir"
attribute on the<html>
node. When omitted, the default is"ltr"
. (Per-component directionality / directional islands are not currently supported due to inadequate CSS support.) - As with any DOM change, the app must
refresh()
the component if the directionality changes dynamically. (This provides a hook for component housekeeping, and allows caching.)
- Default Value:
"ltr"
- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 888
Returns:
the reading direction, either"ltr"
or"rtl"
- Type
- string
-
<protected> #_GetSavedAttributes(element) → {Object}
-
Gets the saved attributes for the provided element. This is usually the original list of attributes set on the element.
Parameters:
Name Type Description element
Object jQuery selection, should be a single entry - Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 359
Returns:
savedAttributes - attributes that were saved for this element.- Type
- Object
-
<protected> #_InitOptions()
-
This method is called before
_ComponentCreate
, at which point the component has not yet been rendered. Component options should be initialized in this method, so that their final values are in place when_ComponentCreate
is called.This includes getting option values from the DOM, where applicable, and coercing option values (however derived) to their appropriate data type. No other work should be done in this method. See below for details.
Overrides of this method should call
this._super
first.Usage:
- If the component has an option like
disabled
that can be set from the DOM at create time, then the "get from DOM" logic should live in this method. E.g. a typical override might say "if thedisabled
option still has its initial value ofundefined
(i.e., the option has not been set), then get the DOM property and set it on the option." (See also next bullet.) - For attributes that live on the component's root node, keep in mind that anything specified via
the
rootAttributes
option will not be placed on the DOM until_AfterCreate
. So when getting attributes from the root node, components must first look in therootAttributes
option, and then, only if the attribute is not found there, look on the component root (if it already exists). - For options that, unlike
disabled
, have no corresponding DOM property, and are not otherwise set from the DOM, there is nothing to do in this method. - Do NOT set anything on the DOM in this method (like the resolved
disabled
value, or anyrootAttributes
values). The resolved option values should be set on the DOM later, in_ComponentCreate
, and therootAttributes
values are set inbaseComponent._AfterCreate
.
- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 249
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining. - If the component has an option like
-
<protected> #_RestoreAttributes()
-
Restores the saved element's attributes
- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 385
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining. -
<protected> #_SaveAttributes(element)
-
Saves the element's attributes within an internal variable to be reset during the destroy function The JSON variable will be held as : [ { "element" : element[i], "attributes" : { attributes[m]["name"] : {"attr": attributes[m]["value"], "prop": $(element[i]).prop(attributes[m]["name"]) } } ]
Parameters:
Name Type Description element
Object jQuery selection to save attributes for - Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 320
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining. -
<protected> #_SetRootAttributes()
-
Reads the
rootAttributes
option, and sets the root attributes on the component's root DOM element.class
andstyle
are appended to the current class and style, respectively. All other attributes overwrite any existing value.- Inherited From:
- Source:
- ojcomponentcore/jqueryui-base.js, line 103
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.