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"}
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 controls
ribbon.hide();
// shows all Ribbon controls
ribbon.show();
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 controls
ribbon.disable();
// enables all Ribbon controls
ribbon.enable();
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
Related sample: Ribbon. Enable/Disable 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");
Related sample: Select/unselect - DHTMLX Ribbon
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();
Related sample: Select/unselect - DHTMLX Ribbon
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
Related sample: Select/unselect - DHTMLX Ribbon
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"]
You can add controls dynamically with the add() method of TreeCollection.
ribbon.data.add({
type:"button",
icon:"dxi-plus",
value:"New"
},-1,"blockId");
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"
}
]
});
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");
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();
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
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)
});
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");
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");
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);
Back to top