Skip to main content

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.

info

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" }
]
}
note

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"
}
note

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>"
}
note

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"
}
note

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"
}
note

View the full list of properties of the input object in the related article.

// navItem
{
type: "navItem",
value: "Some",
icon: "dxi-check"
}
note

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: []
}
note

View the full list of properties of the selectButton object in the related article.

Separator template​

// separator
{
id: "sepId",
type: "separator"
}
note

View the full list of properties of the separator object in the related article.

Spacer template​

// spacer
{
id: "spacerId",
type: "spacer"
}
note

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"
}
note

View the full list of properties of the title object in the related article.