Data Loading

There are several simple ways of loading data into dhtmlxRibbon:

  • load data from an external file
  • load data from a local data source

First, you need to prepare a data set that will be loaded into Ribbon.

Preparing data set

dhtmlxRibbon expects loaded data in the JSON format. Here is an example of an appropriate data set:

var 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"
            }
        ]
    }
 
];

A data set consists of objects with configurations of Ribbon controls. Templates for Ribbon controls in JSON format are given below.

Loading from a local source

You can load data to a ribbon from an array with the parse() method of TreeCollection. Pass a predefined data set as a parameter of this method:

ribbon.data.parse(data);

Loading from an external file

The load method loads the ribbon data from an external JSON file. All the data are loaded at once. The parameter of the method is the path to the JSON file.

ribbon.data.load("[path to this file]/file.json");

The component will make an AJAX call and expect the remote URL to provide valid JSON data.

Data loading is asynchronous, so you need to wrap any after-loading code into a promise:

ribbon.data.load("/some/data").then(function(){
   // some logic here
});

Saving and restoring state

To save the current state of a ribbon, use the serialize() method of Tree Collection. It converts the data of a ribbon into an array of JSON objects. Each JSON object contains the configuration of a separate Ribbon control.

var state = ribbon1.data.serialize();

Then you can parse the data stored in the saved state array to a different ribbon. For example:

// creating a new ribbon
var ribbon2 = new dhx.Ribbon(document.body);
// parsing the state of ribbon1 into ribbon2
ribbon2.data.parse(state);

JSON format templates

This section will give you the idea of JSON format templates for separate Ribbon controls.

Common template

// common
[
    {id: "item_a", type: "button", ...},
    {id: "item_b", type: "input", ...},
    {id: "item_c", type: "text", ...}
]

Block

The Block object has the following properties:

  • type - (string) the type of a control, set it to "block"
  • id - (string) the id of a control, auto-generated if not set
  • title - (string) sets a text label beneath the block
  • direction - (string) defines the layout of controls within the block: "col" or "row"; controls that do not fit in one row/column are automatically placed in the next row/column
  • items - (array) an array of nested controls
  • css - (string) adds a custom CSS class to the block
{
   type: "block",
   title: "Action",        
   items: [
     { id: "copy", icon: "mdi mdi-content-copy", value: "Copy" },
     { id: "cut", icon: "mdi mdi-content-cut", value: "Cut" }
   ]
}

Button

The button object has the following properties:

  • type - (string) the type of a control, set it to "button"
  • id - (string) the id of a control, auto-generated if not set
  • css - (string) adds style classes to a button
  • hotkey - (string) the name of the hot key for the button
  • value - (string) a value of the button
  • tooltip - (string) a tooltip for the button
  • count - (number) a badge with a number
  • countColor - (string) the color of a badge with number: "danger" | "secondary" | "primary" | "success"
  • items - (array) an array of nested controls
  • group - (string) defines the name of a group of controls a button belongs to. If one of the buttons in the group becomes active, all others automatically become inactive
  • twoState - (boolean) the flag that defines whether a button can be used in two states: active (pressed) and inactive (unpressed)
  • active - (boolean) for twoState buttons, if true, the button is in the active state
  • multiClick - (boolean) defines the behavior of the Undo/Redo buttons:
    • true - all the actions are reverted/re-applied one by one when the Undo/Redo button is clicked and held
    • false - one action is reverted/re-applied on each click of the Undo/Redo button
  • icon - (string) an icon of the button
  • view - (string) defines the look of a button: "flat"|"link"
  • size - (string) defines the size of a button: "small"|"medium"
  • color - (string) defines the color scheme of a button: "danger"|"secondary"|"primary"|"success"
  • full - (boolean) extends a button to the full width of a form
  • circle - (boolean) makes the corners of a button round
  • loading - (boolean) adds a spinner into a button
// button
{
    id:         "add",              
    type:       "button",           
    icon:       "dxi-plus",         
    value:      "Add",              
    count:      11,                                 
    tooltip:    "Add a new user"    
}

Custom HTML Button

The customHTMLButton object has the following properties:

  • type - (string) the type of a control, set it to "htmlbutton"
  • id - (string) the id of a control, auto-generated if not set
  • html - (string) a string with HTML that should be inserted into the button
  • twoState - (boolean) adds two states to the button: active (pressed) and inactive (unpressed)
  • active - (boolean) sets the state of a twoState button
  • value - (string) the value of a custom HTML button
  • count - (number) a badge with a number
  • tooltip - (string) a tooltip for the button
// custom HTML button
{
    id:"htmlbutton",
    html:"<div style='height:30px; border: 2px solid'>My HTML button</div>"
}

ImageButton

The imageButton object has the following properties:

  • type - (string) the type of a control, set it to "imageButton"
  • src - (string) the path to the image
  • value - (string) the value of a button
  • id - (string) the id of a control, auto-generated if not set
  • twoState - (boolean) adds two states to the button: active (pressed) and inactive (unpressed)
  • active - (boolean) sets the state of a twoState button
  • group - (string) defines the name of a group of controls a button belongs to. If one of the buttons in the group becomes active, all others automatically become inactive
  • hotkey - (string) the name of the hot key for the button
  • count - (number) a badge with a number
  • countColor - (string) the color of a badge with number: "danger" | "secondary" | "primary" | "success"
  • size - (string) defines the size of a button: "small"|"medium"|"auto"
  • tooltip - (string) a tooltip for the button
// imageButton
{
    id:       "user",               
    type:     "imageButton",        
    src:      "../imgs/avatar.png"              
}

Input

The input object has the following properties:

  • type - (string) the type of a control, set it to "input"
  • id - (string) the id of a control, auto-generated if not set
  • icon - (string) the name of an icon from the used icon font
  • placeholder - (string) a tip for the input
  • width - (number) the width of the input field
  • label - (string) a text label for the Input control
  • value - (string) the initial value of the field
  • tooltip - (string) a tooltip for an input
// input
{
    id:          "lookup",                    
    type:        "input",                     
    value:       "",                         
    placeholder: "Type in to search...",      
    width:       100,                         
    label:       "Search"
}

NavItem

The navItem object has the following properties:

  • type - (string) the type of a control, set it to "navItem"
  • id - (string) the id of a control, auto-generated if not set
  • css - (string) adds style classes to a navItem
  • value - (string) a value of the navItem
  • tooltip - (string) a tooltip for the navItem
  • count - (number) a badge with a number
  • countColor - (string) the color of a badge with number: "danger" | "secondary" | "primary" | "success"
  • items - (array) an array of nested controls
  • icon - (string) an icon of the navItem
  • size - (string) defines the size of a navItem: "small"|"medium"|"auto"
// navItem
{
    type:"navItem", value:"Some",
    icon:"dxi-check"
}

SelectButton

The selectButton object has the following properties:

  • type - (string) the type of a control, set it to "selectButton"
  • id - (string) the id of a control, auto-generated if not set
  • icon - (string) the name of an icon from the used icon font
  • value - (string) a value of the button
  • items - (array) an array of nested controls
  • size - (string) defines the size of a button: "small"|"medium"
  • tooltip - (string) a tooltip for the SelectButton control
// selectButton
{
    id:"select",
    type:"selectButton",
    icon:"dxi-some",
    items:[]
}

Separator

The separator object has the following properties:

  • type - (string) the type of a control, set it to "separator"
  • id - (string) the id of a control, auto-generated if not set
// separator
{
    id:     "sepId",        
    type:   "separator"     
}

Spacer

The spacer object has the following properties:

  • type - (string)the type of a control, set it to "spacer"
  • id - (string) the id of a control, auto-generated if not set
// spacer
{
    id:     "spacerId",     
    type:   "spacer"        
}

Title

The title object has the following properties:

  • type - (string) the type of a control, set it to "title"
  • id - (string) the id of a control, auto-generated if not set
  • value - (string) the value of the Title control
// title
{
    id:         "collection",       
    type:       "title",                
    value:      "Music",                
    tooltip:    "Current collection"    
}
Back to top