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"]);

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 controls
ribbon.hide();
// shows all Ribbon controls
ribbon.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"]);

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 controls
ribbon.disable();
// enables all Ribbon controls
ribbon.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) an id of an item

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

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) an id of an item
unselect	(boolean) optional, true - to unselect previously selected items, otherwise - false; true by default

ribbon.select("print");

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 item
ribbon.unselect("print");

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

// unselects all previously selected items
ribbon.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) an id of a ribbon item

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

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);

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);