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.

Adding the Ribbon JS Runtime to the Page

Installing the Scripts

Copy the AcidJs.Ribbon folder from the distribution you have downloaded to your project's root. If needed you may add the runtime of the control in a nested folder, like "path/to/AcidJs.Ribbon", but then you need to change the src attributes of the scripts below and use the appRoot property (check below) of control's initializer.

Include the following scripts at the bottom of the page, right before the closing </body> tag. *

* Optionally, scripts could be added to the <head></head> section of the page, but then initialization should be done on load or on DOMContentLoaded.

Example Configuration

Below is an example object, which can be used to configure the ribbon.



This is just a sample configuration. You can have these tools in your own order, etc. Refer to the Tools chapter to learn how to add tools to the ribbon.

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

Initialization

To create a ribbon you need to create an instance of window.AcidJs.Ribbon, and pass the above mentioned configuration object to it. Once this is done, you need to invoke ribbon's init() method.

(function() { // as private variable var _ribbon1 = new window.AcidJs.Ribbon(config); _ribbon1.init(); // as global variable window.ribbon1 = new window.AcidJs.Ribbon(config); ribbon1.init(); })();
Ribbon Configuration Properties

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


  • boundingBox - Object, required. An empty div#some-id element on the page, which will be used to render Ribbon JS.

    boundingBox: $("#ribbon-01") // {jQueryDomObject} [required] ribbon bar placeholder element
  • appIconUrl - String, optional. 16 x 16 pixels top left icon. Default icon is the HTML5 logo (AcidJs.Ribbon/icons/small/acidjs-ui-ribbon-app-icon.png). The custom icon should be added to the AcidJs.Ribbon/icons/small/ folder. The property is available in version 4.1.0+.

    appIconUrl: "my-custom-app-icon.png" // {String} [optional] top left application icon
  • flat - Boolean, optional. If set to true the ribbon will be applied flat styles (as in Office 2013 and above). Default: false. The property is available in version 4.1.0+

    flat: true // {Boolean} [optional] applies flat ribbon styles as in MS Office 2013 and above.

    * To enable or disable programmatically at runtime flat styles to a ribbon you can also use the enableFlatStyles() and disableFlatStyles() methods.

  • cssClasses - Array, optional. Additional CSS classes to be applied to the boundingBox.

    cssClasses: [ // {Array} [optional] additional CSS classes to be applied to the boundingBox. Default: [] "css-class-abc", "css-class-def", "css-class-ghi" ]
  • loadCss - Boolean, optional. If set to false, the stylesheet of the ribbon will not be loaded from the control, but you will have to register it on the page via the <link /> tag. Default: true.

    loadCss: false
  • appRoot - String, optional. By default, the URLS of the ribbon are resolved from the root of the website. Here you can specify different folder.

    appRoot: "path/to/AcidJs.Ribbon/"
  • width - String, optional. Width (CSS max-width) of the ribbon in pixels of percentage. Default: "100%".

    width: "1300px" // {String} [optional] width (max-width) of the ribbon in pixels of percentage. default: "100%"
  • minwidth - String, optional. CSS min-width of the ribbon in pixels of percentage. Default: "auto".

    minwidth: "1200px"
  • config - Object, required.
    • defaultSelectedTab - Number, optional. Default selected tab. Default: 0 (the first tab).

      defaultSelectedTab: 0, // {Number} [optional] default selected tab, default: 0
    • tabs - Array, required. Ribbon tabs configuration. Check the tabs chapter for configuring the tabs.
    • fileTabMenu - Array, optional. Items for the file tab menu tool. Check the tools chapter for configuring the file tab menu.
    • quickLaunchToolbar - Array, optional. Items for the quick launch toolbar. Check the tools chapter for configuring the file tab menu.

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


Example Initialization of a Ribbon



Refer to the API chapter for ribbon methods and events.

Tabs

The main tool container of a ribbon is a tab. Tabs can contain ribbons and tools. In Ribbon JS tabs is an array, passed to the config object of the instance.

tabs: [{ label: "Home", // {String} [required] label for the tab button hint: "Go home", // {String} [optional] label for the tab button name: "tab-home", // {String} [optional] id of the tab. if not set, a GUID will be used enabled: true, // {Boolean} [optional] default: true visible: true, // {Boolean} [optional] default: true, props: { // {Object} [optional] object, containing custom key/values, // which are returned by the "acidjs-ribbon-tab-changed" // event or get/set via the getTabProps() and setTabProps() // methods of the ribbon someNumber: 1, someString: "A String", anObject: { 1: 2, 3: [] }, anArray: [1, 2, 3] } ribbons: [] },{ label: "Insert", // {String} [required] label for the tab button hint: "This is the Insert Tab", // {String} [optional] label for the tab button name: "tab-home", // {String} [optional] id of the tab. if not set, a GUID will be used enabled: true, // {Boolean} [optional] default: true visible: true, // {Boolean} [optional] default: true ribbons: [] }]

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

Tool Icons

The icons used by Ribbon JS are stored under the AcidJs.Ribbon/icons/ folder in two different sub folders - "large" for the 32 x 32 pixel icons and "small" for the 16 x 16 pixels icons. The URLs to the icons are resolved automatically depending on config object's appRoot and the size properties of the tools.

Ribbons

A ribbon is a group of tools, contained within a tab. In Ribbon JS ribbons is an array, passed to the config object of the instance.

ribbons: [{ label: "Clipboard", // {String} [required] width: "10%", // {Number|String} [optional] width of the ribbon in pixels, percentage, etc. default: "auto" minWidth: "160px", // {Number|String} [optional] min width of the ribbon in pixels or percentage tools: [{ type: "split-button", // {String} [required] tool identifier size: "large", // {String} [required] "small" | "large" commands: [{ hint: "Paste Options", // {String} [optional] hint for the default item name: "paste", // {String} [required] command identifier label: "Paste", // {String} [required] item label icon: "paste.png" // {String} [optional] item icon },{ name: "paste-special", label: "Paste Special", icon: "paste-special.png" },{ name: "paste-from-word", label: "Paste Word", icon: "paste-from-word.png" },{ name: "paste-as-hyperlink", label: "Paste Link", icon: "paste-as-hyperlink.png" },{ name: "paste-plain", label: "Paste Plain", icon: "paste-plain.png" }] },{ type: "buttons", // {String} [required] tool identifier size: "small", // {String} [required] "small" | "large" items: "break", // {String} [optional] "break" | "floated" items flow. default: "floated" commands: [{ name: "cut", // required hint: "Cut (Ctrl+X)", // optional label: "Cut", // optional icon: "cut.png" // required },{ name: "copy", hint: "Copy (Ctrl+C)", label: "Copy", icon: "copy.png" },{ name: "format-painter", hint: "Format painter", label: "Format Painter", icon: "format-painter.png" }] }] }]

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

Continue to the Tools section or jump to the API docs.