AcidJs.SplitButton

Welcome to AcidJs.SplitButton!

SplitButton.JS is an easy way to create cool looking and functional split buttons for the forms, toolbars or other components on your webpages.

Version 2.0 is elegant and fast, event-driven with extremely small footprint and look and feel, following the latest trends. Its powerful, yet easy to use client API provides various methods, properties and events to manipulate the component and make flexible and usable for various applications. At last, but not least – to have it up and running on your page is a matter of minutes.

Table of Contents

This demo also serves as documentation page for the component, so make sure you check everything.

Various Split Buttons - With Icons, Without Icons, Mixed, Disabled and Disabled Items

Below are demos of different split buttons with various customization options, created on pageload with declarative data.

For better insight and understanding of configuration, usage and trouble shooing AcidJs.SplitButton, please use your browser's console and the source code of the demos.

Rendering a Split Button out of AJAX Data

Click here to fetch the items configuration of the split button from the server rather than declaratively and render the widget.

// render split button sb-07 out of ajax data
$("#render-from-ajax-data").on("click", function(e) {
    e.preventDefault();
    $.ajax({
        url: "test-data/ajax-split-button.json",
        success: function(data) {
            // create split button sb-06
            window.sb7 = new window.AcidJs.SplitButton({
                boundingBox: $("#sb-07"),
                items: data.items
            });
            // render split button sb-06
            window.sb7.render();
            // listen to the "acidjs-splitbutton-item-clicked" event of split button sb-06
            window.sb7.boundingBox.on("acidjs-splitbutton-item-clicked", function(e, data) {
                window.sb7.log(e.type, data);
            });
        }
    });
});
            

The data file ("test-data/ajax-split-button.json"):

{
    "items": [{
        "label": "JavaScript",
        "icon": "AcidJs.SplitButton/icons/js.png",
        "name": "js"
    },{
        "label": "CSS3",
        "icon": "AcidJs.SplitButton/icons/css.png",
        "name": "css"
    },{
        "label": "HTML5",
        "icon": "AcidJs.SplitButton/icons/html5.png",
        "name": "html5"
    },{
        "label": "PHP",
        "icon": "AcidJs.SplitButton/icons/php.png",
        "name": "php",
        "enabled": false
    },{
        "label": "Java",
        "icon": "AcidJs.SplitButton/icons/java.png",
        "name": "java"
    },{
        "label": "CSharp",
        "enabled": false,
        "name": "cs"
    }]
}
            

Rendering a Split Button Widget on Demand

Click here to create a split button on demand.

// render split button sb-08 on demand width declarative items data
$("#render-on-demand").on("click", function(e) {

    e.preventDefault();

    window.sb8 = new window.AcidJs.SplitButton({
        boundingBox: $("#sb-08"),
        defaultSelectedItem: 2,
        items: [{
            label: "Guitar",
            icon: "AcidJs.SplitButton/icons/guitar.png",
            name: "guitar"
        },{
            label: "Drums",
            icon: "AcidJs.SplitButton/icons/drums.png",
            name: "drums"
        },{
            label: "Synthesizer",
            icon: "AcidJs.SplitButton/icons/piano.png",
            name: "piano"
        }]
    });
    // render split button sb-08
    window.sb8.render();
    // listen to the "acidjs-splitbutton-item-clicked" event of split button sb-06
    window.sb8.boundingBox.on("acidjs-splitbutton-item-clicked", function(e, data) {
        window.sb8.log(e.type, data);
    });
});
            

Client API

Adding AcidJs.SplitButton to the Page, Initialization and Configuration

1. To add AcidJs.SplitButton, copy the following right before the closing </body> body tag:

<script src="AcidJs.SplitButton/lib/jquery-1.10.2.min.js"></script>
<script src="AcidJs.SplitButton/classes/SplitButton.js"></script>
            
Make sure your page is in standards-compliant mode (i.e. the DTD of the page is HTML5, XHTML1.0 or XHTML1.1), otherwise the widget will not initialize.

2. In your markup, at the spot you wish to render a split button widget, create an empty <div></div> element, and supply it with an ID:

<div id="sb-01"></div>
            

3. Copy the following initialization code right after the script tag you have registered in Step 1:

<script>
(function() {
    "use strict";

    // create split button sb-01
    window.sb1 = new window.AcidJs.SplitButton({
//      appRoot: "path/to/", // {String} [optional] Path to the AcidJs.SplitButton folder, used to resolve the URLS to the stylesheets; default: ""
        boundingBox: $("#sb-01"), // {jQueryDomObject} [required] The element, which will be used to render the widget. Should be an ID-selector, like $("#split-button-01")
//      skin: "Default", // {String} [optional] The skin, which will be applied to the split button; default: "Default"
        cssClasses: [ // {Array} [optional] Additional CSS classes that can be applied to the boundingBox
            "custom-css-class-01",
            "custom-css-class-02"
        ],
//      width: 300, // {Number} [optional] Width of the split button in pixels; default: 200
//      enabled: true, // {Boolean} [optional] Enabled state of the split button; false is disabled; default: true
//      defaultSelectedItem: 1, // {Number} Default selected item; default: 0 (first item)
        items: [{ // {Array} [required] Items of the split button;
            label: "Export as PDF", // {String} [required] Item label
            icon: "AcidJs.SplitButton/icons/pdf.png", // {String} [optional] Item icon
            name: "pdf", // {String} [optional] Item name, which can be used with the "acidjs-splitbutton-item-clicked" event,
            customKey1: "customValue1", // {Any} [optional] Custom field
            customKey2: "customValue2" // {Any} [optional] Custom field
        },{
            label: "Export as MS Word",
            icon: "AcidJs.SplitButton/icons/doc.png",
            name: "doc"
        },{
            label: "Export as Plain Text",
            icon: "AcidJs.SplitButton/icons/txt.png",
            name: "txt"
        },{
            label: "Export as JSON",
            name: "json"
        },{
            label: "Export as XML",
            name: "xml"
        },{
            label: "Export as HTML",
            name: "html"
        }]
    });
    // render split button sb-01
    window.sb1.render();
    // listen to the "acidjs-splitbutton-item-clicked" event of split button sb-01
    window.sb1.boundingBox.on("acidjs-splitbutton-item-clicked", function(e, data) {
        window.sb1.log(e.type, data);
    });
})();
</script>
            

5. Hit F5 to reload the page. If you have followed the steps properly you will see your first split button rendered on the page.

Please, walk through Step 4 to learn more about the configuration properties or keep reading this manual for more insight about the methods and events of AcidJs.SplitButton.

Methods

render()

Render a split button widget, defined in the config object of the constructor.

window.sb1.render();
            

enable()

Enable a split button widget, which has been disabled via the disabled() method.

window.sb1.enable();
            

disable()

Disable a split button widget. The disabled split button is grayed-out, not clickable and does not trigger any events.

window.sb1.disable();
            

enableItem(index)

Enable a previously disabled item in a split button widget by specified zero-based index. If you wish to enable the second item in your sb1, you should:

window.sb1.enableItem(1);
            

disableItem(index)

Disable an item in a split button widget by specified zero-based index. If you wish to disable the second item in your sb1, you should:

window.sb1.disableItem(1);
            
A disabled item is not clickable, grayed-out and does not trigger any events.

click(index)

Programmatically click an item in the split button by specified index. If you wish to click programmatically the third item of your split button, you should:

window.sb1.click(2);
            
The method returns an object, which you can immediately use:
{
    boundingBox: "...", // {jQueryDomObject}
    selectedIndex: 2, // {Number}
    item:
    {
        icon: "path/to/icon.png", // {String}
        label: "Item Label", // {String}
        name: "item", // {String}
        customKey1: "...", // {Any}
        customKey2: "..." // {Any}
    }
}
            

getItems()

Get the items array, set in the items object of the constructor.

window.sb1.getItems();
            

destroy()

Unbind and remove the UI of a split button widget.

window.sb1.destroy();
            

log()

Internal utilization of browser's console.log():

window.sb1.log("output", 1, 2, 3, 4, "some text", [1, 2, 3], "etc...");
            

Events

"acidjs-splitbutton-item-clicked"

This event is triggered each time an item of the split button has been clicked. You can use this event to define actions for the items of the button, for example:

// listen to the "acidjs-splitbutton-item-clicked" event of split button sb-01
window.sb1.boundingBox.on("acidjs-splitbutton-item-clicked", function(e, data) {
    window.sb1.log(e.type, data);
});
            
The event returns an object, which you can use for the custom logic of the split button (for example define custom action according to the value name) property.
{
    boundingBox: "...", // {jQueryDomObject}
    selectedIndex: 2, // {Number}
    item:
    {
        icon: "path/to/icon.png", // {String}
        label: "Item Label", // {String}
        name: "item", // {String}
        customKey1: "...", // {Any}
        customKey2: "..." // {Any}
    }
}
            

Supported Browsers

Trial Version Limitations

The trial version of AcidJs.SplitButton is fully functional, but displays a trial message and clicking of an item shows an alert box.

The free distribution is just for consideration and testing purposes and using it on a production/live server is forbidden. If you wish to use AcidJs.SplitButton on a live server, you need to purchase a license.