Ribbon JS

HTML5, CSS3 and JavaScript Ribbon Bar. State-of-the-art UI. By Martin Ivanov.

Documentation and API

For better understanding of ribbon's API, use your browser's developer tools. To test a method, just copy the example code into your browser's console and hit enter.

API

Methods
init()

Ribbon initializer. Use it to render a ribbon on the page after an instance of AcidJs.Ribbon has been created. Check the Initialization topic for more info on creating instances and configuring ribbons.

window.ribbon1.init();
getBoundingBox()

Returns the object of the bounding box (the element defined in the boundingBox property of ribbon's config) of the ribbon.

window.ribbon1.getBoundingBox();
renderTabs([tabs], placement)

Programmatically add an array of tabs tab by specified data and placement. The tabs parameter is an array, similar to the tabs array, set in the configuration of a ribbon. The placement parameter is optional and defines the placement of the tab button - as a first of last item and it's default value is "append". Other possible value is "prepend", which adds the new tab as first.

window.ribbon1.renderTabs([{ label: "Another Tab", hint: "Hint for this other tab", name: "tab-page-layout", enabled: true, visible: true, ribbons: [{ label: "Themes", tools: [] },{ label: "Page Setup", tools: [] },{ label: "Page Background", tools: [] },{ label: "Paragraph", tools: [] },{ label: "Arrange", tools: [] }] },{ label: "Yet Another", hint: "Hint for this one", name: "tab-another-tab", enabled: true, visible: true, ribbons: [{ label: "Themes", tools: [] },{ label: "Page Setup", tools: [] },{ label: "Page Background", tools: [] },{ label: "Paragraph", tools: [] },{ label: "Arrange", tools: [] }] }], "prepend")
disableTools([tools])

Programmatically disable array of ribbon tools by tool names.

window.ribbon1.disableTools(["bold", "cut"]);
enableTools([tools])

Programmatically enable array of disabled ribbon tools by tool names.

window.ribbon1.enableTools(["bold", "cut"]);
getConfig()

Return the configuration object of the ribbon.

window.ribbon1.getConfig();
destroy()

Unbind and remove the UI of the ribbon. The method returns the config object of the ribbon before disposing it.

window.ribbon1.destroy();
setToolsActive(tools, triggerToolClicked)

Set array of tools as active and optionally trigger the "acidjs-ribbon-tool-clicked" of each tool in the array if the Boolean property triggerToolClicked is set to true.

window.ribbon1.setToolsActive(["bold", "italic"], true);
setToolsInactive(tools)

Set array of tools as inactive (not toggled).

window.ribbon1.setToolsInactive(["bold", "italic"]);
getToolsByName(name) version 4.0.1+

Get the DOM node of tool occurrences (for example, you can have multiple "paste" buttons in the same instance of a ribbon) , defined by it's name. The method returns an array of matching DOM elements.

window.ribbon1.getToolsByName("paste");
clickTools([names])

Programmatically click an array of tools and trigger the "acidjs-ribbon-tool-clicked" event of the ribbon.

window.ribbon1.clickTools(["bold", "underline", "italic"]);
selectDropdownValue(dropdownToolName, newValue, triggerToolClicked)

Programmatically select new value (newValue) of a dropdown tool, defined in the dropdownToolName property and optionally trigger the ribbon's "acidjs-ribbon-tool-clicked" event if the Boolean property triggerToolClicked is set to true. The value of the newValue should be a value, set to a dropdown item of the tool, defined in the dropdownToolName property.

window.ribbon1.selectDropdownValue("font-family", "Consolas", true)
selectColorByValue(colorPickerName, newColorValue, triggerToolClicked)

Programmatically select new color value (newColorValue) of a color picker tool, defined in the colorPickerName property and optionally trigger the ribbon's "acidjs-ribbon-tool-clicked" event if the Boolean property triggerToolClicked is set to true. The value of the newColorValue should be a value, set to a color item item of the tool, defined in the colorPickerName property.

window.ribbon1.selectColorByValue("font-color", "#dbe5f1", true);
disableRibbon()

Programmatically disable the ribbon and set the UI as non-interactive.

window.ribbon1.disableRibbon();
enableRibbon()

Programmatically enable a ribbon, which has been disabled via the disableRibbon() method and set it's UI back to interactive.

window.ribbon1.enableRibbon();
hide()

Programmatically hide the ribbon.

window.ribbon1.hide();
show()

Programmatically hide a ribbon, which has been hidden via the hide() method.

window.ribbon1.show();
collapse()

Programmatically collapse a ribbon. This method is also being used by the collapse button of the UI.

window.ribbon1.collapse();
expand()

Programmatically expand a ribbon, which has been collapsed via the collapse() method of the control. This method is also being used by the collapse button of the UI.

window.ribbon1.expand();
getTabButtonByName(name)

Return the DOM node of a queried tab button, defined by it's name. The name property is the property that has been defined in tab's configuration object.

window.ribbon1.getTabButtonByName("tab-insert");
setTabActive(name)

Set a tab, queried by it's name to active. This method will not execute if the queried tab is hidden or disabled.

window.ribbon1.setTabActive("tab-insert");

The method fires the "acidjs-ribbon-tab-changed" event of the ribbon, which returns an object, containing the name of the tab and it's index:

{ name: "tab-insert", index: 1 }
disableTabs([names])

Disable tabs by specified array of names. Only tabs, which are not active will be disabled

window.ribbon1.disableTabs(["tab-insert", "tab-page-layout"])
enableTabs([names])

Enable tabs, which have been disabled via the disableTabs() by specified array of names.

window.ribbon1.enableTabs(["tab-insert", "tab-page-layout"]);
removeTabs([names])

Remove tabs by specified array of names. Only inactive tabs can be removed. Once removed, these tabs stop functioning and are not available in the ribbon any more.

window.ribbon1.removeTabs(["tab-insert", "tab-page-layout"]);
hideTabs([names])

Hide tabs by specified array of names. Only inactive tabs can be hidden. Once hidden, these tabs can be shown back by using the showTabs([names]).

window.ribbon1.hideTabs(["tab-insert", "tab-page-layout"]);
showTabs([names])

Show tabs, which have been hidden via the hideTabs() method, by specified array of names.

window.ribbon1.showTabs(["tab-insert", "tab-page-layout"]);
getTabContentBoxByName(name)

Return the DOM object of a tab by it's name. The returned object can be used in conjunction with any other JavaScript or jQuery methods and functions.

window.ribbon1.getTabContentBoxByName("tab-home");
getRibbonByLabel(label)

Return the DOM node of a tab's ribbon by it's label. The returned object can be used in conjunction with any other JavaScript or jQuery methods and functions.

window.ribbon1.getRibbonByLabel("Clipboard")
getRibbonContextBoxByLabel(label)

Return the content box node of a tab's ribbon by it's label. The returned object can be used in conjunction with any other JavaScript or jQuery methods and functions.

window.ribbon1.getRibbonContextBoxByLabel("Clipboard");
selectSplitButtonCommand(newCommandName, triggerToolClicked)

Set new default command to a split button by specifying a newCommandName and optionally trigger the "acidjs-ribbon-tool-clicked" event or the control.

window.ribbon1.selectSplitButtonCommand("paste-special", true);
renderQuickLaunchToolbar([commands])

Add commands to the quick launch toolbar tool. The commands array is similar to the quickLaunchToolbar array, which can be optionally defined in the configuration object of a ribbon.

window.ribbon1.renderQuickLaunchToolbar([{ name: "save", hint: "Save (Ctrl+S)", //label: "Save", icon: "save.png", },{ name: "cut", hint: "Cut (Ctrl+X)", icon: "cut.png" },{ name: "copy", hint: "Copy (Ctrl+C)", icon: "copy.png" },{ name: "paste", hint: "Paste (Paste+V)", icon: "paste.png" },{ name: "undo", hint: "Undo (Ctl+Z)", icon: "undo.png", label: "Undo" },{ name: "redo", hint: "Redo (Ctl+Y)", icon: "redo.png", label: "Redo" },{ name: "repeat", hint: "Repeat", icon: "repeat.png", label: "Repeat" }]);
renderFileTabMenu([commands])

Create a file tab menu tool. The commands array is similar to the fileTabMenu array, which can be optionally defined in the configuration object of a ribbon.

window.ribbon1.renderFileTabMenu([{ hint: "Click to see the file menu", name: "file", label: "File" },{ name: "save", label: "Save", icon: "save.png" },{ name: "save-as", label: "Save As", icon: "save-as.png" },{ name: "Open", label: "Open", icon: "open.png" },{ name: "close", label: "Close", icon: "close.png" },{ name: "print", label: "Print", icon: "print.png" }]);
highlightTabsGroup([names], groupName, groupTitle, color) version 4.1.0+

Highlight tabs group (as in MS Word's Table Tools, for example).

window.ribbon1.highlightTabsGroup(["tab-insert", "tab-page-layout"], "font-tools", "Font Tools", "#f00");

The method returns an object, containing the currently highligted tab groups:

{ "tab-group-name": { color: {String} groupTitle: {String} name: {String} tabs: {Array} } }
unhighlightTabsGroup(groupName) version 4.1.0+

Remove the highlighting of a tab group (cancel the highlightTabsGroup method).

window.ribbon1.unhighlightTabsGroup("font-tools");

The method returns an object, containing the currently highligted tab groups:

{ "tab-group-name": { color: {String} groupTitle: {String} name: {String} tabs: {Array} } }
enableFlatStyles() version 4.1.0+

Programmatically set Office 2013+ flat styles to the ribbon. The method returns config.flat: {Boolean}.

window.ribbon1.enableFlatStyles();
disableFlatStyles() version 4.1.0+

Programmatically set classic (before Office 2013) styles to the ribbon. The method returns config.flat: {Boolean}.

window.ribbon1.disableFlatStyles();
getReleaseNotes() version 4.2.0+

Programmatically open ribbonjs.com/release-notes and display the release notes of the current version of Ribbon JS.

window.ribbon1.getReleaseNotes();
getToolData(name) version 4.2.0+

Get the data associated with the queried tool by it's name

window.ribbon1.getToolData("cut");

The method returns an object, containing the command, active, value and props data of the tool/command:

{ active: {Boolean} command: {String|null} props: {Object|null} value: {String|null} }
setToolProps(name, key, value) version 4.2.0+

Set the optional props key (check the Ribbon JS configuration documentation) to a tool/command definition for more info about this key. The required parameters are tool/command name (String) of the tool/command, key (String or Number) name and value (Any).

// set a number window.ribbon1.setToolProps("cut", "newKeyName", 1234); // set an object window.ribbon1.setToolProps("cut", "anotherKey", {a:1, b: [1, 2, 3, c: "Some String"]}); // set a string window.ribbon1.setToolProps("cut", "oneMoreKey", "This one is a string");

The method returns the props object, associated with the queried tool/command:

{ props: {Object} }
getToolProps(name) version 4.2.0+

Get the props object, associated with a tool or command.

window.ribbon1.getToolProps("cut");

The method returns an object or null:

{ props: {Object|null} }
getTabProps(name) version 4.2.0+

Get the props object, associated with a tab, queried by its name.

// set a number window.ribbon1.getTabProps("tab-home", "newKeyName", 1234); // set an object window.ribbon1.getTabProps("tab-home", "anotherKey", {a:1, b: [1, 2, 3, c: "Some String"]}); // set a string window.ribbon1.getTabProps("tab-home", "oneMoreKey", "This one is a string");

The method returns an object or null:

{ props: {Object|null} }
setTabProps(name, key, value) version 4.2.0+

Set the optional props key (check the Ribbon JS configuration documentation) to a tab for more info about this key. The required parameters are tab name (String) of the tool/command, key (String or Number) name and value (Any).

window.ribbon1.setTabProps("tab-home", "newKey", 1234);

The method returns the props object, associated with the queried tab:

{ props: {Object} }

Events

Ribbon JS triggers three types of custom events, which return useful data that can be used to connect the control to other JavaScript widgets or to react on button clicks, etc.

To understand what data is returned by each event, go to the demos page and open the console of your browser's development tools.

"acidjs-ribbon-ready"

The event is triggered when ribbon is fully initialized and rendered on the page. You can use this event for example to disable or set tools as active, etc as shown below.

window.ribbon1.getBoundingBox().on("acidjs-ribbon-ready", function(e, data){ window.console.info("acidjs.ribbon event fired", e.type, data); // disable the ribbon on ready //window.ribbon1.disableRibbon(); // hide the ribbon on ready //window.ribbon1.hide(); // collapse the ribbon on ready //window.ribbon1.collapse(); // set some tools as disabled by default /*window.ribbon1.disableTools([ "paste", "cut", "change-case", "cut", "toggle", "line-and-paragraph-spacing", "font-shrink", "format-painter", "paste-from-word", "replace", "paste", "font-family", "font-color", "toggle-dropdown-1", "exclusive-menu-1", "my-custom-styles", "my-custom-dropdown-with-guitars" ]);*/ });

Object, returned by the event:

{ ready: true, // {Boolean} config: {Object} // ribbon config }
"acidjs-ribbon-tool-clicked"

The event is triggered if any ribbon tool is clicked, selected or interacted with. The event returns the command name, its value (if set) and active state. You can use this even to react invoke external code (for example trigger an execCommand), open a dialog, etc.

window.ribbon1.getBoundingBox().on("acidjs-ribbon-tool-clicked", function(e, data){ window.console.info("acidjs.ribbon event fired", e.type, data); switch(data.command) { case "bold": console.log("make selected text bold"); break; case "cut": console.log("cut selected text"); break; } });

Object, returned by the event:

{ command: {String}, // command name active: {Boolean} // tool active state value: {String|null} // tool value props: {Object|null} // the custom object, set to a tool/command }
"acidjs-ribbon-tab-changed"

The event is triggered when a ribbon tab has been selected and returns the name of the tab and its index.

window.ribbon1.getBoundingBox().on("acidjs-ribbon-tab-changed", function(e, data){ window.console.info("acidjs.ribbon event fired", e.type, data); });

Object, returned by the event:

{ index: {Number}, // tab index name: {String} // tab name props: {Object|null} // the custom object, set to a tab }
"acidjs-ribbon-toggle" version 4.2.0+

The event is triggered when tab button is clicked (in this case the event always returns {expanded: true}) or when the ribbon is collapsed or expanded either by clicking the expand/collapse button in the top right corner of the control or programmatically via the expand() and collapse() methods.

window.ribbon1.getBoundingBox().on("acidjs-ribbon-toggle", function(e, data){ window.console.info("acidjs.ribbon event fired", e.type, data); });

Object, returned by the event:

{ expanded: {Boolean} }

Use this document as a complete copy/paste reference for a ribbon configuration.

Go to the Tools section or go back to the docs home.