Skip to main content

Work with Ribbon

Setting/getting values and states#

You can change the value or state (for a TwoState button) of a control with the help of the setState() method. It takes one parameter: a key-value pair with the ID of the control and its new value (state).

This is how you can set the state of a twoState button:

{ type:"button", twoState:true, id:"check" }...ribbon.setState({"check":true});ribbon.setState({"check":false});

Related sample: Ribbon. Set State

And this is how you can change the value of an input:

{ type:"input", id: "file_name" }...ribbon.setState({"file_name":"My file"});

To get the current value of the control, use the getState() method.

This is what the method returns for a TwoState button:

{ type:"button", twoState:true, id:"check" }...ribbon.getState();// { check:true }// or// { check:false }

Related sample: Ribbon. Get State

And this is how you can get the current value of an input:

{ type:"input", id:"file_name", value:"My file" }...ribbon.getState();
// {"file_name":"My file"}

Hiding and showing controls#

You can show or hide controls by their IDs. Pass them to the corresponding methods - show() and hide():

ribbon.hide("add_btn");ribbon.show(["save_btn","del_btn"]);

Related sample: Ribbon. Show/Hide Ribbon Item

Starting from v7.0, it is possible to hide/show all Ribbon controls on the page at once by using the methods without parameters:

// hides all Ribbon controlsribbon.hide();// shows all Ribbon controlsribbon.show();

Disabling and enabling controls#

You can disable or enable controls. The related methods - enable() and disable() - take the IDs of controls as parameters:

ribbon.disable("add_btn");ribbon.enable(["save_btn","del_btn"]);

Related sample: Ribbon. Enable/Disable Ribbon Item

Starting from v7.0, it is possible to disable/enable all Ribbon controls on the page at once by using the methods without parameters:

// disables all Ribbon controlsribbon.disable();// enables all Ribbon controlsribbon.enable();

Checking if a Ribbon item is disabled#

To check if an item of Ribbon is disabled, call the isDisabled() method. The method takes one parameter:

id(string, number) an id of an item

ribbon.isDisabled("1"); // -> true/false

Related sample: Ribbon. Enable/Disable Ribbon Item

Selecting/Unselecting an item#

Selecting a ribbon item#

To select a particular Ribbon item, make use of the select() method of Ribbon. The method takes two parameters:

id(string, number) an id of an item
unselect(boolean) optional, true - to unselect previously selected items, otherwise - false; true by default

ribbon.select("print");

Related sample: Ribbon. Select/Unselect

Unselecting a ribbon item#

To remove selection from a selected item, apply the unselect() method of Ribbon. The method may take the id of an item as a parameter:

// unselects a specified selected itemribbon.unselect("print");

It is also possible to remove selection from all previously selected items of Ribbon via the unselect() method:

// unselects all previously selected itemsribbon.unselect();

Related sample: Ribbon. Select/Unselect

Checking if a ribbon item is selected#

To check if an item of Ribbon is selected, call the isSelected() method. The method takes one parameter:

id(string, number) an id of a ribbon item

ribbon.isSelected("print"); // -> returns true/false

Related sample: Ribbon. Select/Unselect

Getting selected items#

To get the selected items, call the getSelected() method. The method returns an array of IDs of selected items:

ribbon.getSelected(); // -> ["selected_1", "selected_1.1"]

Using Tree collection API#

Adding controls#

You can add controls dynamically with the add() method of TreeCollection.

ribbon.data.add({    type:"button",    icon:"dxi-plus",    value:"New"},-1,"blockId");

Related sample: Ribbon. Add

This is how you can add a block of controls:

ribbon.data.add({    label:"File",    type:"block",    id:"files",    direction:"row",    items: [        {            icon: "dxi dxi-undo",            size: "small",            ribbonHeight: "double"        },        {            icon: "dxi dxi-redo",            size: "small",            ribbonHeight: "double"        }    ]});

Getting controls by IDs#

You can get a particular Ribbon control by its ID via the getItem() method:

var add_btn = ribbon.data.getItem("add_btn");

To get the ID of the parent of the control, call the getParent() method:

var parentId = ribbon.data.getParent("add_btn");

You can also access the children of a control with the getItems() method:

var items = ribbon.data.getItems("block1");

You can use the getLength() method of TreeCollection to count children of a control:

ribbon.data.getLength("block1");

Iterating through controls#

You can work with all (or some) Ribbon controls with the help of the map() method of TreeCollection:

ribbon.data.map(function(item){    // remove all icons    item.icon = "";});ribbon.paint();

Iterating through children#

To iterate through all controls in a particular block, pass one more parameter to map() - the ID of the block:

ribbon.data.map(function(item){    // remove all icons    item.icon = "";},"bl_1");ribbon.paint();

If you want to iterate only through immediate children, pass a third parameter - false:

ribbon.data.map(function(item){    /// remove all icons    item.icon = "";},"bl_1",false);ribbon.paint();

Iterating through children is also can be done with the eachChild() method of TreeCollection:

ribbon.data.eachChild("bl_1",function(item){    // remove all icons    item.icon = "";});ribbon.paint();

To access only the immediate children, add the direct parameter and set it to false:

ribbon.data.eachChild("bl_1", function(item){    // remove all icons    item.icon = "";},false);ribbon.paint();

To check whether an item has childs, use the haveItems() method of TreeCollection:

ribbon.data.haveItems("block1");// -> true

Iterating through parents#

To iterate through all the parent items (the immediate parent and its parent, etc. until the parent is the ribbon itself), use the eachParent() method of TreeCollection:

ribbon.data.eachParent("new_btn",function(item){    console.log(item)});

Rearranging Ribbon controls#

You can move Ribbon items to different positions with the move() method of TreeCollection. For example, this is how you can move a block with ID "bl_2" to the right edge of the Ribbon:

ribbon.data.move("bl_2",-1);
note

The ID should always be a string, even if in the configuration of control you've set it as a number.

To get the current position of a block, use the getIndex() method of TreeCollection:

ribbon.data.getIndex("bl_2");

Making copies of controls#

You can add a copy of a control and place it in the specified position on the ribbon with the copy() method of TreeCollection:

ribbon.data.copy("block1",2);

You can copy a control into a block of the same ribbon:

ribbon.data.copy("save_btn",1,ribbon.data,"block2");

You can also copy a control and place it into another ribbon:

ribbon1.data.copy("save_btn",1,ribbon2.data,"block3");

Clearing Ribbon#

To remove all controls from Ribbon, users should call the removeAll() method of TreeCollection. Afterwards, you can load other items.

ribbon.data.removeAll();ribbon.data.parse(new_controls);