Creating Split Buttons

With the inclusion of the optional Menu library, it is possible to create Buttons that incorporate a menu.

Split Buttons can be created with or without existing HTML. In either case, create a Split Button by setting the "type" configuration attribute to "split" and the "menu" configuration attribute to one of the following values:

• Object specifying a YAHOO.widget.Menu instance.
• Object specifying a YAHOO.widget.Overlay instance.
• String specifying the id attribute of the <div> element used to create the menu. By default the menu will be created as an instance of YAHOO.widget.Overlay. If the default CSS class name for YAHOO.widget.Menu is applied to the <div> element, it will be created as an instance of YAHOO.widget.Menu.
• String specifying the id attribute of the <select> element used to create the menu.
• Object specifying the <select> element used to create the menu.
• Array of object literals, each representing a set of YAHOO.widget.MenuItem configuration properties.
• Array of strings representing the text labels for each item in the menu.

Creating Split Buttons Using Existing Markup

Since the "menu" attribute can be set to the id of an existing <select> element, a Split Button can be used to collapse two HTML form controls (<input> and <select>) into one DHTML control. For example, consider the following HTML:

<input type="submit" id="splitbutton1" name="splitbutton1_button" value="Split Button 1"> <select id="splitbutton1select" name="splitbutton1select" multiple> <option value="0">One</option> <option value="1">Two</option> <option value="2">Three</option> </select> <input type="button" id="splitbutton2" name="splitbutton2_button" value="Split Button 2"> <select id="splitbutton2select" name="splitbutton2select"> <option value="0">One</option> <option value="1">Two</option> <option value="2">Three</option> </select>

To instantiate a Split Button, pass the id of the source element as the first argument to the Button's constructor. Set the "type" configuration attribute to "split" and the "menu" configuration attribute to the id of the Button's corresponding <select> element.

var oSplitButton1 = new YAHOO.widget.Button("splitbutton1", { type: "split", menu: "splitbutton1select" }); var oSplitButton2 = new YAHOO.widget.Button("splitbutton2", { type: "split", menu: "splitbutton2select" });

As a convenience, if the "type" attribute of the Button's source <input> element was set to "submit", clicking on any MenuItem in the Button's Menu will automatically submit the Button's parent <form>.

Adding MenuItems To A Button's Menu

Add MenuItems to a Button's Menu using the Menu's addItem, addItems, and insertItem methods. The following example adds two additional MenuItems to the first Button's Menu by passing an array of object literals (each containing a set of MenuItem configuration properties) to the addItems method.

// "render" event handler for the Button's Menu var onMenuRender = function (p_sType, p_aArgs) { this.addItems([ { text: "Four", value: 4 }, { text: "Five", value: 5 } ]); }; // Add some additional MenuItems to the Button's Menu once it has been rendered oSplitButton1.getMenu().subscribe("render", onMenuRender);

Adding Click Event Listeners To A Split Button

The most common events to listen for on a Split Button are click events. A standard click event is fired when the face/text label of a Split Button is clicked. Use the on method or onclick configuration attribute to listen for the click event. (Note: The click event is not fired when the user clicks on the area of the Button that displays the Button's Menu.)

// "click" event handler for the Button - called when the user clicks // on the Button's text label, not when the user clicks on the area // of the Button that displays the Button's Menu. var onButtonClick = function () { YAHOO.log("You clicked the Button."); }; // Create a Button using an existing <input> and <select> element var oSplitButton2 = new YAHOO.widget.Button("splitbutton2", { type: "split", menu: "splitbutton2select", onclick: { fn: onButtonClick } });

Split Buttons also fire an option event when the user clicks on the area the that invokes the display of its menu. Use the on method to listen for the option event.

// "click" event handler for the Button - called when the user clicks // on the Button's text label, not when the user clicks on the area // of the Button that displays the Button's Menu. var onButtonClick = function () { YAHOO.log("You clicked the Button."); }; // Create a Button using an existing <input> and <select> element var oSplitButton2 = new YAHOO.widget.Button("splitbutton2", { type: "split", menu: "splitbutton2select", onclick: { fn: onButtonClick } }); // "option" event listener - called when the user clicks on the // area of the Button that displays its Menu. var onOption = function () { YAHOO.log("You clicked the Split Button's option area."); }; // Add a listener for the Button's "option" event oSplitButton2.on("option", onOption);

Add event listeners to a Button's Menu using the Menu's subscribe method. The following example adds a click event listener to the Button's Menu. The click event listener displays the text label and value of the MenuItem that was clicked.

// "click" event handler for the Button - called when the user clicks // on the Button's text label, not when the user clicks on the area // of the Button that displays the Button's Menu. var onButtonClick = function () { YAHOO.log("You clicked the Button."); }; // Create a Button using an existing <input> and <select> element var oSplitButton2 = new YAHOO.widget.Button("splitbutton2", { type: "split", menu: "splitbutton2select", onclick: { fn: onButtonClick } }); // Click event listener for the second Button's Menu instance var onMenuClick = function (p_sType, p_aArgs) { var oEvent = p_aArgs[0], // DOM event oMenuItem = p_aArgs[1]; // MenuItem instance that was the target of the event if (oMenuItem) { YAHOO.log("[MenuItem Properties] text: " + oMenuItem.cfg.getProperty("text") + ", value: " + oMenuItem.value); } }; // Add a "click" event listener for the Button's Menu oSplitButton2.getMenu().subscribe("click", onMenuClick); // "option" event listener - called when the user clicks on the // area of the Button that displays its Menu. var onOption = function () { YAHOO.log("You clicked the Split Button's option area."); }; // Add a listener for the Button's "option" event oSplitButton2.on("option", onOption);

Another way to create a Split Button from markup is to begin with an <input> element and the markup format required for Overlay:

<input type="button" id="splitbutton3" name="splitbutton3_button" value="Split Button 3"> <div id="splitbutton3menu" class="yui-overlay"> <div class="bd">Split Button 3 Menu</div> </div>

To instantiate the Split Button, pass the id of the source element as the first argument to the Button's constructor. Set the "type" configuration attribute to "split" and the "menu" configuration attribute to the id or node reference of the HTML element to be used to create the Overlay:

var oSplitButton3 = new YAHOO.widget.Button("splitbutton3", { type: "split", menu: "splitbutton3menu" });

Using an Overlay instance as a Split Button's menu is useful when you need a simple container to house HTML content or another YUI widget, such as a Calendar or Color Picker.

Creating Split Buttons Using JavaScript

It is also possible to create a Split Button that utilizes Overlay completely from JavaScript. Begin by instantiating an Overlay. Then instantiate a Split Button, setting its "type" configuration attribute to "split" and its "menu" configuration attribute to the Overlay instance via an object literal passed as a single argument to the Button's constructor:

// Search for an element to place the Split Button into via the // Event Utility's "onContentReady" method YAHOO.util.Event.onContentReady("splitbuttonsfromjavascript", function () { // Instantiate an Overlay instance var oOverlay = new YAHOO.widget.Overlay("splitbutton4menu", { visible: false }); oOverlay.setBody("Split Button 4 Menu"); // Instantiate a Split Button var oSplitButton4 = new YAHOO.widget.Button({ type: "split", label: "Split Button 4", menu: oOverlay, container: this }); });

Another easy way to create a Split Button from JavaScript is to set the "menu" configuration property to an array of MenuItem configuration properties.

// Search for an element to place the Split Button into via the // Event Utility's "onContentReady" method YAHOO.util.Event.onContentReady("splitbuttonsfromjavascript", function () { // "click" event handler for each item in the Button's Menu var onMenuItemClick = function (p_sType, p_aArgs, p_oItem) { var sText = p_oItem.cfg.getProperty("text"); YAHOO.log("[MenuItem Properties] text: " + sText + ", value: " + p_oItem.value); }; // Create an array of YAHOO.widget.MenuItem configuration properties var aSplitButton5Menu = [ { text: "One", value: 1, onclick: { fn: onMenuItemClick } }, { text: "Two", value: 2, onclick: { fn: onMenuItemClick } }, { text: "Three", value: 3, onclick: { fn: onMenuItemClick } } ]; // Instantiate a Split Button using the array of YAHOO.widget.MenuItem // configuration properties as the value for the "menu" // configuration attribute. var oSplitButton5 = new YAHOO.widget.Button({ type: "split", label: "Split Button 5", name: "splitbutton5", menu: aSplitButton5Menu, container: this }); });

Configuration for This Example

You can load the necessary JavaScript and CSS for this example from Yahoo's servers. Click here to load the YUI Dependency Configurator with all of this example's dependencies preconfigured.