Toolbar Configuration Settings

The toolbar contains a panel with instruments for editing and formatting the content of the table's cells.

The structure of toolbar can be presented as:

  • Toolbar:
    • File block
      • Sheets select
      • Import from Excel button
      • Export to Excel button
      • Print button
      • Hide/show print borders button
    • Undo/Redo block
      • Undo button
      • Redo button
    • Font block:
      • Font family select
      • Font size select
      • Font type buttons
      • Font color select
      • Background color select
      • Borders select
    • Align block:
      • Horizontal Align button
      • Vertical Align button
      • Text Wrap button
      • Merge button
      • "Increase indent" button
      • "Decrease indent" button
    • Number block:
      • Number format select
      • Increase decimal places button
      • Decrease decimal places button
    • Edit block:
      • Sort A to Z button
      • Sort Z to A button
      • Create filter button
      • Named range button
      • Conditional format button
      • Lock/unlock cell button
      • Add link button
      • Create dropdown button
      • Clear button
    • Insert block:
      • Image button
      • Graph button
      • Comment button
    • View block:
      • Row button
      • Column button
      • Hide/show gridlines button
      • Hide/show headers button
      • Freeze/unfreeze rows button
      • Freeze/unfreeze columns button
      • Hide/show formulas button

Toolbar Modes

There are two display modes of a toolbar: the "default" short one and the "full" one. In the default mode, the toolbar is shown with a limited set of buttons.

To show all available buttons on the toolbar, you should set the toolbar property to the "full" value:

webix.ui({
    view:"spreadsheet",
    data: base_data,
    toolbar: "full"
});

Related sample:  Toolbar with all buttons

To refer to the toolbar object, first you need to specify the id of a toolbar in the toolbar configuration.

var bar = {
    view: "toolbar",
    css: "webix_ssheet_toolbar webix_layout_toolbar",
    id: "bar",
    elements: [{...}]
}

Then you can address the toolbar via its id.

spreadsheet.$$("bar");

Settings for the default toolbar are specified in the buttons configuration object. It contains the names of button blocks as parameters. The parameters' values are arrays of buttons that are included into the blocks.

buttons: {
    "undo": ["undo","redo"],
    "font": ["font-family","font-size","font-weight","font-style",
    "underline","strike","color","background","borders"],
    "align": ["text-align","vertical-align","wrap","span"],
    "format": ["format"]
}

The names of button blocks correspond to the properties defined in the localization files, which specify the language of its labels.

Customizing the "toolbar" Collection

The Toolbar's specificity is that it can include only one row of buttons. However, there is also a way to customize the Toolbar so that it would have a multi-row structure. In this case the "toolbar" collection should be used. It allows specifying the width and height of buttons, setting margins and paddings and setting separators between the blocks of buttons.

The key points of the custom toolbar are the following:

  • the Toolbar elements are placed into the toolbar object
  • Toolbar has the Layout structure and the buttons' arrangement is defined by columns and rows (it allows making more than one row of buttons)
  • a button extending a preset button should include the $button property with the button's name as a value
  • the buttons' offsets can be set and managed using the padding and margin properties
  • the labels of the buttons' blocks are defined by the ssheet-bar-title view with the help of templates
  • the default sizes of buttons and templates can be changed using the width and height properties
  • a separator between views can also be added using the ssheet-separator view
 toolbar: [
    {
        rows:[
          {
            margin: 2,
            cols: [
                {$button: "undo"},
                {$button: "redo"}
            ]
          },
          {},
          {template: "Undo/Redo", view: "ssheet-bar-title", height: 24}
        ]
    },
    {view: "ssheet-separator"},
    {
        rows:[
           {
             margin: 2,
             cols:[
                {$button: "font-family", width: 167},
                {$button: "font-size", width: 90}
             ]
           },
           ...
        ]
    },
    ...
]

Related sample:  Custom toolbar

Full Code for Toolbar elements

The full code for all toolbar elements is given in a separate article.

Toolbar Buttons

This section provides a detailed description of each block of buttons, their names and their purposes.

File block

webix.ui({
  view: "spreadsheet",
  data: base_data,
  toolbar: [
    {
      rows: [
        {
          margin: 2,
          cols: [
            {
              name: "sheet",
              view: "ssheet-button-icon-top",
              label: "Sheets",
              arrow: true,
              options: [
                { id: "new-sheet" },
                { id: "copy-sheet" },
                { id: "remove-sheet" },
                { id: "hide-sheet"}
              ],
            },
            {
              rows: [{ $button: "excel-import" }, { $button: "excel-export" }],
            },
            {
              rows: [{ $button: "print" }, {$button: "print-borders"}],
            },
          ],
        },
      ],
    },
  ]
});

It includes the "sheet" select, which allows working with a sheet and contains four options:

  • "new-sheet" - for creating a new sheet
  • "copy-sheet" - for copying the sheet's content into a new sheet
  • "remove-sheet" - for removing a sheet
  • "hide-sheet" - for hiding a sheet

and four buttons:

  • "excel-import" button allows importing data from Excel
  • "excel-export" button allows exporting data into Excel
  • "print" - for printing the data from a sheet
  • "print-borders" - toggles the visibility of the printing borders

Undo/Redo block

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        { $button: "undo", view: "ssheet-button", label: "Undo", width: 80 },
        { $button: "redo", view: "ssheet-button", label: "Redo", width: 80 },
      ],
    },
  ]

It includes two buttons:

  • the "undo" button discards the recent change and Spreadsheet reverts to its previous state
  • the "redo" button restores the cancelled (undone) change

Font block

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        {
          margin: 2,
          cols: [
            {
              margin: 2,
              cols: [
                {
                  $button: "font-family",
                  width: (webix.skin.$active.inputHeight + 2) * 4 + 6,
                },
                { $button: "font-size" },
              ],
            },
            { $button: "borders" },
          ],
        },
        {
          margin: 2,
          cols: [
            {
              margin: 2,
              cols: [
                { $button: "font-weight" },
                { $button: "font-style" },
                { $button: "underline" },
                { $button: "strike" }
              ],
            },
            { $button: "background" },
            { $button: "color" },
          ],
        },
      ],
    },
  ]

This block contains a large group of buttons for setting fonts and cell borders:

  • the "font-family" select allows choosing the necessary font
  • the "font-size" select sets the font size
  • the Font group of buttons helps to make the content of the cell bold, italic, underlined or strikethrough:
    • the "font-weight" button
    • the "font-style" button
    • the "underline" button
    • the "strike" button
  • the "color" select sets the font color
  • the "background" select sets the background color
  • the "borders" select is used to apply a new style for cell borders

Align block

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        {
          margin: 2,
          cols: [{ $button: "text-align" }, 
                 { $button: "span" }, 
                 {$button: "increase-indent"}],
        },
        {
          margin: 2,
          cols: [{ $button: "vertical-align" }, 
                 { $button: "wrap" }, 
                 {$button: "decrease-indent"}],
        },
      ],
    },
  ]

Beside managing Horizontal and Vertical cell alignment, this block also includes means of text wrapping, indenting text in a cell to the left or to the right, merging cells' content:

  • the "text-align" select allows specifying one of the three modes of text alignment in a cell: left, right or center
  • the "vertical-align" select defines the mode of vertical text alignment in a cell: top, middle or bottom
  • the "wrap" button lets wrap text in a cell
  • the "span" button allows merging the content of several cells as well as splitting it
  • the "increase-indent" button indents text in a cell to the right
  • the "decrease-indent" button indents text in a cell to the left

Number block

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        { $button: "format" },
        {
          margin: 2,
          cols: [
            { $button: "increase-decimals" },
            { $button: "decrease-decimals" },
          ],
        },
      ],
    },
  ]

This block contains the "format" select, which sets the format of cell content. The available formats are:

  • Common
  • Currency
  • Number
  • Percent
  • Custom

Besides, it includes a pair of buttons "increase-decimals" and "decrease-decimals" which allow increase/decrease the number of decimal places.

Edit block

  view: "spreadsheet",
  toolbar: [
    {
      padding: 3,
      rows: [
        {
          cols: [
            { $button: "sort-asc" },
            { $button: "create-filter" },
            { $button: "conditional-format" },
            { $button: "add-link" },
            { $button: "clear" },
          ],
        },
        {
          cols: [
            { $button: "sort-desc" },
            { $button: "add-range" },
            { $button: "lock-cell" },
            { $button: "add-dropdown" },
          ],
        },
      ],
    },
  ]

The block includes a set of buttons for editing the cell's content:

  • the "sort-asc" and "sort-desc" buttons are used for sorting in ascending and descending directions
  • the "create-filter" button sets a filter in a cell
  • the "add-range" button sets a named range of cells for using it further in math formulas
  • the "conditional-format" button allows specifying a particular style for a cell, depending on a certain condition
  • the "lock-cell" button blocks/allows editing of the cell's value
  • the "add-link" button sets a link in a cell
  • the "add-dropdown" button creates an editor with options in a cell
  • the "clear" select contains a set of options for clearing a cell:
    • the "clear-value" - for clearing the cell value
    • the "clear-style" - for clearing styles applied to a cell
    • the "clear-conditional-formats" - for clearing conditional formatting applied to a cell
    • the "clear-dropdown-editors" - for clearing applied filters and dropdown lists
    • the "clear-all" - for clearing all of the above

Insert block

  view: "spreadsheet",
  toolbar: [
    {
      padding: 3,
      rows: [
        {
          cols: [
            {
              $button: "image",
              view: "ssheet-button",
              label: "Image",
              width: 110,
            },
            {
              $button: "add-comment",
              view: "ssheet-button",
              label: "Comment",
              width: 110,
            },
          ],
        },
        { $button: "graph", view: "ssheet-button", label: "Graph", width: 110 },
      ],
    },
  ]
  • the "add-image" button adds an image into a cell
  • the "add-sparkline" button inserts a sparkline into a cell
  • the "add-comment" button adds a comment into a cell

View block

  view: "spreadsheet",
  toolbar: [
    {
        padding: 3,
        rows:[
          {
            cols:[
                  {rows:[
                            {$button:"row"},
                            {$button:"column"}
                        ]},
                  {rows:[
                            {$button:"hide-gridlines"},
                            {$button:"hide-headers"},
                        ]},
                  {rows:[
                            {$button:"freeze-rows"},
                            {$button:"freeze-columns"}
                        ]},
                  {rows:[
                            {$button:"show-formulas"},
                            {}
                        ]}
                ]
            },
        ]
    },
  ]
  • the "row" button is used to insert, delete, hide, show rows
  • the "column" button is used to insert, delete, hide, show columns
  • the "hide-gridlines" button toggles gridlines of Spreadsheet
  • the "hide-headers" button toggles the headers of rows and columns
  • the "show-formulas" button shows formulas in cells instead of values
  • the "freeze-rows" button freezes and unfreezes rows
  • the "freeze-columns" button freezes and unfreezes columns

Customizing Buttons

The SpreadSheet toolbar contains blocks of buttons grouped according to their functionality. The arrangement of button blocks in the toolbar is specified in the "buttons" collection.

Removing a block or a button

In case you want to remove some block or button specified in the default configuration, don't define them in the buttons object.

Defining Buttons Position

Buttons object contains a hash of data, where the key is the name of a block of buttons and the value is an array of button names.

There are four blocks of buttons on the toolbar by default:

  • “undo” - Undo/Redo
  • “font” - all operations related to font and color manipulations
  • “align” - align operations including cell span and text wrap
  • “format” - number format settings
webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
       "font": ["font-family","font-size","font-weight","font-style",
            "underline","strike","color","background","borders"],
       "align": ["text-align","vertical-align","wrap","span"],
       "format": ["format"]
   }
});

You can add a new block with or without a name. To hide the name of the block, begin the name with a dollar sign.

You can specify the title of the buttons block in the Spreadsheet locale.

To define a preset button in the toolbar, you only need to state its name.

Adding text buttons

To add a new text button, you need to put an object with the configuration of the button (including its name) into the corresponding block set in the buttons property:

webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
        ...
       "My Block": [
           {   view: "button", name: "a", width: 40, label: "New button" }, 
           ...
       ]
    }
});

Related sample:  Text buttons

Adding icon buttons

For icon buttons in SpreadSheet we recommend to define the following settings in order to fit the general SpreadSheet appearance:

  • set the width equal to 40px
  • use "webix_ssheet_button_icon" as a part of the icon element classname
  • as a background-image use simple icons with transparent background and the #787878 color

For example, you can specify icon buttons in the following way:

webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
       ...
       "Insert": [
        {
           view: "button", name: "insert-image", width: 40,
           label: "<span class='webix_ssheet_button_icon icon_image'></span>",
           tooltip: "Insert image", click: insertImage
         }
       ]
   }
});

Related sample:  Icon buttons

Grouping Buttons

If the number of buttons you want to show exceeds the Toolbar's width, you can group them. For this purpose, add an icon button and attach a popup to it. This popup will contain all buttons of the group.

Use the code below to create such a structure:

webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
       ...
       "$other": [
          {},
          {
            view: "button",  name: "a", width: 40,
            label: "<span class='webix_ssheet_button_icon icon_other'></span>",
            tooltip: "Other options", popup: $$("mypopup")
          }
       ]
   }
});

Related sample:  Additional buttons

Customizing Popups

Popup with Icon Buttons

To create a popup with icons, use the datasuggest view and put the "ssheet-icons" view in its body:

webix.ui({
   id: "mypopup",
   view: "datasuggest",
   body:{
       view: "ssheet-icons",
       xCount:3,
       yCount:1,
       tooltip: {
           template: "#title#"
       }
   },
   data: [
       {id: "insert_image", css: "bar_chart", title: "Bar"},
       {id: "insert_chart", css: "line_chart",  title: "Line"},
       {id: "insert_column", css: "pie_chart", title: "Pie"}
   ]
});

The “ssheet-icons” is a Dataview-based view. So, you can set the layout for icons using the xCount and yCount properties of DataView.

The css property in data items defines the CSS rule where you can define the background image:

.bar_chart{
   background: url("images/bar-chart.svg");
}

Related sample:  Icon buttons in popup

Styling Icons in Popups

The style of icons used in popups should be consistent with the rest of the icons in the toolbar. To achieve this, follow the tips below:

  • use "webix_ssheet_button_icon" as a part of the icon element classname
  • as a background-image use simple icons with transparent background and the #787878 color

Popup with Named Buttons

A popup can be attached to a button with the help of the popup property. You need just to set this property in the configuration of the button.

webix.ui({
   view:"spreadsheet",
   buttons: {
       ...
       "$other": [
           { view: "button", popup: $$("mypopup"),...}
       ]
   }
});

It's also possible to call the show() method and pass the DOM element of a button to show the popup, like this:

$$("mypopup").show($$("mybutton").$view);

Related sample:  Additional buttons

List Popups

To create a list popup, use the “ssheet-suggest” view. This view is based on the ContextMenu view. Therefore, it supports sub-popups and line separators:

webix.ui({
   id: "mypopup",
   view: "ssheet-suggest",
   template: "<span class='webix_ssheet_button_icon #icon#'></span> #value#",
   data:[
       { id: "insert_image", icon: "image", value: "Insert image"},
       { id: "insert_chart", icon: "chart",  value: "Insert chart"},
       { $template: "Separator" },
       { id: "insert_column", icon: "column", value: "Insert column"},
       { id: "insert_row", icon: "row",  value: "Insert row"}
   ]
});

Form Popups

You can also create a form popup and attach it to a Spreadsheet button.

Follow the tips below to set form controls inside of the popup properly:

  • use only the bottom border
  • set placeholders
  • apply "webix_ssheet_suggest" CSS and set padding to 0 for a suggest of a form control
  • use the "ssheet-colorpicker" view as a color selector

To apply correct borders for all controls in this popup, you can use the “ssheet-form-popup” view instead of “popup” and the "ssheet-form-suggest" one for the control's suggests:

webix.ui({
   id: "mypopup",
   view: "ssheet-form-popup",
   body: {
       view: "form",
       borderless: true,
       elements:[
            {view: "text", placeholder: "Name",...},
            {view: "richselect", label: "Type", placeholder: "Select", suggest:{
               view:  "ssheet-form-suggest",
               data:["Area","Bar","Line"]
            }},
            {view: "ssheet-colorpicker", label: "Color"}
      ]
   }
});

Related sample:  Popup with Form

Customizing Dialogs

Form controls in a SpreadSheet dialog follow the same rules as popup controls do. We recommend to use the "ssheet-dialog" view to create a dialog instead of the window one.

The "ssheet-dialog" view applies styling for the header and adds three buttons: the Close icon at the top and two buttons (Cancel and Save) at the bottom.

To define the title of the dialog, use the head property.

webix.ui({
   id: "mydialog",
   view: "ssheet-dialog",
   head: "Editor",
   body: {
       view: "form",
       elements:[
           ...
       ]
   }
});

Related sample:  Dialog

The Close icon settings

The background of this icon is defined by the “webix_ssheet_hide_icon” CSS.

.webix_ssheet_hide_icon{
   background: url("images/edit.svg");
}

The dialog fires the onHideClick event on the icon click:

on:{
   onHideClick: function(){
       // click happened 
       this.hide();
   }
}

The Cancel and Save buttons

The Cancel and Save buttons are added for dialogs automatically. Set the buttons property to false, if you don’t want to show them:

view: "ssheet-dialog",
buttons: false,

The buttons' titles are specified in the SpreadSheet locale:

webix.i18n.spreadsheet.labels.cancel = "Cancel";
webix.i18n.spreadsheet.labels.save = "Save";

The dialog fires the following events on a button click: onCancelClick and onSaveClick.

Adding DataTable

Besides form controls you can add any views into the dialog, e.g. a datatable. In this case we recommend you to choose the "ssheet-dialog-table" view to apply the appropriate styling.

webix.ui({
    id: "mydialog",
    view: "ssheet-dialog",
    head: "Editor",
    body: {
        cols:[
            {
                view: "ssheet-dialog-table", autowidth: true, autoheight:1,autoConfig:true,
                data:[
                    {id: 1, name: "Range1", range: "A3:C8"},
                    {id: 2, name: "Range2", range: "D3:F8"}
                ]
            },
            {
                view: "form",
                elements:[
                    ...
        ]}
    ]}
});

Related sample:  DataTable in Dialog

Back to top