Data loading
You can load data into DHTMLX Ribbon in two ways:
- During Ribbon initialization
- After Ribbon initialization
Both ways start from a prepared data set.
Preparing data set
DHTMLX Ribbon expects data in JSON format.
If you specify id fields in the tree collection, their values must be unique. You can also omit these fields. In this case Ribbon generates the values automatically.
The following data set is valid:
const data = [
{
type: "block",
items: [
{
value: "New",
icon: "dxi dxi-file-outline",
size: "small"
}
]
},
{
type: "block",
direction: "col",
items: [
{
value: "Add",
icon: "dxi dxi-plus",
size: "small"
},
{
value: "Remove",
icon: "dxi dxi-delete",
size: "small"
}
]
}
];
Each object in the data set configures a Ribbon control. The JSON format templates section lists templates for all Ribbon controls.
Loading data on initialization
You can load a predefined data set into Ribbon during initialization. Use the data configuration property:
const ribbon = new dhx.Ribbon("ribbon_container", {
css: "dhx_widget--bordered dhx_widget--bg_white",
data: data
});
Related sample: Ribbon. Initialization with config.data
Loading data after initialization
You can load data into Ribbon after initialization in two ways:
Loading from a local source
The parse() method of TreeCollection loads data into a ribbon from an array. Pass a predefined data set to this method:
ribbon.data.parse(data);
Related sample: Ribbon. Initialization with data.parse()
Loading from an external file
The load() method of TreeCollection loads all ribbon data from an external JSON file at once. The method takes the path to the file as a parameter:
ribbon.data.load("[path to this file]/file.json");
Related sample: Ribbon. Initialization with data.load()
The component makes an AJAX call and expects the remote URL to return valid JSON data.
Ribbon loads data asynchronously, so place the code that depends on the loaded data into the then() callback:
ribbon.data.load("/some/data").then(function(){
// some logic here
});
Saving and restoring state
The serialize() method of TreeCollection saves the current state of a ribbon. The method converts ribbon data into an array of JSON objects. Each JSON object contains the configuration of a separate Ribbon control.
const state = ribbon1.data.serialize();
You can parse the saved state array into a different ribbon:
// creating a new ribbon
const ribbon2 = new dhx.Ribbon("ribbon_container2");
// parsing the state of ribbon1 into ribbon2
ribbon2.data.parse(state);
JSON format templates
This section shows JSON format templates for Ribbon controls.
Common template
// common
[
{id: "item_a", type: "button", ...},
{id: "item_b", type: "input", ...},
{id: "item_c", type: "title", ...}
]
Related sample: Ribbon. Initialization with config.data
Block template
// block
{
type: "block",
title: "Action",
items: [
{ id: "copy", icon: "mdi mdi-content-copy", value: "Copy" },
{ id: "cut", icon: "mdi mdi-content-cut", value: "Cut" }
]
}
View the full list of properties of the block object in the related article.
Button template
// button
{
id: "add",
type: "button",
icon: "dxi-plus",
value: "Add",
count: 11,
tooltip: "Add a new user"
}
View the full list of properties of the button object in the related article.
Custom HTML template
// custom HTML
{
id: "custom_html",
type: "customHTML",
html: "<div style='height:30px; border: 2px solid'>My HTML button</div>"
}
View the full list of properties of the customHTML object in the related article.
ImageButton template
// imageButton
{
id: "user",
type: "imageButton",
src: "../img/avatar.png"
}
View the full list of properties of the imageButton object in the related article.
Input template
// input
{
id: "lookup",
type: "input",
value: "",
placeholder: "Type in to search...",
width: 100,
label: "Search"
}
View the full list of properties of the input object in the related article.
NavItem template
// navItem
{
type: "navItem",
value: "Some",
icon: "dxi-check"
}
View the full list of properties of the navItem object in the related article.
SelectButton template
// selectButton
{
id: "select",
type: "selectButton",
icon: "dxi-some",
items: []
}
View the full list of properties of the selectButton object in the related article.
Separator template
// separator
{
id: "sepId",
type: "separator"
}
View the full list of properties of the separator object in the related article.
Spacer template
// spacer
{
id: "spacerId",
type: "spacer"
}
View the full list of properties of the spacer object in the related article.
Title template
// title
{
id: "collection",
type: "title",
value: "Music",
tooltip: "Current collection"
}
View the full list of properties of the title object in the related article.