Start

Webix - JavaScript UI Framework for desktop and mobile browsers.

Meet Webix 3.3!

  • New layout widgets: AbsLayout and DataLayout
  • Drag-n-drop for component items on touch devices
  • Sparklines for DataTable and TreeTable

and many more...


Start

Overview

Webix is a cross-browser, cross-device JavaScript framework for building interactive web applications using JavaScript, CSS, HTML5 techniques. The library delivers over 70 fully customizable components, provides JQuery integration and can work with any server-side platform: PHP, .NET, Java, etc. Flexible layouts, unlimited extensibility, controllable look-and-feel, and intuitive API allow creating apps of any difficulty that will work equally well on desktop, mobile and tablet devices.

Main features
1. Rich UI
The library supplies over 70 fully customizable components such as form, tree, grid, list etc.

2. Supported data formats: xml, json, jsarray, csv
Developers can use their favourite formats to specify data. All popular data formats are supported.

3. Intuitive JS OOP
Simple and light weight code provides easy and understandable OOP concepts.

4. Simple integration with server side
Some platforms (PHP, .NET, Java) have ready solutions for data loading, saving, exporting.

5. Full API support
A full range of API with the detailed descriptions is available.

6. Unlimited extensibility
Webix doesn't limit developers in functionality and provides abundant possibilities in extending existent components and creating new ones.

7. Support for internationalization and localization
Support for internationalization allows applications be translated and modified into local versions for hundreds of languages.

8. Styling with standard css
You can use CSS in conjunction with components content to achieve the desired look-and-feel. CSS can be applied to the whole layout or to specific components, items etc.

9. Flexible layouts
Each element in the layout can be configured individually or as a part of layout: width, height, color etc.

10. On-the-fly filtering and sorting
The library offers rich means of filtering and sorting, starting from built-in tools and ending with fully custom filtering logic.

11. Possibility to show or hide components
Any component in the layout can be hidden (showed) programmatically.

12. Integration with jQuery
Webix is integrated with jQuery that allows you to follow the main mantra of the jQuery library while developing - running with the least amount of configuration.

13. Dynamically fetching data from the server when the component is scrolled up and down
While working with large datasets, a developer can load data dynamically to reduce complexity and improve performance. Polling interval and the number of loaded records are controlled.

14. Callbacks for all events: load, sorting, etc.
Numerous events let you handle any action or proceeding that can happen in the app.

15. Inline editing
All data containing components can be directly edited on the page, saving users from having to go to a separate page first.

16. Drag-and-drop
Users have the possibility to drag-and-drop items of the components. The library supports both external and internal DND and allows customizing 'drag', 'drop' operations.

17. Integration with third party libraries
Webix can be integrated with various third party libraries: Backbone.js library, Google, Nokia and Yandex maps, Mercury, NicEdit, Tinymce and Code Mirror text editors, etc.

18. Copying to/from clipboard
By common CTRL+C/CTRL+V keyboard shortcuts data can be copied to some other application for further processing or moved within one or several components.

19. Offline support
Offline support allows your apps run and be updated offline and don't depend on the state of the network.

20. Data binding
Data binding is the technique that allows you to bind several components together and keep them in sync, i.e. when the data in some of components changes its value, the remaining components are automatically updated to reflect the change.

21. Variable length and localizable pagination
One or several pagers can be added to the app to display data page by page. Data will not be retrieved from server side until the related page is opened. The number of rows per page, templates for navigation controls are set up.


Start

Getting Started

Webix UI

Quick Start Guide

This tutorial gives you a detailed instruction how to make your first steps with Webix.
Start Coding with Webix

This tutorial introduces basic principles of using the Webix library for web app development.
Creating basic app

This tutorial discusses the main points of creating a simple app with the Webix library:

  • Setting Components
  • Interaction Between App Elements
  • Implementing Server-side Integration
    • Introduction to Events

    This tutorial explains the essence of Webix events model and discusses the basics of event processing.

    Webix DataTable

    Quick Start with Datatable

    This tutorial teaches how to create a simple app containing DataTable and populate it with data.

    Webix Documentation

    Webix Docs Guide

    This chapter guides you through the contents of Webix documentation and gives a short description of each section.


Quick Start Guide

Fast start

The following steps will take you to your own Webix based app.

  • Create a simple html-page. Specify HTML5 doctype for it.
<!DOCTYPE HTML>
<html>
    <head>
    <link rel="stylesheet" href="http://cdn.webix.com/edge/webix.css" type="text/css">
    <script src="http://cdn.webix.com/edge/webix.js" type="text/javascript"></script>
    </head>
    <body>
        <script type="text/javascript" charset="utf-8">
    /* place for UI configuration */
        </script>
    </body>
</html>
  • Define the UI configuration
webix.ui({
  rows:[
      { view:"template",
        type:"header", template:"My App!" },
      { view:"datatable",
        autoConfig:true,
        data:{
          title:"My Fair Lady", year:1964, votes:533848, rating:8.9, rank:5
        }
      }
  ]
});

And that is all. Just open the page in a browser and you have a working mini app.

What's next
  • Read a more detailed introduction to the library

or check one of interactive tutorials

  • Interactive step-by-step tutorial
  • Interactive DataTable tutorial
  • Interactive Form tutorial


Beginner

Introduction to Webix

Including library

1 . Create a simple html-page. Specify HTML5 doctype for it.

2 . Install Webix for your future app. There can be several ways:

Use CDN

Include 2 Webix files (webix.js and webix.css) directly from Webix CDN

<!DOCTYPE HTML>
<html>
    <head>
    <link rel="stylesheet" href="http://cdn.webix.com/edge/webix.css" type="text/css">
    <script src="http://cdn.webix.com/edge/webix.js" type="text/javascript"></script>
    </head>
    <body>
        <script type="text/javascript" charset="utf-8">

        // here your app will "take shelter"
        </script>
    </body>
</html>

If you need to get one of the older Webix versions, you should include the necessary number of the version into the links to the code files:

<link rel="stylesheet" href="http://cdn.webix.com/2.2/webix.css" type="text/css">
<script src="http://cdn.webix.com/2.2/webix.js" type="text/javascript"></script>

Use Bower/NuGet

Install local Webix files via Nuget or Bower package managers by a single command. You don't need to download anything.

NuGet

nuget install Webix

//If you use Microsoft Visual Studio, execute this from Package Manager Console
install-package Webix

Bower

bower install webix

Download Webix package

Download and unzip the library to the necessary directory. Include webix.js and webix.css files into the document's head section.

<!DOCTYPE HTML>
<html>
    <head>
    <link rel="stylesheet" href="../../codebase/webix.css" type="text/css">
    <script src="../../codebase/webix.js" type="text/javascript"></script>
    </head>
    <body>
        <script type="text/javascript" charset="utf-8">

... // here your app will "take shelter"
        </script>
    </body>
</html>

UI initialization

3 . The apps are to be placed between the script tags. The components you create are initialized inside the view.

Just a clean page

webix.ui({
  // components
});

Here you should be aware of the following:

  • to ensure that your code is executed after the page is fully loaded, you can make use of the webix.ready(function(){ ....}), which is our alternative to the onDocumentReady event;
webix.ready(function(){
  webix.ui({
      ....
  });
});

Next we'll declare base elements, create the app layout and finally nest it with ui components.

4 . At this step we'll specify an HTML container for the app with the following properties:

<style>
#app_here{
  width:1000px; height:400px; margin:20px;
}

</style>
...
<div id="app_here"></div>

Then we'll create a layout structure which will be put into the above created container:

  • a layout with 2 rows
  • the 2nd row will contain one more layout with 3 columns
webix.ui({
  container:"app_here",
  view:"layout", // optional
    rows:[
      {...},
        { view:"layout", // optional
         cols:[
           {...},
           {...},
           {...}
        ]}
    ]
});

As the value of the container property the id of HTML element should be specified.
Note that you can easily omit the view:"layout" lines and start setting rows and columns at once.

5 . Now we can insert some components into the layout view.

We'll put a template that will serve as the app's header into the 1st row.

webix.ui({
  container:"app_here",
    rows:[
      { view:"template", type:"header", template:"My App!"},
        { cols:[
           {...},
           {...},
           {...}
        ]}
    ]
});
  • you can easily omit the view:"template" definition;
  • the "header" type of template is used to set headers for layout rows/columns;

6 . It's high time to place components into the 2nd row. The 3 columns of the 2nd row will be occupied by Tree and DataTable components and a resizer line between them:

webix.ui({
  container:"app_here",
  rows:[
     { type:"header", template:"My App!" },
     { cols:[
      { view:"tree", id:"mytree", gravity:0.3, select:true, data:tree_data },
      { view:"resizer" },
      { view:"datatable", id:"mydatatable", autoConfig:true, data:small_film_set }
    ]}
     ]
});

Let's look at the above code in detail:

  • one of the key properties of any component and any item is its ID, the unique string or number that helps us refer to the object. ID should be specified if you are going to work with this component/item later as all functions are applied and events are attached to the component through its ID;
  • the gravity parameter sets relative size proportions for the elements within the common parent container;
  • the select property enables item selection in the tree;
  • the data parameter defines the datasource for the component;

We use JSON in the sample, so the items of the tree_data dataset look like this:

[
  { id: "1", type: "folder", value: "Music", css:"folder_music", data:[..child items..]},
    ...
]

The grid_data dataset includes data items in the next mode:

[
  { id:1, title:"The Shawshank Redemption", year:1994, votes:678790, rating:9.2, rank:1},
    ...
]
  • the autoConfig property creates columns of datatable on the basis of data properties. Headers of columns are based on property names in dataset.

7 . At the last step we'll illustrate the usage of ids. In order to refer to a component the following structure should be used - $$("id").
We will use the Tree method open to open the tree branches and the DataTable method select to select the 1st item of the datatable.

webix.ui({
  container:"app_here",
  rows:[
     { type:"header", template:"My App!" },
     { cols:[
      { view:"tree",id:"mytree", gravity:0.3, select:true, data:tree_data },
      { view:"resizer" },
      { view:"datatable", id:"mydatatable", autoConfig:true, data:grid_data }
    ]}
  ]
});

$$("mytree").open(1);
$$("mytree").open(2);

$$("mydatatable").select(1);

The ready app is presented in the following picture:

You can check the live demo and play with code by the next link http://webix.com/snippet/eadf0190

See also

  • Interactive step-by-step tutorial
  • Interactive DataTable tutorial
  • Interactive Form tutorial


Beginner

Start Coding with Webix

Working with the Webix library you should go through typical development stages that include setting goals and understanding the requirements, choosing components and designing the app to foresee the result and finish it all with the coding itself, which is merely a technical side.

  • Setting the goal
  • Preparing Workspace
  • Designing
  • Main principles of coding with the webix
  • HTML Containers
  • Code Optimization

Setting the goal

At this stage your should determine the app's functionality and evaluate the means of achieving this goal. You should clearly see the purpose of your future app and try to imagine all possible features it may need to meet the requirements.

Preparing Workspace

At this stage you define all the properties of your app and its components, play with event handlers and apply methods for your app to dance in the hands of users. You can check the state of your app in the real time just as you've put the last bracket/brace/colon after the code piece.

The lib package you download from the site includes two versions - debug and standard one. Debug version helps control the app during the development stage while standard script version goes for ready-made products. Both scripts are identical in terms of component building yet webix_debug.js version includes a number of handy debugging tools. Read more about the bonuses of the debug version.

All the coding can be done in any text editor that is capable of syntax highlighting (just for convenience sake) and save the code to desired format (js, html, php, xml etc.).

At the initial stage, you need to include Webix library files into your document. It's recommended to use HTML5 doctype.
There are 3 possible ways:

1) Include Webix files from Webix CDN

You can directly set links to webix.js and webix.css files located in Webix CDN:

<!DOCTYPE HTML>
<html>
    <head>
    <link rel="stylesheet" href="http://cdn.webix.com/edge/webix.css" type="text/css">
    <script src="http://cdn.webix.com/edge/webix.js" type="text/javascript"></script>
    </head>
    <body>
        <script type="text/javascript" charset="utf-8">

... // here your app will "take shelter"
        </script>
    </body>
</html>

By the way, if you need to get one of the older Webix versions, you can include the necessary number of version into the links to the code files:

<link rel="stylesheet" href="http://cdn.webix.com/2.2/webix.css" type="text/css">
<script src="http://cdn.webix.com/2.2/webix.js" type="text/javascript"></script>

This variant is suitable only to the Webix version distributed under GPLv3.

2) Including Webix files via Package Managers

Webix lib can be installed via special dependency management tools. For now, Webix library is integrated with:

  • NuGet package manager for the Microsoft development platform;
  • Bower package manager for the web.

Installing Webix requires by means of these tools requires executing just a line of code inside them (you don't need to download anything):

NuGet

nuget install Webix

//If you use Microsoft Visual Studio, execute this from Package Manager Console
install-package Webix

Bower

bower install webix

This variant is also suitable only to the Webix version distributed under GPLv3.

3) Including Webix Files from Downloaded Package

Compulsory Webix files from the downloaded package are webix.js and webix.css. They are included via standard script and link attributes. Be attentive to specify the right relative path to the files.

This method allows choosing between debug and production version.

<!DOCTYPE HTML>
<html>
    <head>
        <!-- Webix CSS file-->
        <link rel="stylesheet" href="../../codebase/webix.css" type="text/css">
        <!-- Webix JS file-->
        <script src="../../codebase/webix.js" type="text/javascript"></script>
    </head>
    <body>
        <script>
... // here your app will "take shelter"
        </script>
    </body>
</html>

Designing

Here you think about the app's layout, its look-and-feel, build color scheme and, of course, select all the components for it. You should already decide how the components would be related to each other. Building App Architecture article will help you position components and make you acquainted with layout types the library offers.

Further on, there are a number of data-presenting components and special features like toolbar, menu and calendar that would breathe life into your app and make it dynamically change to implement all the functions you wish it to perform.

The library is supplied with a rich set of samples to show you how the components look and perform in reality. So you won't regret having spent some time studying them.

So, there comes time for creativity, so put on your thinking cap and pass to coding.

Main principles of coding with the Webix

All the components inherit from the base view component and are embedded into it to appear in the output. So, the most frequent piece of code you are going to write is

webix.ui({
    view:"...",// specifies the component name you want to create
    id:"...",
    //other parameters
});

..or

var table = new webix.ui({ //any var name will do
    view:"...",
    id:"...",
    //other parameters
});

Working with Component ID

Why is ID so important? Because it's the element you can refer to in order to call component methods (including the one that attaches a handler to an inner event):

//attaches handler to inner event
$$("component_id").attachEvent("onSomethingHappens", do_something(){...});
//forces repainting
$$("component_id").refresh();

Methods can be call directly from the component object:

var table = new webix.ui({...});
//or
table.attachEvent("onSomethingHappens", do_something(){...});
table.refresh();

However, if you don't specify the ID, it will be automatically generated with the "$component_name1" pattern for each instance of a component.

Auto Generated ID

webix.ui({
    view:"list",
    //config options
});

$$("$list1").select(5); // $list1 is an auto-generated ID

Related sample: Auto-Generated ID

Still, referring to the components by specifying the auto-generated ID is not safe as it may change in case a new instance of one and the same component is added to the application.

Getting Component ID at Runtime

At any moment you can get the component ID (either custom or auto-generated one) through its configuration:

var id = table.config.id;

and use it for calling methods:

$$(id).refresh();

HTML Containers

You can set position, style and dimensions of the needed components with the help of javascript only (study Layout and Sizing Components articles) or place the into html containers to take the task to CSS. To achieve this, make up an html-layout, set ID to div elements and set this ID as the value of the component's container parameter.

<body>
    <div id="dataA" style="width:500px;height:150px;"></div>
    <div id="dataB" style="width:500px;height:300px;"></div>
    <script>
    webix.ui({
        view:"dataview",
        id:"mydataview1",
        container:"dataA",
        ...
    });

    webix.ui({
        view:"dataview",
        id:"mydataview2",
        container:"dataB",
        ...
    });
    </script>
</body>

Coding Tips

Components are removed from the application by simply wiping the code in the editor, but they can be as well destructed programmatically with the removal of all HTML elements and event for the component.

$$('mydataview1').destructor();

In addition, you can programmatically check whether the component with the specified ID was created and exists in the app:

if(!$$("my_dataview").exists())// -> returns boolean value
    var dataview = new webix.ui({
        view:"dataview",
        id:"my_dataview",
        ..config
    });

Code Optimization

Sometimes it is recommended to take some parts of an app to separate variables and include them into the webix.ui() command. It makes it easy to track mistakes and read the code later on.

var simple_config1 = ...;
var simple_config2 = ...;
var simple_config3 = ...;

webix.ui({
    rows:[
        simple_config1,
        simple_config2,
        simple_config3,
    ]
})

In case of a really big app with lots of components, controls and functions refer to the Structuring a Big App article to learn all nuances of code optimization.

Read more about HTML templates here.

For further information please study Common Tasks and Event Handling articles.


Debug Version of the Library

Debug version of the Webix library can be found in a webix_debug.js file in the codebase folder of a downloaded package.

Debug version is recommended for use during development stage for it has a number bonuses that helps you understand what's going on with your app and track bugs during development stage.

Main Features:
  • Debug script version inspects function arguments and some component settings and informs about improper configuration like undefined variables, syntax mistakes. etc. instead of some incomprehensible internal errors;
  • In case data loading goes wrong, these will be a corresponding message with the information about the error;
  • Enables debugging flags usage;
  • Enables debugging menu for each component.

Debugging Flags
  • webix.debug = true; - enables event logging, which is the best way to see what events are there;
  • webix.debug_size = true; - logs the info about current component sizes;
  • webix.debug_render = true; - logs the info about how the component are rendered in the application;
  • webix_debug_proto = true; - logs the info about the way components were created;
  • webix.debug_time = true; - logs data loading and component rendering time.

Debugging Menu

Debugging menu is activated with a "Ctrl + right mouse click" combination on the needed component and offers a lot of debugging options:

  • look up into the documentation for this component;
  • learn the component's dimensions;
  • study the component heirarchy on the page;
  • long links to the key features of the component, namely the its JS and HTML object, configuration and data for the component.


Creating Basic Apps

  • Setting Components
  • Interaction Between App Elements
  • Implementing Server-side Integration


Beginner

Setting Components

Here we create a simple filmset - a list of films, where you can add elements.

Here you will need:

  • a list with film data;
  • a form to add new items to the set;
  • a toolbar with 'add' and 'delete' to control the app.

First of all, you should create the app layout and then, place ui components and controls there.

Follow the guide step by step:

Step 1.Introduction

This is a clean page:

webix.ui({

});

Step 2. Rows

Divide the page into two rows with the upper one being for toolbar. Set the width to the app - 500px.

webix.ui({
    width:500,
    rows: [
        { template:"Row 1" }, //1st row
        { template:"Row 2" }  //2nd row
    ]
});

The layout doesn't show empty cells. That's why we temporary put templates into rows to force the layout to display the structure.

Step 3. Columns

Divide the lower row into two columns for list and form components.

webix.ui({
    width:500,
    rows: [
        { template:"Row 1" },
        { cols:[
            { template:"Column 1" },//1st column
            { template:"Column 2" } //2nd column
        ]}
    ]
});

Step 4. Toolbar
  • Place a toolbar with two buttons into the first row;
  • Define text for the buttons with the help of their value property;
  • Set the width of the buttons to 100 pixels (with the width property).
webix.ui({
    width:500,
    rows: [
        { view:"toolbar", elements:[
            { view:"button", value:"Add",    width:100 },
            { view:"button", value:"Delete", width:100 }
        ]},
        { cols:[
            { template:"Column 1" },//1st column
            { template:"Column 2" } //2nd column
        ]}
    ]
});

Step 5. Form

Place a form into the first column. The form will contain two text inputs stored in the elements array.

webix.ui({
    width:500,
    rows: [
        { view:"toolbar", elements:[
            { view:"button", value:"Add",    width:100},
            { view:"button", value:"Delete", width:100 }
        ]},
        { cols:[
            {view:"form", elements:[
                { view:"text", placeholder:"Title"},
                { view:"text", placeholder:"Year"}
            ]},
            { template:"Column 2" } //2nd column
        ]}
    ]
});

Step 6. List
  • Place a list into the 2nd column;
  • Use the data property to populate the list with data in JSON format (there can be other possibilities);
  • Notice, how the title and year properties are reflected in the list template.
webix.ui({
    width:500,
    rows: [
        { view:"toolbar", elements:[
        { view:"button", value:"Add",    width:100},
        { view:"button", value:"Delete", width:100 }
        ]},
        { height:120, cols:[
            {view:"form", elements:[
            { view:"text", placeholder:"Title"},
            { view:"text", placeholder:"Year"}
                ]},
            {
                view:"list",
                template:"#title# - #year#", // which data to show
                select:true, //enables selection
                height:400,
                data: [
                    { id:1, title:"The Shawshank Redemption", year:1994},
                    { id:2, title:"The Godfather", year:1972},
                    { id:3, title:"The Godfather: Part II", year:1974},
                    { id:4, title:"The Good, the Bad and the Ugly", year:1966},
                    { id:5, title:"My Fair Lady", year:1964},
                    { id:6, title:"12 Angry Men", year:1957}
                ]
            }
        ]}
    ]
});

Related sample: Creating Basic App. Step 1

Go further:

  • Interaction between App Elements
  • Server-Side Integration


Beginner

Interaction Between App Elements

As soon as you've learned how to create a basic app, let's go on and enable the app's functionality with the help of attached events and functions.

In the previous step we made a form and a list. Now we want to add items to the list by filling the form as well as to delete items from list.

At the same time, here we'll additionally create an update button on toolbar to update existing records in the list and a clear form button to delete values from the form before inputting new values.

Setting IDs, attaching event handlers

We need to attach functions to the buttons so that they can implement adding, updating and deleting operations stated by their values.

An event handler can be attached to the components in two ways:

  • using native attachEvent() method;
  • using components properties such as click and on.

All the native methods (including the one that attaches event handlers) are called from the component object that can be received using the following construct:

var obj = $$("component_id");

And then call any native method, e.g.:

$$("component_id").attachEvent(...);
$$("component_id").clear();

To attach functions to buttons, you need to specify the event that will trigger their execution and the functions (function names). Here, dedicated functions are called by button click.

{ view:"button", value:"Add", width:70, click:"add_row"},
{ view:"button", value:"Delete", width:70, click:"delete_row"},
{ view:"button", value:"Update", width:70, click:"update_row"},
{ view:"button", value:"Clear Form", width:70, click:"$$('myform').clear())"}

Then, let's set IDs to the needed components. We will work with form to get values from it as well as with list to add and update records there.

{view:"form", id:"myform", elements:[...]},
{view:"list", id:"mylist", template:"..."}

Apart from ID, components and controls have another identifier, name. It's a read-only component property. In the case of the form component, we need element names to derive form values.

{ view:"text", name:"title", placeholder:"Title"},
{ view:"text", name:"year", placeholder:"Year"}

Now, let's describe the functions:

"Delete" button to delete a row

To delete a row from the list, we need to get the selected item and them pass it to the remove(); function as parameter.

function delete_row(){
    var id = $$("mylist").getSelectedId(); //returns the ID of selected item
    $$("mylist").remove(id);
}

"Add" button to add a new record

To add an item, we need to get text values from the form and assign them to list according to its template values.

Form values are derived with the getValue() function called from the form using its ID. To get to the necessary value, specify its name.

function add_row() {
    $$("mylist").add({
        title: $$("myform").getValues().title,
        year: $$("myform").getValues().year,
    })
}

"Update" button to update existing records

Item update is a two-step process.

  • Firstly, you need to transmit data from selected list item to form fields;
  • Secondly, you need to push the changed data into the list so that it replaces old values.

1 . Here we use setValues(); method to set selected data as values for the form fields. The function fires on list item selection and takes this item ID as argument. List values are set to the fields with specified names:

$$("mylist").attachEvent("onAfterSelect", function(id){
    $$("myform").setValues({
        title: $$("mylist").getItem(id).title,
        year: $$("mylist").getItem(id).year
    });
});

2 . The core of a custom update_row() function is the getValues() method that gets values from form fields. Finally, the list is updated with the updateItem() function:

function update_row() {
    var sel = $$("mylist").getSelectedId(); //checks whether the item is selected
    if(!sel) return; // if not, function execution is stopped

    var value1 = $$('myform').getValues().title;
    var value2 = $$('myform').getValues().year;

    var item = $$("mylist").getItem(sel); //selected item object
    item.title = value1;
    item.year = value2;
    $$("mylist").updateItem(sel, item);
}

Confirmation window

To avoid accidental deletion of an important item, you need to safeguard user actions with a "confirm" window:

function delete_row() {
    var id = $$("mylist").getSelectedId();
    webix.confirm({
        title: "Delete",
        text: "Are you sure you want to delete the selected item?",
        callback: function(result) {
            if (result) {
                $$("mylist").remove(id);
            }
        }
    });
}

Confirmation window is initialized by the webix.confirm constructor. It includes

  • title (string) - text header of the window;
  • text (string) - text message to the user;
  • callback - the function that will be called on button click. The result parameter is true or false depending on your choice (yes or no). If result is positive, the remove(); function is executed.

Read more about message boxes in the corresponding chapter.

Related sample: Creating Basic App. Step 2

Related articles:

  • Event Handling
  • Data Update
  • HTMLform and Form Treatment

Go to the previous page - Creating a Basic App

Go further to Server-Side Integration


Intermediate

Implementing Server-side Integration

On previous steps we've done good job.

  • We've set the layout for the app and placed there UI components. See Basic All Tutorial. Step 1.
  • We have enabled interaction between different components within the app. See Basic All Tutorial. Step 2.

Now it's time to learn how to work with data stored in the database and how should we treat CRUD (create, read, update, delete) operations so that they not only appear on the page, but also change data in the database.

The tasks for serverside are as follows:

  • To populate our list with data from the database;
  • To ensure that all the changes you make on the client side (within the component) should be reflected in the database (items should be added, deleted and updated in the DB)

Serverside Integration is described in detail in the related article of documentation while here let's make the following steps:

Loading Data from the Database

Data loading is performed with the help of ready-made dataConnector, a script that retrieves data from the necessary database table and renders its data to the component. With library package, you get a wide choice of data connectors to serve the needs of serverside work. There exist .Net, PHP and Java versions.

The connector should be set as data url for a component.

{
  view: "list", id: "mylist",
  template: "#title# - #year#",
  select: true,
  url: "../common/connector.php",
  datatype: "xml"
}

DataConnector enables only server->client interaction, it's the component's datasource. Used alone, it doesn't push client-side changes back to the database, which is the responsibility of DataProcessor.

DataProcessor Initialization

Webix.DataProcessor is responsible for server-side integration and handles all the CRUD operations.

It should be initialized for the component you'd like to perform server work with:

var dp = new webix.DataProcessor({
  master: $$('mylist'),  // specifies the desired component
  url: "../common/connector.php"  // specifies the server API endpoint
});

Very often dataProcessor gets the same url that is specified as component datasource. At the same time, it can be your own piece of code if you want your own custom logic.

DataProcessor will automatically "translate" all your actions to the server: when you add a record to the list, the new record will appear in the database table, etc.

Component Binding

At last, let's make a step up and simplify form update. On previous step we used an "onAfterSelect" event to transmit list data into the form and a complicated "update_row" function to push edited data back to list. It was for the sake of learning.

At the same time, Webix library has powerful Binding API to enable data synchronization between components. Bind() function is used to make one component a datasource for another one on selection basis.

The update(); function is no longer needed as well since from now on we apply save(); method to the form to push changes back to the list and the database.

webix.ui({
  view: "toolbar",
  cols: [
    {...},
    {
      view: "button",
      id: "update",
      value: "Save",
      width: 100,
      click: "$$('myform').save()"
    }
  ]  // the new function for the button
});

$$("myform").bind($$("mylist")); //component binding

Addition and removal of items goes the same way as it was on previous step.

Related sample: Creating Basic App. Step 3

Related Articles:

  • Data Binding
  • Server-Side Integration. Dataprocessor


Beginner

Introduction to Events

Events are the core of any web application. Why? They help to interact with users and bring interactivity to the page.
When the user makes some action on the page, an event occurs. The developer uses this event to detect the action and run the appropriate script.
In one word, events events are a way to detect user actions and define how to react to them (which functions to run).

Webix events model

Webix supports a large number of cross-browser events to treat its components.

To see the events provided for a certain component, flip to API Reference chapter and click on this component. On the opened page you see all available events.

How to process Webix events?

To process an event, i.e. run a special script when the event triggers on a certain page element, you need to attach event handler to this page element.

To attach an event handler to a Webix component, you should use the attachEvent method as in:

$$("componentId").attachEvent("onItemClick", function (id){
    //handler code
});

The method takes 2 parameters:

  • name - (string) the event name
  • handler - (function) the handler function

For different events, handler functions take different parameters. The information about event parameters you can find on the page devoted to this event in the API Reference chapter.

Once you call the method, each time the event fires for the calling component the code specified as the second parameter will be executed.

Usage example

Let's consider a simple example: you have a list that displays your favourite films. When you click on the film you want a message box to be shown with the details of this film: the title, director and running time.

var films_set = [
  {id:1, title:"The Shawshank Redemption",director:"Frank Darabont",      time:142},
  {id:2, title:"The Godfather",           director:"Francis Ford Coppola",time:175},
  {id:3, title:"The Godfather: Part II",  director:"Francis Ford Coppola",time:200},
  {id:4, title:"Pulp Fiction",            director:"Quentin Tarantino",   time:154}
];

var fList = webix.ui({
    view:"list",
    data:films_set,
    template:"#title#"
});

fList.attachEvent("onItemClick", function(id){
    var item = this.getItem(id);
    webix.message("<b>"+item.title+"</b></br>director: "+item.director+
    ", time:"+item.time);
})

Related Articles

For more information about Event Handling in Webix, please, study the corresponding article of the documentation.


Webix Docs Guide

To make a great app you need to learn different things but if you're new to Webix you might be wondering where to begin.

Some platforms (Java, .Net, PHP) get ready-to-use solutions for data loading, saving, exporting.

For understanding the basic concepts and getting the desired information in the most convenient way we offer you to follow this road map:

  1. Compatibility - lets you find out whether your development tools satisfy the library requirements.
  2. Getting Started - gives essential notes that will help you to create your first Webix-based application.
    • Start Coding with Webix - says about fundamental principles and covers development process from planning to coding.
    • Quick Start Guide - links to a short article that will teach you how to easily get a simple application up and running.
    • Creating Basic Apps - introduces a detail tutorial that takes a bit more time but cover all nuts-and-bolts of the library
  3. UI Components - describes available components: short overview, initialization, usage, related guides and API.
  4. Guides - the main chapter of the documentation covering developer-oriented tasks in details.
    • App architecture - answers general configuration questions: how to specify and size required component, set headers(footers), manipulate visibility, handle events etc.
    • UI features - tells you how to fine-tune the appearance of your app and data in it with the help of css classes, templates, special helpers and modes.
    • Data operations - covers techniques for performing general operations under data, such as sorting, filtering, copy-pasting and selection.
    • Third Party Integration - says which third-party libraries and how can be integrated with Webix components.
  5. Auxiliary Resources - covers advanced techniques implemented by means of helper components. Mostly intended for expert developers to customize the existent functionality.
  6. API Reference - provides reference information you need for coding: all the available methods, parameters and events of the library.


Start

Compatibility

Server-side compatibility

As Webix is a client-side library, it doesn't depend on server backend, so you can use it with any server side technology.
For some platforms ( Java, .Net, PHP ) - ready to use solution available for data loading, saving, exporting.

Client-side compatibility

Webix-based applications work on PCs and laptops using the following browsers:

  • Internet Explorer 8+;
  • Google Chrome;
  • Apple Safari;
  • Mozilla Firefox;
  • Opera.

Webix is also intended for mobile use and fully supports the following devices:

  • iPad;
  • iPhone;
  • iPod;
  • Android-based devices.

As Webix is compatible with PhoneGap, you have access to mobile app stores, such as Android Market or Apple App Store, for distributing your applications.


Start

What's New

  • Version 3.3 April 26, 2016
  • Version 3.2 February 24, 2016
  • Version 3.1 November 24, 2015
  • Version 3.0 September 22, 2015
  • Version 2.5 July 24, 2015
  • Version 2.4 May 22, 2015
  • Version 2.3 March 24, 2015
  • Version 2.2 January 23, 2015
  • Version 2.1 November 26, 2014
  • Version 2.0 September 12, 2014
  • Version 1.10
  • Version 1.9
  • Version 1.8
  • Version 1.7
  • Version 1.6
  • Version 1.5
  • Version 1.4
  • Version 1.3
  • Version 1.2
  • Version 1.1
  • Version 1.0.2
  • Version 1.0.1


Version 3.3

released on April 26, 2016

Breaking Changes
  • header and headerImage properties were renamed to docHeader and headerImage in PDF export configuration. Additionaly, the header property was introduced to tune the appearance of an exported table.
  • the last argument of webix.event helper was modified. Now it awaits a context object with master, id and capture properties while before it indicated an object to which this keyword refers (master).

New features
  • AbsLayout widget
  • DataLayout widget
  • sparklines for DataTable and TreeTable
  • ability to send json in Webix Ajax calls via:
    • "json" proxy for Ajax calls within data components
    • passing "Content-Type":"application/json" header in the webix.onBeforeAjax event
  • drag-n-drop of component items on touch devices

Updates
  • enhanced FileManager appearance
  • liveEditor input in Spreadsheet
  • pointerevents flag to webix.env helpers
  • new positioning for dragged Kanban items
  • export API returns promise
  • shift key support for DataTable/Treetable areaselection
  • onBeforeAreaRemove and onAfterAreaRemove events for DataTable and TreeTable
  • onBefore/AfterColumnHide and onBefore/AfterColumnShow events for DataTable and TreeTable
  • DataTable and TreeTable multiline header and paddings for TreeTable in Excel export
  • extended configuration for PDF export
  • DataTable footer is included into Excel and PDF exports
  • "$empty" property support for items in suggest lists
  • onBeforeApply event for Pivot Table
  • keepText property for MultiCombo
  • setContext() method for Context and ContextMenu
  • sorting for options in select filters in Pivot Table
  • support for missed values in Pivot Table
  • default color range for Charts changed
  • "drag over" background during item drag-n-drop changed

Fixes
  • always suggest the first record if no items are selected in select inputs
  • option selection by typing its exact text in select inputs
  • vertical radio size calculation
  • possibility to configure header image of the exported PDF document
  • hiding columns from selected areas in Pivot
  • "light" gradient for bar Chart with small radius
  • changing month on day click in Calendar with disabled navigation
  • fix areaselection with column hide and show
  • Multiselect shows placeholder only during first rendering
  • filtering and optionslist in multiSelectFilter in DataTable
  • Chart destruction
  • history track in case of dynamic loading in FileManager
  • custom templates with links (link click fires "onfocus" event) in File Manager
  • onpaste should not be called with opened editor
  • multiSelectFilter and multiple options in data cells
  • tabs ordering
  • multiple views with ActiveContent
  • webix.toPNG can't be used with ID of HTML element
  • parameters for server side filtering and sorting
  • HtmlForm with clean/dirty values
  • escape url params with server filtering and sorting
  • inputs lost focus after paste on pages with clipboard enabled
  • add document footer to base locales in PDF export
  • Portlet events
  • drag position for custom drag text
  • Portlet DND on touch devices
  • touch events call for views with no scroll
  • correction for "illegal" characters in sheet names in Excel export
  • adding for collapsed Accordion item
  • cancel Window move at runtime
  • disabled Checkbox
  • removeAllSeries for RangeChart
  • columns reset in Pivit Table
  • add footer into onBeforeRender event for Pivot Table
  • stopEvent in File Manager
  • uploading and readonly mode in File Manager
  • counter as ActiveContent (blur handler is not called for buttons)
  • keeping selection color for invalid items
  • disabled style for buttons
  • hiding covered popups on modal area click
  • RangeChart throws errors in case of no data
  • setting the first value in Multiselect
  • per-grid subview storage to avoid clearing it for nested subviews
  • export DataTable columns with templates that require a column config
  • calculate Button autowidth on resize
  • bug with hideColumn and header colspans
  • tag navigation and disabled Checkbox
  • resizing of DataTable subviews works one way
  • masterCheckbox with dynamically loaded data
  • destructor() call for a modal Window
  • download and upload in File Manager
  • styling of DataTable icons
  • undo and changeId
  • calling changeId for same IDs
  • hide/show series in a Chart with no legend
  • scrolling of a DataTable with spans
  • corrected height of Calendar icons
  • focus in forms with complex structure
  • German "de" locale


Version 3.2

released on February 24, 2016

Breaking Changes

  • Datatable methods exportToPDF() and exportToExcel() as well as Pivot methods toPDF() and toExcel() aren't available anymore. Use webix.toPDF() and webix.toExcel() methods instead.

  • The mechanism of loading Excel files into data components is modified. The "excel" proxy was removed. Use the "binary" proxy object to load files like Excel into data components and the "excel" datatype for parsing Excel files.

Check the Migration Guide for more details.

New Features
  • Spreadsheet widget (PRO edition)
  • Rangechart widget (PRO edition)
  • undo functionality for all data components
  • export to PDF for all data components
  • area selection for Datatable and Treetable

Updates
  • patch methods for webix.ajax() module
  • download method for webix.html module
  • custom xAxis for Pivot Chart
  • onViewResize event for window
  • download functionality for PDF viewer
  • parse method for PDF viewer
  • support for structure without columns in Pivot Table
  • selectAll and unselectAll methods for datatable
  • proxy support for dynamic loading Related sample: Dynamic loading through Data Proxy
  • dynamic loading support for multicombo suggestions
  • support for proxy and editable columns in File Manager
  • "missed values" support in Pivot Table
  • drag order for x-lists
  • binary proxy for reading files as ArrayBuffer
  • excel data driver (and datatype) for parsing the contents of Excel files. Used in Excelviewer and Spreadsheet

Fixes
  • header spans during hide and show of datatable columns
  • edit operations in datatable and 0 value
  • columns filtering in datatable
  • incorrect focus for toggle buttons
  • history track in case of dynamic loading
  • dynamic loading for Treetable
  • call scrollTo after Datatable reload
  • get suggested value from Suggest list without selection in it
  • getScrollState for Datatable
  • area/block selection in 'split' cases
  • subrows for dynamic loading in DataTable
  • onDataUpdate, onAfterAdd, onAfterDelete events fire after visual changes are applied
  • repainting Datatable subview in hidden state
  • onAfterAdd is called after added item is drawn
  • fix touch inputs
  • customCheckbox and customRadio in IE10
  • onStoreLoad call added for importData
  • style for disabled buttons
  • toolbar height in Flat and Compact skins
  • double watcher logic in Angular integration
  • DP parameters passing to updateItem
  • label/id of input elements
  • multi-day rendering in Mobile Scheduler
  • pager size
  • filtering by multiple fields in Pivot Table
  • tab-click events in ExcelViewer
  • update visible selection after colorboard suggest is displayed
  • FileManager selection
  • spans rendering after columns number has changed
  • onAfterScroll event and non-touch handlers
  • onchange event for multitext control
  • url in loadBranch
  • auto-positioning of popups in case of global scroll
  • DP parameters passing to updateItem
  • label/id of input elements
  • proxy.load call
  • IE8: vertical text of collapsed items
  • clearing hidden canvas
  • performance problem with .toExcel
  • native selection in views with enabled 'clipboard'
  • editing in views with enabled clipboard
  • regression in updateFromResponse
  • automatic data loading after receiving error response
  • clearing hidden canvas
  • full-screen for new iOS versions
  • newValues: default selection removed
  • touch: avoiding resize handling on virtual keyboard for focused inputs
  • workaround for iOS Safari bars overlapping in the landscape mode


Version 3.1

released on November 24, 2015

New Features
  • Sidemenu widget
  • TreeMap (PRO edition)
  • Sidebar extension
  • autowidth for Menu and Button

Updates
  • listMarginX and listMarginY settings for organogram
  • open() and close() methods for organogram
  • newValues for multiselect
  • eachLeaf() for TreeStore
  • support for numPad keys UIManager
  • onSubViewOpen event handler for DataTable
  • inputName parameter for uploader
  • "multiselect" support for KanbanLists
  • setStructure() for PivotTable
  • "root" batch for File Manager
  • animateView method and "month" view animation for Scheduler on touch devices
  • error message on init non-GPL views with Webix GPL
  • tagMode property for multicombo
  • load() method for PdfViewer
  • toFront property for windows and popups
  • getTextSize() method for html helper

Fixes
  • nested isolated scopes
  • refreshColumn correctly removes filters
  • clipboard: clicks on selected item/cell
  • subrow opening in TreeTable
  • Multicombo and bottomPadding
  • numberFilter to accept 0 and fractional numbers
  • remove sub items with parent in tree
  • accordion doesn't resize the header panel
  • progressBar in window
  • disabled Resizer
  • json format in php files
  • scrolling DataTable with span(s) on touch devices
  • Fieldset vertical padding
  • handling mouseup outside browser window
  • pager update on data count change
  • focus() method for checkbox and radio
  • Carousel navigation z-index
  • regression in windows focus handling
  • regression in form focus handling
  • data corrupting by counter in the footer
  • size of editors in case of sub-forms, sub-rows
  • sub-rows and precise scroll
  • double-rendering from onchange handler in Chrome
  • handling mouseup outside browser window
  • DataProcessor in updateFromResponse mode doesn't trigger update events
  • checkbox doesn't trigger onDataUpdate event
  • JSON date parser doesn't recognize dates without milliseconds
  • IE8 compatibility for uploader
  • size of fillspace columns for very small grids
  • Fieldset vertical padding
  • export to Excel and Webix Jet (RequireJS)
  • progressBar in window
  • disabled Resizer
  • date-time shifting in export to Excel
  • webix.copy correctly processes Date objects
  • parsing boolean values from HTML markup
  • blockDates in Calendar
  • totalColumn in Pivot Table
  • custom columns in Excel export
  • format property in DatePicker can accept a function
  • hiding columns in a DataTable, those were added dynamically
  • export to Excel, dates processing
  • FireFox: customCheckbox and customRadio
  • regression in DataTable click processing
  • regression in form.setValues api


Version 3.0

released on September 22, 2015

New features
  • Excel viewer
  • PDF viewer
  • export to Excel for all data views
  • export to PNG for all views
  • subviews and subrows for Datatable
  • serverMultiSelectFilter for Datatable
  • ability to resize windows;
  • any serverside response except for {"status":"error"} defines successful uploading for Uploader
  • dynamic loading in two modes for File Manager
  • onAfterScroll event for all scrollable components

Updates
  • ability to set datatype of serverside response for Uploader
  • move API for DataCollection and TreeCollection
  • placeholder for Multiselect
  • suggest property for richSelectFilter, multiSelectFilter, multiComboFilter, datepickerFilter filters in datatable, which makes them configurable
  • tooltip for Property view
  • editable property for ColorPicker
  • find() method for all data components
  • open() method for Tree supports second parameter to allow opening all parent of the item
  • %c as ISO 8601 date format within Date module
  • webix.require() returns promise
  • ignore refreshFilter() for not existing filters
  • scopes for Backbone integration
  • dependence on Underscore is removed from BackBone integration
  • data binding for tree-like components
  • ability to use data updates in TreeStore
  • remove layoutConfig from carousel
  • promise as parameter of onBeforeAjax event
  • noselect styling for certain views / view elements
  • onHeaderInit event for Pivot Table
  • menuFilter and separate menus for items and clear space in File Manager
  • search results clearing on opening folder in File Manager
  • block selection for path elements in File File Manager

Fixes
  • case of window destruction from "onHide" handler
  • calculation of layout cells during browser resizing
  • calling mouse event handling for html elements that are outside columns in datatable
  • displaying chart tooltips in case of series overlap
  • not all hotkeys work correctly
  • adjust columns in treetable
  • adjustRowHeight in hidden containers
  • getDirtyValues for complex data
  • tab navigation for checkbox and radio
  • DataTable: calling mouse event handling for html elements that are outside columns
  • total column, footer and data formatting in Pivot Table
  • custom scroll styling
  • open dynamic folders in File Manager
  • closing editor popups after clicking on control in the popup view
  • webix.storage.cookie doesn't escape special chars
  • find doesn't search in closed nodes in tree
  • destroy options collection on master component destruction
  • resize autoheight textarea
  • height of datatable header in case of split and small screen width
  • unnecessary closing of popup editor in datatable
  • select options as array
  • parsing of select options for components that don't use map collection (tree, dataview, list)
  • XHR in IE
  • webix.require do not recognize full http paths
  • styling of selected row after validation in the datatable
  • grouping performance in Pivot
  • anyOnly uploader and full-screen body style
  • incorrect work of showItem method
  • secure cookies for https
  • export to excel in FireFox
  • week number calculation in calendar
  • selection within disabled date range in calendar
  • refreshing data in select-based filters on options load
  • scrolling view with borders
  • autosizing columns with filter in the datatable header
  • incorrect scroll state in datatable after refreshColumns() call
  • folder opening and noFileCache in File Manager
  • navigation fixes
  • dataFeed and "post" proxy
  • id of newly added item in case of synchronous data saving
  • scrolling view with borders (customscroll)
  • incorrect landing for dragOut event
  • native context can't be used with inline editors
  • custom scroll and accordion panels
  • suggest ignores template for returned value
  • headermenu and colspans in grid
  • export doesn't include summ values from a footer
  • data binding in property view
  • conflict between updateFromResponse and new ID in DataProcessor
  • incorrect focus after hiding window
  • IE9 and node selection
  • blur and focus with htmlform
  • extra requests during dynamic loading in tree
  • importData doesn't work with missed properties
  • sending two Content-Type headers during loading
  • FileManager: multiple-file upload in old IEs
  • onStructureUpdate event in datatable occurs a bit erlier
  • Fix filemanager edit
  • refreshing items in tree after adding into an empty folder
  • webix.require do not recognize full http paths
  • cell selection mode and colspans in datatable
  • using the popup element as part of WebivView during integration with BackBone
  • ie8 upload
  • tooltip do not disapears in some cases
  • regression in block-selection visualization in datatable
  • not applying new options collection after changing structure of datatable
  • using clearAll against grouped component
  • suggest doesn't use template when used against HTML input
  • incorrect processing of null values by richselect
  • event starts in lists templates for all-day events in scheduler
  • scroll in datatable blocks other touch scroll components
  • not-preserving text in filter input after server side filtering in datatable
  • unnecessary checks in Backbone View
  • SVG elements and locate() in datatable
  • position of added items in filtered state
  • changing cursor in case of open editor
  • get list selection as an array in multiselect
  • top positioning for filtered popup in multiselect
  • clearing selection on file deleting in File Manager


Version 2.5

released on July 24, 2015

New features
  • Support of Microsoft Edge, default browser of Windows 10
  • Ability to disable time periods for Calendar widget
  • Ability to populate Form, Toolbar and Property sheet with complex data
  • Swimlanes in Kanban widget to visualize separate work flows
  • Total column and footer (both with sum counters) for Pivot widget

Updates
  • resize() method for CustomScroll
  • second parameter for Datatable refreshColumns() method
  • preserve mode for Datatable selectRange() method
  • "box" and "select" modes for Datatable blockSelect property
  • Datatable showColumnBatch() method extended
  • map configuration options for Datatable and Datacollection
  • timeout() method for Ajax API
  • markInvalid() method for Form
  • applyChanges() method for UIManager
  • tab/enter processing and values order for Multiselect
  • Pivot configuration window: fields are copied into "Filters" sector (not moved)
  • Pivot Table and Pivot Chart: "id" has been excluded from "fields" list
  • updated design and layout of Pivot configuration window
  • style improvement, and first letter capitalizing for Pivot Chart
  • using webix.ui for view moving, top and nested
  • auto closing on click for tooltips

Fixes
  • Filemanager upload
  • multiselect selecting items on suggest showing for multiselect
  • datatable column adjustment and dynamic loading
  • settings fixed height to accordion items
  • customScroll repainting in tree and treetable
  • repainting dataview after changing xCount or yCount values
  • accordion with hidden panels
  • customscroll doesn't adjust itself after resizing
  • layout reconstruct() method doesn't work in case of hidden cells
  • incorrect data binding in case of long page loading time for Angular
  • workaround for Chrome updates: sizing of scrollable area
  • uploading files into an empty folder
  • block-selection for datatable in edit mode
  • incorrect resizing of x-scroll in hidden state
  • refreshing data widget after deleting all items from the last page
  • parsing "%y" to correct year
  • repainting UI in case of angular integration
  • toObject() doesn't called for external proxies
  • suggest selection
  • label vertical align
  • keyboard navigation for datatable in paging mode
  • loading select editors from array of objects
  • upload target
  • copy item from plain to hierarchical view
  • importing data without "id" during sync
  • chart series definition; default line color; stacked bar rendering
  • scrolling to selected value in suggest list
  • label vertical align
  • replacing layout/body structure with the new one that contains the same ids
  • apply input values on resize
  • buttons right-click handling
  • unnecessary scrolling for datatable with huge rowspans
  • footer styling and paging sizes for datatable
  • slider step processing
  • content-type for ajax calls
  • tree lines in Flat skin
  • Safari vscroll in dataTable
  • IE checkbox dblclick
  • list filtering in Combo
  • dateFilter filter and empty records
  • ability to cancel and enable scroll within datatable
  • templateStart for grouplist and unitlist
  • disabling views with scrolls
  • input width and label position top
  • input rendering in form controls
  • checkbox double
  • animations in datatable
  • chrome: frozen columns and column resize
  • checkbox double
  • text selection while using a custom scrolls
  • datatable sizes
  • Chrome resize
  • combos in one column layout
  • regression in restoring scroll state in datatable
  • display native context menu on a page with Webix context menu
  • bottomPadding and invalidMessage
  • textarea sizing
  • processing headers without sorting
  • avoiding errors when refresh() that is called before render()
  • repainting changes in the hidden view
  • styling of disabled buttons


Version 2.4

released on May 22, 2015

New features
  • Portlet widget
  • MultiCombo widget
  • Range Slider widget
  • Advanced validation messages for forms

Updates
  • "button" config property
  • "multicombo" control and onBeforeShow event
  • "static" property for non-animated Multiviews
  • event onBeforeEventShow for Scheduler
  • getPopup method for combo editor
  • ie9 support for progress bar
  • invalid message and bottom label for form widget
  • metaKey support (mac OS) for multiselection
  • methods getCurrentFolder and getSelectedFile for FileManager
  • noselect style for views in drag and multi-selection processes
  • onPopup event for pivots (fires on popup creation)
  • paging for TreeTable
  • proxy is released after view destruction
  • range slider
  • read-only mode for pivot chart and table
  • static mode for animation (multiview with iframes)
  • webix ajax object to arguments of onBeforeAjax event
  • addStyle reused previously created style tag
  • headers as 5th argument of onBeforeAjax event
  • updated FontAwesome to 4.3.0 version

Fixes
  • ActiveContent doesn't survive component repainting in IE
  • adding new items in filtered branches of treetable
  • buttons inside html form
  • clipbuffer styling in IE8
  • close all sub-windows on master popup closing
  • closing of nested popups ignores windows
  • colspans and split mode
  • column drag-n-drop on touch devices
  • combo accepts full data object as a value
  • combo behavior in dyn. loading mode
  • correct input width for inputs with no label (richselect-based filters of datatable)
  • creating new branches in filtered state
  • CSV parser ignores the trailing new-lines
  • detach options handler after master component destruction
  • disabling headermenu for hidden column
  • events on SVG elements
  • FileManager upload and Uploader in IE8
  • focus() and blur() for buttons
  • hidden:false and modal:true in window config
  • hot keys and numpad
  • IE GET requests
  • IE9 doesn't allow setting custom properties on AJAX object
  • incorrect rendering of first row in case of paging
  • invalid math in newly added rows
  • material skin detection
  • message width and height
  • missed onAfterFilter event for server side filtering
  • multitext with suggest
  • onBeforeFileAdd in IE9
  • onChange event in combo
  • regression in data saving handling
  • regression in tooltip for icon
  • regression in treetable filtering
  • resize last column in right-split mode
  • responsive attribute doesn't work for clean and line layouts
  • richselect filter in IE8
  • richselect: setting an empty value clears list selection
  • scroll definition for datatable on Touch devices
  • scroll position on last row in paging mode
  • serialization of data by webix.ajax
  • serialization of Date object
  • server side filtering with active editors
  • tabFocus doesn't work for icon view
  • text positioning in datatable
  • unnecessary scroll blocking by datatable
  • using select api in datatable with complex id
  • validation in dataprocessor breaks insert operations
  • validation in hidden form
  • value binding and dataFeed
  • value formatting
  • web skin active button color


Version 2.3

released on March 24, 2015

Breaking changes

  • Default parse format is changed for datepicker and calendar controls from "%Y-%m-%d" to "%Y-%m-%d %H:%i". Both of them can be altered within current locale.

  • Sizing of layouts changed. In Webix 2.2 and earlier height and width on layout were not including padding and margins. Starting from Webix 2.3 height and width of layout is a full size of layout, including all margins and paddings.

Check migration guide for more details.

New features
  • new material skin
  • [pro] barcode widget
  • [pro] organogram (organization chart) widget
  • [pro] multiselect and datepicker filters to Pivot
  • [pro] header sorting and value formatting in Pivot
  • [pro] processing of equal file names in File Manager
  • [pro] file upload for IE9 in File Manager
  • onChange event for toolbar and form to capture user changes
  • onValues event for toolbar and form
  • getMenu method for menu to get current menu/submenu object
  • parseTimeFormat is added as "%H:%i" by default to parse "time" strings
  • badges and icons for list and menus (and views based on them)
  • badges for buttons
  • placeholder for richselect
  • spacer element in menu view
  • ability to provide submenu configuration in submenuConfig property of the topmost menu
  • ability to trigger onReady in a synchronous way
  • "Today" and "Clear" buttons are added to the date editor. They are hidden by default.
  • editor object can receive full data item

Updates
  • DataCollection has getCursor and setCursor methods by default
  • second click on a button with popup property will close the popup
  • autoConfig can be reused for datatable, e.g. after clearAll() call
  • $touchCapture flag in component configuration for touch limited mode. Used for slider control.
  • before sending to server side all dates are serialized
  • error handlers of webix.remote calls will receive the text of response
  • treestore has ability to serialize all data or filtered one
  • scrollable "Month" view in Scheduler
  • better default styling, ability to customize layout configuration

Fixes
  • fix regression in data loader initialization
  • correct values for onChange event in slider
  • using TreeDataLoader instead of DataLoader
  • unfiltering to affect not filtered view
  • getActiveId() for empty carousel
  • correct rendering of buttons after changing visibility state
  • removeView() to remove related value from form values
  • onChange event in form triggers only on edit operations in form
  • readonly mode for datepicker and colorpicker
  • onChange event for slider
  • using template.escape with null or undefined values
  • key navigation in empty combo
  • incorrect adding of hidden views in accordion
  • using quotas in button's text
  • onChange handlers for text and select controls used as ActiveContent
  • tooltip for inputs, progress in IE8
  • x-scroll in tree
  • tree horizontal scroll
  • borders in top level (and borderless) space layout
  • using removeView() to remove current view in the multiview
  • special chars handling in text inputs
  • progress bar positioning (scrolling offset for "icon" type only)
  • top and bottom positioning
  • layout uses fixed height and width without alterations
  • recurring editStop() calls
  • tree horizontal scroll
  • slider fix for Touch in limited mode
  • webix.ajax(url) call returns promise
  • promiz will not occur if error was caught
  • promiz throws an error only in debug version
  • fonts for compact skin
  • hiding columns with colspan
  • clipboard breaks focus in the editor
  • dynamic loading on touch devices
  • scrolling to the last row index in case of scroll overflow
  • IE8 fixes: preventing default actions and mouse event handling
  • hiding columns with colspan
  • regression in skin mapping
  • borders in datatable when Bootstrap used
  • clipboard breaks focus in the editor
  • drag-n-drop for columns in the datatable, header with colspans
  • dynamic loading on touch devices
  • fixing promize functionality which can export self to external structure when global "module" is defined
  • maximum tab number calculation
  • TreeStore: each method and filtered branches
  • applying new configuration after config reloading in datatable
  • tabs rendering (border-box sizing)
  • multiselect ignores non-existing values
  • set optionHeight for skins
  • checkAll() and uncheckAll() methods
  • configuration of richselect with options from HTML
  • inputHeight in case of labelPositon top
  • tree ignores open call for already opened items
  • regression in getValue() of colorpicker
  • attribute checking in block-selection for datatable
  • value property in tabview
  • fixed datathrottle usage
  • Date serialization during ajax operations
  • resetting uploader after file choosing
  • focusing checkbox editor in Chrome
  • disabled counter in IE10
  • options with quote in multi-select
  • regression in getValue of colorpicker
  • resetting text filter value after reloading data from the server side
  • filters in treestore
  • autoheight in templates
  • tabbar "more" icon styling
  • blockselection and custom scroll
  • blockselecting and dbl-click events
  • blockselection in scrolled state
  • blockselection in the empty datatable
  • getValue(), "editable" value
  • setLocale() and arrays extend
  • setValue() and getValue() of datepicker
  • setLocale() extend for complex properties
  • remove icons from Scheduler's calendars
  • timepicker position
  • FileManager locale: confirmation popups; collisions resolving without url handler
  • conflicts between native navigation keys and navigation hotkeys
  • server side filter reacts on navigation keys
  • object id for gridsuggest
  • solve request collisions (delete+rename/move/create)
  • createFolder for fileManager
  • default hotkeys for windows
  • treestore serialize (filtering)
  • provideAPI
  • moving items in tree and tree table while in the filtered state
  • missed methods in TreeCollection
  • "format" of datepicker and filemanager fixes
  • processing setState with empty filter value
  • select filter in FF
  • regression in click handling inside of multi-level popup
  • incorrect filter processing during setState call


Version 2.2

released on January 23, 2015

Breaking changes
  • width and height settings for all data components include size of scrollbar (so component will always take exactly the same size as was defined by width and height properties)
  • ajax.header was deprecated in favor of ajax.headers

If you are updating from Webix 1.x - please check the Migration guide.

New features
  • data binding for Tree, TreeTable and TreeCollection
  • optional Today and Clear buttons in the Calendar
  • ability to define file types for file uploader
  • webix.ajax API can be used to fetch binary data (file downloading via AJAX)
  • optional hover for rows in DataTable
  • horizontal and vertical auto-scrolls during drag-n-drop for data components
  • extra options for filtering in Tree and TreeTable
  • improved scrolling on touch devices
  • advanced tooltip options for DataTable
  • all data components supports object notation for $css property
  • onClick and other mouse handlers can use any CSS class, not only the first one
  • view.show can be used without animation
  • markup.init will return newly constructed UI
  • columns size and order can be restored through the setState API
  • removeHotKey accepts human-readable key names

Fixes
  • addView for TabView doesn't support extended tab configuration
  • assigning the same CSS class during layout reconstruction
  • calendar is incompatible with Bootstrap
  • calendar: cellHeight support
  • changing value in combo after focus out
  • click event handling in IE8
  • CSS for collapsed accordion items in compact and flat skins
  • custom and touch scroll in Tree
  • custom id in scheme.$init for Tree and TreeTable
  • datePickerFilter can't be combined with other filters
  • double call for dynamic loading in the Tree
  • dynamic loading in filtered state for Tree and TreeTable
  • export to Excell and null values in the DataTable
  • header menu and column hiding
  • header sorting for clicks in rich-filters in the header
  • headermenu for grid with auto-config and remote data loading
  • hotkeys in IE8
  • IE8 fixes and pair event handling (context menu)
  • IE8 sorting fix (map method)
  • IE8 XML parsing
  • incorrect filter value preservation during DataTable repainting
  • incorrect id in the onDataRequest event
  • incorrect menu sizing
  • incorrect scroll state for the hidden datatable
  • incorrect scroll state processing for grid with non-aligned rows
  • incorrect size setting from dtable.setState
  • incorrect state of headermenu after menu reloading
  • invalid handling of 0 as the option value
  • invalid result of hasEvent call after detaching event
  • iOS fix for full-screen mode; uploader fix (status processing)
  • minutes containers and browser zooming in calendar
  • multiselect and idSpace fix
  • non-numeric arguments in math formulas in the datatable
  • popup closing delay
  • popup doesn't adjust after inner content resize
  • preserving value of multi-select filter after DataTable refresh
  • regression in addView for accordion
  • regression in block selection in DataTable
  • regression in context handlers
  • regression in input disabling from config
  • regression in isolate tabbar handling
  • repainting after removing item in the Tree
  • replacing hidden cell in multiview
  • richSelectFilter and getFilter API
  • scroll state in DataTable after hide/show operations
  • selection in dataview with dynamic loading
  • setState in DataTable will ignore columns with non-unique ids
  • sorting ignores state set by the markSorting API
  • special chars handling by select filter
  • spinner progress position
  • styling of sparse datatable
  • template breaks on "->" chars
  • text vertical align for inputs inside toolbar
  • uncheck for checkboxes in indeterminate state
  • uncheck of initially enabled radio button
  • unnecessary error message in case of AJAX call canceling
  • unwanted onclick reaction on buttons in IE
  • uploader active area for macos
  • x-scroll in autosized lists


Version 2.1

released on November 26, 2014

Major features
  • Better compatibility with Bootstrap and jQuery
  • Icon font contains 479 icons now ( Font Awesome updated to 4.2 )
  • "strict" mode for Webix
  • Datatable and treetable math can be extended with custom functions
  • Uploader can work in Internet Explorer 8-9

If you are updating from Webix 1.x - please check the Migration to latest Webix version

Minor features
  • ability to send extra data with file upload
  • addView() and removeView() methods can be used to add and remove tabs in tabview
  • find API for all data components
  • addOption() method supports option object as argument
  • addDropZone() method for uploader to allow file upload by drag-n-drop on html area
  • webix.ui.animate to animate view creation
  • tabview can have custom width for different cells
  • tab close and tab/segment remove events
  • separator for multiselect

Fixes
  • dataprocessor doesn't use scheme serializer before data sending to the server side
  • view.show works correctly for tabview
  • richfilter styling
  • styling for invalid radio button
  • dblclick events in the list
  • unfiltering multi-select filter
  • colspans in case of many datatables per page
  • validation and third-party elements in the form
  • destroy component in the tab after tab closing
  • non-existent hours in specific time zones (Brazil for example)
  • incorrect sizing for adjust command in datatable
  • scroll config option for datatable
  • sorting datatable in filtered state
  • using markSorting against hidden grid
  • error in math results in empty cell
  • edit events in liveEdit mode
  • htmlbutton template typo
  • segment button display on iOS
  • treestore filtering
  • regression in the carousel view
  • sorting of hidden column
  • adjustColumn against the hidden column
  • multiple multiselects per page
  • column d-n-d and rotated headers
  • incorrect parsing of width in complex menu while loading config from xml
  • export of data with special characters
  • reloading data in menu with hidden items
  • ungroup API inconsistence
  • ie mobile animation
  • mouse-wheel other custom scrolls
  • pie chart map clearing
  • invalid this reference in webix.require callback
  • addView can't be used with accordion
  • eachColumn works incorrect after column's reconfiguration


Version 2.0

released on September 12, 2014

Major features
  • Promises API for all ajax operations
  • Progress bars and overlays
  • Improved keyboard navigation
  • Extra locales added
  • Package includes source map files
  • [pro] PRO edition includes Pivot component
  • [pro] Multiselect and multitext inputs
  • [pro] Advanced editors for DataTable and Property views
  • [pro] Datasuggest and Gridsuggest views for form controls and editing;
  • [pro] Colspans and Rowspans in DataTable
  • [pro] Column menu in DataTable
  • [pro] Grouped columns in DataTable
  • [pro] Advanced filters for DataTable
  • [pro] Optional header rotating in DataTable
  • [pro] Optional custom scrollbars
  • [pro] Extra 300 locales

If you are updating from Webix 1.x - please check the Migration to latest Webix version

Minor features
  • custom height for header lines in datatable
  • dark style for carousel
  • getState api for dataprocessor
  • onViewMove and onViewMoveEnd events to movable
  • optional close button for tabs
  • password editor
  • simple way to add icons to tabs
  • storage.clear for all models
  • if id for data object was not provided, value will be used as id
  • onMenuItemClick can block menu hiding
  • overlay works for all components
  • parse can accept raw ajax response and webix components
  • suggest for text editors

Fixes
  • ability to define popup as raw json config
  • active style for danger button
  • zero border radius in Safari
  • accordion labels
  • active content
  • adjust doesn't work for columns with string template
  • adjustRowHeight in grid with dynamic loading
  • bar chart border correction
  • changing master id doesn't work for bind forms
  • closing popup editors after editor closing
  • custom suggest types in combo and richselect
  • datatable lost sorting marker after column resize
  • datepicker in grid and empty value
  • icon sizes
  • icon tabs vertical align
  • IE8 compatibility
  • incorrect header size after setColumnWidth call
  • isBranch API fixed
  • loading xml data into template
  • popup closes after click on button in the list
  • regression in suggest and edit configuration
  • right split recalculation
  • serializing state of hidden filters in datatable
  • series in case of custom x-axis
  • series in chart with custom scale
  • sizing of carousel after adding/deleting extra views
  • slashes in templates
  • space mode ignores borderless setting of layout
  • text wrapping in the rich select control
  • textarea and label styles
  • type $css property for unitlist
  • yCount and context menu


Version 1.10

Full list of changes and fixes

New functionality

  • onSubmit event for Form ("enter" listener for "text"-based controls inside form)
  • target for menu links
  • column batches in datatable

Updated functionality

  • each and eachChild iterators accepts "all" flag for TreeStore
  • "property" styles in "flat" and "touch" skins
  • textarea styles
  • unsync api for backbone integration

Fixes

  • not valid HTML for textarea control
  • focus in empty form
  • removeHotKey removes all hotkey handlers except of one specific
  • webix.ui usage for cell replacement
  • dynamic inputs can corrupt form's data
  • double rendering in window
  • changing month in main view (case of last day selected)
  • month changing in case of last days selection (like 31 March than go to Feb)
  • autosuggest in combo breaks after form.clean
  • backbone integration and empty collection
  • indeterminate checkbox styling and some other tree styles
  • cancel validation for hidden form fields
  • pager styling
  • pre-selecting combo and richselect options in case of custom template for list
  • options mapping
  • options mapping
  • carousel sizing (carousel was completely rebuilt: view-based, layout is inside)


Version 1.9

Major new features

  • Hotkey for inputs Check details.
  • HTML links in menu Check details

Full list of changes and fixes

New functionality

  • webix.onAjaxError event
  • ability to set default calendar sizes in skin
  • bind can be be used to add new item into collection
  • dayTemplate property
  • focus style for buttons in flat and compact skins
  • getHeaderNode method
  • hotkey for controls
  • menu links
  • refreshFilter api

Updated functionality

  • calendar sizes in touch skin
  • eachColumn for visible and all columns
  • eachRow and data each can loop through hidden elements
  • form.focus() will focus first focusable item in the form
  • strToDate will not break when incoming parameter is already a Date

Fixes

  • async data loading in IE
  • better handling of server side sorting and server side filtering
  • data updates for checkbox in grid
  • dnd in treegrid on header
  • event for master checkbox
  • hidden column in datatable with colspans
  • incorrect work of date, combo, richselect editors
  • label height
  • labels reset
  • lint semicolon error fix
  • menu link width
  • next/prev toggle buttons
  • option width support
  • placeholder in datepicker
  • regression in reloading layout content with webix.ui
  • select editors in property
  • showColumn against initially hidden columns
  • sync webix.require without callback
  • validation css for non-input controls
  • webkit transitionEnd prefix (scroll was not disappeared in Chrome)
  • standalone pager


Version 1.8

Responsive Layouts and Tabbar

  • Layout view can be hidden or moved if there's not enough space for them on the screen. Check details.
  • Tabbar tabs can be moved to a related popup if there are not enough space for them on the screen. Check details.

Disabling dates in Calendar

Calendar dates can be disabled to prevent their selection. Check details.

Breaking changes

  • webix.proxy.$callback was replaced with webix.ajax.$callback
  • adjustHeaders deprecated

Full list of changes and fixes

New functionality

  • limited width for tabs and popup with additional tabs
  • onClick handler accepts names from $scope
  • server side filtering and sorting for datatable
  • template@type = clean
  • template@onClick handler
  • predefined webixbutton css class
  • getChildViews(), getBody() methods to scrollview
  • "local" proxy for working with localstore
  • hide/show of top level views
  • tooltip option for inputs

Updated functionality

  • popup in tabbar refactoring
  • adjust property accepts "data" and "header" values, adjustHeaders deprecated
  • show and hide refactoring
  • min|max date refactoring
  • direction top and bottom for animation in multiview
  • attributes, placeholder and readonly works for all inputs
  • datastore importData can work with primitive sources
  • data@save = true, works the same as @save = @url
  • cssFormat receives 4th parameter - column id

Fixes

  • regression with popup rendering
  • tabview operations in hidden state
  • _refresh_scroll for boolean "scroll" config; padding for popup
  • hiding popup on resize; better popup style
  • popupTemplate customization, size calculation
  • scroll for contextmenu or submenu
  • closing of nested popups
  • position of centered window in case of fullpage scroll
  • sizing of horizontal accordion
  • clipboard operations on macos
  • scrolling in datatable on macos
  • clipboard operations and dyn. grid
  • pager initialized after master component doesn't work correctly
  • datatable blocks global page scrolling
  • regression in dataprocessor url handling
  • drag column over split area
  • obj.open can be any positive value to mark branch open
  • webix.require doesn't trigger callback for already loaded files
  • regression in suggest for plain text fields
  • collections and options for editors
  • double-rendering in case of fillspaces
  • collections and options in datatable
  • webix.extend and webix.EditAbility
  • math operations with complex keys
  • webixEvent doesn't allow to block event
  • using Webix with requireJs
  • initial toggle state must be defined by "value"
  • updateItem overwrite target instead of updating
  • processing proxy callback
  • tab id can't contain a single quote
  • IE8 and list autosizing
  • empty cell in math formulas
  • column.minWidth has lesser priority than grid.minColumnWidth
  • calendar doesn't reset zoom level on hide
  • touch scroll for datatable
  • onChange event for counter view


Version 1.7

Breaking changes in API

datatable.locate method returns object with "row" and "column" properties, in the previous version result object has "row" and "col" properties respectfully.

Default skin

Default skin changed to flat ( you still can use the old skin by using skins/air.css )
Compact skin changed to flat theme as well ( old one renamed to skins/aircompact.css )

Improvements in API

  • text sorting mode for datatable
  • autoheight property for "property" view
  • ability to edit math formulas in the datatable
  • "touch" mode for multiselect

Full list of changes and fixes

New functionality

  • "text" sorting mode for datatable
  • autoheight for "property" view
  • editMath option for datatable
  • keyPressTimeout option for the suggest
  • multiselect="touch" for all data components
  • new compact skin
  • placeholder for richselect and datepicker
  • touch-multiselect mode

Updated functionality

  • pager styling
  • placeholder for richselect and datepicker
  • folder codebase/imgs to codebase/fonts
  • datatable.locate returns different data structure
  • new skin based samples
  • tree and treetable can render hierarchy from db starting from any level
  • webix.message.keyboard disables all text input for modal boxes

Fixes

  • adjustHeaders in case of colspans or rowspans
  • ajax error for destroyed views
  • combo autocomplete after moving focus to the different control
  • cssFormat adds garbage to css string
  • custom checkbox and custom radio clicks in iframes
  • customScroll in datatable and removeView
  • datafeed works only with strings
  • dataprocessor with connector as proxy can send empty request to a server side
  • drag-n-drop in latest FireFox
  • export of treetable data to pdf and excel
  • filter values lost after column resize
  • freezing when focus target can't be found
  • getChildViews in accordion
  • getItemNode in case of split
  • isDirty status and named buttons
  • layout resize fix (maxlength should be checked before its usage in object)
  • minHeight and inner content auto-sizing
  • multi-level form validation
  • native event absent in onDrop handlers
  • popup close delay is too big on desktop
  • refreshColumns doesn't work correctly without first parameter
  • regression in hierarchical data parsing from XML
  • removeView for named field in form
  • render calls for inputs in hidden views
  • rendering of hidden select and combo
  • rendering of layout with all cells hidden
  • resizing in form nested in accordion
  • richselect and combo in IE8
  • suggest box render self in case of empty suggest list
  • uploader demo
  • Web Fonts bug in Google Chrome
  • window positioning for windows with "move" property


Version 1.6

Breaking changes in DataProcessor

Parameters of onBeforeSync, onAfterSync was changed
onError event replaced with two new events - onBeforeSaveError and onAfterSaveError

Improved support for mobile devices

  • win8 touch support
  • drag-n-drop on touch devices

Improvements in Server side integrations

  • full support of REST API
  • data in components can be updated from server side
  • client side code can't be broken by server side errors anymore
  • ability to set custom headers for server side calls

UI components

  • better memory cleaning after component destruction
  • improved API for complex forms

Full list of changes and fixes

New functionality

  • multiview.config.fitBiggest option
  • win8 touch support
  • drag-n-drop on touch devices
1.5.1
  • columns.options accepts url of data feed
  • combo and richselect: setting value on list load
  • datastore importData
  • getDirtyValues and getCleanValues methods
  • getFormView
  • live edit functionality
  • locate method for chart (required for dblclick event handling)
  • math operations in treetable
  • onBeforeAjax event
  • onBeforeDateSelect/onAfterDateSelect events to calendar
  • onColumnResize and onRowResize events
  • relatedView and relatedAction attributes
  • required and validateEvent attributes for form elements
  • sort:"server" in datatable
  • unbind and unsync, correct destruction of synced and binded elements

Updated functionality

  • disabled tap iOS7 highlighting
  • addCss and removeCss attempts to set styles directly in DOM without full repainting
  • error handling by dataprocessor, better support of REST mode
  • "move" command attempts to make changes directly in DOM without full repainting
  • special handling for dnd in case of mobile webkit
  • updating data in the client side component after saving
  • webix.env.mouse contains names of pointer events for current devicePM
  • xml data feeds for suggests
1.5.1
  • all layout components can use events
  • destructor correctly removes the related views
  • function resolving can work with both "someMethod" and "someMethod()" notations
  • getColumnConfig returns config for hidden columns
  • setColumnWidth uses column id as parameter, not column index

Fixes

  • branch deleting in dyn. loading mode webix-hub/tracker#84
  • config options and html template during parsing from html markup
  • data reordering in datatable in case of mobile webkit
  • destructed views not removed from auto-resize list
  • destructing suggest if a master control of this suggest is destructed
  • detection of Win Phones
  • disabled styling in case of labelPosition="top"
  • focus in inline editor after component repainting
  • inline editors and correct edit state in datatable
  • layout resizing on touch devices
  • min value for slider
  • scrollview doesn't adjust itself after inner content change in case of touch
  • styling of list during drag-n-drop
  • styling of row during drag-n-drop
  • tree editor position self incorrectly
  • webix.DragControl on touch devices
  • webix.html.pos in case of touch events
1.5.1
  • $scope not defined inside of window
  • adding borderless element to layout through addView results in the incorrect sizing
  • addView and removeView do not updated elements collection for rich formsPM
  • after deleting view from the form its value still accessible through getValues
  • camelCase parameters during initialization from HTML
  • checkbox reacts on empty space clicks, #75
  • clock icon
  • custom scroll and disabled areas
  • custom scroll doesn't react on addview command
  • custom scroll in suggest boxes
  • datatable blocks whole page mouse-wheel scroll
  • delete dataprocessor on master view destruction
  • dynamic loading for deep sub levels
  • elementsConfig doesn't work for nested fieldset
  • empty text in combo input;
  • fieldset breaks parentView chain
  • form with scroll ignores height
  • getChildViews for fieldset
  • getFormView throws an error for element outside of form
  • illegal comma removed
  • invalid behavior for movable window and position:center
  • invalid editor sizes after column or row resizing
  • isDirty doesn't work for the fresh form
  • isolate property and multiview, #79
  • popup zIndex was not increased on show
  • regression in popup editors
  • regression in richselect related to after-loading value
  • regression in xml-xhtml data parsing
  • submenu that is not based on menu
  • unnecessary custom scroll in datatable
  • window sizing ignores min-width for the inner content


Version 1.5

Improved support for mobile devices

  • new skin for mobile UI (demo)
  • functionality of desktop UI adapted to touch events and gestures

Improvements in DataTable

  • adjustRowHeight method added to datatable ( autodetects and applies the correct row height )
  • fillspace can be used for multiple columns ( percent based sizing in datatable )
  • richselect can be used as editor in the datatable
  • checkboxes can have checkValue and uncheckValue options

Improvements in Angular and Backbone

  • [angular] webix-ui is compatible with ng-repeat
  • [angular] webix-data works for options in combo and select

  • [angular] initialization through angular directive links event handlers to the current scope

  • [backbone] handling of reset event

  • [backbone] handling of models with getters
  • [backbone] WebixView is compatible with backbone 1.1
  • [backbone] using sync with already loaded collection

Full list of changes and fixes

New functionality

  • ability to define form as editor
  • activeTitle option for the tree (open/close an item on click)
  • adjustRowHeight method
  • checkValue and uncheckValue for checkbox
  • checkValue and uncheckValue for checkbox and radio editors in the grid
  • className correctly processed while parsing data from the html
  • getItemNode method
  • global hotkeys for edit operations and window closing
  • htmlbutton button type
  • minWidth setting for grid's column
  • onValueSuggest event for the suggest control
  • retina support for canvas
  • richselect editor for the grid
  • webix.once method

Updated functionality

  • $formElement deprecated
  • a bit better visual position for showItem
  • ability to toggle accordion items in any modes
  • backbone integration - reset event and getter usage
  • button and inputs styling for font-awesome
  • cssFormat can be a string with name of function
  • editCell in datatable can be called without column id
  • fillspace can be used on multiple columns with different weights
  • function names can be resolved in custom scope
  • getSelection -> getSelectedId
  • idColumn to csv abd jsarray data drivers
  • initialization through angular directive links method to the current scope
  • look of tabbar in clouds skin
  • selectFilter in datatable sorts options by default
  • suggest can use complex popups
  • support for multiline rows in datatable
  • tab navigation works for grid without active editor
  • webix-data can be used to define the select options
  • webixEvent and webixData works for object initialization (angular)
  • window closing and modality

Fixes

  • slider for touch
  • autoscroll and autoopen during dnd
  • autosizing of templates
  • backbone view must return this
  • calling ungroup on clearAll
  • carousel resize after changing structure
  • combo editor do not work with config.options
  • datatable selection (multiselect was always applied)
  • dblclick doesn't work in cell selection mode
  • debug file throws an error while generation error message for empty data set
  • deleting selected row in treetable may cause auto-loading attempt
  • disabled buttons in IE8
  • form with scroll still uses maxHeight
  • fullScreen for latest devices
  • getItemNode for datatable
  • getSelectedId doesn't work when plain id requested
  • grouplist width
  • icon font on old mobile devices
  • icons in Touch skin
  • incorrect $scope for child views
  • incorrect processing text nodes in xml
  • incorrect rendering of touch scroll for datatable in Chrome Mobile
  • invalid uid generation code
  • item styling for the the selected state
  • menu vertical align
  • named types for treetable
  • named types in datatable
  • ng-repeat and webix json integration
  • onChange event in text inputs
  • onRotate was called on window resize
  • options collections and backbone 1.1
  • overflow for label
  • parsing long text content from xml in FF
  • regression in angular initialization
  • regression in getSelectedId
  • regression in webixElements (angular)
  • regression in window position
  • resizing of templates and onload handler in iframe
  • richselect icon
  • selection mode affects the id to string conversion
  • solution for 4K text node Firefox limitation
  • styling of disabled elements in IE
  • sync ignores configuration parameter
  • sync with backbone ignores already loaded data
  • tabbar doesn't adjust itself after active tab change
  • text-based validation rules aren't recognized
  • using calendar suggest for text inputs
  • using js code literals in xml config
  • view throws an error if angular provides non collection as a data
  • webix_security flag isn't set correctly for the connector calls


Version 1.4

Advanced data selection controls

  • mutli-column select box Related sample: Grid Suggest
  • rich content select box Related sample: Data Suggest

New Server Integrations

  • loading and saving data through websockets (details)
  • loading and saving data through indexedDB (details)

Improvements in Window Positioning

  • window can have complex relation size and position (details)
  • window can be shown in fullscreen mode

Other

  • autoConfig option for the datatable
  • dataprocessor tracks data moving events
  • keyboard navigation for list component
  • correct sizing of layout with hidden panels
  • elementsConfig supported for nested collections
  • getSelection deprecated in favor of getSelectedId
  • better styling for icon buttons
  • webix.onReady event
  • webix.ui.zindexBase property added
  • different small fixes in UX and styling


Version 1.3

New skins

  • 6 new skins added (details)

Improvements in UI

  • video player component (ui.video) added (details)
  • API and look of carousel control improved (details)
  • charts can use logarithmic scale (example)

Other

  • small fixes in form controls and datatable


Version 1.2

Integration with AngularJS

  • webix-ui directive to define webix views directly in HTML
  • webix-show, webix-event, webix-data directives to link webix components and scope
  • webix component can be used with angular data bindings
  • check details

Integration with Backbone

  • webix components can load data from Backbone Collections
  • webix components can save data back to Backbone Collections
  • WebixView, that can be used as normal Backbone View
  • Backbone Router can be used to alter Webix Layouts
  • check details

Others

  • setContent method for template component
  • isolate configuration property for layout components
  • onBeforeDropOut event added
  • tooltip functionality added to the DataTable, TreeTable and Tree
  • more than 50 different fixes


Version 1.1

Server side integration

  • all components can save data through REST API
  • offline and caching loading strategies
  • custom data saving and data loading transports

UI improvements

  • "disabled" configuration options for all views ( including all form controls )
  • webix.history can be used with multiview control
  • per-submenu configuration is possible ( "config" property of menu item )
  • improved visual filtering in treetable and tree

API

  • onViewResize event added
  • "disabled" option added for all views
  • ability to define XSS safe templates

Fixes

  • popup's visibility on iOS
  • incorrect sizing of multiview and accordion
  • incorrect behavior of drag-n-drop in datatable
  • setValue doesn't work for radio buttons


Version 1.0.2

New functionality

  • getText method for datatable
  • lineMaxLimit parameter that cuts a line in "non-item" position
  • ui.fullScreen solution for FF
  • default size of resizer changed
  • xml parse can recognize arrays
  • addView adds to the end of layout if index was not defined
  • skin updates, important flags removed where possible
  • csrf key now sent through http headers

Fixes

  • IE ignores hotkeys
  • IE8 doesn't generated dblClick events
  • IE8 sets invalid value after changing cell value with select editor
  • minWidth and maxWidth settings from xml
  • loading tree-like data from XML
  • datatable do not allow to define order of columns during export to pdf and excel
  • incorrect remove action for local and session storage
  • regression in layout rendering when views are added through addView
  • dataprocessor and id change during binding
  • label align in segmented button
  • incorrect in-layout positions after showBatch call
  • invalid animations in FF and Chrome


Version 1.0.1

New functionality

  • layouts are correctly shown when they are zoomed by a browser
  • selectFilter can show data from the attached collections
  • better strategy for x-layout rendering
  • API calls against hidden items in menu
  • init from html|xml markup improved
  • dataprocessor can have different urls for different action
  • value attribute for tabview
  • getTopParentView method added for all views
  • getPopup method added to the datepicker
  • setHTML method added to the label
  • setValue and getValue methods added to the multiview

Fixes

  • invalid size and focus of popup editors
  • toggle button ignores inputWidth settings
  • regression in treetable checkbox behavior
  • regression in datatable markup parsing
  • conflict between data and content properties of template
  • row markers are not removed during clearAll
  • mulitiview with no animation
  • chart rendering in multiview (no animation case)
  • label position in pie chart
  • validation and htmlform control
  • incorrect column autosizing in case of hidden container
  • native selection during cell resize
  • hideItem throws an error for menu's item which was already hidden
  • incorrect handling of custom popups in editors
  • sizing of scrollview was broken
  • window ignores y parameter of show command
  • dnd in tree as child


Start

UI Components

The Webix UI library supplies over 70 fully customizable components to help you build interfaces of different kinds, nicely present data and work with it. There are also multiple controls and specific features to make your applications good-looking and user-friendly. All the components are objects made with the webix.ui() constructor where the type of the component is set by the 'view' property (the declarative syntax is available as well).

Pivot

Mobile Scheduler

Kanban Board

File Manager

Spreadsheet

Data Components

Data components are used to present data of a specified type on the page. Such components manage the space allocated for their data and provide functionality for its access and configuration.

Chart

DataTable

Dataview

Grouplist

List

Organogram

PropertySheet

RangeChart

Tree

TreeMap

TreeTable

Unitlist

Layouts

Layouts help you to organize your web page, define its overall look-and-feel. You can arrange the content in columns and rows, divide it into groups and control through navigation or animation.

Accordion

Carousel

Form

Layout

Portlet

Multiview

Scrollview

Tabview

Toolbar

Context Components

Context components let displaying spatial and temporal information on some user's action, such as click on a button or filling in a field.

Context

ContextMenu

Menu

Popup

Sidemenu

Window

HTML-oriented Components

Html-oriented components supply handy means for using habitual HTML elements in an application. There you can specify HTML templates, inline frames, forms etc.

HTMLForm

IFrame

Video

Template

Auxiliary components

Auxiliary components help you to complete the picture of your application, to add special features that can't be achieved with the standard set of components presented above.

Barcode

Calendar

Colorboard

Excel Viewer

PDF Viewer

Uploader

Controls

Controls are mainly responsible for handling events since they enable user-app interaction by triggering functions attached to them. Note that any event can be attached to any component by referring to its ID.

  • Button
  • Checkbox
  • ColorPicker
  • Combo
  • Counter
  • Datasuggest
  • Datepicker
  • Icon
  • Fieldset
  • Gridsuggest
  • Label
  • Multicombo
  • Multiselect
  • Multitext
  • Radio
  • RangeSlider
  • Richselect
  • Search
  • Select
  • Segmented
  • Slider
  • Suggest
  • Tabbar
  • Text
  • Textarea
  • Toggle

UI Extensions

UI extensions are helpful components that are mostly task-oriented and intended to accomplish a certain purpose. They are already quite configurable and need only initializing on the page to start serving.

To see a complete list of extension components and find out details on their use, please, go to the chapter - UI Extensions.


Accordion

API Reference
  • Methods, properties and events
  • Samples

Overview

Accordion consists of panes arranged into layout rows and cols. Each pane, or accordion item, features body and header and can be fully expanded and collapsed by clicking its header. You can place text or any component into each pane. The component inherits from layout.

Initialization

Accordion with three panes

webix.ui({
    view:"accordion",
    multi:true,
    cols:[ //or rows
        { header:"col 1", body:"content 1" },
        { header:"col 2", body:"content 2" },
        { header:"col 3", body:"content 3" }
    ]
});

Related sample: Complex Accordion

Comments:

  • By essence, each row/column is a ui-related accordionitem component; however, it's direct initialization isn't compulsory - you can just enumerate its properties in the row (column) as shown above.
  • Moreover, you can omit the view:"accordion" line as well. The component will be drawn anyway as soon as you divide a row/column into header and body parts.
  • There can be as well rows/ cols without headers. It goes without saying that they are non-collapsable.

Related sample: Horizontal Accordion

Note that view name can be omitted (view:"accordion"). If you place an array of objects with body and header into row or column - the view will be automatically recognized as accordion.

webix.ui({
    cols:[ //or rows
        { header:"col 1", body:"content 1" },
        { header:"col 2", body:"content 2" }
    ]
});

Related sample: Layout with Headers

Working with Accordion

Accordions differ by their possibility to show and hide panes at the same time. There's a special multi parameter to set the necessary mode.

  • multi:true - all panels can be expanded as well as collapsed at a time;
  • multi:false (default) - only one panel can be (and must be) visible at a time;
  • multi:"mixed" - all panels can be expanded at a time, but you cannot close them all. One panel remains visible.

Related Articles
  • Setting Borders to the Components
  • Adding Headers to Components
  • Sizing Components
  • Resizing Components
  • Layout
  • Multiview
  • Scrollview
  • Carousel
  • Accordion CSS Image Map


Accordionitem Configuration

Accordionitem inherits from view and is an integral part of the ui-related accordion component. You need at least two accordionitems to make a workable accordion.

Any accordionitem must have two properties: header for heading and body for main text or some ui component.

webix.ui({
     rows:[ // or cols
        {
            view:"accordionitem",
            header:"Pane 1",
            headerHeight:20,
            headerAlt:"Pane 2 Closed",
            body:{ view:"form", ...} //ui component
        },
        {
            view:"accordionitem",
            header:"Pane ",
            headerAlt:"Pane 2 Closed",
            body:"This is Pane 2 body", //just text
            collapsed: true
        }]
})

Comments:

  • header - defines text heading for a panel in an expanded state;
  • headerAlt - defines text heading for a panel in a collapsed state;
  • headerHeight / headerAltHeight - defines the height of a panel in an expanded/collapsed state;
  • collapsed (false or true) - defines the panel that will be expanded/collapsed on the app's loading.

If you initialize accordion like below, you can omit accordionitem initialization:

webix.ui({
    view:"accordion",
    rows:[
        {header:"Pane", body:"Pane 1"},
        {...}
       });

Related sample: Accordionitem

Accordionitems can be collapsed and expanded programmatically with the help of dedicated methods:

$$('item1').collapse();
$$('item1').expand();
//don't forget to specify IDs to accordionitems!

If the items of your accordion are arranged in cols, their headers are collapsed to vertical panels as you close an accordionitem.


Available only in PRO Edition

Barcode

API Reference
  • Methods, properties and events
  • Samples

Overview

The Barcode widget represents text values in a machine-readable format by varying the widths and spacing of parallel lines. The widget uses Canvas for lines rendering.

Basic Initialization

To begin with, create a new HTML file and include the related Webix code files in it.

Required code files are:

  • webix.css
  • webix.js

A basic html page with the included code files

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Barcode</title>
    <script src="../codebase/webix.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="../codebase/webix.css" type="text/css" charset="utf-8">
</head>
<body>
    <script>
        //here you will place your JavaScript code
    </script>
</body>
</html>

Next, you should create a div container to place your barcode into.

<div id="box" style="width:300px;height:200px;"></div>

Now you can initialize the component. To create a new Barcode object, you need to use the next constructor:

Barcode constructor

barcode = new webix.ui({view:"barcode"});

If you want to place the component into the container, you should specify the container property inside of the view constructor:

Basic barcode configuration

barcode = new webix.ui({
    container:"box",
    view:"barcode"
});

Related sample: Initialization

Configuration settings

You can set the following properties to configure Barcode:

  • type - sets the barcode type. There are 3 built-in types: "ean8", "ean13" and "upcA" ("ean13" is the default one):
webix.ui({
    view:"barcode",
    type: "upcA"
});

//or
var barcode = webix.ui({
    view:"barcode"
});
barcode.define("type", "upcA");
  • value - sets barcode value (text):
webix.ui({
    view:"barcode",
    value: "123456789012"
});
  • width - defines the view width
webix.ui({
    view:"barcode",
    width: 250
});

If you want to set flexible width, you need to set the -1 value for this property:

webix.ui({
    view:"barcode",
    width: -1
});
  • height - defines the view height
webix.ui({
    view:"barcode",
    height: 180
});

If you want to set flexible height, you need to set the -1 value for this property:

webix.ui({
    view:"barcode",
    height: -1
});
  • paddingX - sets the left and right paddings (space between widget border and bars)
webix.ui({
    view:"barcode",
    paddingX: 20
});
  • paddingY - sets the top and bottom paddings
webix.ui({
    view:"barcode",
    paddingY: 10
});
  • textHeight - sets the height of the text block
webix.ui({
    view:"barcode",
    textHeight: 20
});
  • color - sets the bar color
webix.ui({
    view:"barcode",
    color: "#000"
});

Setting Value

You can set the value in two ways:

  1. via the value property in Barcode configuration
  2. using the setValue method
var barcode = new webix.ui({
   view:"barcode",
   value: "123456789012"
});
// set the new value
barcode.setValue("453456789015");

Type Definition

Webix Barcode includes 3 definitions for most popular barcodes (EAN8, EAN13 and UPC-A):

  • ean8
  • ean13
  • upcA

"ean13" is the default type.

Use the type property to set the Barcode type:

barcode = webix.ui({
    view:"barcode",
    type: "upcA"
});

The type of Barcode can be changed dynamically via the define method. After the changes are applied, you need to call the render method to redraw Barcode with the new type:

barcode.define("type","ean8");
barcode.render();

Related sample: Built-in types

Custom Types

If you need create a custom barcode, you can add the necessary type to the existing Barcode view.

Each barcode type should contain a function that returns a sequence of “0” and “1” chars based on the incoming text value. This 0-and-1 character combination will be used for bar rendering.

The Library will render black bars for “1” chars and leave gaps for the “0” ones.

To add a new type you need to use the webix.type method that takes two parameters:

  • ui object that the type will be created for ( webix.ui.barcode for Barcode)
  • object with type configuration
webix.type( webix.ui.barcode, {
    /* type configuration here */
});

Type configuration of Barcode must contain 3 properties:

  • name - {string} the name of the code
  • encode - {function} the function that returns sequence of “1”and “0” chars for black-and-white bar rendering
  • template - {function} the function that returns text for barcode

Let's consider an example of the "code39" barcode configuration:

1) define type name in the type configuration:

 name:"code39",

2) set an array with encodings for 43 characters, consisting of uppercase letters (A through Z), numeric digits (0 through 9) and a number of special characters (-,., $, /, +, %, and space):

encodings:[
    "110101001011",
    "101101001011",
    ...
]

3) set the template function that will convert the incoming text to uppercase and add “*” as start and stop characters:

 template: function(value){
      return ("*" + value + "*").toUpperCase();
 }

4) define the encode method that will apply 0-1 sequences from encodings array to incoming text value

encode: function(value){
    var chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-. $/+%*";
    var code =””;

    // apply template method
    value = this.template(value);

    for(var i=0; i<value.length; i++){
        var pos = chars.indexOf( value.charAt(i) );
        if (pos < 0)
            return "";
        if (i)
            code += “0”;

        // apply encoding for character
        code += this.encodings[pos];
    }
    return code;
}

So, the whole "code39" type definition will be as in:

webix.type(webix.ui.barcode, {
    // name
    name: "code39",

    // encodings for "A","B", etc. characters
    encodings: [
        "110101001011",
        "101101001011",
            ...
    ],

    // applies encoding for incoming text
    encode: function(value){
        var chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-. $/+%*";
        var code =””;

        // apply template method
        value = this.template(value);

        for(var i=0; i<value.length; i++){
            var pos = chars.indexOf( value.charAt(i) );
            if (pos < 0)
                return "";
            if (i)
                code += “0”;

            // apply encoding for character
            code += this.encodings[pos];
        }
        return code;
    },

    // returns text for code39 barcode
    template: function(value){
        return ("*" + value + "*").toUpperCase();
    }
 });

Here is an example of the "code39" usage:

barcode = webix.ui({
   view: "barcode",
   type: "code39",
   value: "CODE 39"
});

The result of applying the "code39" type is given in the picture below:

Related sample: Custom types


Calendar

API Reference
  • Methods, properties and events
  • Samples

Overview

UI-related calendar inherits from view and allows you to include the Date and Time picker calendar into an app. It is a handy and fully interactive tool to pick the necessary time and date when filling a form. The dedicated timepicker allows setting the necessary time that will be displayed below the calendar area.

Initialization

webix.ui({
    view:"calendar",
    id:"my_calendar",
    date:new Date(2012,3,16),
    weekHeader:true,
    events:webix.Date.isHoliday,
    calendarDateFormat: "%Y-%m-%d",
    width:300,
    height:250
});

Related sample: Calendar

Comments:

Here is a calendar with basic parameters.

  • weekHeader (boolean) - if true shows weekday above;
  • events (CSS class or specific cases) - e.g. webix.Date.isHoliday highlights days off;
  • date (string, object) - specifies the start date in the "year, month, day" format with months starting from 0. In case of an empty new Date(); you'll be shown current date;
  • dayTemplate (function) - specifies a function that sets a template for each day cell. By default the date is displayed without any styling;
  • icons (boolean) - specifies whether to show "Today" and "Clear" icons.

To see the full list of Calendar properties please refer to the corresponding chapter of the documentation.

Setting Start Day of the Week

By default the calendar starts a week on Sunday. However, you can also set Monday as a start day. For this purpose, use the startOnMonday property with the value true:

webix.Date.startOnMonday = true;

webix.ui({
    view:"calendar", ...
});

Related sample: Calendar: Start on Monday

Working with Calendar

Setting and Getting Dates

Setting dates means their selection. Dates can be set programmatically after calendar initialization:

  • setValue(new Date(2012,3,30)); - common method for setting values to the controls;
  • selectDate(new Date(2012,3,30)); - calendar specific method equal to the above mentioned one;
  • showCalendar(new Date(2012,3,30)); - makes the calendar show the specified date, but doesn't select it.

Getting dates can be done with two corresponding methods:

  • getValue(); - common method for getting the control's value.
  • getSelectedDate(); - calendar specific method.
  • getVisibleDate(); - gets the date even with no selection applied. Date is defined according to the specified rules.
$$('calendar1').selectDate(new Date(2012,3,30));

$$("calendar1").getValue(); // returns the non-formatted date object
                            // -> Mon Apr 30 2012 00:00:00 GMT+0300 (EEST)

Datepicker

Calendar can be displayed on customer request, for instance when a user wants to pick a date and time to fill the form. For these needs a datepicker control is used. Note that here you needn't initialize Calendar - it will appear as soon as you click a datepicker icon. In this case the calendar comes with current date displayed.

webix.ui({
    view:"toolbar",
    type:"MainBar",
    elements:[
        {view:"datepicker",  name: "select_date",  label: 'Select Date' }
    ]
});

Related sample: Date picker in Calendar

Time Selector in Calendar

Webix calendar offers two ways of time selection:

  • built-in timepicker;
  • separate time view.

Time slots in selector are multiple of 5.

Timepicker inside Calendar

The timepicker is hidden by default. To enable it you should set the property to true. Then a timepicker is accessed by clicking a "clock" icon below the calendar grid.

webix.ui({
    view:"calendar",
    date: new Date(2012, 3, 16, 8, 35),
    timepicker:true,
    timepickerHeight:50 //optional, default is 30
})

With timepicker enabled, time is shown below month view within the calendar body. There are three options for the clock:

  • If the time is defined in the new Date(YYYY, MM, DD, HH, mm) constructor, it's shown according to the specified values;
  • If date is set with no time specified (new Date(2012, 3, 16)) - the clock shows midnight;
  • If the new Date function comes with no parameters, current date and time is shown.

Related sample: Timepicker in Calendar

Time view

Time view of the calendar is detached from date selector and is shown separately. To initialize such a control you should set calendar to time mode.

webix.ui({
    view:"calendar",
    type:"time"
});

Related sample: Timepicker in Calendar

Like standard calendar, time view accepts values as string or date object.

Localization

How do we turn a standard calendar into the one with "foreign" month and day names? Here localization can help you.

Locale is a set of rules that tell us how to display months and days. It's a kind of internal "translator" for UI components.

First of all you should specify a locale or a set of needed locales (en-US, fr-FR, ru-RU) and then apply them to the calendar. By default en-US locale is used.

webix.i18n.setLocale('fr-FR');

Afterwards the calendar will look like this:

Related sample: Localized Calendar

You can as well alter current working locale, e.g. change text of "Today" and "Clear" icons:

webix.i18n.calendar.clear: "Clear New";
webix.i18n.calendar.today: "Today New";
webix.i18n.setLocale();

You need to call the setLocale method to make changes come into force.

Disabling Dates and Time Slots in Calendar

The whole calendar can be disabled by a common property:

{view:"calendar", disabled:true}

Related sample: Disabled dates

Disabling dates

To disable a certain period in the calendar, which presupposes specific CSS and blocking of click events, you can go by the two ways:

Defining "active" period

Use the dedicated minDate and maxDate properties to limit the period that will be available for clicking and, hence, selecting:

{ view:"calendar", minDate:'2014-05-07', maxDate:new Date(2014, 4, 13) }

The dates can be defined either as date object or date string formatted under the current locale. Here the default en-US parseFormat is used, "%Y-%m-%d".

Defining blockDates() function for custom logic

The function should return true for the dates that should be disabled in the calendar. Here all date up to 2014 will be disabled:

webix.ui({
    view:"calendar",
    blockDates:function(date){
        if(date.getFullYear()<=2013)
            return true;
    }
});

CSS class applied to disabled dates (.webix_cal_day_disabled) can be redefined.

Disabling time slots

Calendar features a time selector where you can disable time slots. Disabled time slots feature specific CSS and don't respond to click events. They should be multiple of 5.

Defining blocked time periods

Use the dedicated minTime and maxTime properties to set the time period that will be available for selecting:

webix.ui({
    view:"calendar",
    timepicker:true,
    minTime:"8:00",
    maxTime:"18:30"
});

Related sample: Disabled time

Defining blockTime() function for custom logic

The function takes a date object as parameter and should return true for disabled time slots.

var disabledTime = [
    new Date(2015,6,1,8,40),
    new Date(2015,6,1,9,10),
    new Date(2015,6,1,10,30)
];

webix.ui({
    view:"calendar",
    blockTime:function(date){
        for(var i =0; i< disabledTime.length; i++){
            if(disabledTime[i].valueOf() == date.valueOf())
                return true
        }
        return false;
    }
});

Related sample: Disabled time

CSS class applied to disabled time slots (.webix_minutes .webix_cal_day_disabled) can be redefined.

Today and Clear Buttons

The Today button allows selecting the current date. The Clear button removes date selection.

These buttons are optional and specified in the icons array. The code below renders a calendar with a timepicker and Today and Clear buttons:

webix.ui({
  rows:[
    { view:"calendar", timepicker:true, icons:true }
  ]
});

To hide the buttons, you should set the icons property to false.

Related sample: 'Today' and 'Clear' buttons

Related Articles
  • Date Formatting Methods
  • Number Formatting Methods
  • Working with Dates
  • Date and Number Localization
  • Calendar CSS Image Map


Carousel

API Reference
  • Methods, Properties and Events
  • Samples

Overview

Ui-related carousel is designed to present Webix components in one view with the ability to switch between them by clicking on the dedicated buttons or sliding (on touch devices).

Related sample: Carousel Initialization

Initialization

Carousel items are arranged into either rows to scroll through them vertically or in cols to scroll horizontally. Each row/column includes Webix component, e.g:

  • simple or data template for showing texts and images;
  • any data component like dataview, chart, datatable;
  • layout of any complexity.
webix.ui({
    view:"carousel",
    id:"carousel",
    cols:[
        { view:"template" },
        { view:"chart" },
        { view:"datatable" },
        { rows:[...]} //layout
    ]
});

Related sample: Carousel Initialization

Normally, component configuration is stored separately while cols/rows contain an array of corresponding variables. It makes code clear and easy to read.

Navigation Area

Carousel comes equipped with a navigation panel that contains:

  • navigation items (circles) that show the number of carousel views and highlight the opened one;
  • navigation buttons (right/left) placed together to the right of the circles.

You can either click buttons or items to get to the needed view. On touch devices views are switched by swipe movements.

Redefining Navigation

Related sample: Navigation types

Navigation area is controlled via navigation object property of the carousel component. From there you can:

  • separate navigation buttons and place them on the right and left sides of the view, define "side" type;
  • remove navigation items (circles) or buttons by setting false value to the corresponding property.
view:"carousel",
cols:[...],
navigation:{
    type: "side",
    items:false,
    //buttons:false
}

Custom Navigation Area

Any Webix component can be used to navigate through the carousel by using its API.

For instance, you can use one-row dataview with thumbnails of carousel views.

Related sample: List navigation

In layout carousel and the component used for navigation are stored in different rows or cols:

rows:[
    {view: "carousel",
     id:"carousel",
     cols: []
    },
    {view: "dataview",
     id: "imageList",
     yCount: 1, //one row
     select: true, //item selection enabled
     scroll: false, //non-scrollable
     data: [...]
    }
]

Switching is enabled by catching carousel onShow and dataview onItemClick events:

// when dataview item is clicked, the needed view is shown
$$("imageList").attachEvent("onItemClick",function(id){
    $$(id).show();
});

//when carousel item is shown, its thumbnail in dataview is selected
$$("carousel").attachEvent("onShow",function(id){
    $$("imageList").select(id);
});

Learn more about how to show and hide Webix components and study selection pattern of data components.

Scrolling Speed

The default scrolling speed of the carousel is 300ms. To change it use the following:

webix.ui({
    view:"carousel",
    scrollSpeed: "500ms"
});

However, in case of significantly slower scrolling speed smoothness may degrade.

Working with Carousel

1 . You can programmatically navigate through the carousel with the help of the following switching functions: - showPrev() - takes to the previous view; - showNext() - takes to the next view.

These functions can be attached to custom buttons or any on-page and application events:

 { view:"button", value:"Previous View", click:function(){ $$('carousel').showPrev(); }

2 . With touch-based devices initial scrolling pattern can be changed depending on the screen orientation. Scrolling is adjusted by the dedicated method:

$$("carousel").adjustScroll();

Setting the Active Element for the Carousel

3 . Active carousel item is a view that is currently shown. Carousel views can be treated either by their IDs or by their position in the cols/rows array (zero-based numbering).

  • setActive(id) - shows a view with the specified ID;
  • setActiveIndex(index) - shows a view with the specified index;.

4 . The same way you can get the currently shown (active) item:

  • getActiveId(); - returns ID of the active view;
  • getActiveIdIndex(); - returns index of the active view.
$$("carousel").getActiveIndex();

Related Articles
  • Adding Headers to Components
  • Event Handling
  • Sizing Components
  • Resizing
  • Redefinition of Components
  • Layout
  • Multiview
  • Scrollview
  • Carousel CSS Image Map


Chart

API Reference
  • Methods, parameters and events
  • Samples

Overview

Chart is a ui-related component that inherits from view and helps present data in different graphic figures like colored columns, pie pieces or lines. Like all the data-presenting components it takes initial data in various formats.

Initialization

The most important chart properties include type, template and value for data as well as criteria for data presenting (e.g. step of X axis in a bar chart). Specify the chart ID if you are going to work with it later.

Initialization of a Bar Chart

 webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    color:"#f6960a",
    border:true,
    xAxis:{
        template:"'#year#"
    },
    yAxis:{
        start:0,
        end:100,
        step:10,
        ...
    },
    data: dataset
});

Related sample: Chart: XML Dataset

To learn about all the chart properties, please refer to the corresponding chapter of the manual.

Working with Chart
  • Chart Types
  • Range Chart
  • Setting Chart Scales
  • Chart Series - Comparison Charts
  • Setting Legend for a Chart
  • Setting Chart Tooltip
  • Data Grouping
  • Operations with Chart Data
  • Chart Colouring
  • Components Export to PNG
  • Data Components Export to Excel

Related Articles
  • Data Object Operations
  • Supported Data Types
  • Redefinition of the Components
  • Event Handling
  • Operations with Data Items
  • Chart CSS Image Map


Chart Types

Here we speak about various chart types at your disposal. Basically, you should set the type property of the chart constructor to the necessary value to switch to the corresponding chart type.

Pie, 3D Pie Chart and Donut Charts

Initialization

webix.ui({
    view: "chart",
    type:"pie", //or "pie3D", "donut"
    ...
})

Related sample: Pie Chart: Basic Initialization

Settings for Pie Charts

Line and Spline Charts

Line chart features a broken line to join the points while a spline chart has a curved one.

Initialization

webix.ui({
    view:"chart",
    type:"line" //or "spline"
    ...
})

Related sample: Line Chart: Basic Initialization

Settings for Line Charts

Bar, BarH, StackedBar and StackedBarH Charts

Initialization

webix.ui({
    view:"chart",
    type:"bar" //or "barH", "stackedBar", "stackedBarH"
    ...
})

Related sample: Bar Chart: Basic Initialization

Settings for Bar Charts

Area and stackedArea Charts

Initialization

webix.ui({
    view:"chart",
    type:"area", //or stackedArea
    ...
})

Related sample: Area Chart: Basic Initialization

Setting for Area Charts

Radar Charts

Initialization

webix.ui({
    view:"chart",
    type:"radar",
    ...
})

Related sample: Radar Chart: Points

Settings for Radar Chart

Scatter Charts

Initialization

webix.ui({
    view:"chart",
    type:"scatter",
    ...
})

Related sample: Scatter Chart: Basic Initialization

Settings for Scatter Chart


Settings for Pie Charts

Data Presentation

Template items are taken from the dataset defined for the component.

data=[{sales:"20", month:"Jan", color: "#ee3639"}]
  • value ('#sales#') - data item that is taken for graphical representation. Its values form 'pie' pieces;
  • label ('#month#') - data item used for making text label for 'pie' pieces;
  • labelOffset (number) - the offset of sector labels from the pie frame (20px by default);
  • pieInnerText ('#sales#') - text (numeric) values displayed on each 'pie' piece;
  • color ('#color#') - color for each piece. Can be either in the dataset, or if not mentioned, default colors will be displayed.

Styling and Positioning

These settings can be easily omitted yet add style to your chart.

  • radius (number) - radius of the chart 'pie';
  • x (number) - horizontal offset of pie center from left side of the parent container;
  • y (number) - vertical offset of pie center from the top border of the parent container
  • gradient (boolean) - gradual color shifting;
  • shadow (boolean) - decorative shadow for the component;
  • cant (number) - defines the slope angle of 3D pie(from 0 to 1, 0.5 by default);

Back to all chart types


Settings for Bar Charts

Data Presentation
  • value (template) - template from the dataset for data item to present graphically;
  • data / url (string/url) - the datasource;
  • label (template) - text label for each bar;

Learn how to draw chart scales in the dedicated chapter of the manual

Styling and Positioning
  • barWidth(number) - width for each bar in pixels;
  • radius (boolean) - if true, sets curved bar tops;
  • gradient ( boolean, string, function)) - gradient for each bar;
  • padding (obj) - offset from the whole chart to the parent container {top:50, left:0, right:30, left:40}
  • color (template, hex code, function) - color effects for the bars;
  • alpha (number between 0 and 1) - transparency of chart bars;
  • border (boolean) - if false, removes a black border of the bars. True by default.

Read more about Chart Coloring

Bar Chart Types

Table 1 Bar chart types
Type | Vertical Bars | Horizontal Bars
Single data | bar | barH
Several data values | stackedBar | stackedBarH

StackedBar and stackedBarH charts display data of several configuration objects (chart series), e.g. graphical representation of sales of three companies.

Bar Chart Series

Series can be defined for all bar charts. Series with bar and barH chart differ from those of stackedBar and stackedBarH. With the former bars are placed by each other in groups, which is greater for comparison. Moreover, the legend for them allows hiding and showing the dedicated chart by single mouseclick.

Table 2 Presenting several data properties on bar chart
Using series
'stackedBar'/'stackedbarH'
charts

Related sample: Bar Chart: Several Graphs in One Chart

The rules of series definition are described here.

Presets for Bar Chart

The library provides 3 presets for Bar charts. To set one of presets you should specify the preset property for the chart:

webix.ui({
    view: "chart",
    type: "bar",
    preset: "stick",
    ...
};

Related sample: Bar Chart: Style Presets

Table 3 Bar chart presets
preset:"column"
preset:"stick"
preset:"alpha"

Back to all chart types


Color Effects

Chart elements can be colored in various way, fixed color being defined by the color parameter that takes hex code. By default items are colored in a rainbow manner.

Custom color

Different color for items can be defined in the dataset already.

var data=[
    { id:1, sales:20, year:"02", color: "#ee4339"}
];

webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    color:"#color#",
    ...
})

Related sample: Basic Coloring

Color Template(Function)

If you want chart elements being colored according to a specific criterion, you should define colors with the help of a function.

Here sales bars are distinguished by sales amount.

webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    color:function(obj){
        if (obj.sales > 60)
            return "#f6960a";
        else
            return "#0ab6f6";
    }
})

Related sample: Specifying Color as a Function

Color Gradient

Gradient can be applied to bar and pie charts. It doesn't contain any information about the data, still it make the chart look more stylish and attractive.

Gradient property can take the following values:

  • boolean - true or false, the easiest way to enable/disable gradient;
  • string - "falling", "rising" to the direction of color shade; "light" and "3D" to add style effects for gradient;
  • function.

Colors for gradient are defined with the help of a addColorStop() method that takes gradient position (a number between 0.0 and 1.0) and desired color codes as parameters.

gradient:function(gradient){
    gradient.addColorStop(1.0,"#FF0000");
    gradient.addColorStop(0.2,"#FFFF00");
    gradient.addColorStop(0.0,"#00FF22");
}

Related sample: Color Gradient

By default gradient is disabled in the pie chart, so you need to enable it by assigning truevalue for the gradient parameter.


Setting for Line Charts

Here various properties of line charts are listed. The properties construct the chart object. Some of the properties contain an object as value. Data-presenting properties are compulsory while a number of styling options can be omitted or replaced.

Data Presentation
  • value (template) - the data item chosen for graphical representation; as a rule, its values are taken for text labels of the Y axis;
  • data / url (string/url) - datasource for the component;
  • label (string) - text labels for each point on the line;

Setting titles for each axis:

Here you should add title parameter for xAxis and yAxis constructor:

xAxis:{...
      title:"Some Text_1"},
yAxis:{...
      title:"Some Text_2"}

Related sample: Line Chart: Axes

Learn how to set scales for the chart in the corresponding chapter of the manual.

Chart Series. Several Graphs in One Chart

Related sample: Line Chart: Several Graphs in One Chart

Read more about Chart Series.

Styling and Positioning
  • item - a point on the line, a stop for each value. It includes:
    • radius (number) - radius on the point in the chart;
    • eventRadius (number) - radius of the virtual circle which events will fire for items within;
    • borderColor (hex code)- border for the point;
    • color (hex code) - inner color of the point.
  • line - a broken or curved (in case of a spline chart) line.
    • color (hex code) - color for the line;
    • width (number) - line width.
    • shadow (boolean) - shadow for nthe line (optional);
  • offset (number) - offset for the first item in a chart, the initial numeric value;

Getting rid of points on the line

item:{radius:0}

Making square points for the line

item:{
       borderColor:"#b64040",
       color: "#b64040",
       type:"d",
       radius:3,
       borderWidth:1 //here you make it square
      }

Related sample: Line Chart: Styling

Style Presets

There're three style presets for the Chart component

  • plot - a blue line with white points;
  • diamond - an orange line with wine red square points;
  • simple - a light green line with dark green points.

All of them are set with the help of preset property.

Related sample: Line Chart: Style Presets

Back to all chart types


Settings for Area Charts

  • value (template) - item template from the dataset;
  • data / url - the datasource;
  • color (hex code, template) - color for the colored area;
  • alpha (a number between 0 and 1) - the transparency of the colored area.

Area chart can be supplied with common functionality that is true for all chart types:

  • Scales, horizontal and vertical lines with values. See Rules of Scale Building for details.
  • Tooltips, pop-up infotips that show the exact value of the key points.
  • Legend, colored markers that explain what each chart within the scales mean.

Chart Series

Both Area and StackedArea charts support presenting graphs for several objects (series).

Series for chart is an array of objects with settings for each graph. Details here.

Related sample: Area Chart: Several Graphs in One Chart

Related sample: Stacked Area Chart

Back to all chart types


Settings for Radar Chart

Custom Initializzation

Data Presentation

  • value (template) - item template from the dataset;
  • data / url - datasource;
  • item - object property that contains settings for radar points. If you don't want to set point, omit this setting.
    • borderColor (hex code) - border color of the point;
    • radius (number) - radius on the point in the chart;
    • eventRadius (number) - radius of the virtual circle which events will fire for items within;
    • color (hex code, template) - color for radar points;
    • borderWidth (int) - border width of the point (for square points;
  • line - object property that contains setting for the line
    • color (hex code) - color of the outline;
    • width (number) - width of the outline;
  • fill (hex code) - color to fill the area limited by the outline;
  • disableLines (boolean) - enable/disable the line that joins points.

Scales

  • xAxis - label for each radar line that goes from the center to the outside:
    • template (string) - text labels for lines;
    • lineColor (hex code) - color of radar lines;
  • yAxis - settings for the radar map and inner lines(circles):
    • lineShape (string) - shape of the outer border of the radar area. 'arc' helps make a circle.
    • bg(hex code) - background color for the radar area;
    • lines (boolean) - if false, inner circles of the radar area aren't shown

Radar Charts Presets

The library provides 3 presets for Radar charts. To set one of presets you should specify the preset property for the chart:

webix.ui({
    view: "chart",
    type: "radar",
    preset: "line",
    ...
};

Related sample: Radar Chart: Style Presets

Radar Chart Series

Chart series is an array of settings for each graph to display different data in comparison.

In case of chart series, legend markers become buttons to show and hide dedicated charts.

Related sample: Radar Chart: Lines

Read more about Chart Series.

Back to all chart types


Settings for Scatter Chart

Custom Inititalization
  • value (template) - item template for Y axis;
  • xValue (template) - item template for xAxis;
  • data /url (url/string) - the datasource;
  • item - an object property that contains setting for each point in the graph:
    • radius (number) - radius on the point in the chart;
    • eventRadius (number) - radius of the virtual circle which events will fire for items within;
    • borderColor (hex code) - the color of the point border;
    • borderWidth (number) - the width fo the border (if set, point take square shape);
    • color (hex code) - color of the points
    • shadow (boolean) - if true makes point cast shadows. False by default.

Style Presets

Presets simplify chart initializing and contain item setting. They are defined by the preset property and can be of the following types:

  • round - semi-transparent blue round points (on the picture above)
  • square - green squares with borders
  • diamond - wine red diamond-shaped points

Related sample: Scatter Chart: Style Presets

Scatter Chart Series

Chart series allow presenting different graphs within on eand the same chart. The graphs differ in color. Settings for the graphs form objects that are placed into the series array.

Related sample: Scatter Chart: Several Graphs in One Chart

See the common rules of series definition here.

With chart series, legend should be used to distinguish between graph values. At the same time, legend markers become clickable and allow to show and hide dedicated graphs.


Setting Chart Scales

Scales are included into the following chart types:

  • Line and spline charts
  • Bar charts (optionally)
  • Area charts
  • Scatter chart

At the same time, radar chart has a specific chart type.

Scales consist of Y and X axes that are chart properties which values are objects containing several properties. Note that scales won't appear during chart initialization by default if you don't include these properties into the chart constructor:

webix.ui({
    view:"chart",
    ...
    xAxis:{
        property:"value"},
    YAxis:{
        property:"value"}
})
  • A vertical, yAxis of a chart is formed according to the values of data, which progress you want to show graphically. Naturally, the values are numeric. This data is specified by chart's value property.
  • A horizontal, xAxis displays progress of the data according to the specified criterion.

If needed, any axis can be omitted.

Take the dataset looks as follows and we want to present sales progress during several years. Each data item contains sales amount and the year.

JSON data

[
    { id:1, sales:20, year:"02"},{ id:2, sales:55, year:"03"},
    { id:3, sales:40, year:"04"},{ id:4, sales:78, year:"05"},
    { id:5, sales:61, year:"06"},{ id:6, sales:35, year:"07"},
    { id:7, sales:80, year:"08"},{ id:8, sales:50, year:"09"},
    { id:9, sales:65, year:"10"},{ id:10, sales:59, year:"11"}
]

Default Scale

Y-axis Formation

If you set an empty yAxis property object (yAxis:{}), the dataset will be analyzed and the scale will be formed automatically. Here:

  • the optimal step for units will be 10 as all the values are lower than a hundred;
  • the lowest unit value for the scale will be 20 as the lowest value in the dataset is 20 and the program takes the closest ten's place.
  • the highest unit value for the scale will be 80 since it's the highest data value.

X-Axis Formation

Minimal compulsory API for the x-Axis includes

  • template - data item from the dataset. Here is it #year#. Each value turns into a labelled unit on the line.

Custom Scale

Y-axis Formation

Y-axis object is constructed with the following properties:

  • start (number) - start position for the axis, the value of the first unit;
  • end (number) - max value for the axis, the last unit;
  • step (number) - 'distance' to the next unit (not necessarily labelled with text);
  • template - template for text label of the axis. Template function can define which numeric values to display. If not specified, text values are displayed depending on the 'step' parameter.

If you don't want to label each unit, you can set a function template to label only units multiple of the specified number (here it's 20):

template:function(obj){return (obj%20?"":obj)

X-axis Formation

  • template(template) - template for text labels on the X axis;
  • lines (boolean) - if false, the line for the axis isn't shown. By default this value is true.
  • origin (number) - it's the property of the chart constructor, not the xAxis object. However, its value affects the position of x-Axis relative to the Y-axis. Data items with values lower that the stated one, are displayed below the line.

There exists a possibility to create a fully custom axis for working with dates.

Offset

For line, scatter and area charts you can set the offset property which defines whether the first item of the scale will be drawn with the offset equal to the half of the scale's step (relative to the origin of the chart).

The default value for line and scatter charts is true. The default value for area charts is false.

webix.ui({
    view:"chart",
    type:"line",
    ...
    xAxis:{
        property:"value"},
    YAxis:{
        property:"value"},
    offset:false
})

Related sample: Line Chart: Axes

Logarithmic Scale

Webix charts are equipped with two types of scale:

  • "linear" - used in all charts by default;
  • "logarithmic" - enabled by chart scale property:
webix.ui({
    view:"chart",
    type:"bar",
    scale: "logarithmic",
    ...
});

Related sample: Chart: Logarithmic Scale

Titles for the Axes

Titles are included into axes' objects:

webix.ui({
    view:"chart",
    ..config..,
    xAxis:{ ..
            title: "Year"},
    yAxis:{..
            title:"Sales per Year"}
})

In case of horizontal bar charts (type barH, stackedBarH) X and Y axes exchange their properties.


Custom X-Axis Formation

Sometimes you need to create a detailed scale, especially when you work with dates.

Related sample: Bar Chart: Custom xAxis

Here you work with dates and sales per date stored in JSON dataset. Note that dates are stored as strings.

var dates_dataset = [
    { id:1, sales:20, date:"05.01.2012", color: "#ee4339"},
    { id:2, sales:55, date:"10.01.2012", color: "#ee9336"},
    { id:3, sales:40, date:"15.01.2012", color: "#eed236"},
    ...]

Sales are represented by y-Axis values, while dates form the timeline on the x-Axis, each unit representing a day of month. The quantity of unit per month should be equal to the real quantity of days in this or that month, which isn't a static value.

In this case, the looks of the X-axis is totally customized features several object and function properties, namely template, lineColor, value and units.

Units

The object properties set the first and the last unit for the scale as well as sets a step between neighbouring units.

units:{
       start:new Date(2012,0,1), //starting from January, the 1sr
       end:new Date(2012,1,29), //finishing on February, the 29th
       next:function(d){
             return  webix.Date.add(d, 1, "day", true);
            }

Step is set by the add function that takes date object, number of units to add and unit name as parameters.

Template

Template defines text label for an axis. Normal chart scale features one label below an axis, but here we need to underwrite each month of the timeline.

The function below allows placing the right label under the 15th day of each month:

 template:function(obj){
                return obj.$unit.getDate()==15?webix.Date.dateToStr("%F")(obj.$unit):""
            },

The function gets day number from the Date object of each unit. If it equals to 15, the date is parsed to string and formatted to output the full name of the month. Otherwise, the unit receives no label.

LineColor

Line color within x-Axis object defines the color of vertical scale units. In this case we need that a line for the first day of February is darker than the others.

 lineColor:function(obj){
                return obj.$unit.valueOf() == (new Date(2012,1,1)).valueOf()?"#737373":"#cfcfcf"
            }

The function defines the value of each unit. If is equals fo the February, the 1st, it return dark grey (#737373). Otherwise, the color is light grey.

Value

Values are not displayed right in the chart, yet shown with a help of the tooltip. Here we can set an approproate formatting method for

Date string is taken from the dataset (obj.date) and turned to date object formatted under the "day number-month number-full year" pattern.

  value:function(obj){
                console.log(webix.Date.strToDate("%d.%m.%Y")(obj.date))
                return webix.Date.strToDate("%d.%m.%Y")(obj.date);
            },


Chart Series

Chart series help display comparative graphs. In other words, you have an ability to present data of different objects within one and the same chart to see their dynamics in comparison. The functionality is true for line, bar, radar and area charts.

For instance, you want too see the sales progress of three companies during some time period.

First of all, each item from dataset must contain data for all the needed objects (here - companies).

JSON Data

var multiple_dataset = [
    { sales:"20", sales2:"35", sales3:"55", year:"02" },
    { sales:"40", sales2:"24", sales3:"40", year:"03" },
    { sales:"44", sales2:"20", sales3:"27", year:"04" },
    { sales:"23", sales2:"50", sales3:"43", year:"05" },
    ....
];

Sales, sales2 and sales3 are sales amounts for three different companies, each of which should be represented in a separate chart. On the picture above, there are three bar chart series differing from each other in color.

In fact, here we initialize one component - bar chart and distribute data among its series. Hence, settings for the bar charts form an array called series. Each array item includes data values as well as settings for each series.

webix.ui({
    view:"chart",
    type:"bar",
    series:[
        {   // 1st company - turquoise blue bars
            value:"#sales#",
            color: "#58dccd",
            tooltip:{
                template:"#sales#"
            }
        },
        {   //2nd company - green bars
            value:"#sales2#",
            color:"#a7ee70",
            tooltip:{
                template:"#sales2#"
            }
        },
        {   // 3rd company - blue bars
            value:"#sales3#",
            color:"#36abee",
            tooltip:{
                template:"#sales3#"
            }
    }]
})

Related sample: Bar Chart: Several Graphs in One Chart

Chart series require a legend to explain different charts within one and the same scales. Legend markers act as well as buttons to show and hide dedicated chart series.

If you work with one and the same chart type, the series object only item settings should be included. Look for them in the setting for each chart type.

Different Chart Types

Still, chart series can encompass different chart types.

Related sample: Bar Chart: Different Types in One Chart

This time, the series object for a differing chart type should include the whole set of its properties:

webix.ui({
    container:"chartDiv",
    view:"chart",
    type:"bar",
    //bar chart config
    series:[
        {   //setting for each bar
            value:"#sales2#",
            color:"#69ba00",
            tooltip:{
                template:"#sales2#"
            }
        },
        {   //setting for a line chart
            type:"line",
            value:"#sales3#",
            color:"#36abee",
            item:{
                borderColor: "#b7286c",
                color: "#de619c",
                type: "s"
            },
            line:{
                color:"#de619c",
                width:2
            }
    }]
})


Operations with Chart Data

Getting an Item's Value

Getting the value of **year** property

            $$("chart").attachEvent("onItemClick", function(id){
            id = this.getItem(id).year;
            alert(id);
        });

Related sample: Chart: Events

Adding Items

While adding an item, make use of the add() method and state new data as an object and position of the new item:

 var counter = 12;
        function addNew () {
            $$("barChart").add({
                year:"'"+counter,
                sales:"some_value"
            });
            counter++;
        }

Additionally, you can define a counter that sets the starting position of the new items to observe dataset integrity.

Item Deletion

To delete an item you should pass its ID into the remove() function (zero-base numbering) or make use of first() and last() methods to delete first and last items from the dataset.

$$("barChart").remove(4); // the 5th item will be removed

function deleteFirst(){
            $$("barChart").remove($$("barChart").getFirstId());
        }

Related sample: Chart: Adding/Deleting Data Items

Study the corresponding chapter of the manual to learn more about adding and deleting of items.

Sort Data

Here you use a sort() method that takes property from the initial dataset and sorting manner (ascending or descending) as parameters.

$$('chart').sort('#year#','desc');

Related sample: Chart: Sorting

Sort method in API Reference

Filter Data

As a rule, filter() method takes a function as parameter. In the function you specify the data you want to be filtered.

Make the chart show you only sales exceeding 50.

function filter1(){
    $$('chart').filter(function(obj){
        return obj.sales >50;
    });
}

Related sample: Chart: Filtering

Rules of Data Filtering


Setting Legend for a Chart

Chart legend explains data and color correspondence. Generally, to specify the chart legend you should use the legend property:

Specifying the legend for a chart

webix.ui({
    view:"chart",
    type:"bar",
    ...
    legend:{
        values:[
            {text:"Company A", color:"#58dccd"},
            {text:"Company B", color:"#a7ee70"},
            {text:"Company C", color:"#36abee"}
        ],
        align:"right",
        width:110,
        layout:"y"
    }
})

Related sample: Bar Chart: Several Graphs in One Chart

See the full list of legend parameters in API Reference.

Default Legend

Built-in means allow defining a default legend. For these needs, you should specify what element from the initial datasource will be in the legend area. Default legend is great for pie and bar charts with multicolored bars and pie pieces.

Then, the legend takes a color value from the dataset:

JSON Dtata

[
    { sales:"20", month:"Jan", color: "#ee3639" },
    { sales:"30", month:"Fen", color: "#ee9e36" }
]
webix.ui({
    view:"chart",
    type:"pie",
    value:"#sales#",
    color:"#color#",
    legend:"#month#",
    ...
});

Related sample: Pie Chart: Basic and Custom Legend

See the full list of legend parameters in API Reference.

Custom Legend
  • Legend customization includes marker dimensions and arrangement, their alignment towards the chart, colors and border as well as custom text for the markers.
  • Custom legends are vital with chart series for different graphs need to be explained for users could read the charts.
  • Legend markers defined for chart series are used to show and hide dedicated graphs (lines, areas, bars..) by clicking on their signs. Invisible charts can be shown back by clicking the grey 'inactive' marker sign.

Legend markers become "show-and-hide" buttons for all charts with series except for stacked charts (stackedArea, stackedBar, stackedBarH), because such charts presuppose series usage and don't imply visual comparison.

Custom legend

webix.ui({
    view:"chart",
    type:"",
    ...
    legend:{
        layout:"y",
        width: 110,
        align:"right",
        valign:"middle",
        marker:{
            width:15,
            radius:3
        },
        values:[
            {text:"company A",color:"#3399ff"},
            {text:"company B",color:"#66cc00"}]
    }
});

Related sample: Radar Chart: Lines

See the full list of legend parameters in API Reference.

Customizing Legend Markers

By default, legend markers are squares with rounded edges that feature 3-px border radius. To change this pattern, use the marker parameter of the into the legend property.

legend:{
    ...
    marker:{
        type:"round",
        width:15,
        radius:3
    },
}

Related sample: Radar Chart: Areas

'item' marker

Webix charts offer a possibility to set for a marker the same template that uses items of the related graph.

legend:{
    values:[{text:"Company A"},{text:"Company B"},{text:"Company C"}],
    ...
    marker:{
        type: "item",
        width: 18
    }
}

Related sample: Line Chart: Legend Markers

Setting different markers for different graphs

To set different markers for graphs you should:

  • Specify legend items manually, through the values parameter (don't use template);
  • Use markerType property to assign the desired marker type to a graph.
legend:{
    layout:"y",
    align:"right",
    valign:"middle",
    width:100,
    values:[
        {text:"Company A",color:"#00ccff"},                   //the default marker
        {text:"Company B",color:"#e9df40"},                   //the default marker
        {text:"Average",color:"#b25151",  markerType: "item"} //the redefined marker
    ]
}

Related sample: Bar Chart: Different Types in One Chart


Chart Tooltip

Tooltip is a graphical UI element that becomes visible when a user places a mouse pointer over the predefined area. It's used as an infotip giving additional information on user request.

Tooltip helps interpret chart values, giving precise numbers for bars as well as points in line, area, scatter and radar charts. Tooltip isn't normally used with pie charts as its values are written on pie pieces.

Chart tooltips are displayed in squares and include value of the the element you've places a cursor over.

Useful tip - define eventRadius for chart with a tooltip bigger than an item radius.

In essence, tooltip works under Event Handling principles: it appears and disappears on "on MouseOver" and "onMouseOut" events respectively, both of them being attached to an item in the chart. Items are usually small and users need to be very precise with cursor pointing. Setting eventRadius bigger doesn't change anything in the chart appearance but it simplifies tooltip triggering.

Tooltip Values

Tooltip values are defined on the base of datasource values. While the chart represents a numeric graphically, tooltip gives literal explanation of this value.

Let's take the left chart from above. It shows sales amounts per each year. Years are displayed over a horizontal scale while sales amount defines the height of the point on the vertical scale.

JSON Data

var dataset = [
    { id:1, sales:20, year:"02"},
    { id:2, sales:55, year:"03"},
    ...];

Tooltip here takes #sales# value and shows the exact sales amount as you place a cursor over the point.

webix.ui({
    view:"chart",
    type:"line",
    value:"#sales#", //settings for yAxis
    xAxis:{
            template:"'#year#"}, //settings for xAxis
    ....
    tooltip:{
           template:"#sales#" //tooltip
         }
    eventRadius: 10
})

Related sample: Line Chart: Styling

Templates may include several properties of one and the same data object.

If you want to see year - sales tooltip for the chart above, change the tooltip template and include #year# to it:

tooltip:{
           template:"#year# - #sales#" //
         }

Such tooltips are especially convenient for Scatter charts where points aren't connected by lines and it's difficult to read exact value:

Related sample: Scatter Chart: Templates


Colorboard

API Reference
  • Methods, properties and events
  • Samples

Overview

UI-related colorboard is a tool to get the hex code of a color that you are going to use for styling. By default, colors are presented in a rainbow-like manner. The detalization level you set manually.

Initialization

Colorboard is used in conjunction with a colorpicker control. In such a case, you needn't to initialize a colorboard since it will appear as soon as you click a control.

When used separately, colorboard is initialized in the following way:

webix.ui({
        view:"colorboard",
        cols    :30,
        rows    :30,
        width   :400,
        height  :400
});

Related sample: Colorboard

Comments:

  • width and height denote the dimensions of a square with a color palette;
  • cols and rows denote the number of colors in each axle - the bigger it is, the more detailed is the palette;
  • gradient nature of the colorboard can be controlled via lightness values:
    • minLightness (0.15 by default) - start value of lightness (the darkest part);
    • maxLightness - (1 by default) - end value of lightness (the lightest part).

Working with Colorboard

You can customize your colorboard by:

  • setting the way of color presentation

webix.ui({
    view:"colorboard",
    cols:7,
    rows:4,
    width:600,
    height:370,
    template:"<div class=\"value_cell\">" +
            "<div>{obj.val}</div>" +
            "<div class=\"color_block\" style=\"background:{obj.val};\"></div>" +
            "</div>"
});

Related sample: Palette - Templates

  • defining your own color set

var colors = [
    ["#C6D9F0", "#8DB3E2", "#548DD4"],
    ["#F2DCDB", "#E5B9B7", "#D99694"],
    ["#EBF1DD", "#D7E3BC", "#C3D69B"]
];

webix.ui({
    view:"colorboard",
    ...
    palette:colors
});

Related sample: Colorboard - Colors

Deriving Selected Color Value from the colorboard:

Normally, selected color is derived with the help of the getValue() method:

$$("colorboard1").getValue();

In addition, color values can be logged once val, control and ev parameters are passed into the logging function.

function doLog(val, control, ev){
        webix.message(this.config.id + " - " + val);
    }

Related Articles
  • Making Templates
  • Component Styling


Context

API Reference
  • Methods, properties and events
  • Samples

Overview

Ui-related context points to an element that will be shown on the page on right mouse click. The context looks like a popup window where you can place any HTML element or UI component.

Initialization

webix.ui({
    view:"context",
    width: 300,
    body:{ ... },
    padding:20,
    master:"areaA"
});

Related sample: Context Menu: UI Components Inside

Comments:

  • master - the ID of an HTML container that will be shown on page loading. It is the area where the right mouse click will make context elements visible. This element is included into the body property;
  • body - an element (ui component) that appears on right mouse click;
  • width - width of UI component that appears on right mouse click;
  • padding - offset from context border and its inner contents.

Context features hidden property set to true by default. It can be changed during component initialization, but this won't make much sets since context purpose is to be hidden and appear only on right click.

Working with Context

What can be a context element?

  • Any ui-related component. For instance a two-button toolbar:

webix.ui({
    view:"context",
    body:{view: "toolbar", cols:[
        {view:"button", value:"Button1", width: 100},
        {view:"button", value:"Button2", width: 100}]
    },
    width: 300,
    master:"context_area"
});

Related sample: Context Menu: UI Components Inside

  • Any HTML element referred to by its ID:

The ID is specified in the body constructor as value of content property.

body:{
    content:"details"
}

Content will get elements that are inside the container.

<div id="details">
    Power of HTML5
    <hr>
    <img src='http://Webix.com/codebase/images/bg_touch.gif'>
</div>

Related sample: Context Menu: HTML Content

Related Articles
  • Contextmenu
  • Popup


ContextMenu

API Reference
  • Methods, properties and events
  • Samples

Overview

Contextmenu is triggered by right mouse click. Ui-related Contextmenu inherits from both window and list. It looks like ui-related menu and shares most of its properties, methods and events.

Initialization

1 . ContextMenu - List

webix.ui({
    view:"contextmenu",
    id:"my_menu",
    data:[
        "Add",
        "Rename",
        "Delete",
        { $template:"Separator" }
        ,"Info"
    ],
    master:"areaA" //  ID of a DIV container
});

Related sample: Context Menu

Data property includes list items in the window, separator stands for a line to divide window areas while master property defines the area where the component is initialized.

2 . ContextMenu - Menu

webix.ui({
    view:"contextmenu",
    id:"my_menu",
    data:[
        { value:"Translate...", submenu:[
                "English", "Slavic...", "German"
        ]},
        { ...},
        { ... }
    ]
    master:"areaB"
});

Here data includes menu constructor with some items having submenus.

Related sample: Context Menu

Working with ContextMenu

Getting an Item's Value

You can access any element of a contextmenu and its submenus and attach events to them with the help of the following patterns:

//for list contextmenu
$$("my_menu").attachEvent("onItemClick":function(id){
    webix.message(this.getItem(id).value);
});

//for "menu-like" contextmenu
$$("my_menu").attachEvent("onItemClick", function(id){
    var menu = this.getSubMenu(id);
    webix.message("Click: "+menu.getItem(id).value);
})

Linking a Contextmenu to a Component

A contextmenu can be initialized for any Webix component. A three-step process includes the following stages:

1) Firstly, you should include an onContext property into the component's construction:

webix.ui({
     view:"list",
     id:"list",
     //list config
     onContext:{} // the empty object
});

2) Secondly, you initialize a contextmenu in a separate within a separate webix.ui function:

webix.ui({
    view:"contextmenu",
    data:[....],
    ...
});

3) Thirdly, you link the contextmenu to the necessary component with the help of either

  • an attachTo() function:
$$('contextmenu1').attachTo($$('list'));

Related sample: Context Menu: Attaching to List

  • or contextmenu master property that points to the necessary component object:
webix.ui({
    view:"contextmenu",
    data:[....],
    master:$$("list")
});

You can link either to a component object or to its HTML container (like any other HTML on page). The difference lies within data components - to attach context menu to their items, you need to link to a component object.

A component HTML container is stored in its $view specific property:

$$("list").$view; //returns <div class="webix_view webix_list" ...></div>

Attaching contextmenu to list

//works with list items
$$('contextmenu1').attachTo($$('list1'));

//works with the whole list
$$('contextmenu1').attachTo($$('list1').$view);

It is the nice option to attach contextmenu to Webix controls, e.g. button or any HTML elements on the page:

$$('contextmenu1').attachTo($$('button1').$view);

$$('contextmenu1').attachTo(document.getElementById("myElement"));

Getting Properties of the Master Component

Like with context, the area upon which the context menu is called master area or (if you call it over a component or its item), master component.

Master component object is retrieved with the getContext() property.

webix.ui({
    view:"contextmenu"
    on:{
        onItemClick:function(id){
            var context = this.getContext();
            var list = context.obj; //list item object
            var listId = context.id; //id of the clicked list item

            webix.message("List item: <i>"+list.getItem(listId).title+"</i> <br/>
                Context menu item: <i>"+this.getItem(id).value+"</i>");
        }
    }
});

Related sample: Context Menu: Attaching to List

Related Articles
  • List
  • Menu
  • Event Handling
  • Context


DataTable

API Reference
  • Methods, properties and events
  • Samples
Overview

DataTable is a pure JavaScript component that provides professional look-and-feel and convenient programming model for displaying data in a scrollable and sortable table. It’s a powerful yet easy-to-use control
that supports different data sources (xml, json, csv, jsarray, html tables) and has various possibilities (filtering, sorting, pagination, resizing, styling, copying etc.) still being very fast handling thousands of records. Read more...

Guides

Configuration

  • General columns settings
  • Creating index columns
  • Headers and footers
  • Colspans and rowspans
  • Data loading
  • Internationalization
  • Sizing and resizing
  • External configuration
  • Adding Active Elements to Datatable Cells
  • Adding Subrows
  • Adding Subviews
 Teaches you how to define the common structure and content of DataTable: columns, headers, dimensions and data inside it.

Operations with data

  • Copy-pasting
  • Editing
  • Filtering
  • Math operations
  • Paging
  • Selection
  • Sorting
 Discusses operations you can perform on the data in DataTable: filtering and sorting techniques, inline editing, work with the clipboard, etc.

Look-and-feel

  • Cell templates
  • Sparklines
  • Number and date formatting
  • Styling
  • Split mode or 'frozen columns'
 Focuses on how to fine-tune the DataTable appearance: applying templates to the data, 'freezing' columns, redefining the default component CSS classes, etc.

Integration

  • DHTMLX
  • jQuery
  • Server-side solutions
 Says about libraries and platforms you can integrate DataTable with.

Export

  • Export to PNG
  • Export to Excel
  • Export to PDF
 Describes the formats and procedures you've got to import/export the DataTable's data.


DataTable Overview

DataTable is a pure JavaScript component that provides professional look-and-feel and convenient programming model for displaying data in a scrollable and sortable table. It's a powerful yet easy-to-use control that supports different data sources (xml, json, csv, jsarray, html tables) and has various possibilities (filtering, sorting, pagination, resizing, styling, copying etc.) still being very fast handling thousands of records (dynamic loading).

Main features
1. Supported data formats: xml, json, jsarray, csv
Developers can use their favourite formats to specify data. All popular data formats are supported.

2. Initializing from an HTML table
Any HTML table can be turned into DataTable by a single command.

3. Linkable tables
This feature allows developers to create multiple DataTable instances on a page and easily implement various relationships through APIs.

4. Simple integration with server side
Simple integration with any server side solution, such as PHP, .NET, Java.

5. Full API support
A full range of API with the detailed descriptions is available.

6. Support for internationalization
Support for internationalization allows applications be translated and modified into local versions for thousands of languages.

7. Flexible columns
Each column in DataTable is configured individually: width, height, color etc.

8. Complex headers and footers
The header(footer) can be presented as a single or multi line (the number of sublevels is unlimited) and contain almost any content: text, an image, an html input, a link, a built-in filter, colspans, rowspans.

9. Different selection modes
You can set 7 different modes specifying how data will be selected by: cell, row, column, multi cell, multi row, multi column, block.

10. Styling with standard css
You can use CSS in conjunction with DataTable content to achieve the desired look-and-feel. Css can be applied to the whole table or to a specific column, row, cell.

11. Resizable columns and rows
Columns width or rows height can be changed by dragging the related border.

12. Copying to/from clipboard
By common CTRL+C/CTRL+V keyboard shortcuts data can be copied to some other application for further processing or moved within one or several DataTables.

13. On-the-fly filtering
The library offers abundant possibilities of filtering, starting from built-in filters (text and select) and ending with fully custom filtering logic.

14. Sorting a column by clicking the header with data type detection
This feature allows users to sort data (according to one of 4 predefined sorting types: integer, date, string and string_strict) by a single clicking the header. Custom sorting rule can be defined as well.

15. Variable length and localizable pagination
One or several pagers can be added to the app to display data page by page. Data will not be retrieved from server side until the related page is opened. The number of rows per page, templates for navigation controls are set up.

16. Fixed one or more left (right) columns when table is scrolled horizontally
The library provides the 'split' mode that allows you to have the table separated into two parts: 'fixed' and 'scrolled'.

17. Possibility to show or hide columns
Any column in the table can be hidden (showed) programmatically.

18. Math formulas for cells
Developers have an opportunity to load data that are stored as mathematical expressions. DataTable parses, evaluates such expressions and presents result in the related cells.

19. Scrolling options for table viewport
When your viewport is less than a page you can enable vertical(horizontal) scrolling to be able to see the hidden info. You also have the possibility to enable scrolling by whole rows.

20. Possibility to set different heights for rows and different widths for columns
You can set different widths(heights) for columns(rows). Set values will be saved regardless of any other enabled size parameters.

21. Export to PDF, Excel
DataTable can be exported to PDF, Excel for further processing. Besides, you can define how the table will look in the document after it is exported by configuring various server side options.

22. Integration with the Webix 3 library
The library can be integrated with three Webix 3 components: WebixLayout, WebixGrid and WebixMenu.

23. Integration with jQuery
DataTable is integrated with jQuery that allows you to follow the main mantra of the jQuery library while developing - running with the least amount of configuration.

24. Dynamically fetching the rows from the server when the table is scrolled up and down
Working with large datasets, developer can load data dynamically to reduce complexity and improve performance. Polling interval and the number of loaded records are controlled.

25. Callbacks for all events: load, sorting, etc.
Numerous events lets you handle any action or proceeding that can happen in the app.


Getting started with DataTable

To make a great app you need to learn different things but if you're new to DataTable you might be wondering where to begin.

Some platforms (Java, .Net, PHP) get ready-to-use solutions for data loading, saving, exporting.

For understanding the basic concepts and getting the desired information in the most convenient way we offer you to follow this road map:

  1. Tutorial - gives essential notes you should know to create the first DataTable-based application.
  2. Detailed guidelines - the main chapter of the documentation covering the developer-oriented tasks in details.
    • Configuration - explains how to configure a table: to specify and size required columns, set headers(footers) for them, populate the table with data and etc.
    • Look and Feel - tells you how to fine-tune the appearance of your table and data in it with the help of css classes, templates and special modes.
    • Operations with data - covers techniques for performing general operations under data in DataTable, such as sorting, filtering, copy-pasting and selection.
    • Operations with cells - describes basic operations you surely will use while developing: getting/setting the value of a cell.
    • Integration - says which libraries and how can be integrated with DataTable.
    • Data export to PDF, Excel - shows the process of exporting data from DataTable to PDF and Excel documents.
    • Saving data on server - describes server-side work.
  3. Events handling - says how to use events: to attach and detach, which events can be handled and how.
  4. API Reference - provides reference information you need for coding: all the available methods, parameters and events of the library.


Creating a Basic Application

This tutorial walks you through creating a basic application containing DataTable. As you follow the steps, you learn how to initialize DataTable, customize and configure its appearance, load data to it. The final code of the tutorial can be used as the start point while creating applications using DataTable.

Related sample: Quick start with DataTable

A new HTML file and related code files

To start, create a new HTML file and include the DataTable code files in it.

Required code files are:

  • webix.css
  • webix.js

A basic html page with the included DataTable code files

<html>
<head>
    <title>Quick start with DataTable</title>
    <script src="../codebase/webix.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="../codebase/webix.css" type="text/css" charset="utf-8">
</head>
<body>
    <script>
        //here you will place your JavaScript code
    </script>
</body>
</html>

Including Webix files via Package Managers

OR, as an alternative to downloading, you can install Webix library via such package managers as NuGet and Bower.

Installing Webix requires by means of these tools requires executing just a line of code inside them (you don't need to download anything):

NuGet

nuget install Webix

//If you use Microsoft Visual Studio, execute this from Package Manager Console
install-package Webix

Bower

bower install webix

Placing DataTable on a page

On the next step, you should create a div container where you then place your DataTable.

<div id="box" style="width:400px;height:200px;"></div>

Object constructor

After the place for DataTable has been prepared, move to its initialization.

To create a new DataTable instance you need to use the next constructor:

dtable = new webix.ui({ view:"datatable" })

Let's specify 2 mandatory parameters inside the constructor:

  1. container - the HTML container for DataTable. We created it on the previous step.
  2. columns - the array of objects, each of which specifies an individual column. Each object must at least has the id attribute set.

It addition to id, we will specify 2 often used column attributes: header (the header of a column) and width (the width of a column).

Basic DataTable configuration

dtable = new webix.ui({
        container:"box",
        view:"datatable",
        columns:[
            { id:"title",   header:"Film title",   width:200},
            { id:"year",    header:"Release year", width:80},
            { id:"votes",   header:"Votes",        width:100}
        ]
});

General settings

On the previous step, we have defined primary settings for DataTable. For more available configuration, read other articles in this documentation, such as:

  • General columns configuration - brief announcement of available column settings;
  • Selection - describes different types of selection (cell, column, row etc.) and their use;
  • Sorting and Filtration - says about means for sorting and filtering.

Loading data

There are various ways to load data into DataTable (read about them in chapter Data loading).
We will use the easiest of the ways and specify data directly in the constructor with the help of the data parameter:

dtable = new webix.ui({
        container:"box",
        view:"datatable",
        columns:[
            { id:"title",   header:"Film title",    width:200},
            { id:"year",    header:"Release year" , width:80},
            { id:"votes",   header:"Votes",         width:100}
        ],
        data:[
            { id:1, title:"The Shawshank Redemption", year:1994, votes:678790},
            { id:2, title:"The Godfather",            year:1972, votes:511495}
        ]
});

Congratulations! Now you can run your app and it'll produce DataTable shown at the very beginning.

Related sample: Quick start with DataTable

What's next

What can we suggest you to do next?

  • Check the code sample of the mentioned above example (use the link above);
  • Read about possible data formats and how you can get data from database;
  • Find out about available columns configuration;
  • Check other supplied samples.


Getting/setting the cell value

API of DataTable allows you to retrieve existing values of cells or set new ones.

Getting the value

To get the record object, you should use method item():

Getting the record object

grid = webix.ui({
    view:"datatable",
    data:[ {id:"row1", title:"The Shawshank Redemption", year:"1994"} ],
    ...
});
...

//'record' variable will contain an object of the related DataTable record
var record = grid.getItem("row1");

//you can access data members directly
var title = record.title;

Setting the value

To change the current value of a cell, you should use the following technique:

Setting the cell value

record = grid.getItem(row_id);
record[column_name] = new_value;

grid.refresh();
//or
grid.updateItem(row_id, record);

Methods refresh() and update() lead to one and the same result and don't have any specificity.

Getting values of cells range

When you work with a block of cells you can use 2 'special' methods allowing you to get values of several cells and perform some action on them:

  • mapCells - gets the current values of the specified cells (called for each specified cell by turn).

Reversing text in the specified cells range

grid.mapCells(start_row,start_col,numRows,numCols,
function(value, row_id, column_id, row_ind, col_ind){
        return value.toString().split("").reverse().join("");
});

Related sample: Mapping cells

  • mapSelection - gets the current values of the selected cells ( called for each selected cell by turn).

Reversing text in all selected cells

grid.mapSelection(function(value){
        return value.toString().split("").reverse().join("");
});

Related sample: Mapping selection

For more on the mentioned and other related methods, see API Reference.


Configuration

  • Columns Configuration
  • Creating Index Columns
  • Headers and Footers
  • Datatable Rowspans and Colspans
  • Loading Data into DataTable
  • Sizing and Resizing
  • Internationalization of DataTable
  • External configuration
  • Adding Subrows
  • Adding Subviews


Columns Configuration

Columns configuration is specified by parameter columns and all settings are managed on its level.

grid = new webix.ui({
    view:"datatable",
    columns:[{...}, {...}],
    ...
});

With the help of the columns parameter you can:

  • specify headers/footers;
  • set widths of columns;
  • add built-in filter;
  • set built-in sorting;
  • set the text alignment in a column;
  • set the format of data presentation;
  • specify data of columns through math formulas;
  • specify datasource for the column;
  • define templates for data presentation;
  • define individual css class for any column;
  • hide/show a column;
  • hide/show columns in groups;
  • add/delete columns dynamically;
  • group columns;
  • define colspans and rowspans;

Automatic Column Configuration

Normally, you need to specify an array of column configurations for the datatable, which allows for setting various parameters needed by this or that datatable separately:

view:"datatable",
columns:[
    {id:"id", header:"Id", width:50, sort:"int"},
    {id:"title", header:[ "Film title",{content:"textFilter"}]
]

At the same time, you can switch to data-based column configuration provided by autoconfig property:

view:"datatable",
autoconfig:true

In this case columns array is no longer needed. Datatable will analyze the dataset passed to it and build columns automatically. The columns will have default values (no sorting or filtering, width of 50px, etc.)

Headers/footers

Enabled by parameters header, footer (by default, headers are enabled).

Specified by attributes header, footer and can be both string and object.

In case of string, you can specify just the label.

Object definition allows you to specify more complex column presentation. As an object, header/footer can contain the following properties:

  • text - the text label of a column;
  • colspan - the number of columns a cell should span;
  • rowspan - the number of rows a cell should span;
  • content - the built-in filter of a column (textFilter or selectFilter).

Defining header and footer for a specific column

//simple string
grid = new webix.ui({
        view:"datatable",
        ...
        footer:true,
        columns:[
            { id:"col1", header:"Column 1", footer:"Footer 1"},
            {...}
        ]
})
//object
grid = new webix.ui({
        view:"datatable",
        ...
        footer:true,
        columns:[{
            id:"col1",
            header:[{ text:"Column1", colspan:"2"}, { content:"selectFilter" }],
            footer:[{ text:"Total", rowspan:"2"}, { text:" " } ]
        },
        ...]
})

Related sample: Standard header(footer) implementation

For more details, read the Headers and footers article.

Widths of columns

Setting the width of columns

To set widths of columns you should use the width attribute.

Setting the width of a column

columns:[
    { id:"col1",  width:200 }
]

Related sample: Sizing through the 'width', 'height' parameters

Adjusting the width of columns to the parent container

To make a column or several columns fill the unused space of the parent container, use the fillspace attribute with the true value:

columns:[
   { id:"title", header:"Film title", fillspace:true},
   ...
]

The column with the "title" value will take all the free space of the container. If there are more than one column with the enabled fillspace attribute, they will divide the free space between them.

Related sample: Adjusting columns to the parent container

Distributing free space between columns

You can also set the fillspace attribute with numeric values for several columns. In this case their width will be calculated as a proportion defined by the values:

columns:[
    { id:"id", header:"ID", fillspace:1},
    { id:"title", header:"Film title", fillspace:4}
]

In the above code the "title" column is 4 times bigger than the "id" one, which is 20 to 80 percent relation.

Related sample: Adjusting columns to the parent container

Adjusting column to its content

To adjust the width of a column to the related content size, you can use the adjust attribute. There are two options possible:

  • data - adjusts column width to the content of the widest item in it;
  • header - adjusts column width to its header content.
columns:[
    { id:"title", header:"Film title", adjust:"data"},
    { id:"rank", header:"Rank", adjust:"header"}
        ...
]

Pay attention that the resulting column's width won't be less than minWidth, in case this parameter is set for the column.

Related sample: Adjusting columns to the content

For more details, read the Sizing and resizing article.

Built-in filters

The header or footer of a column can contain filter. The following types of filters are available:

  • textFilter - text filter. Retrieves values which contain mask defined through text field;
  • selectFilter - select filter. Retrieves values which contain mask defined through dropdown list of possible values.
  • and 6 more..

Filter is set by property content of the header attribute.

Adding filter to the header of a specific column

columns:[
    { id:"col1", header:[{ text:"Column 1", colspan:"2"}, { content:"selectFilter" }]},
    {...}
]

Related sample: Filtering. Built-in Text Filter, Select Filter

For more details, read the Filtering article.

Built-in sorting

You are allowed to sort data in columns. The way of sorting depends on the column sorting type. There are 3 predefined sorting types:

  • int
  • string
  • string_strict

Last one is a case-sensitive string sorting

The sorting is specified by attribute sort.

Activating sorting for a specific column

columns:[
    { id:"col1", sort:"string" },
    {...}
]

Related sample: Sorting. Using built-in means

For more details, read the Sorting article.

Text alignment

To set the text alignment in a column you should use attribute css:

Setting the text alignment in a column

<style>
.myStyle{
    text-align:right;
}
</style>
columns:[
    { id:"col1" css:"myStyle"},//in a separate css class
    { id:"col2", css:{'text-align':'right'} //directly in the attribute
]

Read more about using the css attribute in the Styling article.

Data formats

Formatting is applied to date and number values and defined for each column separately. To set some format for a column, use attribute format.

Setting the format for a specific column

columns:[
    //data will be formatted according to the current locale
    { id:"col2", format:function(value){ return webix.ui.numberFormat(value)};}
]

Related sample: Using date templates

For more details, read the Number and date formatting article.

Math in columns

You can write simple math formulas to specify values in column cells. Formulas can be set for a whole column or for a single cell.

Using formulas for setting values in the whole column

columns:[
    { id:"col1", math:"[row_id,col_name] + [row_id,col_name]"}
]

Related sample: Using formulas

For more details, read the Using formulas article.

External Datasource for the Column

The collection property of the column allows syncing column data with that of a dataCollection object or any data management component.

{   id:"order-1",
    view:"datatable",
    columns:[
        { id:"product", header:"Product", collection:"dash-pro" },
        { id:"quantity", header:"Quatity",  ... },
        { id:"price", header:"Unit price",  ... }
    ],
    dataFeed:"data/orderproducts.php", //main datasource
};

Collection for the first column points to other datatable with "dash-pro" ID.

{   view:"datatable", id:"dash-pro",
    columns:[
        { id:"name", header:"Product name", ..  },
        {..//other columns}
            ],
   url:"data/products.php",
   save:"connector->data/products.php" //dataprocessor
};

With the help of this property you can also sync the datatable with various dataCollections.

Templates

Through attribute template you can set a template of cells presentation corresponding to your needs.

Using templates for configuration data of a column

columns:[
    { id:"col4", template:function(obj){return obj.col1+obj.col2*2+obj.col3*3;}}
]

Related sample: Using string templates

For more details, read the Data templates article.

Styling

Many aspects of column can be customized to achieve the desired look-and-feel. Column style can be adjusted in a css class and applied through attribute css.

Applying a css class to a specific column

columns:[
    { id:"col1", css:"someStyle"}
]

For more details, read the Styling article.

Hiding/showing columns

Initially, all the datatable columns are visible by default unless a specific hidden property is used in its configuration:

var grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"col1", header:"Title", hidden:true}, //this column is hidden initially
        { id:"col2", header:"Rating"} //this column is visible
   ]
})

Through the hideColumn() and showColumn() methods you can manipulate visibility of columns dynamically.

Hiding a column

grid.hideColumn("col2");

Setting hidden/visible columns in groups

Datatable API allows for setting the initially visible group of columns (visibleBatch) as well as show and hide any chosen column group defined by batch property:

grida = new webix.ui({
  view:"datatable",
  visibleBatch:1,
  columns:[
    { id:"id",  header:"#", css:"rank",  batch:2,   width:50},
    { id:"title", header:"Film title", fillspace:true },
    { id:"year",  batch:1,  header:"Released" , width:80},
    { id:"category", header:"Category", batch:1},
    { id:"votes", batch:3, header:"Votes",  width:100},
    { id:"rating", batch:3, header:"Rating", width:100},
    { id:"rank", header:"Rank", css:"rank",  batch:2,width:50}
  ]
});

Any column group can be shown with the showColumnBatch method that takes column batch value as parameter:

//show show id, rank
grida.showColumnBatch(2);
//show votes, rating
grida.showColumnBatch(3);

Related sample: Column Batches

Adding/deleting columns dynamically

Since datatable columns is an array of JSON objects, you can treat it like any JavaScript array. At any moment you can add elements (columns) to this array and delete elements from it - and then repaint the datatable with the new configuration.

Replacing current columns with new ones

grid.config.columns = [..new collection of columns..];
grid.refreshColumns();

In addition, Webix offers its own API for working with arrays:

  • webix.toArray() - converts an array to "Webix" array;
  • array.insertAt() - inserts an element to array into the specific position;
  • array.removeAt() - removes an element from the array at the specific position.

Adding/Removing Separate Columns

var columns = webix.toArray(grid.config.columns);
//adding
columns.insertAt({
    id:"c"+webix.uid(),
    header:"New column"
},2);

//deleting
columns.removeAt(2);

//refreshing
grid.refreshColumns();

Related sample: Adding/removing columns

Grouping columns

The functionality is available in Webix Pro edition only.

Column batches can be used to organize groups of columns that are shown/hidden by clicking on the header of an aggregating column:

For these needs a multiple line header is used. The first line of an aggregating column is defined via an object with the following properties:

  • content (string) - content-forming property, here: columnGroup. The property is also used to define header filters;
  • batch (string, number) - ID of the group;
  • groupText (string) - title of the group (it is shown when the group is in a closed state);
  • closed (boolean) - the initial state of the group, false by default;
  • colspan (number) - the number of columns in the group, including the aggregating one.

Also, each column that belongs to some group, should be given a group ID defined by batch property:

columns:[
    //aggregating column
    { id:"2008_1", header:[
      { content:"columnGroup", closed:true, batch:"2008", groupText:"2008", colspan:12},
      "January"
    ]},
    //other columns from the group
    { id:"2008_2",  batch:"2008", header:[null, "February"] },
    { id:"2008_3",  batch:"2008", header:[null, "March"] },
    { id:"2008_4",  batch:"2008", header:[null, "April"] },
    ...
]

Related sample: Grouped columns in DataTable

Read more about colspans and rowspans in Webix datatable header.

Setting Colspans/Rowspans

The feature is available in Webix Pro edition only.

Datatable allows defining colspans and rowspans by span configuration provided with the dataset within the data property of the grid.

To enable the rowspans and colspans functionality, you should set the spans parameter with the true value in the datatable configuration.

Each rowspan/colspan definition consists of the row id, column id, width and height of the span, value to display and css class to apply:

grida = new webix.ui({
    view:"datatable",
    columns:[...],
    spans:true,
    data:{
        data:grid_data,
        spans:[
            [1, "title", 3]
        ]
    }
});

Related sample: Colspans in the DataTable

To learn more on this topic, please visit the Datatable Rowspans and Colspans article.


Creating Index Columns

In this chapter you will learn how to create index columns in DataTable.

There are 2 types of index columns:

  • Static (rows indices aren't changed whether you move, delete rows etc.)
  • Dynamic (rows indices can vary depending on the current position of rows)

Static index columns

To create a static index column in your datatable, use the following technique:

Specifying static index column in DataTable

dtable = new webix.ui({
    view:"datatable",
    columns:[
        { id:"index",   header:"",           sort:"int"},
        { id:"title",   header:"Film title", sort:"string"},
        { id:"year",    header:"Year",       sort:"int"}
    ],
    scheme:{
        $init:function(obj){ obj.index = this.count(); }
    },
    ...
});

Related sample: Index column

Let's consider what we do in the code above:

  1. In the columns parameter we assign an individual column to serve as the index entry.
  2. Then, we specify the scheme property with the $init key inside. The $init key runs when data is being loaded to the component initially and when data is being reloaded for new elements. The key is called for each data item, that's why we can use it as an iterator to assign indices to rows.
    Read more about the key in the related article - 'Defining Data Scheme. $init key'.

Dynamic index columns

To create a dynamic index column in your datatable, use the following technique:

Specifying dynamic index column in DataTable

dtable = new webix.ui({
    view:"datatable",
    id:"mytable",
    columns:[
        { id:"index",   header:"",           sort:"int"},
        { id:"title",   header:"Film title", sort:"string"},
        { id:"year",    header:"Year",       sort:"int"}
    ],
    on:{
        "data->onStoreUpdated":function(){
            this.data.each(function(obj, i){
                obj.index = i+1;
            })
        }
    },
    ...
});

Related sample: Index column

Let's consider what we do in the code above:

  1. In the columns parameter we assign an individual column to serve as the index entry.
  2. With the on parameter we attach a handler to the onStoreLoad event.
    "data->onStoreUpdated" is equal to $$('mytable').data.attachEvent('onStoreUpdated', function(){...})
  3. The onStoreLoad event fires after data is changed in the data store.
  4. The each method allows us to iterate through the collection of data items.


Headers and Footers

Headers and footers in DataTable are enabled by the header, footer parameters and configured by attributes header, footer in the columns parameter.

Header can be presented as:

  1. A single line header;
  2. A multiline header;
  3. A single line (or multiline) header containing colspans (rowspans), built-in filters;

Footer can be presented as:

  1. Single-line footer;
  2. Multiline footer;
  3. A single line (or multiline) footer containing colspans (rowspans), built-in counter;

Additionally, both header and footer can be rotated and take custom height.

Single line header

To define a simple (single line) header you should specify it as a string.

In this case you can put the following to the header:

  • text labels;
  • images;
  • html inputs;
  • links.

Defining a single line header

columns:[
    //header as a button
    { id:"col1", header:"<input type='button' value='Do something' class='dummy_button'>"},
    // header as an image
    { id:"col2", header:"<img src='../common/imdb.png'>"},
    //header as a text label
    { id:"col1", header:"Year"},
    // header as a link
    { id:"col4", header:"<a href='http://google.com'>Link</a>"}
]

Related sample: Different types of content in the header

Multiline header

You should use 'array' definition to split header into several subheaders (each value of the array specifies a single subheader).

Defining a multiline header

columns:[
    { id:"rank",  header:["#", ""]},
    { id:"title", header:["Film title", "Second line"]},
    { id:"year",  header:["Year", ""]},
    { id:"votes", header:["Votes", ""]}
]

Note, you can specify different number of subheaders for different columns (number of subheaders is equal to number of values in array).

Related sample: Multiline header

Complex header containing colspans (rowspans), built-in filters

To specify colspan(rowspan) in the header or put filter into it, you should specify the header as an object or array of objects.

When the header is presented as an object, it has the following properties:

  1. text - the text label of a column;
  2. colspan - the number of columns a cell should span;
  3. rowspan - the number of rows a cell should span;
  4. content - functional header content, built-in filters or group definition;
  5. rotate - if true, switches header to rotated state;
  6. height - defines a custom height for a header line.

Colspan

To create a cell that will span across 2 (or more) columns you should use the following technique:

Using colspans

columns:[
    { id:"title", header:["Film title", {text:"Subheader", colspan:3}]},
    { id:"year",  header:["Year", ""]},
    { id:"votes", header:["Votes", ""]}
]

Related sample: Colspans and rowspans in the header

Rowspan

To create a cell that will span across 2 (or more) rows you should use the following technique:

Using rowspans

columns:[
    { id:"title", header:[{ text:"Film title", rowspan:2}]},
    { id:"year",  header:["Year", ""]},
    { id:"votes", header:["Votes", ""]}
]

Related sample: Colspans and rowspans in the header

Built-in filters

To put filter into the header, you should use the following technique:

Using filters in the header

columns:[
    { id:"title", header:["Film title",{ content:"textFilter"}]},
    { id:"year",  header:"Released"},
    { id:"votes", header:"Votes"}
]

Related sample: Filters in the header

More information about built-in and custom filters is in the separate article.

Header Menu

The functionality is available in Webix Pro edition only.

Built-in header menu allows end users to control visibility of the columns by several mouse clicks. The definition is as well simple:

{ view:"datatable", columns:[...], headermenu:true}

Related sample: Header menu in the DataTable

Headermenu can be customized. For more details, go to the Datatable Header Menu article.

Single line footer

By default, headers are enabled whereas footers are disabled.
So, before using footers - enable them.

Enabling footers in DataTable

grid = new webix.ui({
    view:"datatable",
    ...
    footer:true
});

Then, use all the same logic as for headers:

Using footers

columns:[
    //footer as a button
    { id:"col1", footer:"<input type='button' value='Do something' class='dummy_button'>"},
    // footer as an image
    { id:"col2", footer:"<img src='../common/imdb.png'>"},
    //footer as a text label
    { id:"col1", footer:"Year"},
    // footer as a link
    { id:"col4", footer:"<a href='http://google.com'>Link</a>"}
]

Related sample: Standard header(footer) implementation

Multiline footer

Same as with header, multiline footer is comprised of an array of texts for each footer line.

Defining a multiline footer

columns:[
    { id:"rank",  footer:["Total", "Second line"]},
    { id:"title", footer:["", ""]},
    { id:"year",  footer:["", ""]},
    { id:"votes", footer:["12547", ""]}
]

Complex footer containing colspans/rowspans

Colspans and rowspans are used under the same logic as with headers. Footer line should be presented as an object that may contain:

  1. text - the text label of a footer;
  2. colspan - the number of columns a cell should span;
  3. rowspan - the number of rows a cell should span;
  4. content - the built-in functor of a column (summColumn);
  5. rotate - if true, switches footer to rotated state;
  6. height - defines height for a footer line.

Colspans in footer

columns:[
    { id:"rank",  footer:{text:"Total", colspan:3}},
    { id:"title", ...},
    { id:"year", ...},
    { id:"votes", footer:"12547"}
]

Sum counter in the footer

The library provides the summColumn counter that can be used to get the total value in the footer of a column.

To put the counter into the footer, you should use the following technique:

Using the sum counter in the footer

columns:[
    { id:"rank",  header:"", footer:{text:"Total:", colspan:3}},
    { id:"title", header:"Film title"},
    { id:"year",  header:"Released"},
    { id:"votes", header:"Votes", footer:{content:"summColumn"}}
]

Related sample: Counter in the footer

Rotated header/footer

Note that this feature is available in Webix Pro edition only.

To define rotated state for the header or footer you should specify it as an object (or array of objects in case of multiline header/footer).

Header height will be adjusted to text size.

columns:[
    {   id:"year",
        header:{ text:"Released", rotate:true },
        footer:{ text:"Footer", rotate:true}
    }
]

Related sample: Header rotate

Custom Height for Header and Footer

To set a custom height, present footer line as an object and use the height property:

columns:[
    {   id:"title",
        header:{ text:"Film title", height:25 },
        footer:{ text:"80px footer", height:80}
    }
]

Related sample: Custom height for header lines

Custom Header and Footer Content

All content elements that can be integrated to the datatable header or footer are stored in a webix.ui.datafilter object and feature the same configuration pattern.

There are two mandatory methods refresh() that provides logic and render() that draws an element. Their parameters include:

  • master - component object (here: datatable);
  • column - related column object;
  • node - HTML element (here: header td).

You can either extend or redefine the functionality of any existing content element, or create a totally custom element

Extending Existing Content Element

For datatable footer there exists a pre-built summColumn element that counts the sum from column rows and displays them under the main part or the datatable.

If you need to show an average value instead of a sum inherit from the summFilter and redefine its refresh():

webix.ui.datafilter.avgColumn = webix.extend({
    refresh:function(master, node, value){
        var result = 0;
        master.mapCells(null, value.columnId, null, 1, function(value){
            value = value*1;
            if (!isNaN(value))
                result+=value;
            return value;
        });

        node.firstChild.innerHTML = Math.round(result/master.count());
    }
}, webix.ui.datafilter.summColumn);

Creating Custom Content Element

A custom content element can be created totally from the scratch.

It must possess the following mandatory methods (declare them even if you don't need any specific performance from them):

  • getValue - gets the current value of an element;
  • setValue() - sets the value to an element;
  • render() - paints an element;
  • refresh() - defines dynamic performance of an element.

And you may define as many methods as you need.

A content element can feature the following properties:

  • trackCells (boolean) - indicates whether an element should be refreshed each time component data changes ( if true, refresh() method of a content element will be called automatically).
webix.ui.datafilter.customFilterName = {
    getValue:function(){}, //not used methods
    setValue: function(){},
    refresh: function(master, node, column){
        //event handlers
        node.onchange = function(){...};
        node.onclick = function(){...}
    },
    render:function(master, column){
        var html = "...";
        return html;
    }
};

Related sample: Custom content for header and footer


Available only in PRO Edition

Datatable Header Menu

Datatable built-in header menu is used to control column visibility with the help of a dedicated popup list with column names.

By default it is enabled by a right click over any column header while clicks on menu items change the state of the corresponding columns.

Simple Configuration

The simplest header menu is set with the help of a datatable headermenu property and has the following features:

  • it is triggered by a right click over the header of any column;
  • each menu item stands for a column;
  • hidden columns are included into the menu without an "eye" (visible) icon;
  • height of the menu is adjusted to the number of menu items;
  • width of the menu is 150px.
{ view:"datatable", columns:[...], headermenu:true}

Related sample: Header menu in the DataTable

Extended Configuration

Headermenu can be presented as a JSON object with configuration options for the menu list. The options duplicate Webix list properties and may include:

  • width (number) - width of the popup in pixels;
  • height (number) - height of the popup in pixels;
  • autoheight (boolean) - if true, adjusts popup height to the number of menu items. True by default;
  • yCount (number) - the number of menu items to show;
  • scroll (boolean) - if true, enables the scrollbar. False by default;
  • data (object) - columns to show in the menu (if not set, all columns are reflected in the menu). Each item contains:
    • id - ID of the datatable column (the same one it has in the columns configuration);
    • value - title of the datatable column (its header, as a rule).
  • template (string) - template of menu items (if you need to show a property other than value in the list).

Scrollable header menu with extra width

view:"datatable",
columns:[...],
headermenu:{
    width:250,
    autoheight:false,
    scroll:true
}

Related sample: Extended Header menu in the DataTable

Header menu with limited item quantity

view:"datatable",
columns:[...],
headermenu:{
    data:[
        { id:"year", value:"Released"},
        { id:"rating", value:"Rating"}
    ]
}

Related sample: Extended Header menu in the DataTable

Excluding a column from the menu

To exclude any column from the header menu, one should define a headermenu property for it and set its value to false:

{
    view:"datatable",
    headermenu:true, //enables the header menu
    columns:[
        //excluding "id" column from the menu
        {id:"id", header:"#", headermenu:false},
        {id:"title", header:"Title"}, ...
    ]
}

Attaching Headermenu to Other Elements

Extra "headermenu" column

Header menu can as well be shown by a left mouse click over the special datatable column that features a "headerMenu" content.

view:"datatable",
columns:[
    { header:{ content:"headerMenu" }, headermenu:false, width:35 }
]

Related sample: Header menu icon in the DataTable

If there is such a column in the datatable configuration, the headermenu property for it can be omitted.

Content property of a header line is also used to set built-in filters and define column groups.

Showing header menu on demand

The headermenu unique ID can be accessed through datatable config object. If you know this ID, you can work with the headermenu like with any other popup window, e.g. show it when needed.

webix.ui({
    view:"datatable", id:"dt2", columns:[...], headermenu:true
});

//show the headermenu by API
function showMenu(node){
    var menu = $$("dt2").config.headermenu;
    $$(menu).show(node);
}

Related sample: Header menu icon in the DataTable


Available only in PRO Edition

Datatable Rowspans and Colspans

Datatable API allows for setting rowspans and colspans with the help of span configuration that is passed together with datatable data.

To enable the rowspans and colspans functionality, you should set the spans parameter with the true value in the datatable configuration.

The data you want to display in the datatable is passed in the data object that contains:

  • data/url - a data collection that should be loaded;
  • spans - an array of rowspans and colspans for the datatable;
webix.ui({
    view:"datatable",
    columns:[...],
    spans:true,
    data:{
        data:[
            { id:1, title:"The Shawshank Redemption", country: "USA", year:1994,
                votes:678790, rating:9.5, rank:1},
            { id:2, title:"The Godfather", country: "USA", year:1972, votes:511495,
                rating:9.2, rank:2},
            { id:3, title:"The Godfather: Part II", country: "USA", year:1974,
                votes:319352, rating:9.0, rank:3},
            ...
        ],
        spans:[
            //span for 3 rows
            [1, "country", 1, 3],
            //span for 4 columns, styled
            ["sub1", "country", 4, 1, null, "highlight"],
        ]

    }
});

Related sample: Colspans in the DataTable

Each definition of a rowspan or colspan includes:

  • row id - id of the row that starts colspan/rowspan;
  • column id - id of the column that starts colspan/rowspan;
  • width - how many columns should the span include. Default value is 1;
  • height - how many rows should the span include. Default value is 1;
  • value (optional) - value that the span area should display. If the value of the start cell is required, omit this field or pass an empty value ("", null);
  • css (optional) - css class that should be applied to the span area.

Besides setting an array of rowspans and colspans directly in the datatable configuration, you can use the addSpan method to add spans into the datatable. It takes the same parameters that were described above, e.g.:

grid.addSpan(1, "country", 1, 3);

It's also possible to remove unnecessary spans with the help of the removeSpan method:

grid.removeSpan(1, "country");

The method takes 2 parameters:

  • id - (string/number) row id that starts a colspan/rowspan
  • column - (string) column id that starts a colspan/rowspan

Don't forget to call the refresh method after addSpan or removeSpan in order to rerender the datatable with the applied changes:

grid.refresh();

You can also get the span configuration array with the help of the getSpan method.

var span = grid.getSpan();

CSS for Rowspan and Colspans

The simplest way to add styling to the rowspan or colspan is to mention its css class in the configuration (as shown above).

Extra rules for span elements should be applied to properly position long texts in case of a row span:

Span CSS

<!-- ensuring proper display-->
.webix_span_layer{
    background: transparent;
    position:absolute;
    left:0px;
    top:0px;
    height:0px;
    width:0px;
    overflow: visible;
}
.webix_dtable_span{
    position:absolute;
    background: #fff;
    white-space: normal;
}
<!--colouring-->
.hrow{
    background: #DFF;
}

Datatable configuration:

Styled Spans

var text2 = "Learn more about each film, read recent reviews and explore ratings...";

webix.ui({
    view:"datatable",
    columns:[...],
    spans:true,
    data:{
        data:grid_data,
        spans:[
            //span for 3 columns
            [ "2", "rank",  6, 1, text2, "hrow"]
        ]

    }
});

Related sample: Colspans in the Big DataTable


Loading Data into DataTable

DataTable can load data of various formats, such as:

  • JSON;
  • XML;
  • JSArray;
  • CSV.

Examples of data formats

In addition to the mentioned above, you can define any custom format (read how to do this in article Data Drivers).

There are two main ways of loading data in DataTable:

  1. To define datasource in the object constructor;
  2. To use parse or load method.

Both ways lead to one and the same result and don't have any specificity.

Loading data from inline dataset

grid = new webix.ui({
    view:"datatable",
    ...
    data:[
        { id:1,name:"The Shawshank Redemption",year:1994},
        { id:2,name:"The Godfather",year:1972}
    ]
});

Related sample: Loading from inline datasource

Loading data from a data file

grid = new webix.ui({
    view:"datatable",
    ...
    url:"data/data.json"
});

Related sample: Loading from an external data file

Loading from XML, CSV, jsArray

When loading of non-json data, you need to specify the datatype property in config, or set the second parameter of the parse/load method to the name of the expected data type.

Also, you need to show in the columns configuration, which data will go to each column.

Loading from XML

grid = new webix.ui({
    view:"datatable",
    columns:[
        { map:"#cells[0]#", header:"Will use value from first cell sub-tag" }
        { map:"#details#", header:"Will use value from details attribute or sub-tag" }
    ],
    datatype:"xml"
    url:"data/data.xml"
});

Related sample: Loading from an external data file

If you use xml format with tag names equal to column ids, you may skip mapping, DataTable will be able to auto-map values

Loading from CSV

grid = new webix.ui({
    view:"datatable",
    columns:[
        { map:"#data1#", header:"First column" }
        { map:"#data2#", header:"Second column" }
    ],
    datatype:"csv"
    url:"data/data.csv"
});

Related sample: Loading from an external data file

For more details, check Data Mapping

Converting HTML table to DataTable

To turn an HTML table into DataTable you should call method parse with next parameters:

  • data - the id of the table;
  • datatype - the format of data. Must be set to value 'htmltable'.

Loading data from an html table

<table id="films">
    <tr>
        <td width="40">id</td>
        <td width="200">Film title</td>
        <td width="80">Release year</td>
    </tr>
    ...
</table>
<script>
grid = new webix.ui({
    view:"datatable",
    ...
});

grid.parse("films", "htmltable");
</script>

Related sample: Loading from HTML table

Loading from database

To load data from database table(s) you should deal with both client- and server-sides.

On the client side you must define parameter url (or call method load()) and specify a server-side script there.

On the server side you should write the script realizing server-client 'communication' that returns data in the XML or JSON format:

Static loading from db. Server-side code

<?php
   require_once("../../common/config.php");
   $data = new JSONDataConnector($conn, $dbtype);
   $data->dynamic_loading(30);
   $data->render_table("packages_plain","id","package, size, architecture, section");
?>

Static loading from db. Client-side code.

grid = new webix.ui({
    ...
    url:"data/table_data.php"
});
//or
grid.load("data/table_data.php");

Related sample: Loading from DB

Loading big datasets (dynamic)

Generally, data source in case of dynamic loading is database.

On the client side you must define parameter url (or call method load()) with a file realizing server-side 'communication'.

On the server side, if you don't write server-side code by yourself and use WebixConnector you should just call the dynamic_loading() method:

Dynamic loading from db. Client-side code

grid = new webix.ui({
    ...
    url:"data/data_dyn.php"
});

Dynamic loading from db. Server-side code

require_once("../../common/config.php");//including the connector file
$data = new JSONDataConnector($conn, $dbtype);//initializing the connector object
$data->dynamic_loading(30);//enabling dynamic loading
$data->render_table("packages_plain","id","package, size, architecture, section");//loading data from the specified database table

Related sample: Dynamic loading from DB

Note, inside dynamic_loading() you should specify a number of records that will be loaded at once.

Dynamic related parameters

The library offers you different properties and methods that can help you to set when, how often and which data will be loaded.

Table 1 Dynamic related parameters
Parameter | Description | Usage example
datafetch | Defines the number of records that should be loaded from server side during each dynamic loading request. 50 by default. | You want to load the particular number of records (e.g. 80), then you set datafetch:80. Related sample: Setting loading position
datathrottle | Sets polling interval that can be used to decrease the number of requests to server | As a rule, data are getting loaded when a user starts to scroll DataTable. If he scrolls DataTable slowly, the app pushes a big amount of requests to the server, a major part of which is unnecessary. To exclude unnecessary requests and reduce server overloading, you can set the datathrottle property, for example to 5, and requests start to be sent to server at 5 seconds intervals. Related sample: Setting polling interval
loadahead | Allows you to avoid DataTable from possible 'blank spots' while scrolling | When you start scrolling, DataTable detects where you scroll (up or down) and loads next records in this direction (the number of records is defined by the parameter). If you set loadahead:50, then on each scrolling movement DataTable will load next 50 records. Related sample: Dynamic loading. Load Ahead

Loading screen

When you deal with large data size, it's useful to display the loading screen showing users that the app is actually doing something.

To enable the loading screen for DataTable you should call method showOverlay(), to disable it after - hideOverlay().

Using the loading screen in DataTable

grid = new webix.ui({
    view:"datatable",
    ...
    on:{
        onBeforeLoad:function(){
            this.showOverlay("Loading...");
        },
        onAfterLoad:function(){
            this.hideOverlay();
        }
    },
    url:"data/table_data.php"
});

Related sample: Loading screen

In case you don't call method hideOverlay() , instead of the loading screen you will set the overlay text. It can be useful in some situations. For example, when your DataTable doesn't contain any data, you can display the overlay text to inform users about it.

Defining the overlay text for DataTable

on:{
    onAfterLoad:function(){
        if (!this.count())
        this.showOverlay("Sorry, there is no data");
    }
}

Related sample: Adding overlay text

Loading configuration

You can load configuration from server side along with data. In such case your data will look as:

{
    config:{
        columns:[ ... columns configuration here... ],
        ... any extra options here, same as in constructor...
    },
    data:[ ... array of data objects here, as in above samples... ]
}

Read more on the topic in article External configuration.


Examples of Data Formats

Table 1 Initial data
Country | Population | Estimate
China | 1 341 990 000 | 2011
India | 1 193 290 000 | 2011
United States | 311 960 000 | 2011
Indonesia | 237 556 363 | 2010

XML

<?xml version="1.0" encoding="UTF-8"?>
<data>
  <item id="1">
    <country> China </country>
    <population> 1 341 990 000 </population>
    <year> 2011 </year>
  </item>
  ...
  <item id="4">
    <country>  Indonesia </country>
    <population> 237 556 363 </population>
    <year> 2010 </year>
  </item>
</data>

you are not limited to the above xml format, check Data Mapping for instruction how any xml file can be loaded in the datatable.

JSON

[
    { id:"1", country: "China", population: "1 341 990 000", year: "2011" },
    { id:"2", country: "India", population: "1 193 290 000", year: "2011" },
    { id:"3", country: "United States", population: "311 960 000", year: "2011" },
    { id:"4", country: "Indonesia", population: "237 556 363", year: "2010" }
]

JSArray

[
    [ "China", "1 341 990 000", "2011" ],
    [ "India", "1 193 290 000", "2011"],
    [ "United States", "311 960 000", "2011"],
    [ "Indonesia", "237 556 363", "2010"]
]

CSV

China, 1 341 990 000, 2011
India, 1 193 290 000, 2011
United States, 311 960 000, 2011
Indonesia, 237 556 363, 2010


Data Mapping

It's possible to define mapping between loaded data and columns of datatable.

By default, DataTable will assume that incoming json/xml has attribute with the same name as columns id. So for well formed xml/json you need to define only column id.

In case of xml/json in custom format, you can use "map" attribute of column, it defines which property of loaded data object need to be used for that column in grid

Loading from XML

grid = new webix.ui({
    view:"datatable",
    columns:[
        {
            id:"size",
            map:"#cells[0]#",
            header:"Will use value from first cell sub-tag"
        },
        {
            id:"url",
            map:"#details#",
            header:"Will use value from details attribute or sub-tag"
        }
    ],
    datatype:"xml"
    url:"data/data.xml"
});

The code above will correctly show data from XML as in:

<rows>
    <item details="http://mysite.com"><cell>15x24</cell><cell>19.02.2008</cell></item>
    <item details="http://mysite.com"><cell>10x12</cell><cell>22.02.2008</cell></item>
    ...
</rows>

Specific of CSV and jsArray data types

During csv(jsarray) parsing, its columns are named as data1 .. dataN You can use that values as column's ids

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"data1"  },
        { id:"data2"  }
    ],

Related sample: Loading from inline datasource

or you can use mapping, to define more meaningful names for columns

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"url",   map:"#data1#"  },
        { id:"size",  map:"#data2#"  }
    ],

Converting values to the native type

When you loading data from xml, all values will be loaded as string ( in json - string or numbers ), but it is not very useful as we need to work with different types of objects, date objects for example.

Mapping logic allows to define the native type of value, and during data mapping it will be converted from the string to the defined type

webix.ui({
    view:"datatable",
    columns:[
        { id:"start", map:"(date)#start#" }
    ]

Related sample: Converting strings to dates

If id of columns and name of mapped field is equal you can shorten it to

webix.ui({
    view:"datatable",
    columns:[
        { id:"start", map:"(date)" }
    ]

Scheme data mapping

If all above doesn't work you can use scheme property to define custom data mapping function

webix.ui({
    view:"datatable",
    scheme:{
         $init:function(obj){
         //obj - data object from incoming data
             obj.count = obj.cells[0]; //set value based on some data in incoming dataset
             obj.price = obj.cells[1];
             obj.total = obj.price * obj.count;   //or calculate values on the fly
         }
    },
    columns:[
        { id:"count" },
        { id:"price" },
        { id:"total" }
    ],
    ...

Data scheme if described in detail separately.

Common mapping for all data items

Data can be mapped initially to created aggregated properties that can be later used as column IDs:

webix.ui({
    view:"datatable",
    map:{
        name:"#firstname# #lastname#",
        birth:"(date)#birthdate#"
    },
    columns:[
        { id:"name", header:"User name" },
        { id:"birth", header:"Date of birth"}
    ],
    data:[
        { id:1, firstname:"Adam", lastname:"Smith", birthdate:new Date(1985, 1, 1) },
        { id:2, firstname:"Tom", lastname:"Brown", birthdate:new Date(1986, 2, 2) },
    ]
});


Sizing and Resizing

In this chapter you will learn how to set sizes for different DataTable elements and then change them, if it's needed.

We will consider 3 elements:

  1. DataTable container;
  2. Column;
  3. Row.

and 3 possible situations (scenarios) for them:

  1. Setting the fixed size;
  2. Autosizing;
  3. Resizing.

Setting the fixed size

DataTable container

By default, DataTable adjusts to the parent container size that gives us 2 ways to set the fixed size for it:

  1. To set the size of the parent 'div' container;
  2. To use the width and height parameters within DataTable constructor.

Setting the fixed size for DataTable

//way 1
<div id="box" style="width:300px;height:400px;"></div>

grid = new webix.ui({
    container:"box",
    view:"datatable",
    ...
});
//way 2
<div id="box"/>

grid = new webix.ui({
    container:"box",
    view:"datatable",
    height:400,
    width:300,
    ...
});

Related sample: Adjusting to the parent container

Related sample: Sizing through the 'width', 'height' parameters

Column

Fixed column width

By default, datatable columns feature fixed size of 100px. To change it, you should either:

  • use width while configuring the column to set width to a column individually, or
  • use columnWidth while configuring the datatable to set common width for all the columns. Like default common width, it can be overridden by individual width value, or
  • use minWidth property in the column configuration to define minimal width for it. If there's more space initially or after resizing, column width will be increased, but it can never be less than minWidth value, or
  • use minColumnWidth property in datatable configuration to set common minimal width for all columns. It can be overridden by individual minWidth value.

Setting different widths for columns

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:"Film title" ,   width:80},
        { id:"title", header:"Release year" , minWidth:50}
    ]
});

Altering common width for all columns

grid = new webix.ui({
    view:"datatable",
    columnWidth:200,
    columns:[
        { id:"title", header:"Film title"},
        { id:"title", header:"Release year"}
    ]
});

Relative Sizing

  • adjusting the width of datatable to the parent container

If you set widths for columns and their sum is less than the width of the parent container, you can use the fillspace attribute to force some of columns to widen for filling the unused space.

Using attribute fillspace

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:"Film title", fillspace:true},
        ...
    ]
});

Related sample: Adjusting columns to the parent container

  • adjusting the width of a column to other datatable columns

There can be more than one fillspace in the datatable; in this case width will be calculated on the base of a proportion defined by numeric values:

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"id", header:"ID", fillspace:1},
        { id:"title", header:"Film title", fillspace:4}
    ]
});

In the above code the title column is 4 times bigger than the id column, which is 20 to 80 percent relation.

Adjusting column to its content

If you want to adjust the width of a column to the related content size, you can use attribute adjust. It is defined for the needed column individually and features two modes:

  • "data" - adjusts column width to the content of the widest item in it;
  • "header" - adjusts column width to its header content;
  • true - searches for the widest item among data and header(s) and adjusts column width to its content.

Adjusting the column width to fit the content size

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:"Film title", adjust:"data"},
        { id:"rank", header:"Rank", adjust:"header"},
        { id:"votes", header:"Votes", adjust:true}
        ...
    ]
})

Related sample: Adjusting columns to the content

Note that resulting column width after adjusting won't be lesser than minWidth for this column provided that the latter is set.

Row

To set the fixed height for a row you should use $height while defining the data you will load into DataTable. If you set the height in such a way, it will save its value regardless of any other enabled size parameters (e.g. - autoheight).

Setting different heights for rows

grid = new webix.ui({
    view:"datatable",
    ...
    data:[
        { $height:20, id:1, title:"The Shawshank Redemption", year:1994},
        { $height:40, id:2, title:"The Godfather",            year:1972},
        ...
    ]
});

Related sample: Setting custom size for rows

Autosizing

Autosizing to parent container

Datatable automatically adjusts to the size of a parent container provided that no content autosizing is not enabled.

To make the Datatble fill the entire width, you should define fillspace for at least one of its columns:

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:"Film title", fillspace:true},
        { id:"year", header:"Year", width:100}
    ]
});

In this case, title column will be calculated as container width - 100.

Autosizing to content

You can enable width, height (or both of them) autosizing to adjust DataTable to the size of its content horizontally or vertically. Autosizing is enabled by the following parameters:

  • autowidth;
  • autoheight.

DataTable autosizing

grid = new webix.ui({
    view:"datatable",
    ...
    autoheight:true,
    autowidth:true
});

Related sample: Height and width autosizing

Resizing

By resizing we mean 2 possible scenarios:

  • resizing columns, rows by hovering, dragging mouse over some border;
  • setting other sizes for DataTable elements programmatically.

Related sample: Row auto-height

Mouse resizing

To enable the possibility to resize columns (rows) by mouse you should use one of the following parameters (or both of them at once):

  • resizeRow;
  • resizeColumn.

Enabling the possibility to resize columns and rows by mouse

grid = new webix.ui({
    view:"datatable",
    ...
    resizeColumn:true,
    resizeRow:true
});

Related sample: Column and row resizing

For these resizing options there exist relevant events onRowResize and onColumnResize.

Dynamic resizing

For dynamic resizing DataTable elements, the library offers method resize(). When you change size of some element and call this method, child(parent) container of the calling element will adjust to his new size.

Adjusting the parent container to the DataTable size

grid = new webix.ui({
    view:"datatable",
    ...
})

grid.define("width", 700);
grid.resize();

Related sample: Dynamical adjusting to the parent container

In some situations you may need to adjust an element to the size of the outer parent HTML container. In such the situation you may use method adjust() instead of resize():

Adjusting DataTable to the size of the parent container

grid = new webix.ui({
    container:"box",
    view:"datatable",
    ...
})

webix.toNode("box").style.width = "700px";
grid.adjust();

Related sample: Dynamical adjusting to the parent container

The resize() and adjust() methods can lead to one and the same effect. For example, you have DataTable placed into a 'div' container, named as 'box'. The initial height of DataTable is 50 px. You want to increase it to 80 px. Possible solutions can look as shown in the table below:

Table 1 Use of adjust() and resize() methods
Image Related code
document.getElementById('box').style.height="80px";
grid.adjust();

grid.define("height", 80);
grid.resize();

You can use events to call the mentioned above methods:

Adjusting DataTable to the size of a window, it’s placed into

webix.event(window, "resize", function(){ grid.adjust(); })

Related sample: Sizing and events

Dynamic Adjusting Columns and Rows

To dynamically adjust column width of row height to the size of their content, you can you the corresponding methods:

  • adjustColumn(id) - adjusts the with of a chosen column specified by its ID;
  • adjustRowHeight(id) = adjusts height of a chosen tow specified by its ID. The method can slow down the application.

Scrolling

By default, scrolling (vertical and horizontal) is enabled in DataTable. It can be disabled by parameters scrollY, scrollX.

Disabling vertical scrolling

grid = new webix.ui({
    view:"datatable",
    ...
    scrollY:false
});

The size of the scroll bars (vertical and horizontal at the same time) can be managed by parameter scrollSize (by default, 18px).

Managing the size of the scroll bars

grid = webix.ui({
    view:"datatable",
    ...
    scrollSize:20
})

You can also force DataTable to be scrolled just by whole rows, i.e. you won't be able to scroll along the full length of rows. The related parameter you should enable is scrollAlignY:

Scrolling DataTable by whole rows

grid = new webix.ui({
    ...
    scrollAlignY:true
});

Related sample: Different scrolling behaviours


Internationalization of DataTable

DataTable provides support for numbers, currency and date internationalization.

The standard package of the Webix library includes 9 locales, namely:

  • 'en-US' - North American (used by default);
  • 'ru-RU' - Russian;
  • 'fr-FR' - French;
  • 'ja-JP' - Japanese;
  • 'be-BY' - Belarusian;
  • 'de-DE' - German;
  • 'es-ES' - Spanish;
  • 'it-IT' - Italian;
  • 'zh-CN' - Chinese.

Webix Pro edition includes over 300 locales to match a great variety of cultures.

To localize your app into some other language, you should do the following:

  1. Create a locale file.
  2. Activate the locale.

Creating locales

Locale is created in a separate js file named as "ll-CC", where

  • ll - a two-letter language code;
  • CC - a two-letter country code.

Creating Spanish (Spain) locale for DataTable. The 'es-ES.js' file

webix.i18n.locales["es-ES"]={   //"es-ES" - the locale name, the same as the file name
  groupDelimiter:" ",         //a mark that divides numbers with many digits into groups
  groupSize:3,                //the number of digits in a group
  decimalDelimiter:",",       //the decimal delimiter
  decimalSize:2,              //the number of digits after the decimal mark

  dateFormat:"%d/%m/%Y",      //applied to columns with 'format:webix.i18n.dateFormatStr'
  timeFormat:"%H:%i",         //applied to columns with 'format:webix.i18n.dateFormatStr'
  longDateFormat:"%d %F %Y",  //applied to columns with 'format:webix.i18n.longDateFormatStr'
  fullDateFormat:"%d.%m.%Y %H:%i",//applied to cols with 'format:webix.i18n.fullDateFormatStr'

  price:"{obj} EUR",//EUR-currency name.Applied to cols with 'format:webix.i18n.priceFormat'
  calendar:{
     monthFull:["Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio", "Julio", "Agosto",
                "Septiembre", "Octubre", "Noviembre", "Diciembre"],
     monthShort:["En", "Feb", "Mar", "Abr", "Mayo", "Jun", "Jul", "Ago", "Sep", "Oct",
                "Nov", "Dic"],
     dayFull:["Domingo", "Lunes", "Martes", "Miercoles", "Jueves", "Viernes", "Sabado"],
     dayShort:["Dom", "Lun", "Mar", "Mier", "Jue", "Vier", "Sab"]
  }
};
  • monthFull - the full names of months starting from January;
  • monthShort - the short names of months starting from January;
  • dayFull - the full names of week days starting from Sunday;
  • dayShort - the short names of week days starting from Sunday.

Activating the locale

To activate locale:

  1. Include the related locale file on the page;
  2. Call webix.i18n.setLocale('locale_name') ( !before DataTable initialization).
<script src="../locale/es-ES.js" type="text/javascript" charset="utf-8"></script>

<script>
    webix.i18n.setLocale("es-ES");
    grid = new webix.ui({
        view:"datatable",
        columns:[
            { header:"Date",  id:"start", format:webix.i18n.dateFormatStr},
            { header:"LongDate",width:170, id:"start",format:webix.i18n.longDateFormatStr},
            { header:"Price",  id:"number", format:webix.i18n.priceFormat },
        ],
        ...
    });
</script>

Related sample: Internationalization


External configuration

You have the possibility to load not only data but also DataTable configuration from external file or the server side.

Providing configuration as part of data

Configuration from a JSON file

To load both data and configuration from JSON file, initialize DataTable as shown below:

dtable = new webix.ui({
    container:"box",
    view:"datatable",
    url:"data/data-config.json" //path to json file. See the file content below
});

The specified data-config.json file should have the following structure:

'data-config.json' file

{
    "config":{
        columns:[
            { id:"title",   header:"Film title", width:200},
            { id:"year",    header:"Released",   width:80},
            { id:"votes",   header:"Votes",      width:100}
        ],
        height:100,
        autowidth:true
    },
    "data":[
        {id:"1", title:"The Shawshank Redemption", year:"1994", votes:"678790"},
        {id:"2", title:"The Godfather",            year:"1972", votes:"511495"}
    ]
}

Configuration from an XML file

To load both data and configuration from XML file, initialize DataTable as shown below:

dtable = new webix.ui({
    container:"box",
    view:"datatable",
    url:"data/data-config.xml"// path to XML file. See the file content below
});

The specified data-config.xml should have the following structure:

'data-config.xml' file

<?xml version='1.0' encoding='utf-8' ?>
<data>
    <config>
        <columns>
            <column id="title"   header="Film title"  width="200"></column>
            <column id="year"     header="Released"    width="80"></column>
            <column id="votes"    header="Votes"       width="100"></column>
        </columns>
        <height>100</height>
        <autowidth>true</autowidth>
    </config>
    <item id='1' title='The Shawshank Redemption' year='1994' votes='678790'></item>
    <item id='2' title='The Godfather'            year='1972' votes='511495'></item>
</data>

Related sample: Loading configuration from external url

Loading configuration from a separate file

Configuring from the server side

To load DataTable configuration from the server side, initialize DataTable as shown below:

webix.ajax("data/config.json", function(text){
    var config = webix.DataDriver.json.toObject(text);
    new webix.ui({
        container:"box",
        view:"datatable",
        columns:config,
        data: [
            { id:1, title:"The Shawshank Redemption", year:1994,  votes:678790},
            { id:2, title:"The Godfather",            year:1972,  votes:511495}
        ]
    });
});

The specified config.json file should have the following structure:

'config.json' file

[
    { id:"title",   header:"Film title",  width:200},
    { id:"year",    header:"Released" ,   width:80},
    { id:"votes",   header:"Votes",       width:100}
]

Configuring and populating from the server side

To load both data and configuration from the server side, initialize DataTable as shown below:

webix.ajax("data/data-config.json", function(text){
    var obj = webix.DataDriver.json.toObject(text);
    new webix.ui({
        container:"box",
        view:"datatable",
        columns:obj.config,
        data:obj.rows
    });
});

The specified data-config.json file should have the following structure:

'data-config.json' file

{
    "config":[
        { id:"title",   header:"Film title", width:200},
        { id:"year",    header:"Released",   width:80},
        { id:"votes",   header:"Votes",      width:100}
    ],
    "rows":[
        { "id":1, "title":"The Shawshank Redemption", "year":1994, "votes":678790},
        { "id":2, "title":"The Godfather",            "year":1972, "votes":511495}
    ]
}

Related sample: Loading configuration from server side


Available only in PRO Edition

Adding Subrows

In case you need to give some additional information for the content of a datatable row, you can add a subrow after it.

To add a subrow into Datatable, use the subrow property. As a parameter, it takes a template with the names of data properties that should be shown in the subrow:

{
    view:"datatable",
    subrow:"Rating: #rating#, Category: #category#",
    ...
}

In the columns configuration you should specify the template property with the value like "{common.subrow()} #title#", where:

  • {common.subrow()} - renders "+" and "-" icons to open/close subrows
  • #title# - defines the data that should be rendered in the column next to the icon
columns:[
    { id:"title", header:"Title",
        template:"{common.subrow()} #title#", width:220 },
    { id:"year",  header:"Year",  width:100, sort:"int"},
    { id:"votes", header:"Votes", width:100, sort:"int"}
]

Related sample: SubRows in DataTable

Setting autoheight for subrows

If the text in a subrow is too long, you can set the subRowHeight property with the auto value. It will force the subrow to adjust its height to the size of the text:

webix.ui({
    view:"datatable",
    subrow:"#details#",
    columns:[
        ...
    ],
    subRowHeight:"auto",
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790,
            details:"Long text Long text Long text Long text Long text Long text Long text
                        Long text Long text Long text Long text Long text Long text
                            Long text Long text Long text Long text Long text "},
        ...
    ]
});

Related sample: SubRows in DataTable - Size to Data

Changing the content of a subrow

If you need to alter the text in the subrow dynamically, you should access the related data item and apply changes to it.

Take that you render details data property in a subrow:

{
    view:"datatable", id:"dt1",
    // the data specified in the "details" property will be rendered
    subrow:"#details#",
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790,
            details:"Long text Long text Long text Long text Long text Long text
            Long text Long text Long text Long text Long text Long text Long text
            Long text Long text Long text Long text Long text "},
        ...
    ]
}

To change it, you should use the getItem method that will return data item object by the specified id. And then specify the new text for the details property of this item:

{
    // return the object of the id with id "1" and set
    // the text "One line" in the "details" property
    $$("dt1").getItem("1").details = "One line";
    $$("dt1").refresh()
}

Related sample: SubRows in DataTable - API

API reference

There's a couple of functions you can use to manipulate the subrows in a datatable:

  • openSub() - opens a subrow by the item id:
$$("myDatatable").openSub(id);
  • closeSub() - closes an opened subrow by the item id:
$$("myDatatable").closeSub(id);


Available only in PRO Edition

Adding Subviews

Besides simple subrows it's also possible to render subviews in a datatable. Below you can see the details on how to insert a sub-grid or a sub-form into Datatable. If necessary, any Webix component can be used as a subview.

Sub-Grid in a DataTable

To add a subview into Datatable, use the subview property. In the case of datatable, you should specify a Datatable configuration with all the necessary parameters as value of this property.

In the columns configuration of the Datatable you should specify the template property with the value like {common.subrow()} #title#, where:

  • {common.subrow()} - renders "+" and "-" icons to open/close subviews
  • #title# - defines the data that should be rendered in the columns next to the icon

Subgrid with static data

webix.ui({
    view:"datatable",
    // subgrid configuration
    subview:{
        view:"datatable",
        columns:[
            { id:"Outlet", sort:"string", fillspace:true },
            { id:"January" },
            { id:"February" },
            { id:"March" }
        ],
        data:[
            { Outlet:"North", January:100, February:230, March:180 },
            { Outlet:"West", January:70, February:120, March:160 },
        ],
    },
    // datatable configuration
    columns:[
        { id:"title",   header:"Title", sort:"string",
            template:"{common.subrow()} #title#", width:220 },
        { id:"year",    header:"Year",  width:100, sort:"int"},
        { id:"votes",   header:"Votes", width:100,  sort:"int"}
    ],
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790 },
        ...
    ]
});

Related sample: Sub-Grid in a DataTable

Loading data into a subview

To populate a subview with data, you can either

  • specify a static dataset in the datatable configuration (as shown above);
  • use the load or parse methods to populate the subgrid with "item-related" data.

Using inline data

To load inline data into the sub-grid when a subview is created, use the onSubViewCreate() event with two parameters:

  • view - the created subview;
  • item - the item for which a subgrid is created.

In the event handler apply the parse method and pass the data item property with sub-grid's data into it:

webix.ui({
    view:"datatable",
    subview:{
        view:"datatable",
        columns:[
           { id:"Outlet", sort:"string", fillspace:true },
           { id:"January" },
           { id:"February" },
           { id:"March" }
         ],
     },
    on:{
        onSubViewCreate:function(view, item){
            view.parse(item.outlets);
        }
    },
    columns:[
        ...
    ],
    data:[
      { id:1, title:"The Shawshank Redemption", year:1994, votes:678790, outlets:[
         { Outlet:"North", January:100, February:230, March:180 },
         { Outlet:"West", January:70, February:120, March:160 },
      ]},
      ...
    ]
});

Related sample: Sub-Grid in a DataTable - Inline Data

Loading data from an external source

To load data from an external source, use the load method that takes the path to the necessary file or script that will return data for a subgrid.

{
    view:"datatable",
    subview:{
        view:"datatable",
        columns:[
            ...
        ],
    },
    on:{
        onSubViewCreate:function(view, item){
          view.load("../../../15_datatable/16_dyn_loading/data/data_dyn.php?for="+item.id);
        }
    },
    columns:[
        ...
    ],
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790 },
    ]
}

Related sample: Sub-Grid in a DataTable - Loading Data

Sub-Form in a Datatable

The same as with a Sub-Grid, you can add a Sub-Form into Datatable.

You need to initialize a form view inside of the subview property and define the configuration of form elements. Note that name attributes of the form fields should coincide with data item properties to ensure a simple and clear way of two-way binding.

To add values into the sub-form when a subview is created, use the onSubViewCreate() event with two parameters:

  • view - the created subview;
  • item - the item for which a subview is created.

And in the event handler use the setValues method with the item object as a parameter.

webix.ui({
    view:"datatable",
    subview:{
        view:"form",
        elements:[
            { view:"text", name:"title", label:"Title"},
            { view:"text", name:"year", label:"Year"},
            { cols:[
                { }, { view:"button", value:"Save", click:function(){
                    var form = this.getFormView();
                    var values = form.getValues();
                    var changed = form.getDirtyValues();
                    // get master datatable
                    var master = form.getMasterView();

                    master.updateItem(values.id, changed);
                    // close the subgrid
                    master.closeSub(values.id)
                }}
            ]}
        ]
    },
    on:{
        onSubViewCreate:function(view, item){
            view.setValues(item);
        }
    },
    columns:[
        ...
    ],
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790 },
        ...
    ]
});

Related sample: Sub-Form in a DataTable


Look and Feel

  • Cells Templates
  • Number and Date Formatting
  • Styling DataTable
  • Split Mode or 'Frozen Columns'


Cells Templates

String templates

To customize data content and specify which data will be presented in DataTable and how, you can use templates. Data templates are set in the related column by attribute template.

By value wrapped in the hash signs (e.g. "#title#") you refer to the definite property of a data item.

You can read about templates syntax in article Templates.Syntax.

Specifying data template for a specific column

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:"Film title",    template:"<strong>#title#</strong>",
        { id:"year",  header:"Release year" , template:"at #year#",}
    ]
});

Related sample: Using string templates

Templates can be used for presenting almost any content in DataTable ( anything which can be done through HTML - can be placed in DataTable's cell) such as: images, links, numbers, string, dates.

Table 1 Templates for different types of content
Content Example of template
strings
template:"<strong>#title#</strong>"
images
template:"<img src='.imgs/#id#.jpg'/>"
links
template:"<a href='http://google.com?q=#title#'>#title#</a>"

Complex templates

You can set custom template for a column by presenting the template attribute as a function (function accepts raw object and returns the result string).

grid = new webix.ui({
    view:"datatable",
    columns:[
      {id:"title", header:"Film title"},
      {id:"votes", header:"Votes", template:function(obj){ return obj.votes/1.2547}};
    ],
    ...
})

Related sample: Converting strings to dates

For more on styling, read article Styling DataTable

Combining templates and formats

If you want to use both template and format for the same column, you should include the formatting method into a template function:

grid = new webix.ui({
    view:"datatable",
    columns:[
      {id:"votes", header:"Votes", template:function(obj, common){
           return "no more than "+ webix.i18n.numberFormat(obj.votes);
      }}
    ],
    ...
})

Adding buttons in templates

You can insert any custom html to the row elements, which gives an easy way for adding buttons or similar controls to Datatable's rows

grid = new webix.ui({
    view:"datatable",
    columns:[
      {id:"votes", header:"Votes",  template:"#votes#
            <input type='button' value='Show details' class='details_button'>'"}
    ],
    onClick:{
        details_button:function(id, ev){
            //will be called on button click
            some_custom_method(id.row, id.column);
        }
    }
    ...
})

Related sample: Datatable: Custom Handler

Built-in templates

Through the template you can define common elements for the cells belonging to one and the same column, namely:

  • checkboxes;
  • radio buttons;
  • "edit" cons;
  • "trash" icons;
  • sparklines.

You can define additional common elements within the component type.

webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"ch1", header:"", template:"{common.checkbox()}"},
        { id:"ra1", header:"", template:"{common.radio()}"}
    ]
});

Related sample: Checkbox and radio in DataTable

Learn more about checkboxes and radios in a separate article - Checkbox and Radio in DataTable

webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"edit", header:"", template:"{common.editIcon()}"},
        { id:"trash", header:"", template:"{common.trashIcon()}"}
    ]
});

You can set built-in template via a function:

webix.ui({
    view:"datatable",
    ...
    columns:[
        //for radio and checkbox
        { id:"ra1", template:function(obj, common, value, config){
             return common.radio(obj, common, value, config);
        }},
        //for editIcon and trashIcon
        { id:"edit", header:"", template:function(obj, common){
            return common.editIcon(obj, common);
        }}
    ]
});

As you can see, common.checkbox() and common.radio() functions take four parameters:

  • item object with its properties from the dataset;
  • common object with four methods:
    • common.checkbox(obj, common, value, config);
    • common.radio(obj, common, value, config);
    • common.editIcon(obj, common);
    • common.trashIcon(obj, common);
  • value - current checkbox/radio state;
  • config - column configuration object.


Templates. Syntax

There are several ways to define a template:

HTML with text

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"col1", header:"Column1", template:"#Package# : #Version#<br/>#Maintainer#"},
    ]
});

In the code snippet above, values within sharps are replaced with the related properties from data objects that can look like shown below:

//for next data
[
 {Package:"Webix Connector", Version:1.1, Maintainer:"Server side Team"},
 {Package:"Webix Scheduler", Version:3.5, Maintainer:"Scheduler Team"},
...
]
//Above template will generate text as
var template ="#Package# : #Version#<br/>#Maintainer#"
var text =    "Webix Connector : 1.1 <br/>#Maintainer#"

Function

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"col1", template:function(obj){
            return obj.Package +"<br/>"+obj.Maintainer;
        }}
    ]
});

HTML container

<textarea id="template_container" style="display:none">
 #Package# : #Version# <br/>#Maintainer#</textarea>
// instead of 'textarea' can be any appropriate HTML tag
...
grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"col1", header:"Column1", template:"html->template_container"},
    ]
});

External file

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"col1", header:"Column1", template:"http->../common/template.html"},
    ]
});


Available only in PRO Edition

Using Sparklines in Datatable

Sparklines are small graphs embedded into the datatable and used for presenting the general variation of certain parameters. Each data value is specified as a point in the sparkline. Depending on the value, points are located at a different height relative to each other.

Sparklines are set in the datatable through the {common.sparklines()} template. The column's id coincides with the property in the data set that contains data values. The sparklines chart is built on the basis of these values:

webix.ready(function(){
  grida = webix.ui({
  container:"testA",
  view:"datatable",
  columns:[
    { id:"name", header:"Name", width:150},
    { id:"avIncome", header:"Income", width:120},
    // sparklines
    {
        id:"income",
        header:"Income per Period",
        template:"{common.sparklines()}",
        width:160
    }
  ],
  autoheight:true,
  autowidth:true,
  data: [
    { id:1, name:"Austria", income:[150,200,170,210,250,190], avIncome: 200},
    { id:2, name:"France", income:[230,300,220,270,210,250], avIncome: 246.67},
    { id:3, name:"Germany", income:[250,240,300,230,270,280], avIncome: 255.83},
    { id:4, name:"UK", income:[280,230,280,290,260,210], avIncome: 250.83}
  ]
});

Related sample: Sparklines


Number and Date Formatting

Number formatting

To set the required format for number fields you should use attribute format.

Using number templates

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"votes", format:webix.Number.numToStr({
            groupDelimiter:",",
            groupSize:3,
            decimalDelimiter:".",
            decimalSize:2})
        },
        ...
    ]
});

Related sample: Using number templates

Method numToStr() allows you to set the following properties for fractional numbers:

  • groupDelimiter - a mark that will be used to divide numbers with many digits into groups;
  • groupSize - the number of digits in a group;
  • decimalDelimiter - a mark that will be used as the decimal delimiter;
  • decimalSize - the number of digits after the decimal mark.

There are two default presets - numberFormat and priceFormat which provides number and price formatting according to the current locale

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"votes", format:webix.i18n.numberFormat },
        { id:"price", format:webix.i18n.priceFormat }
    ]

For details on number formatting methods, see Number formatting methods.

Date formatting

Dates in DataTable can be specified by both DateTime and string values.

But formatting can be applied only to DateTime objects. Therefore, to format string values you should convert them to DateTime format at first.

Common date formatting

To set the required format for date and time values, specify the format attribute.

As a value for the attribute you can use:

  • Members of the i18n object;
  • The dateToStr() method of the Date object.

Setting date formats

grid = new webix.ui({
    view:"datatable",
    columns:[
        { template:"#start#", header:"Date",  format:webix.i18n.dateFormatStr},
        { template:"#start#", header:"Y-m-d", format:webix.Date.dateToStr("%Y-%m-%d")}
    ],
    data:[
        { text:"Finish", start:new Date(2012,11,12) },
        { text:"Start",  start:new Date(1988,1,29) }
    ]
});

Related sample: Using date templates

For details on date formatting methods, see article Date formatting methods.

Converting string values to DateTime format

To correctly work with dates, you need to have data in the grid as valid Date object, but in all common formats data is presented as string. DataTable provides a way to mark columns for auto-conversion from Date string to Date objects

grid = new webix.ui({
    view:"datatable",
    columns:[
        { map:"(date)#start#", header:"Date",  format:webix.i18n.dateFormatStr},

});

Related sample: Converting strings to dates

the (date) marker at start of map declaration forces data conversion from string to object. By default datatable will assume that data will be in "%Y-%m-%d" (mysql date format), but you can change it as

webix.i18n.parseFormat = "%m.%d.%Y"
webix.i18n.setLocale();

For more details, see Date formatting methods.

Custom formatting

You can apply custom formatting to a column by presenting the format attribute as a function (function accepts raw value and returns the formatted one).

grid = new webix.ui({
    view:"datatable",
    columns:[
        {id:"title", header:"Film title"},
        {id:"votes", header:"Votes", format:function(value){
            value = some_custom_logic(value);
            return value; }
        }
    ],
    ...
})


Styling DataTable

You can use CSS in conjunction with DataTable content to achieve the desired look-and-feel. This article will help you to cover support of cascading style sheets (CSS) in DataTable.

You can fine-tune the style of:

  1. A whole table;
  2. Columns;
  3. Rows;
  4. Cells;
  5. The header.

A whole table

To apply some style to a whole table you can use the css parameter. As the value of the parameter you must specify the name of the appropriate css class.

Styling the whole table

<style>
    .my_style .webix_hcell{
        background:#009966;
        color:white;
        font-weight:bold;

    }
    .my_style .webix_column{
        font-style:italic;
        background:#ddFFdd;
    }
    .my_style .webix_column > div{
        border-color:#ddd;
    }

</style>

<script>
webix.ui({
    view:"datatable",
    css:"my_style",
    ...
})
</script>

Related sample: Basic styling

Columns

For applying some style to a specific column, you should specify css attribute within columns parameter while configuring the column.

As the value of the attribute you can specify:

  • the name of the appropriate css class;
  • an object containing the css properties.

Styling of a single column

<style>
    .my_style {
        font-weight:bold;
        color:#B51454;
    }

</style>

<script>
webix.ui({
    view:"datatable",
    columns:[
        // a separate css class
        { id:"title", header:"Film title", css:"my_style" },
        // an object with css properties
        { id:"votes", header:"Votes",      css:{"text-align":"right"}}
    ],
...
})
</script>

Related sample: Columns styling

Rows

Generally, to apply some style to a specific row, you may use the $change key of the scheme parameter. The key is a function that runs each time data is changed in the table. As a parameter, the function takes the data item object.

General styling of rows

<style>
    .highlight{
        background-color:#FFAAAA;
    }
</style>

<script>
webix.ui({
    view:"datatable",
    scheme:{
        $change:function(item){
            if (item.year > 1980)
                item.$css = "highlight";
        }
    },
    columns:[
        { id:"title", header:"Film title"},
        { id:"votes", header:"Votes"}
    ],
...
})
</script>

If you specify data directly inside the DataTable constructor, you have one more way to set the desired style for a row:

  • set parameter rowCss to value #css#;
  • use $css attribute inside the data parameter to set the desired style.

We don't recommend to dynamically change attributes with the '$' prefix (e.g. $css, $cellCss). Please, use the addCellCss, addRowCss methods instead.

Setting rows style directly in the dataset

<style>
    .my_style{
        background-color:#FFAAAA;
    }
</style>

<script>
grid = new webix.ui({
    view:"datatable",
    rowCss:"#css#",
    columns:[
        { id:"title",   header:"Film title"},
        { id:"votes",   header:"Votes"}
    ],
    data:[
        { id:1,
        $css:"my_style",
        title:"The Shawshank Redemption",
        votes:678790
        },
        { id:2,
        $css:{ "text-align":"right" },
        title:"The Godfather",
        votes:511495,
        }
    ],
...
});
</script>

Related sample: Rows styling

Applying hover styles

You can specify a custom style for selection of a row when the mouse pointer is over it.

For this purpose, you should define your css style in the hover property.

<style>
    .myhover{
        background: #F0DCB6;
    }
</style>

<script>
grid = webix.ui({
    view:"datatable",
    columns:[
        { id:"title",   header:"Film title",    width:200},
        { id:"year",    header:"Released",      width:80},
        { id:"votes",   header:"Votes",         width:100}
    ],
    hover:"myhover"
    ...
});
</script>

Related sample: Row hover

Cells

Applying cssFormat method

Generally, to apply some style to specific cells in a column, you should use the cssFormat attribute inside the columns parameter. The attribute sets a function that will define how cells of the column must be colored. The function takes the following parameters:

  • cell value (compulsory) - current cell value;
  • row item object - all values for the current row;
  • row id - ID of the row in question;
  • column id - ID of the column in question.

(function).

General styling of cells

function mark_votes(value, config){
    if (value > 400000)
        return { "text-align":"right" };
    return value;
}

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"title",   header:"Film title"},
        { id:"votes",   header:"Votes",   cssFormat:mark_votes }
    ],
    ...
})

Cell styling within configuration

If you specify data directly inside the DataTable constructor, you have one more way to set the desired style for a cell - property $cellCss:

We don't recommend to dynamically change attributes with the '$' prefix (e.g. $css, $cellCss). Please, use the addCellCss, addRowCss methods instead.

Setting cells style directly in the dataset

<style>
    .my_style{
        background-color:#FFAAAA;
    }
</style>

<script>
grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"title",   header:"Film title"},
        { id:"votes",   header:"Votes"}
    ],
    data:[
        { id:1,
          title:"The Shawshank Redemption",
          votes:678790,
          $cellCss:{
              votes:"highlight"
          }
        },
        { id:2,
          title:"The Godfather",
          votes:511495,
          $cellCss:{
              votes:{ "text-align":"right" }
          }
        }
    ],
...
})
</script>

Related sample: Cells styling

The header

To set style for a specific cell of the header you should use the following technique:

General styling of the header

<style>
    .my_style{
        background-color:#FFAAAA;
    }
</style>

<script>
grid = new webix.ui({
        view:"datatable",
        columns:[
            { id:"title",   header:{ text:"Film title", css:{ "background":"#AFA"}} },
            { id:"votes",   header:{ text:"Votes",      css:"my_style"} }
        ]
...
})
</script>

Related sample: Header styling

CSS maps

Table 1 CSS image maps
CSS class | Description
.webix_dtable | container with DataTable
.webix_ss_header | container with the header
.webix_ss_header .webix_hcell | a cell of the header
.webix_ss_header .webix_first | the first cell of the header
.webix_ss_header .webix_last | the last cell of the header
.webix_ss_footer | container with the footer
.webix_ss_footer .webix_hcell | a cell of the footer
.webix_ss_footer .webix_first | the first cell of the footer
.webix_ss_footer .webix_last | the last cell of the footer
.webix_ss_body | container with the table body
.webix_column | a column of the table
.webix_column .webix_last | the last column of the table
.webix_column .webix_first | the first column of the table
.webix_column .webix_cell | a cell of the column


Split Mode or 'Frozen Columns'

Split mode allows to have DataTable separated into two parts: 'frozen' and 'scrolled'.
The frozen part is fixed. It can contain the last columns on the right(left) side or on the both sides at a time.
The scrolled part is movable and can be scrolled horizontally.

To 'froze' columns, you should use parameters leftSplit and rightSplit.

Enabling the 'split' mode

dtable = new webix.ui({
    view:"datatable",
    ...
    leftSplit:2, // 2 columns will be frozen on the left side
    rightSplit:2 // 2 columns will be frozen on the right side
});

Related sample: Frozen columns. Basic implementation


Operations with data

  • Copy-Pasting DataTable Data
  • DataTable Filtering
  • Math Operations
  • Paging with Datatable
  • Selection with Datatable
  • Area Selection in DataTable
  • DataTable Sorting
  • DataTable Editing
  • Checkbox and Radio in DataTable


Copy-Pasting DataTable Data

To enable the possibility to copy/paste DataTable data by the CTRL+C/CTRL+V keyboard shortcuts you should use parameter clipboard.

The parameter can have one of 3 values:

  1. 'block' ( or true. It's the default value);
  2. 'selection';
  3. 'repeat'.

Each of the types has its specificity and define its behavior of copying.

Setting the desired behavior of copying

grid = new webix.ui({
        view:"datatable",
        ...
        clipboard:"selection",
});

Related sample: Copying between grids

'Block' copying

It's the default type and can be also specified by setting the true value.

It's can be characterized as follows:

  • When the copy area is less than the one selected, copied cells are not repeated and fill only the related selected cells.
  • When the copy area is greater than the one selected, copied cells fill not only the selected area but also the related cells nearby.

Related sample: 'block' copying

'Selection' copying
  • When the copy area is less than the one selected, copied cells are not repeated and fill only the related selected cells.
  • When the copy area is greater than the one selected, copied cells fill only the selected area and don't 'touch' the cells nearby.

Related sample: 'selection' copying

'Repeat' copying
  • When the copy area is less than the one selected, copied cells are repeated a specific number of times to fill the selected cells.
  • When the copy area is greater than the one selected, copied cells fill only the selected area and don't 'touch' the cells nearby.

Related sample: 'repeat' copying


DataTable Filtering

The library provides ability to filter data on client-side by one or several criteria using for this built-in or custom-created filters.

Filters in the header

You can define a built-in filter in the header or footer of a column. Webix offers 8 filter types:

  • in a standard free version:
    • textFilter;
    • serverFilter (text-based);
    • serverSelectFilter (select-based);
    • selectFilter;
    • numberFilter;
    • dateFilter;
  • additionally, in the Webix Pro edition:
    • richSelectFilter;
    • multiSelectFilter;
    • datepickerFilter.

All of them are described in detail below.

Built-in filter is set by property content of the header/footer attribute. Note, to add a filter to the header(footer), the header(footer) must be specified as array.

columns:[
    { id:"title", header:[{content:"{filtername}Filter"}, "Title"] }
]

If you need to create a custom filter (or smth) for header content, or you need to redefine the behaviour of an already existing filter, go here for the instructions.

Text filter

Retrieves values that contain mask defined through text field.

{ id:"title",header:[ "Film title",{content:"textFilter"}] }

Related sample: Filtering. Built-in Text Filter, Select Filter

Server Filter

A text filter that works with backend. Retrieves values that contain mask defined through text field and sends a request to server to return filtered dataset.

{ id:"title",   header:["Film title", {content:"serverFilter"}] }

Related sample: Datatable: Serverside Filtering and Sorting

Request parameters include:

  • count - the number of data records to return. Its value depends on dynamic loading parameters, if any;
  • start - ID of the data record to start from (0 - beginning). Its value depends on dynamic loading parameters, if any;
  • filter[column_name] - name of the column (in brackets) for which filtering is performed. Its value is a text value you've entered in the filter input.

If serverside sorting is enabled, data is both filtered and sorted on server.

Select filter

Retrieves values that contain mask defined through a dropdown list of possible values. Based on a standard HTML select input.

{ id:"title", header:["Film title",{content:"selectFilter"}] }

Related sample: Filtering. Built-in Text Filter, Select Filter

Number filter

Text filter used for number columns. Retrieves values which contain mask defined through text field. Allows users to use the following comporison operators in it:

  • '=' - equal to;
  • '>' - greater than;
  • '<' - less than;
  • '<=' - less or equal;
  • '>=' - greater or equal.
{ id:"year", header:[ "Released",{content:"numberFilter"}] }

Related sample: Filtering. Built-in Numeric Filter

Date filter

A text filter used for date columns. Retrieves values that contain mask defined through text field. Allows users to use the following comparison operators in it:

  • '>' - greater than;
  • '<' - less than;
  • '<=' - less or equal;
  • '>=' - greater or equal.

There are 3 ways you can input data to the dateFilter:

  1. 'yyyy' - 4-digits year;
  2. 'mm.yyyy' - 2-digits month and 4-digits year separated by point;
  3. 'dd.mm.yyyy' - 2-digits day, 2-digits month and 4-digits year separated by points
{ id:"year", header:[ "Released",{ content:"dateFilter"}],
    format:webix.i18n.dateFormatStr}

Related sample: Filtering. Built-in Date Filter

Richselect Filter

Available in Webix Pro edition only.

Retrieves values that contain mask defined through a popup list of possible values. Based on Webix richselect control.

{ id:"year", header:["Released", { content:"richSelectFilter" }] }

Related sample: Multi-select filter in the DataTable

Multiselect Filter

Available in Webix Pro edition only.

Retrieves values that contain mask defined through a popup list of possible values while multiple values can be selected at once. Based on Webix multiselect control.

{ id:"year",header:["Released", { content:"multiSelectFilter" }]

Related sample: Multi-select filter in the DataTable

Datepicker Filter

Available in Webix Pro edition only.

Retrieves values that contain mask defined through the popup calendar. Based on Webix datepicker control.

{ id:"date", header:[ "Released", { content:"datepickerFilter" }],
        format:webix.i18n.dateFormatStr}

Related sample: Date filters in the DataTable

Filtering Logic

Note, each time you start to type text in such a filter, DataTable invokes the filterByAll() method. Each time the method is called, all data is re-filtered (previous results aren't preserved).

AND logic

By default, when you specify filters in several columns, DataTable applies AND logic to them, i.e. the table will display just records that meet all criteria at once.

Related sample: Filtering by several criteria (AND logic)

OR logic

In case you want to apply OR logic (to display records that meet at least one of criteria) you should redefine the filterByAll() method. For example, it can look like this:

Implementing OR logic for filters

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:["Film title", {content:"textFilter"}] },
        { id:"year",  header:["Released",  {content:"selectFilter"}] },
        { id:"votes", header:"Votes" }
    ]
});

grid.filterByAll=function(){
//gets filter values
    var title = this.getFilter("title").value;
    var year = this.getFilter("year").value;
//unfilters the table if values were not selected
    if (!title  && !year) return this.filter();
//filters using OR logic
    this.filter(function(obj){
        if (obj.year == year) return true;
        if (obj.title.toLowerCase().indexOf(title)!=-1) return true;
        return false;
    });
};

Related sample: Filtering by several criteria (OR logic)

Custom filtering rules

A filter is a set of filtering rules applied to specific content. When you specify a filter you have the possibility to set additional filtering rules for it. To set additional filtering rule for the filter you must create a custom function implementing those rule and set property compare of the header(footer) attribute to this function.

Custom function specified as a filtering rule takes 2 parameters:

  1. value - a column value (the function checks values by turn);
  2. filter - the entered in the filter value.

For example, to make DataTable filtered just by the start letter of column values, you may specify the filtering rule shown below:

Filtering by the start letter of the column values

function startCompare(value, filter){
    value = value.toString().toLowerCase();
    filter = filter.toString().toLowerCase();
    return value.indexOf(filter) === 0;
}

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"title", header:["Film title",{content:"textFilter", compare:startCompare}]},
        ...
    ]
});

Related sample: Using different filtering rules

Filtering by multiple criteria entered via one input

There is the possibility to filter DataTable by different columns using one input for this.

This can be done by:

  1. Redefining method filterByAll();
  2. Specifying an additional filtering rule.

Filtering by multiple criteria (by using method filterByAll)

grid = new webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"rank",    header:["#", { content:"textFilter", colspan:3}] },
        { id:"title",   header:["Film title",""] },
        { id:"year",    header:["Released",""] },
    ]
});

grid.filterByAll=function(){
//gets filter values
    var text = this.getFilter("rank").value.toString().toLowerCase();
//unfilters for empty search text
    if (!text) return this.filter();

//filters using OR logic
    this.filter(function(obj){
        if (obj.year == text) return true;
        if (obj.title.toLowerCase().indexOf(text)!=-1) return true;
        return false;
    });
};

Related sample: Filtering by multiple criteria entered via one input

Filtering by multiple criteria (by specifying an additional filtering rule)

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"rank",    header:["#", {content:"textFilter", compare:oneForAll, colspan:3}]},
        { id:"title",   header:["Film title",""] },
        { id:"year",    header:["Release year",""]}
    ],
});

function oneForAll(value, filter, obj){
    if (obj.year.toString().toLowerCase().indexOf(filter) !== -1;) return true;
    if (obj.title.toLowerCase().indexOf(text)!=-1) return true;
    return false;
};

Related sample: Custom filtering by multiple criteria entered via one input

HTML inputs as filters for DataTable

Setting an HTML input as datatable filter

Setting a Custom Filter

<input type="text" id='myfilter'> //input

grid = new webix.ui({  //component
    view:"datatable",
    columns:[
        {id:"title", ...}
    ]
});

grid.registerFilter(document.getElementById("myfilter"),
    { columnId:"title" }, //column to filter
    {
        getValue:function(node){
            return node.value;
        },
        setValue:function(node, value){
            node.value = value;
        }
});

Related sample: Filtering by multiple criteria

Custom Filtering with filter() method

In addition, the library gives you method filter() to provide fully custom filtering.

For example, if you add an input and button to the page and want to filter DataTable by clicking on it, you code may look like this:

Implementing a custom filter

<input type="text"><input type="button" value='filter' onclick='filterText(this);'>

<script>
    function filterText(node){
        var text = node.previousSibling.value;
        if (!text) return grid.filter();

        grid.filter(function(obj){  //grid is a dataTable instance
            return obj.year == text;
        })
    }
</script>

Related sample: Filtering via a separate input element

Note, in the DataTable constructor you need to specify no parameters.

Find API

Datatable API allows searching for the needed records easily with the help of its find method.

Unlike filtering, it preserves the records visible but returns an array of rows that match the given criterion for further usage.

For instance, it allows highlighting the filtered data:

//res - array of found rows
var res = table.find(function(obj){
    return obj.title.toLowerCase().indexOf(value) != -1;
});

table.clearCss("marker", true)
for (var i = 0; i < res.length; i++)
    table.addCss(res[i].id, "marker", true);
table.refresh();

Related sample: "Find" API

TreeTable specific configuration

In case of TreeTable some extra configurations can be defined to define how filters will be applied

The filterMode property is an object that can contain 2 attributes:

  • showSubItems - (boolean) defines whether the tree must display childs of the filtered items (true) or the filtered items would be displayed as childs of the root node (false). The default value - true.
  • openParents - (boolean) defines whether the tree will expand branches to show the found items (true) or stay as is (false). The default value - true
  • level - (number) sets the nesting level to filter items from (one-based numbering).

Using the filterMode parameter

webix.ui({
    view:"treetable",
    filterMode:{
        showSubItems:false,
        level:2
    }
});

Related sample: Filtering


Math Operations

DataTable gives you an opportunity to load data stored as mathematical expressions. DataTable parses, evaluates such expressions and presents result in the related cells.

Note that this functionality won't work with the webix.env.strict enabled. By default, the flag is disabled and math is supported.

Common (storing data as formulas)

To start parse data as mathematical expressions - just set parameter math to true (by default, it's disabled).
Columns are specified as usual.

Activating math support and parsing data as math expressions

var budget = [
    ...
    {id:4, name:"France", rev:"1229000", exp:"1445000", dif:"=[:3,:2]-[:3,:3]",
    date:"2009"}
];

grid = new webix.ui({
    view:"datatable",
    container:"box",
    columns:[
        { id:"id",   header:"#"},
        { id:"name", header:"Country"},
        { id:"rev",  header:"Revenue"},
        { id:"exp",  header:"Expenditures"},
        { id:"dif",  header:"Deficit/surplus"},
        { id:"date", header:"Date"}
    ],
    math: true, //this parameter enables math support
    data: budget
})

Related sample: Using formulas

Syntax:

  1. Formula must start from the '=' sign.

  2. Within formulas can be used:

    • basic mathematical operators, which are: +, -, /, *, (, );
    • cell references;
    • custom functions.

You can refer to a cell in 2 ways:

  • [id, field] - takes the value from the specified field of an item with the specified id.
var data = [
    { id:1, num1:"67000", num2:"15000", difference:"=[1,num1]-[1,num2]"},
    { id:2, num1:"56000", num2:"11000", difference:"=[2,num1]-[2,num2]"},
    { id:3, num1:"45300", num2:"10000", difference:"=[3,num1]-[3,num2]"}
];
  • [:row_ind, :col_ind] - the indices of the row and column (zero-based numbering).
var data = [
    { id:1, num1:"67000", num2:"15000", difference:"=[:0,:1]-[:0,:2]"},
    { id:2, num1:"56000", num2:"11000", difference:"=[:1,:1]-[:1,:2]"},
    { id:3, num1:"45300", num2:"10000", difference:"=[:2,:1]-[:2,:2]"}
];

Note that if you use math operations in TreeTable, you can refer to rows only by their IDs, as row indexes are refreshed after each change.

You can also combine 2 variants and use [id, :col_ind] or [:row_ind, field].

var data = [
    { id:1, num1:"67000", num2:"15000", difference:"=[:0,num1]-[:0,num2]"},
    { id:2, num1:"56000", num2:"11000", difference:"=[:1,num1]-[:1,num2]"},
    { id:3, num1:"45300", num2:"10000", difference:"=[:2,num1]-[:2,num2]"}
];

You can call any custom function within a formula in case provided operations are not enough:

function mysum(a, b){ return a+b };
...
{ id:3, difference"=mysum([:0, :1], [:0,:2]) + 1 - [:0, :3]" }

Assigning formulas while columns configuration

To apply some formula to a column you may also use attribute math while column configuring. Any formula that will be set as the value of this attribute will be applied to the entire column.

Specifying formulas while columns configuring

var budget = [
    ...
    { id:4, name:"France ", rev:"1229000", exp:"1445000", date:"2009"}
];
grid = new webix.ui({
    view:"datatable",
    container:"box",
    columns:[
        { id:"id",   header:"#"},
        { id:"name", header:"Country"},
        { id:"rev",  header:"Revenue"},
        { id:"exp",  header:"Expenditures"},
        { id:"dif",  header:"Deficit/surplus", math:"[$r,:2] - [$r,exp]"},
        { id:"date", header:"Date"}
    ],
    math: true, //this parameter enables math support
    data: budget
})

Related sample: Applying formulas to an entire column

Syntax:

  1. Formula is written without the '=' sign.
  2. The $r keyword refers to the current row id.
  3. The $c keyword refers to the name of the current column.

  4. Within formulas can be used:

    • basic mathematical operators, which are: : +, -, /, *, (, ).
    • cell references;
    • custom functions.

You can refer to a cell in 2 ways:

  • [id, field] - takes the value from the specified field of an item with the specified id (see usage examples above).
  • [:row_ind, :col_ind] - the indices of the row and column (zero-based numbering).
    You can also combine 2 variants and use [id, :col_ind] or [:row_ind, field].

You can call any custom function within a formula in case provided operations are not enough:

function mysum(a, b){ return a+b };
...
{ id:"dif", header:"", math:"mysum([$r,:2] - [$r,exp]) + 1 - [$r, :3]" }

Sum counter

To get the total value of some column you can use the summColumn counter (instead of a math formula), created especially for this need.
The counter is added to the footer of a column (can't be used in the header).

columns:[
    { id:"title", header:"Film title"},
    { id:"year",  header:"Year"},
    { id:"votes", header:"Votes", footer:{content:"summColumn"}}
]

Editing Formulas Directly in Datatable

Math formulas are editable directly in the datatable provided that:

  • editMath property is set to true value;
  • datatable is editable itself;
  • the column where math is used features "text" editor;
  • editAction is specified;
view:"datatable",
columns:[
    { id:"diff", header: "Math", math:"[$r,:2] - [$r,exp]", editor:"text"},
],
math: true,
editable:true,
editAction:"click",
editMath:true

When this property is omitted, you can still open the editor for the calculated cell value and see the result of the formula in the editor input. However, changes won't be saved, since math features higher priority.


Paging with Datatable

DataTable supports paging over the items in the data source. You enable and configure paging through the pager parameter.

Paging doesn't depend on the way you load data into DataTable: static or dynamic, external data file or database table. Datatable can display direction controls (that provide forward and backward navigation) as well as numeric controls that allow a user to move to a specific page.

Generally, you should just specify parameter pager with the required attributes.

Basic pager configuration

grid = new webix.ui({
    view:"datatable",
    ...
    pager:{
        container:"paging_here",// the container where the pager controls will be placed into
        size:100, // the number of records per a page
        group:5   // the number of pages in the pager
    }
})

Related sample: Static paging. Loading from an external data file

Pager controls

If you set the pager parameter, DataTable automatically adds controls for page navigation. You can customize those controls by specifying a certain template for them.

The template is set by the template attribute of the pager parameter and can contain the following values:

  1. {common.first()} - the button to move to the first page.
  2. {common.prev()} - the button to move to the previous page.
  3. {common.next()} - the button to move to the next page.
  4. {common.last()} - the button to move to the last page.
  5. {common.pages()} - numeric controls to move to a specific page.

Depending on what you want to display on the paging area, add the related items to your template.

Using templates in pager

grid = new webix.ui({
    view:"datatable",
    ...
    pager:{
        template:"{common.prev()} {common.pages()} {common.next()}",
        container:"paging_here",
        size:10,
        group:5
    }
});

Related sample: Using templates for pagers

Generally, using the mentioned values, you can set the following combinations for DataTable:

  • Numeric (default)
  • Next/Previous
  • Next/Previous/First/Last
  • Numeric/First/Last
  • Numeric/Next/Previous/First/Last

The first combination is set by default. Other available ones can be achieved with the help of templates (see the table below).

Table 1 Pager controls combinations
Mode | Image | Related template
Numeric |  | default mode, doesn't require specifying a separate template
Next/Previous |  | template:" {common.prev()} {common.next()} "
First/Previous/Next/Last |  | template:" {common.first()} {common.prev()} {common.next()} {common.last()}"
Numeric/First/Last |  | template:" {common.prev()} {common.pages()} {common.next()}"
Numeric/Next/Previous/First/Last |  | template:" {common.first()} {common.prev()} {common.pages()} {common.next()} {common.last()}"

Customizing pager labels

You can set some text instead of arrows for the Next, Previous, First and Last buttons.

Specifying custom labels for pager controls

webix.locale.pager = {
    first: "First",// the first button
    last: "Last",// the last button
    next: "Next",// the next button
    prev: "Prev"// the previous button
};

grid = new webix.ui({
    view:"datatable",
    ...
    pager:{
        template:"{common.first()} {common.prev()} {common.pages()}
                {common.next()} {common.last()}",
        container:"paging_here",
        size:10,
        group:5
    }
})

It's not obligatory to redefine all the mentioned buttons at once, you can redefine just a part of them. In this case, webix.locale.pager will contain just the required buttons.

Related sample: Pager localization

The size of a page

The size of a page is a number of items to display at once on a page. This number is set by the size attribute:

Setting the number of records on a page

pager:{
    size:100,  // the number of records on a page
    ...
}

Multiple pagers on a page

Several pagers can be on one and the same page.

To add an additional pager to a page you should call method clone() and set there configuration of your new pager using the same attributes you use while defining the pager parameter:

Specifying 2 pagers on a page

grid = new webix.ui({
    view:"datatable",
    ...
    pager:{..}
});

grid.getPager().clone({
    container:"paging_here",
    size:10,
    group:5
});

Related sample: Defining several pagers on a page


Selection with Datatable

In DataTable you can specify different types of selection depending on your needs.

Available modes are:

  1. cell;
  2. row;
  3. column;
  4. multi cell;
  5. multi row;
  6. multi column;
  7. block selection;
  8. area selection.

Area selection is available in PRO version only

The desired type is set through parameters select, multiselect and blockselect.

The table below shows which combination of parameters you should use for each type.

Table 1 Types of selection
Type of selection Related parameters
single cell
select:"cell"
single row
select:"row"
single column
select:"column"
multiple cells
select: "cell", multiselect: true
multiple rows
select: "row", multiselect: true
multiple columns
select: "column", multiselect: true
visual block selection
select: "cell", multiselect: true, blockselect: true

For example, to set in your DataTable multi row selection, you should use the following code:

Enabling multi row selection

grid = new webix.ui({
    view:"datatable",
    ...
    select:"row",
    multiselect:true
})

Related sample: Multi-row selection

Related methods

Table 2 Selection methods
Method | Description
clearSelection | clears selection
getSelectedId | returns the selected cells
mapSelection | executes some custom method for all cells in the currently selected block
moveSelection | moves selection to the specified direction
select | selects the specified element
selectRange | selects the specified range of elements
unselect | cancels selection of the specified element

Related events

Table 3 Selection events
Event | Description
onAfterSelect | fired after a cell is selected
onAfterUnSelect | fired after a cell is unselected
onBeforeSelect | fired before a cell is selected
onBeforeUnSelect | fired before a cell is unselected
onSelectChange | fired when selection is changed in DataTable


Available only in PRO Edition

Area Selection in DataTable

Webix DataTable features Excel-like area selection. You can click on any cell in the DataTable and move the mouse pointer over the grid, a block of cells will be selected and colored in grey.

When you release the mouse pointer, the selection will remain and marked with bold border with a handle, like this:

To enable area selection in DataTable, you should specify the areaselect property with the true value in the datatable configuration.

{
    view:"datatable",
    id: "table",
    columns:[
        { id:"rank",    header:"", css:"rank",  width:50},
        { id:"title",   header:"Film title",    width:200},
        { id:"year",    header:"Released",      width:80},
        { id:"votes",   header:"Votes",         width:120},
        { id:"rating",  header:"Rating",        width:80},
    ],
    areaselect:true,            data:small_film_set
}

Area selection will work only with other selection types disabled. So, the select and selectcell properties shouldn't be enabled.

Related sample: Area Selection

Custom Select Area

Adding Custom Select Area

You can apply custom area selection in the DataTable.

For this purpose, you need to use the addSelectArea method. This method allows creating a custom select area.

$$("dtable").addSelectArea(start,end,preserve);

The parameters are:

  • start - (object) the id object of the left top cell, contains two parameters: the row id and the column id
  • end - (object) the id object of the right cell, contains two parameters: the row id and the column id
  • preserve - (boolean) defines, if the previous select area should be saved, false by default
  • area_name - (string) optional, the name used to address to an area to change or to delete it; by default it's generated by the uid() method
  • css - (string) optional, the css style (classname) for the border of an area. By default, the border of area selection is black
  • handle - (boolean) optional, enables/disables a handle for selection area resize (enabled by default)

The first three parameters are mandatory, all others are optional.

Removing Select Area

You can easily remove an unnecessary select area by using the removeSelectArea method.

$$("dtable").removeSelectArea();

To remove some particular select area, you need to pass its name as a parameter of the removeSelectArea(). If the name isn't passed to the method, it will remove the last unnamed select area.

Getting Select Area

To get a select area, you should make use of the getSelectArea method. The method returns the object of the select area.

var area = $$("dtable").getSelectArea();

The object of a certain select area can be received by passing the name of the area as a parameter. Without parameters, the method returns the object of the last select area.

The returned object will contain the mandatory parameters: start, end and preserve. It can also include the optional parameters: area_name, css and handle. The details on the parameters are given here.

Multiple Area Selection

Several areas can be selected in the DataTable at once. The image below illustrates this feature:

To enable multiple selection, you need to define the multiselect property with the true value in the Datatable configuration:

{
    view:"datatable",
    id: "table",
    columns:[
        { id:"rank",    header:"", css:"rank",  width:50},
        { id:"title",   header:"Film title",    width:200},
        { id:"year",    header:"Released",      width:80},
        { id:"votes",   header:"Votes",         width:120},
        { id:"rating",  header:"Rating",        width:80},
    ],
    areaselect:true,
    multiselect:true,                           data:small_film_set
}

While having several select areas in the datatable, you can get all of them at once. For this purpose, apply the getAllSelectAreas method:

var areas = $$("dtable").getAllSelectAreas();

The method returns an object that contains configuration objects of all select areas in the datatable. The parameters of area objects are described above.

Related sample: Area Selection


DataTable Sorting

DataTable allows you to sort data rows on the client side. There are 2 ways to invoke sorting in the table:

  1. By a single click on the header of a column with the enabled sort attribute;
  2. By api call ( can be called from some event or action, i.e button click or page load ) of the sort() method.

Sorting by a click on the header

When you click on the header, DataTable starts to display a special control indicating which column the table is currently sorted by and the direction of this sorting (ascending or descending). Each next click on the same header will reverse the sorting direction.

Columns can have different type of content (numbers, strings, dates) and each type of content requires its specific way of sorting.

Sorting Modes for Different Data Types

For this purpose, DataTable provides 4 sorting types to ensure correct sorting of columns:

  1. int;
  2. date;
  3. string;
  4. string_strict (case-sensitive 'string').

To enable sorting and assign the appropriate sorting type to a column, you should specify an attribute sort among the column's parameters and set it to some of types.

Sorting configuration

grid = new webix.ui({
        view:"datatable",
        ...
        columns:[
            { id:"title", header:"Film title",    sort:"string"},
            { id:"year",  header:"Release year", sort:"int"}
        ]
});

Related sample: Sorting. Using built-in means

The above mentioned sorting modes work with column values defined by their ID attributes and ignore values either defined by column templates or provided by column options.

In the sample column below column titles are sorted, yet categories are displayed (column template overrides column ID during rendering):

{ id:"title",   template:"#cat_id#", header:"Category ID" }

In the sample column below option IDs are sorted, yet option values are displayed:

{ id:"cat_id",  header:"Category", collection:[
    { id:1, value:"Crime"}, { id:2, value:"Thriller" }]
}

Sorting by visible text

Sorting by visible text is enabled width the help of "text" sorting mode that switches on string comparison for the values actually displayed in datatable columns.

It takes into account column values defined by templates and collection values rather than IDs:

columns:[
    { id:"title",template:"#cat_id#", header:"Category ID", sort:"text" },
    { id:"cat_id",  header:"Category",sort:"text", collection:[
        { id:1, value:"Crime"}, { id:2, value:"Thriller" }]
    }
]

Related sample: Sorting. Using built-in means

Triggering Server-side Sorting on Client-side

It's possible to issue a request to server to sort data in backend and reload the sorted dataset to the datatable:

The option is enabled by server sorting mode:

view:"datatable",
columns:[
    { id:"package", header:"Name", sort:"server"},
    {..}
],
url:"data.php"

Related sample: Datatable: Serverside Filtering and Sorting

Now, header clicking will trigger a serverside GET request with the following parameter: sort[package]=desc (data.php?sort[package]=desc), which allows sending:

  • operation name (sort);
  • data property to sort by (here: package);
  • sorting order (here: desc).

The new data will be loaded to the datatable and replace the initial dataset.

If serverFilter is enabled for this column, the data will be both filtered and sorted on serverside before returning to client.

Custom sorting functions

If you want to apply custom sorting behaviour, you can define the related logic in a function and set this function as the value of attribute sort.

This function will be called for each pair of adjacent values and return 1,-1 or 0:

  • 1 - an object with the first value in pair must go before the second one;
  • -1 - the second object goes before the first one;
  • 0 - the order of both objects doesn't change.

The function can be defined in a general way:

Using custom functions for sorting DataTable

function sortById(a,b){
        a = a.rank;
        b = b.rank;
        return a>b?1:(a<b?-1:0);
}

webix.ui({
        view:"datatable",
        ...
        columns:[
            { id:"title",   header:"Film title", sort:sortByParam },
            ...
        ]
})

Related sample: Sorting Datatable. Using custom sorting functions

Programmatic sorting

You should use method sort() to invoke sorting on some event or action, i.e button click or page load. You can't use this method if you want to sort DataTable by a click on the header.

Sorting DataTable on the button click

<input type='button' onclick='grid.sort("#title#", "asc", "string");'>

<script type="text/javascript" charset="utf-8">
        grid = webix.ui({ view:'datatable', ...})
</script>

Related sample: Sorting Datatable. Using sorting methods

Controlling header sorting mark

You can show and hide the sorting sign (^/V) by calling the markSorting() method with the following parameters:

  • column_id - id of the column you want to draw a sorting sign for;
  • dir - sorting direction.

When used with no arguments, the method removed all the sorting signs from the datatable headers.

Cancelling sorting

grid = webix.ui({ view:"datatable", ...})

grid.markSorting("title", "asc");

Related sample: Sorting Datatable. Using sorting methods


DataTable Editing

DataTable is an editable component, i.e. users have the possibility to edit it manually.

Generally, to make the table editable you should set parameter editable to true.

Making DataTable editable

dtable = new webix.ui({
  view: "datatable",
  ...
  editable:true
});

Related sample: Basic use of editors

2 main points related to editing are:

  1. The types of available editors.
  2. The action on which the cell(s) editor(s) will be opened.

Editors

The library provides 12 predefined editors:

  • text, inline-text, password;
  • checkbox, inline-checkbox;
  • select, combo, richselect;
  • multiselect (Webix Pro edition only);
  • date;
  • color;
  • popup.

All of them are described in detail in the corresponding article.

To assign the needed editor type to a column, you should specify attribute editor of the columns parameter and set it to some of types.

Specifying the editor for a column

columns: [
  { id:"title", header:"Film title", editor:"text"}
]

Related sample: Basic use of editors

Creating a custom editor

To create a custom editor, you should set the following methods to it:

  • focus() - sets the focus to the input with the editor.
  • getValue() - gets the value of the editor.
  • setValue() - sets the value of the editor.
  • render() - renders the editor.

webix.editors = {
  "myeditor": {
    focus: function () {...}
    getValue: function () {...},
    setValue: function (value) {...},
    render: function () {...}
  }
};

The functions are defines with the help of the following inner properties:

  • this.node - HTML tag of the editor. Appears after render() execution;
  • this.value - the initial value of an input. Appears after setValue(); execution;
  • this.config - editor configuration;
  • this.popup - popup ID (is used for editors with popup windows)

After your editor is in the collection, you can set it for a column using the familiar technique:

Adding a new editor and setting it for the column

webix.ui({
  view: "datatable",
  columns: [
    ...
    { id: "title", header: "Film title", editor: "myeditor"}
  ]
});

Find more info on Data Editors in the dedicated chapter of the manual.

Setting the action to open editors on

Generally, to set the action on which editors will be opened you should use the editaction property.

Default actions

By default, editors are opened on a single click. To make opening editors occurred on a double click, you should set editaction to dblclick as in:

Opening editors on a double click

webix.ui({
  view: "datatable",
  editable: true,
  editaction: "dblclick"
  ...
});

Custom actions

Using some other action/keyboard key for opening requires some more treat cause you should provide all 'open-edit-close' logic by yourself.

To open editors on some keyboard key press you should do the following:

  • set the editaction property to value 'custom'.
  • use the UIManager mixin (method addHotKey ) to add a hot key and define the processing logic.

Opening editors on the Enter key press

var mytable = new webix.ui({
  view: "datatable",
  ...
  editable: true,
  editaction: "custom"
});

webix.UIManager.addHotKey("enter", function(view){
    var pos = view.getSelectedId();
    view.edit(pos);
}, mytable);

Related sample: Basic use of editors

To open editors on some action you should do the following:

  • set the editaction property to value 'custom'.
  • specify the action (through the related event) and define the processing logic (in the event handler function). You can do this with the help of the on parameter or the attachEvent method.

Opening editors on cell selecting

var mytable = new webix.ui({
  view: "datatable",
  ...
  editable:true,
  editaction: "custom",
  select: "cell",
  on:{
    onAfterSelect: function (data,prevent) {
      this.editCell(data.row, data.column);
    }
  }
})

Use case: editing the entire row, column

To open for editing all cells of the specified row/column make the following:

  1. Set the editaction property to value 'custom'.
  2. Use the on parameter to specify the action and define the processing logic:
    • as an event to handle - onItemClick.
    • editRow, editColumn enables the edit mode for the specified row/column (opens all editors)

Opening editors in all cells of the row, column

//editing the entire row
var table1 = new webix.ui({
  view: "datatable",
  ...
  editable: true,
  editaction: "custom",
  on: {
    onItemClick: function (id) {
      this.editRow(id);
    }
  }
});

//editing the entire column
var table2 = new webix.ui({
  view:"datatable",
  ...
  editable: true,
  editaction: "custom",
  on: {
    onItemClick: function(id){
      this.editColumn(id);
    }
  }
})

Related sample: Opening multiple editors

Apart from row and column editing, datatable API offers the possibilities to

  • programmatically open editor in the next cell of the row (provided that it is editable) - editNext() method;
  • move focus to the active editor (if any) - focusEditor() method;
  • close the editor without saving changes - editCancel() method;
  • close the editor while saving changes - editStop() method.

Editing via a Bind Form

Webix components including datatable can be bound to another component to ensure synchronous changing of their data. For instance, a simple function can be used to bind a form to a grid, which allows to edit datatable data:

  • clicking the datatable row will trigger form filling;
  • then you edit data in the form;
  • form saving will send changed data back to the grid.
$$('form1').bind('datatable1');

Related sample: Editors. Bind Form

Note that name attributes of form fields coincide with ids of datatable columns.

More info about data binding.

The Tab key navigation

By default, the Tab(Tab+Shift) key(s) allows navigating within editors defined in the table.

Main points:

  • The Tab key press closes the current editor and opens the next one. If the current editor is last in a row, the next one will be opened in the next row (from the beginning).
  • The Tab+Shift keys press closes the current editor and opens the previous one. If the current editor is first in a row, the next one will be opened in the previous row (from the end).
  • If a cell doesn't have the editor specified, it won't be included to navigation.
  • The opened editor always resides in the visible area. It means that if you click Tab and the cell is out of the visible area then the table will be scrolled to show it ( regardless of the mode set).
  • When multiple editors are opened in the table at the same time, Tab/Tab+Shift navigates within the opened editors.

Related sample: Tab navigation and scrolling

Related sample: Opening multiple editors


Checkbox and Radio in DataTable

DataTable allows you to add any HTML elements inside of it (using the template attribute of the columns parameter).
Besides, the library provides ready-to-use solutions for popular checkbox and radio controls to save your time.

The controls are specified through the same template attribute of the columns parameter.

webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"ch1", header:"", template:"{common.checkbox()}"},
        { id:"ra1", header:"", template:"{common.radio()}"}
    ]
});

checkbox

A standard checkbox.

To define a checkbox column, set the template attribute to "{common.checkbox()}":

Creating a checkbox column

columns:[
        { id:"ch1", header:"", template:"{common.checkbox()}"}
        ...
]

Related sample: Checkbox and radio in DataTable

radio

A radio button.

To define a radio column, set the template attribute to "{common.radio()}":

Creating a radio column

columns:[
        { id:"ch1", header:"", template:"{common.radio()}"}
        ...
]

Related sample: Using 'inline' editors

Custom checkbox

Shortly,a technique of creating a custom checkbox is the following:

  1. Create a function defining a new checkbox.
  2. Set it as the value of the template attribute.
  3. Set the checkboxRefresh parameter to true to force the table getting refreshed after each change of the checkbox value.

Take a look at the image below and learn how to create the checkboxes displayed in the first column.

1. Create a function that will define your custom checkbox.

The function will accept 3 parameters and be called for each data item:

  • obj - (object) the data item object
  • common - (object) the predefined checkbox template
  • value - (boolean) the value of the checkbox. true, if the box is checked. Otherwise, false. Initially, the parameter is null and take the boolean value just when you check the checkbox.

Please, pay your attention at a very important thing - the 'webix_table_checkbox' css class.
This very class forces a standard DIV to behave as a checkbox. Therefore, defining a look of your checkbox don't forget to apply the 'webix_table_checkbox' css class to it.

Function defining a custom checkbox

function custom_checkbox(obj, common, value){
    if (value)
        return "<div class='webix_table_checkbox checked'> YES </div>";
    else
        return "<div class='webix_table_checkbox notchecked'> NO </div>";
};
<style type="text/css">
    .checked{
        color:green;
        font-weight: bold; cursor:pointer;
    }
    .notchecked{
        color:red;
        font-weight:bold; cursor: pointer;
    }
</style>

2. Set the 'template' attribute of the related column to the name of the function.

Once you do this, the column will display data returned by the function defined above.

Setting custom template for the column

columns:[
        { id:"ch1",     header:"",  template:custom_checkbox}
        ...
]

3. Specify the 'checkboxRefresh' parameter and set it to true.

The checkboxRefresh parameter answers for repainting the related data record. When it set to true, each time the checkbox value is changed DataTable will repaint the related record.

Making DataTable getting refreshed after each change of the checkbox value

webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"ch1",     header:"",  template:custom_checkbox},
        ...
    ],
    checkboxRefresh:true
});

Related sample: Custom radio and checkbox in DataTable

Custom radio

Shortly,a technique of creating a custom radio is the following:

  1. Create a function defining a new radio.
  2. Set it as the value of the template attribute.

Take a look at the image below and learn how to create the radio buttons displayed in the first column.

1. Create a function that will define your custom radio.

The function will take 3 parameters and be called for each data item:

  • obj - (object) the data item object
  • common - (object) the predefined radio template
  • value - (boolean) the value of the radio. true, if the radio is checked. Otherwise, false. Initially, the parameter is null and take the boolean value just when you check the radio.

Please, pay your attention to a very important thing - the 'webix_table_radio' css class.
This very class forces a standard DIV to behave as a radio. Therefore, defining a look of your radio don't forget to apply the 'webix_table_radio' css class to it.

Function defining a custom radio

function custom_radio(obj, common, value){
    if (value)
        return "<div class='webix_table_radio checked'></div>";
    else
        return "<div class='webix_table_radio notchecked'></div>";
};
<style type="text/css">
    .checked{
        background:green;
        width:16px; height:16px; margin-top:3px;
    }
    .notchecked{
        background:orange;
        width:16px; height:16px; margin-top:3px;
    }
</style>

2. Set the 'template' attribute of the related column to the name of the function.

As you specify the template attribute in such a way, the column will display data returned by the function defined above.

Setting custom template for the column

webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"ch1",     header:"",  template:custom_radio},
        ...
    ]
});

Related sample: Custom radio and checkbox in DataTable


Integration

In this chapter you will see how to integrate DataTable with jQuery.

jQuery integration

DataTable can be easy integrated with jQuery.

We want to show you 2 most 'interesting' situations of such integration:

  1. Initializing of a standard DataTable;
  2. Creating DataTable from an HTML table.

Initializing jQuery DataTable

A standard DataTable using jQuery can be initialized as follows:

Integration with jQuery

<div id="box" class="cont"></div>
...

$(".cont").webix_datatable({
    columns:[{...}],
    select:"cell",
    data:some_data
});

Related sample: Integration with jQuery

Creating DataTable from an HTML table

To turn an HTML table into DataTable you should call method datatable() for it:

Creating DataTable from an HTML table

<table>
        <tr>
            <td width="40">id</td>
            ...
        </tr>
        ...
</table>

<script>
$("table").webix_datatable();
</script>

Related sample: Integration with jQuery. Turning HTML Table into DataTable


Keyboard navigation

We can single out 2 types of navigation in DataTable:

  1. Navigating the selection
  2. Navigating the active editor

When one of the types is available, the other is blocked, i.e. when you open some cell editor you won't navigate the selection any more but can navigate the active editor within cells available for editing. Once no editors is open, you can again navigate the selected cell (row, column).

Selection navigation

Initially, the selection navigation is disabled in DataTable.

To activate it, set the navigation parameter to true.

Activating the selection keyboard navigation in DataTable

webix.ui({
    view:"datatable",
    navigation:true,
    ...
})
Table 1 Keyboard commands for navigating the selection
Command | Description
Up arrow key | moves one cell (row) to the up
Down arrow key | moves one cell (row) to the down
Left arrow key | moves one cell (column) to the left
Right arrow key | moves one cell (column) to the right
Home | moves to the top left cell(row, column) in the grid
End | moves to the bottom right cell(row, column) in the grid
PGUP | scrolls the table up
PGDN | scrolls the table down

Related sample: Navigation in DataTable

Active editor navigation

Active editor navigation is navigating within cells available for editing: closing the currently active editor and opening the editor in the next/previous cell.

The navigation is activated once you enable editing in the table.

dtable = new webix.ui({
        view:"datatable",
        ...
        editable:true
});
Table 2 Keyboard commands for navigating the active editor
Command | Description
Tab | closes the current editor and opens the next one
Tab + Shift | closes the current editor and opens the previous one

You can read more about editing and active editor navigation in article DataTable Editing.

Related sample: The Tab key navigation


Drag-and-drop with Datatable

The library supports drag-and-drop within a table or several tables on the page.

Moving rows

To enable the drag-and-drop support for rows, set the drag parameter to true.

Enabling the drag-and-drop support for rows

webix.ui({
        view:"datatable",
        ...
        drag:true
});

To drag/drop rows between several tables you should enable the drag parameter in each of them.

Related sample: Drag-and-Drop between tables in DataTable

The 'order' mode

There is a special drag-and-drop mode - 'order'.

In such a mode, rows can't be dragged out of the table boundaries. Also, while dragging an item the remaining items are automatically rearranged so that when you drop the item to the final destination the remaining items won't need to do any rearrangements.

To enable the d-n-d support and activate the 'order' mode, just set the drag parameter to order.

Activating the 'order' mode for rows

webix.ui({
        view:"datatable",
        ...
        drag:'order'
});

Related sample: The 'order' mode for rows

Moving columns

To enable the drag-and-drop support for columns, set the dragColumn parameter to true.

Enabling the drag-and-drop support for columns

webix.ui({
    view:"datatable",
    ...
    dragColumn:true
});

To drag/drop columns between several tables you should enable the dragColumn parameter in each of them.

Related sample: Drag-and-Drop support for columns

The 'order' mode

There is the 'order' mode for the table columns.

In that mode, columns can't be dragged out of the table boundaries. Also, while dragging a column the remaining columns are automatically rearranged so that when you drop the column to the final destination the remaining columns won't need to do any rearrangements.

To enable the d-n-d support and activate the 'order' mode for columns, just set the dragColumn parameter to order.

Activating the 'order' mode for columns

webix.ui({
    view:"datatable",
    ...
    dragColumn:'order'
});

Related sample: The 'order' mode for columns

Advanced

Information stated in the Common part is enough in most cases. The current part should be used just if you want to customize existing drag-and-drop behaviour.

The part covers the following topics:

  • Custom text of the dragging items;
  • Denying dragging of specific items;
  • Denying dropping to specific positions;
  • Switching between 'move' and 'copy' behaviors;
  • Limiting the draggable area to a certain element;
  • Auto scrolling during drag-n-drop.
  • Related events.

Custom text of the dragging items

To redefine the text displaying for the dragging item(s), you should use the onBeforeDrag event.
The desired template is set through the context.html property. You can use any HTML specifying the value for the property.

Displaying the number of the dragging items

dtable.attachEvent("onBeforeDrag", function(context, ev){
    context.html = context.source.length+" item(s)";
});

Some more use cases:

  • A fixed image and the id of the dragged row:

Displaying the dragged row id and some image

dtable.attachEvent("onBeforeDrag", function(context, ev){
    context.html = "<img src='some.gif'></img> " + context.start;
});
  • The text of the dragged items (in case of multiselect selection):

Displaying the title property of dragged items

dtable.attachEvent("onBeforeDrag", function(context, ev){
    context.html = "";
    for (var i=0; i< context.source.length; i++){
        context.html += context.from.getItem(context.source[i]).title + "<br>" ;
    }
});

Related sample: Using events for customizing dnd

Denying dragging of specific items

To deny dragging of specific items you can use the onBeforeDrag event.

Denying dragging even items

dtable.attachEvent("onBeforeDrag", function(context, ev){
    if(dtable.getIndexById(context.start)%2==0){
        return false;      //denies dragging if the item index is even
    }
    return true;           //allows dragging in any other case
});

From now on, each time d-n-d is started, the item index will be checked, and the row can be dragged only if its index isn't even.

You can use the addCss method to mark items and hasCss to check whether an item has a certain marking.

Denying dropping to specific positions

To deny dropping to some positions, you can use the onBeforeDrop event and return false each time you want to block the operation.

Let's assume you specify a table on the page as below and want to deny dropping to the position of an item with 'id=2':

Denying dropping to a specific position

var dtable = new webix.ui({
    view:"datatable",
    ...
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994},
        { id:2, title:"The Godfather",            year:1972},
        { id:3, title:"The Godfather: Part II",   year:1974}
    ]
});
dtable.data.addMark(2,"type", false,"b"); // adds a flag (type='b') to an item with id=2

dtable.attachEvent("onBeforeDrop", function(context, ev){
//if an item has flag type='b', denies dropping to the position of this item
        if(dtable.data.getMark(context.target,"type")=='b') return false;
        return true;
});

Switching between 'move' and 'copy' behaviors

By default, rows are moved (not copied) while d-n-d.

To set the 'copy' behaviour, use the onBeforeDrop event. Specify inside the copy logic and return false to prevent drag-and-drop processing:

Setting the 'copy' behaviour for d-n-d

dtable.attachEvent("onBeforeDrop", function(context, ev){
    for (var i=0; i< context.source.length; i++){
        context.from.copy(context.source[i],context.start,this,webix.uid());
    }
    return false;
});

Related sample: Using events for customizing dnd

Limiting the draggable area to the specified element

You can provide a behaviour when the user could drag items only by the certain specified areas.

To achieve such a behaviour, just follow this plan:

  • Specify an element you want an item to be dragged by.
  • Set this element as the target object for the onBeforeDrop event (the target object is an object on which the event will occur).
.webix_drag_handle{
    background-image:url(./handle.png);
    background-repeat: no-repeat;
}

var dtable = new webix.ui({
    view:"datatable",
    //...
    columns:[
        { id:"rank",    header:"", css:"rank" },
        { id:"title",   header:"Film title" },
        { id:"year",    header:"Released"},
        { id:"drag",    header:"", template:"<div class='webix_drag_handle'></div>" }
    ],
    on:{
        onBeforeDrag:function(data, e){
                return (e.target||e.srcElement).className == "webix_drag_handle";
        }
    }
});

Related sample: Limiting the draggable area for items (dragging rows)
Related sample: Limiting the draggable area for items (dragging columns)

Scrolling during Drag And Drop

By default datatable will scroll self automatically when drag is near the top or bottom border. This behavior can be disabled by using dragScroll configuration property

webix.ui({
    view:"datatable",
    dragScroll:false
});

By default drag scroll works only for vertical scroll, you can enable it for both x and y directions by using

webix.ui({
    view:"datatable",
    dragScroll:"xy"
});

Related events

The following events are generated during the d-n-d process:

  • onBeforeDrag - fires before the mouse button is pressed and moved over a draggable item
  • onBeforeDragIn - fires before a dragged element is moved over the droppable area
  • onDragOut - fires when a dragged element is moved outside of the droppable area
  • onBeforeDrop - fires before a dragged element is released over the droppable area
  • onAfterDrop - fires after drag-n-drop was finished

In the default scenario there is no need to use any of the mentioned events, because DataTable will process all the operations on its own. But sometimes default behavior needs customizing - this is the time when the mentioned events can be used.


Data Export

This section is intended for the export functionality added in version 3.0. For the details on the previously used functionality, see the article Data Export to PDF and Excel.

  • Export to PNG
  • Export to Excel
  • Export to PDF


Export to PNG

To export data from datatable or treetable into a PNG file, you need to call the toPNG() method. The method takes the following parameters:

  • id - (string) the id of the exported view
  • name - (string) optional, the name of the created png file

For example, if you want to export a datatable to a PNG file, you need to initialize a datatable:

{
    view:"datatable",
    id: "myDataTable",
    // datatable configuration
    ...
}

and then call the toPNG() method with the datatable id as its parameter:

webix.toPNG($$("myDataTable"));

Related sample: Export to PNG


Export to Excel

To export data from datatable/treetable into an Excel document, you need to call the toExcel() method.
The method takes 2 parameters:

  • id - (string, object) the exported view or its id
  • options - (object) optional, a set of configuration options that define what data will be displayed in the Excel file

For example, to export a datatable to an Excel document, you need to start with the view initialization:

{
    view:"datatable",
    id: "myDatatable",
    // datatable configuration
    ...
}

And then the call of the toExcel() method should follow.

webix.toExcel($$("myDataTable"));

Related sample: Export to Excel

Customizing Export

The toExcel() method returns all data specified in the columns parameter of the datatable view. However, you may need to get data from other fields as well as restrict the number of fields in the export file. You can set the necessary fields in the columns property of the toExcel() method.

All in all, export API allows:

  • setting columns you'd like to see in the export file.
webix.toExcel($$("myDataTable"), {
    columns:{
        "rank":true,
        "title":true
    }
});
  • defining custom parameters, such as header, width or template for data in the specified column:
webix.toExcel($$("myDataTable"), {
    columns:{
        "title":{header: "Title", width: 200, template: webix.template("#id#.#name#")},
        "year":{header: "Year", width: 100}
    }
});

The column will be rendered with the stated additional properties, which may differ from the component's parameters.

  • including extra fields into export by forming them right within the export function:
webix.toExcel(datatable, {
    columns:{
        Custom1:{
            template:function(obj){
                return "Year " + obj.year;
            },
            width:50,
            header:"Year"
        },
        //other columns
        title:true
    }
});

"Custom1" (any name can be used) receives data from the year field even if it is not seen in this datatable but is presented in its dataset. The field is rendered with width, template and header that will be the header of the corresponding column in the export table.


Export to PDF

To export data from datatable/treetable into a PDF file, you need to call the toPDF method. The method takes the next parameters:

  • id - (string, object) id or object of the exported view
  • name - (string) optional, name of an exported png file

For example, if you want to export a list to a PDF file, you need to call the toPDF() method with the list id as a parameter:

{
    view:"datatable",
    id: "myDatatable",
    // datatable configuration
    ...
}

And then the call of the toPDF() method should follow.

webix.toPDF($$("myDataTable"));

Related sample: DataTable Export to PDF

Customizing Export to PDF

The toPDF() method returns all data specified in the columns parameter of the datatable view. However, you may need to get data from other fields as well as restrict the number of fields in the export file. You can set the necessary fields in the columns property of the toPDF() method.

Export API allows

  • setting columns you'd like to see in the export file
webix.toPDF($$("myDataTable"), {
    columns:{
        "rank":true,
        "title":true
    }
});
  • defining custom parameters, such as header, width or template for data in the specified column:
webix.toPDF($$("myDataTable"), {
  columns:{
    title:{ header: "My title", width: 200, template: webix.template("#id#.#title#")},
    year:{ header:"Year", width:150}
  }
});

The column will be rendered with the stated additional properties, which may differ from the component's parameters.

  • including extra fields into export by forming them right within the export function:
webix.toPDF(datatable, {
    columns:{
        Custom1:{
            template:function(obj){
                return "Year " + obj.year;
            },
            width:50,
            header:"Year"
        },
        //other columns
        title:true
    }
});

"Custom1" (any name can be used) receives data from the year field even if it is not seen in this component but is presented in its dataset. The field is rendered with width and template as well as header that will be the header of the corresponding column in the resulting table.

  • specifying the autowidth parameter to define the columns' width automatically. By default, the paper size of a PDF document is A4. If you set the autowidth property to true, columns will be able to have any possible width that will define the width of a PDF page
webix.toPDF($$("myDataTable"), {
    autowidth:true
});
  • setting the orientation parameter which defines the PDF page orientation: portrait (default) or landscape
webix.toPDF($$("myDataTable"), {
    orientation:"landscape"
});
  • specifying the docHeader and docHeaderImage parameters to display some text or image in the header of the export file
// setting a custom text in the header of the PDF file
webix.toPDF($$("myDataTable"), {
    docHeader:"This document was made with Webix library. http://webix.com"
});

// setting a custom image in the header of the PDF file
webix.toPDF($$("myDataTable"), {
    docHeaderImage:"../common/logo.jpg",
});

Related sample: DataTable Export to PDF: Custom configuration

Styling the exported data

You can tune the appearance of elements in the exported PDF document.

Configuring the document's header

To configure the header of the exported PDF document, you can set a configuration object as a value of the docHeader property. Inside this object beside the text string specify all the needed properties, e.g. define the text alignment and color.

An example config may look as:

webix.toPDF($$("myDataTable"), {
    docHeader:{
        text: "Datatable with custom styling",
        textAlign:"center",
        color:0x663399
    }
});

Pay attention that the color should be set in hex format starting from the 0x prefix.

There are many other possible properties of the config object. You can look all them up in the corresponding documentation (follow the "document/headeropts" section).

Configuring the header image

The export API allows you not only to set the link to the image, but also to specify an object with the necessary configuration properties of the image:

webix.toPDF($$("myDataTable"), {
    docHeaderImage:{
        url:"link",
        align:"left", // "right"/"center"
        width:300,
        height:20
    }
});

Thus, you can configure the image's alignment, as well as its width and the height. More options are enumerated in the specific documentation (see the "document/imageimg-opts" section).

Configuring the document's table

It's also quite easy to configure the look of the resulting table with data. You can manage the appearance of the following component's elements to get the desired result:

  • the table's header, e.g. set text alignment, the font size, the background color and the color of the text:
webix.toPDF($$("myDataTable"), {
    header:{
        textAlign:"center",
        fontSize:13,
        backgroundColor:0x3498DB,
        color:0xFFFFFF
    }
});
  • the table itself, e.g. align the text in it:
webix.toPDF($$("myDataTable"), {
    table:{
        textAlign:"center"
    }
});
  • the table's footer, e.g. by specifying the font size, its height and text alignment:
webix.toPDF($$("myDataTable"), {
    footer:{
        fontSize:9,
        height:20,
        textAlign:"right"
    }
});

More possible configuration properties are described in the corresponding documentation (follow the "document/tableopts" section)

Related sample: DataTable Export to PDF: extended configuration


Data Export to PDF and Excel

This is an outdated article about export of Datatable to PDF and Excel. This functionality will be deprecated starting from the version 3.2. To get the actual information on Datatable export, read the article Data Export.

Datatable and Treetable data can be exported to the following formats:

  1. PDF;
  2. Excel.

The components don't require any special configuration to be exported.

For the treetable it is possible to add indentations for tree nodes:

// "value" column will be indented in the exported file
view:"treetable",
columns:[
    { id:"id"},
    { id:"value", exportAsTree:true },
    { id:"chapter"}
]

Related sample: Export to PDF, Excel

After that all you need is to apply an appropriate export method to this datatable or treetable.

Export to PDF

To export data from datatable or treetable into a PDF document you need to call exportToPDF(). For example, if you add a button by clicking on which the grid will start exporting, then its code will look like this:

<input type="button" value="Get as PDF" style='width:400px;margin:25px;'
onclick="grid.exportToPDF();">

Above solution uses online data export service, but you can configure a local copy as well - you can download and install the Export package. It must be unpacked inside the root of your web server.

The latest packages for installation can be found here:

  • PHP package
  • Java package
  • ASP .NET package

The code will look like this:

grid.exportToPDF("generate.php"); //provide the correct relative path

Related sample: DataTable to PDF: server processing

Export to Excel

To export data from datatable/treetable into an Excel document you need to call exportToExcel(). For example, if you add a button by clicking on which the grid will start exporting, then its code will look like this:

<input type="button" value="Get as PDF" style='width:400px;margin:25px;'
onclick="grid.exportToExcel();">

Above solution uses online data export service, but you can configure a local copy as well - you can download and install the Export package. It must be unpacked inside the root of your web server.

  • PHP package
  • Java package
  • ASP .NET package

The code will look like this:

grid.exportToExcel("generate.php"); //provide correct relative path

Related sample: Export to Excel: server processing

Customizing Export

Both exportToPDF and exportToExcel return data from all currently visible columns of your datatable without any data formatting (as it is in the dataset). However, you may need to get data from other fields as well as restrict the number of fields in the export file, or apply some format to data values.

All customizing happens within the needed export function:

//in case you use online service
grid.exportToExcel(null, {..setting custom values..});

//in case you use local version of export script
grid.exportToExcel("generate.php", {..setting custom values..});

Export API allows

  • setting columns you'd like to see in export (including ID column). Here column names should be specified:
grid.exportToExcel(null, {
    id:true, // note where id export is set
    columns:{
        customer:true,
        region_id:true,
        country_id:true
    }
});
  • defining a custom template and width for data from specified column:
grid.exportToPDF(null, {
    id:true,
    columns:{
        customer:{
            template:"#customer#",
            width:500
        }
    }
});

The column will be rendered with the stated template and width, which may differ from datatable parameters.

  • including extra field into export by forming them right within the export function:
grid.exportToPDF(null, {
    columns:{
        custom1:{
            template:function(obj){
                return "Year " + obj.year;
            },
            width:50,
            header:[{ text:"Date" }]
        },
        //other columns
        title:true
    }
});

"Custom1" (any name can be used) receives data from year field even if it is not seen in this datatable but is presented in its dataset. The field is rendered with width, template and header that will be the header of the corresponding column in the export table.

Related sample: DataTable: Export Configuration (server)

Configuration

You can define how datatable will look in PDF or Excel document after it is exported, configuring available options in the server side code. For these needs, please download the local script version.

In addition, you gain extra security with local scripts as well as get rid of a text that shows download source.


Events Handling with DataTable

You can assign a custom behavior to different events of DataTable by using its event handling system.

There are 2 ways to add a handler to the event:

  • through the method attachEvent();
  • through the parameter on.

Event names are case-insensitive

Method attachEvent()

You can attach several handlers to the same event and detach them using two respective methods:

A general way to attach/detach the event handler

// to attach event
var myEvent = $$("dataTableId").attachEvent("onItemClick", function () {
  // event handler code
})

// to detach event
$$("dataTableId").detachEvent(myEvent);

Parameter 'on'

With the help of parameter on you can attach any event(s) to DataTable. But you can't detach them later.

Attaching the event handler through parameter 'on'

webix.ui({
  view: "dataTable",
  ...
  on: {"onItemClick": function () {alert("item has just been clicked");}}
);

Cancelable Events

All events with subword 'onbefore' can be cancelled.
To cancel some event you should return false within the appropriate event handler.

Cancelling the event handler

var myEvent = $$("dataTableId").attachEvent("onBeforeTabClick", function () {
  ... // some event handler code
  return false;
})

Accessible objects and data

Inside the event handler you can refer to the holder component through keyword this.
Besides, most event handlers get incoming argument(s), like the id of DataTable's row (see ui.datatable to know exactly what arguments are passed inside event handler).

Btw, using the id of a sub-element you can access a data item associated with it and all its properties, even if they were not used to draw the element. For example:

Referring within the event handler

$$("myTable").attachEvent("onafterselect",function (id) {
  $$("top_label").setValue(this.getItem(id).name)
})


Dataview

API Reference
  • Methods, Properties and Events
  • Samples

Overview

Dataview displays objects with data according to a predefined template. It inherits from view.

Initialization

Specify the component's ID if you are going to work with the dataview later. Optionally, you can place dataview into an HTML container.

webix.ui({
    view:"dataview",
    container:"dataA",
    template:"<div class='webix_strong'>#title#</div> Year: #year#, rank: #rank#",
    data:...,
    datatype:"...",
    xCount:3, //the number of items in a row
    yCount:4 //the number of items in a column
});

Related sample: DataView Basic Initialization

Data property defines datasource for the view. Data can be loaded in one of supported data types.

Working with Dataview
  • Data Loading
  • Defining Data Templates
  • Selection
  • Adding/Deleting Items
  • Editing Data
  • Paging
  • Adding Active Elements to Dataview Items
  • Components Export to PNG
  • Data Components Export to Excel

Note that there's a built-in possibility to edit data with dataview. You should create a prototype dataview-edit object beforehand.

Related Articles
  • Data Object Operations
  • Setting Dimensions for the Components
  • Dynamic Resizing and Adjustment
  • Redefinition of the Components
  • Dataview CSS Image Map


Available only in PRO Edition

Excel Viewer

Excel Viewer is an extension tool intended for viewing Excel files.

Related sample: Excel Viewer

The constructor of the viewer is the following:

{
    view:"excelviewer",
    toolbar:"toolbar",
    excelHeader:true,
    url:"binary->files/data.xlsx"
}

The configuration properties are:

  • toolbar - (string) the id of the related excel toolbar, if used;
  • excelHeader - (boolean) true to use the first row of the Excel table as a column header;
  • url - (string) the url of the excel file that should be displayed.

Binary proxy is used for loading the file, which allows to get its contents as ArrayBuffer.

The default datatype for Excel Viewer is excel. It is strongly recommended not to change it manually to avoid parsing inconsistency.

Excel viewer API

load()

loads an excel file to the viewer

parameters:

  • file - (string) the name of the file to load
  • datatype - (string) data type (should be "excel" here)
$$("viewer").load("binary->data.xlsx", "excel");

parse()

parses file data to the viewer

parameters:

  • file - (object) uploaded file object
  • datatype - (string) data type (should be "excel" here)
 { view:"uploader", value:"Select Excel File", width:200,
    on:{
      onBeforeFileAdd:function(upload){
         $$("excel").clearAll();
         $$("excel").parse(upload.file, "excel");
           return false;
      }
    }
}

Related sample: Excel file Uploading and Downloading

showSheet()

switches to the specified sheet

parameters:

  • name - (string) the name of the sheet
$$("viewer").showSheet("Data");

Excel toolbar and its API

It's possible to show a toolbar with tabs that correspond to the Excel sheets. In order to render such a toolbar, the dedicated excelbar view should be initialized.

{
    view:"excelbar",
    id:"toolbar"
}
  • id (string) - the id of the Excel toolbar.

Excel toolbar API

getInput()

returns the toolbar object

$$("toolbar").getInput();

returns:

  • toolbar - (object) the toolbar object

getValue()

returns the currently selected tab

$$("toolbar").getValue();

returns:

  • tab - (string) the name of the selected tab

setSheets()

sets tabs in the toolbar (should correspond to excel sheets)

parameters:

  • sheets - (array) an array of tabs
$$("toolbar").setSheets(["Data", "Files"]);

setValue()

sets the selected tab within a toolbar

parameters:

  • value - (string) the name of the tab to select
$$("toolbar").setValue(value);

Loading data to Excel Viewer

There are three possible ways of loading data to Excel viewer:

  • specifying the needed file directly in the viewer constructor by using the url parameter:
{
    view:"excelviewer",
    url:"binary->files/data.xlsx"
}
  • calling the load method with the file name as a parameter
{ view:"excelviewer", id:"excel", editable:true, header:false },
...
$$("excel").load("binary->files/data.xlsx", "excel");

Related sample: Excel Viewer

Binary proxy is used for loading the file, which allows to get its contents as ArrayBuffer. The datatype is "excel".

  • parsing uploaded file data with the help of parse method
 { view:"uploader", value:"Select Excel File", width:200,
    on:{
      onBeforeFileAdd:function(upload){
         $$("excel").clearAll();
         $$("excel").parse(upload.file, "excel");
           return false;
      }
    }
}

Related sample: Excel file Uploading and Downloading

Customizing the loaded data

You can customize the presentation of the loaded data, such as displaying headers and controlling the number of the loaded rows.

{
    view:"excelviewer",
    url:"binary->files/data.xlsx@Data[1-10]"
}

The string value of the url property binary->files/data.xlsx@Data[1-10]" includes the following parts:

  • binary - the name of the proxy object
  • files/data.xlsx - path to the Excel file
  • @ - optional, the delimiter that detaches the link from its parameters (can be omitted together with parameters)
  • Data - optional, the name of the Excel sheet to render
  • [1-10] - optional, the rows that should be rendered in the viewer

Related sample: Excel Proxy


Form

API Reference
  • Methods, properties and events
  • Samples

Overview

Any form is a means of getting an information from users. It contains input fields and select components like checkboxes, radiobuttons alongside with submit/cancel buttons depending on the situation. Find them all in our Controls Guide.

Initialization

Ui-related form inherits from view. It resembles layout very much as it is divided into columns and rows where controls are put.

  • elements - the form's specific property, an array of vertically arranged controls and control groups;
  • columns - an array of horizontally arranged controls and control groups;
  • rows - an array of vertically arranged controls and control groups.

Login form

webix.ui({
    view:"form",
    id:"log_form",
    width:300,
    elements:[
        { view:"text", label:"Email"},
        { view:"text", type:"password", label:"Password"},
        { margin:5, cols:[
            { view:"button", value:"Login" , type:"form" },
            { view:"button", value:"Cancel" }
        ]}
        ]
    });

Related sample: Form Basic Initialization

There exists a possibility to specify common configuration for all controls included in this or that form.

Settings Initial Values

Initial form values can be set in different ways:

Setting value of each element separately

Every form control features value property:

{ view:"text", id:"fname", value:"Adam Smith"}

Or, you can call the setValue() method for it:

$$("fname").setValue("Adam Smith");

However, this way is not effective while working with the whole form.

Using setValues API

To set form values in a scope, you can use its setValues() method. It takes an object with values as first (and mandatory) parameter:

$$("$form1").setValues({
    value1:"111", value2:"222"
});

Data names of these values must coincide with values of name parameters of the corresponding form elements:

elements:[
    { view:"text", name:"value1"},
    { view:"text", name:"value2" }
]

Complex Data

Form values can be of any complexity level, which means that sub items are acceptable. For these needs the form should have the following configuration:

  • complexData property should be set to true;
  • element names should be concatenated from all the data names in the chain.
webix.ui({
    view:"form",
    complexData:true,
    elements:[
        { label:"Width", view:"text", name:"layout.width" },
        { label:"Height", view:"text", name:"layout.height"}
    ]
});

$$("sets").setValues({
    layout:{
        width:250,
        height:480
    }
});

Related sample: Form:Data with complex properties

Loading/parsing values

Webix form can load or parse data like any data management component. All the data loading rules are true for it.

Again, data attributes should coincide with names of form fields:

Parsing

var data = {id:1, fname:"Ann", lname:"Brown"};

webix.ui({
    view:"form", id:"myform", elements:[
        {view:"text", name:"fname"},
        {view:"text", name:"lname"}
    ],
    data:data
});
//or
$$("myform").parse(data);

Loading

$$("myform").load("data.php");

Grouping Controls in Form

Dividing form into sections

Form elements can be divided into columns and rows with any level of complexity.

{ view:"form", elements:[
    {cols:[
        { rows:[
            {view:"text"},
            {view:"datepicker"}
        ]},
        {view:"checkbox"},
        {view:"button"}
    ]},

]}

To add user-friendliness to form interface, separated blockes can be set within it by:

  • Adding headers with section type before control blocks;
  • Dividing a form into fieldsets.

Sections

Form elements are placed into different row arrays where the first row is a section header. Its template define text value of the header:

{view:"form", elements: [
    { rows:[
        { template:"Alpha fields", type:"section"},
        { view:"text", label:"Alpha 1", value:'' },
        { view:"text", label:"Alpha 2", value:'' }]
    },
    { rows:[
        { template:"Beta fields", type:"section"},
        { view:"text", label:"Beta 1", value:'' }]
    }
]}

Related sample: Splitting Form into Sections

Fieldsets

Fieldset is a collection of controls surrounded by a border from all the sides. Webix fieldset features text label and body where rows or cols array of controls are stored:

{view:"form", elements:[
    { view:"fieldset", label:"Field Set 1", body:{
         rows:[
            { view:"text", label:"Login"},
            { view:"text", label:"Email"}]
         }
    }
]}

Related sample: Fieldset

Multiview Form

Form field can be placed into different tabs thus forming a multiview layout. Switching between tabs there is implemented with tabbar and segmented buttons as well as with the help of the dedicated tabview.

The switching controls are placed directly into the array of form elements.

{view:"form", elements:[
    {view:"tabview",
        tabs:["A","B","C"],
        cells:[
            { view:"text", name:"value1", label:"value1" },
            { view:"text", name:"value2", label:"value2" }
        ]
    }]
}

Related sample: Form with Tabs

Retrieving Form Values

Getting value of a single element

Since form elements comprise an array you can refer to each of them by its number starting from 0 and get/set the value of any item.

var form1 = [
    { view:"text", id:"log", label:'Login', name:"login"},
    { view:"text", id:"em" label:'Email', name:"email" },
    { view:"button", id:"sub", name:"submit", value:"Sumbit"}
];

webix.ui({
    view:"form",
    id:"my_form",
    elements: form1
});

var login = form1[0].login;// returns current input value;
var button = form1[2].submit; //returns "Submit";

Or, you can apply getValue() method directly to the needed control:

$$("log").getValue();

Getting values of all form elements

To get an associative array of all elements (name:value pairs) you can use getValues method. To get to the necessary value, you should specify the name of the needed control.

var values = $$("my_form").getValues(); //returns { login:"", email:"", submit:"" }

values.login; //returns current value of the text input field

Additionally, you can get only changed and unchanged form values with the following methods respectively:

  • getDirtyValues - returns a hash of changed values;
  • getCleanValues - return hash of unchanged values.

Disabling Form Elements

Any form element can be disabled or switched to readonly mode.

var form2 = [
        { view:"header" }
        { view:"text", value:'..', label:".."},
        { view:"text", type:'..', value:'..', label:".."},
]

form2[i].readonly = true; //where "i" takes the number value of the element staring from 0.
form2[i].disabled = true;

Related sample: Attributes

See also Form and HTMLform Treatment article to learn more about the most important form methods.

Reacting on Changes in Input Fields

If you want to track the moment when the value in an input changes from one to another and attach some event to it, make use of the dedicated "onChange" event.

The event is attached to element object that can be retrieved by its ID or name.

The attached function can be any you wish. Here is an example of logging the changes. The old value comes as oldv parameter while the new one is referred as newv

$$("form1").elements["login"].attachEvent("onChange", function(newv, oldv){
            webix.message("Value changed from: "+oldv+" to: "+newv);

Related sample: 'onChange' Event

Getting Parent Form for the Input

The easiest way to get to a parent form from any of its elements is to call the getFormView:

{view:"text", on:{"onChange":function(){
    var form = this.getFormView();
}}}

Sending Form Data

Form data can be sent to server in either of the following ways:

1 . Using Webix Ajax helper:

webix.ajax().post("some.php", form.getValues());
//with callback
webix.ajax().post("some.php", form.getValues(), function(text, data, xhr){ });

2 . Using webix.send method that emulates HTML form submitting:

webix.send("come.php", form.getValues());

3 . Indirectly, via the bound master component or DataCollection:

The method is good when the form is used for editing the data of the main component (datatable, tree, list, etc.). In this case not the form data matters but the data of the main component. Form saves the data to the master component while the master handles the serverside part.

//data from selected list item is pushed to the form
form.bind(list);

//pushes the data back to list item
form.save()

Data binding concept is described in a separate documentation article.

Related Articles
  • Form and HTMLform Treatment
  • Uploading Files with Form
  • HTMLform
  • Controls List
  • Controls Common Functionality Guide
  • Data Validation in Forms
  • Event Handling
  • Data Binding
  • Creating Message Boxes


Form Controls

Webix delivers a variety of controls that can be placed in the form. These controls can be used for entering text, selecting an option, date or color, switching between multiview cells, etc.

List of Controls

Main controls (can be used standalone):

  • Button
  • Checkbox
  • Colorpicker
  • Combo
  • Counter
  • Datasuggest
  • Datepicker
  • Fieldset
  • Gridsuggest
  • Icon
  • Label
  • Multicombo
  • Multiselect
  • Multitext
  • Radio
  • Range slider
  • Richselect
  • Search
  • Select
  • Segmented
  • Slider
  • Tabbar
  • Text
  • Textarea
  • Toggle

Helper controls (are used to build other controls, can be configured within them to add extra customization):

  • Suggest - a popup with options for select controls. May include:
    • list - select options for combo, richselect and multiselect;
    • colorboard - a color palette for colorpicker;
    • calendar - date selector for datepicker.

It has some variations - gridsuggest, datasuggest, checksuggest, multisuggest - to serve the needs of various controls.

Shared Functionality

Form controls have much in common, namely:

  • feature name property to indicate data name within form values;
  • have label, value, width/inputWidth and height/inputHeight properties;
  • can be hidden and shown;
  • feature getValue() and setValue();
  • ..etc.

For further details check the Controls Guide article.

Samples
  • Form Controls


Button

API Reference
  • Methods, properties and events
  • Shared functionality

Button Types

Standard Buttons

{ view:"button", id:"my_button", value:"Button", type:"...", inputWidth:100 }

Related sample: Button ('button')

Type property of a button defines the way is looks like:

  • base (no type) - default button;
  • 'form' - a button for a form (darker than standard);
  • 'danger' - a red button to attract user attention;
  • 'prev' - a button with left arrow;
  • 'next' - a button with right arrow;

Icon Buttons

{ view:"button", type:"icon", icon:"mail", label:"Mail", width:80 }

Related sample: Icons

Icon button features some specific configuration options:

  • icon (string) - icon name. Full list of icon names is available on Font Awesome;
  • label (string) - text on a button by the icon;
  • type (string) - defines the type of a button:
    • icon - an icon button without a distinct border;
    • iconTop - an big borderless icon button with a text label below the icon;
    • iconButton - a small icon button with a label right of the icon;
    • iconButtonTop - a big icon button with a label below the icon;

For further information about icons in Webix components read the Icons with UI Components article.

Image Buttons

{ view:"button", type: "image", image:".../img.gif", label: "Image Button" }

Related sample: Buttons: Type 'image'

Image button features some specific configuration options:

  • image (path) - path to the desired image;
  • label (string) - text on a button by the image;
  • type (string) - defines the type of a button:
    • image - a borderless image with a left-hand label (if any);
    • imageTop - a borderless image with a bottom label;
    • imageButton - a button with an image and a left-hand label:
    • imageButtonTop - a button with an image and a label below the image;

HTML Buttons

{ view:"button", type: "htmlbutton", css: "icon_back_btn",
  label: '<span class="webix_icon fa-angle-left"></span><span class="text">back</span>',
  inputWidth:100
}

Related sample: Buttons: Styling

A button with an 'htmlbutton' type can be defined by HTML markup and CSS styling. Setting the css property you indicate the CSS class through which you can style the button itself, its text, icon or image:

.icon_back_btn .webix_icon{ ...}
.icon_back_btn .text{ ... }
.icon_back_btn button{ ... }

Buttons with Badges

{ view:"button", width:40, badge:12, type:"icon", icon:"envelope" }

Any button regardless of its type can be equipped with a badge with the help of a same-name property.

Related sample: Buttons: Type 'icon' with Badges

Button Configuration
  • value (string) - defines the text displayed on standard buttons (basic, form, danger, prev, next);
  • label (string) - defines the text or/and HTML markup for the button of imabeButton and iconButton types and their valiarions as well as for htmlbutton;
  • width (number) - sets the width of the button;
  • inputWidth (number) - sets the width of the text on the button and adjusts button's width to it;
  • image (string) - sets a path to the button icon;
  • align (string)- positions a button with relation to a parent view;
  • popup (string)- defines the ID of a popup window that will be shown on button click;
  • click (function) - defines a function that will be executed on clicking the button (another possibility is to attach an event to it using the button's ID);
  • css (string) - name of CSS class applied to a button;
  • badge (number/string) - adds an orange circle that notifies about the number of new message for an icon button;
  • autowidth (boolean) - sets the mode in which the button's width automatically adjusts to the button's content.

Setting Autowidth for Buttons

{ view:"button", label:"Short", autowidth:true }

It's possible to adjust the width of a button to the size of its content, using the autowidth property set to true.

Related sample: Buttons - AutoWidth


Manipulating Groups of Buttons

In case of image buttons, you can use a function to define differently-sized buttons for a toolbar.

Related sample: Buttons: Type 'imageButton'

Image button is a derivation from a standard button. It is defined with an image property where you specify the path to the necessary image.

Button type depends on its size with typical sizes being 18, 24, 32 and 48. If you have the images stored in different folders with corresponding titles, you can make use of a custom function to set the needed size.

function buttons(size){
    return  [
    { view:"button", type:"image"+size,
        image:"../common/imgs/"+size+"/save.gif", width:size+14}, //for image button
    { view:"button", type:"image"+size, label:"Save",
        image:"../common/imgs/"+size+"/save.gif", width:size+60}
        //for image button with a text label - it should be wider
    ];
}

Then, when defining properties of a toolbar constructor, include the function into its cols property and pass the necessary parameter into it.

webix.ui({
    view:"toolbar", paddingY:2, height:28,
    cols: buttons(18)
});

The toolbar above will initially work with icons measuring 18 pixels in width while the width of the button itself is calculated withtin the function.


Checkbox

API Reference
  • Methods, properties and events
  • Shared functionality

Overvier

Checkbox allows for a choice between two possible variants.

Related sample: Check Box ('checkbox')

Initialization

Checkbox Initialization

{ view:"checkbox", id:"field_a", label:"Second age", value:1}

Main properties

  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth - width of the label container;
  • labelRight (string) - set the text of right-hand label. Only checkbox features this functionality;
  • value (boolean) - defines whether the checkbox is selected by default or not (0 for false, 1 for true);
  • align (string)- positions button with relation to a parent view;
  • checkValue (string) - value of the checkbox in the checked state (1 by default);
  • uncheckValue (string) - value of the checkbox in the unchecked state (0 by default);

Webix checkbox control is based on standard HTML checkbox yet some skins use a FontAwesome icon to render it. To switch to a standard HTML checkbox, use customCheckbox property:

{ view:"checkbox", customCheckbox:false}


Colorpicker

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Colorpicker allows for selecting a color from the dedicated colorboard that is initialized on clicking its input field.

Initialization

{ view:"colorpicker", label:"Front color", name:"color", value:"#ffaadd" }

Related sample: Colorpicker in Form

Main Properties

  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • value (hex code) - the initial value of the picker that is changed by picking any color from the colorboard.


Combo

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Ui-related combo is a text-like field with a popup window that appears as you click the field. A popup displays options for users to select. At the same time, you can edit the text field and the items will be filtered according to the input values.

Related sample: Editable Combo Box ('combo')

Initialization

//short form
{ view:"combo", id:'field_m', label: 'Combo', value:"One",
    options:["One", "Two", "Three"]}

//full form
{ view:"combo", id:'field_t', label: 'Combo', value:"1",
    options:[
    {id:1, value:"One"},
    {id:2, value:"Two"},
    {id:3, value:"Three"}
]}

//server options
{ view:"combo", options:"server/data.json"}

Main properties

  • value (string, number)
    • within options array it sets text value for selectable items;
    • within Combo constructor it defines the initially selected item of the control (option ID in case of a full form, option text in case of a short form);
  • placeholder (string) - defines placeholder for combo input. The control should be initialized without an initial value;
  • options (array, object, string) - sets the options to choose from;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container.

Accessing Suggest List

Combo API allows getting an object of a popup and a list inside it for further usage:

var popup = combo.getPopup();
var list = popup.getBody();
//or
var list = popup.getList();

Configuring Suggest List

Combo box control can be customized in a number of ways, e.g.:

  • options can be defined dynamically;
  • options can be loaded from serverside;
  • template can be changed;
  • filtering rule can be changed..

To learn more, go to Advanced Combo and Richselect Settings article.

Pro Extensions for Combo

In the Webix Pro edition the control can be extended to show either a dataview or datatable in the popup:

  • Dataview Suggest
  • Grid Suggest

Getting Current Value

In case of a full initialization form, the getValue() method for combo will return ID of selected option rather than text. Use getInputNode() to get to input object and, hence, the text value.

$$('field_t').getValue(); // ->returns 1
$$('field_t').getInputNode().value // -> returns "One"

Related sample: Working with UnitList Items

Alternatives to Combo Box
  • richselect - identical to combo in look, but text field is non-editable.
  • text coupled with suggest list. Indentical to combo in look, but while combo requires selection from a popup list, suggest offers values that can be either chosen or ignored.


Counter

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Counter is a spin-box that helps select a number by either entering the value in the input field or clicking "+" and "-" buttons to reach the necessary value.

Negative values are possible.

Related sample: Spin Box ('counter')

Initialization

{ view:"counter", label:"Age", step:10, value:33, min:21, max:100}

Main properties

  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • step (number) - sets a step to the next value (1 by default);
  • align (string)- positions a button with relation to the parent view;
  • value (number) - the initial value of a control. 0 by default;
  • min (number) - minimal value for a control. 0 by default;
  • max (number) - maximum value for a control.

Note that if you set min and max parameters, the initial control value should be within the range.


Available only in PRO Edition

Dataview Suggest

Dataview suggest, or datasuggest, is used to add extra functionality to Webix select controls, namely richselect, multiselect, combo, multicombo and similar editors. It is based on Webix suggest list.

Datasuggest extension makes it possible to use Webix dataview in a dropdown menu which is great for inserting pictures while by default Webix list is used.

Using Datasuggest for Form Controls

The extension can be used to redefine dropdown menu of select controls.

Related sample: Data Suggest

Default combo and richselect constructor looks as follows:

{
    view:"combo", //or "richselect"
    value:1,
    options:[...] //options data
}

When extended with datasuggest, the constructor allows setting Webix dataview for a dropdown menu and defining its configuration right among the component's options.

{ view:"richselect", value:1, options:{
    view:"datasuggest",
    data:options
}},

Possible configuration parameters:

  • data (array) - defines data for the options to choose from;
  • template (function) - sets a complex template for control input, for instance, the one with a picture. By default, the first data value after the ID field is shown;
  • textValue (string) - sets data value to display in the input (acts as a string template) and, in case of combo, data value subject to filtering;
  • body (object) - defines complex config for dataview.

Predefined Input Template

{ view:"richselect", options:{
    view:"datasuggest",
    template:"#value# (#color#)",
    data:options
}}

Body allows for setting the following parameters for a dropdown dataview:

  • template (string, function) - defines template for dataview items. By default, the first data value after the ID field is shown;;
  • type (obj) - sets dimensions for dataview cells as an object {width:150, height:100};
  • data (array) - data for the options to choose from. If you use body property for datasuggest configuration, data should be defined inside it.
  • xCount (number) - the number of items on the X scale;
  • yCount (number) - the number of items on the Y scale;
  • autoheight (boolean) - if true, set auto height for the dataview. False by default.

Item template, predefined item dimensions

{ view:"richselect", options:{
    view:"datasuggest",
    body:{
        template:function(obj){
            return obj.value + "</br><img src='data/image00"+obj.id+".jpg'>";
        },
        type:{
            width:270, height:180
        },
    data:options
    }
}}

Using Datasuggest as Editor

Datasuggest can be used as a component editor as part of combo or richselect editors.

For these needs, a popup should be previously initialized, either with default or with customized settings:

Default - that's enough

var popup = webix.ui({
    view:"datasuggest"
});

With the custom configuration all the above-mentioned settings can be used:

Customized

var popup = webix.ui({
    view:"datasuggest",
    body:{
        type:{
            height:100,
            width:160
        },
        template:"<b>#value#</b><br>#year#"
   }
});

Then, this popup should be attached to the column in question with the help of its popup property:

{ id:"title",  editor:"richselect", collection:options, popup:popup }

Related sample: Dataselect Editor

Related Articles
  • Webix Data Loading Pattern
  • Templates for Webix Data Components
  • Data Editing


Datepicker

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Datepicker is used in a combination with ui-related calendar that is initialized on clicking the control. It allows choosing a date and, optionally, time in the calendar for their further usage.

Related sample: Date Picker ('datepicker')

Initialization

{view:"datepicker", date: new Date(2012, 6, 8), label: 'Select Date', timepicker:true}

Main properties

  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • value (string, obj) - initial value to display in the control input field;
  • placeholder (string) - defines placeholder for datepicker input. The control should be initialized without an initial value;
  • timepicker (boolean) - enables a clock for time selection (false by default);
  • date (function) - new Date() constructor to define the initial date of a calendar. If used without parameters, shows current date;
  • stringResult (boolean) - sets the data type of value returned by getValue()/get Values() methods. If true, it returns date as string. By default the property is false and the method returns date object;
  • format (string) - sets a date format to display in the datepicker field. By default it is "%Y-%m-%d".
  • type (string) - (optional) sets the datepicker type:
    • "time" - configures datepicker for time selection only (uses webix.i18n.timeFormat as formatting pattern)

Time selector

If you need to select time (hours and minutes) only, use the datepicker with type "time":

{ view:"datepicker", type:"time", stringResult:true }

Dates are formatted according to the Date formatting methods.

Disabling date and time slots

To limit user ability to pick date and time periods, you should access calendar object that lies in the datepicker popup and apply the needed configuration to it:

{view:"datepicker", suggest:{
    type:"calendar", body:{
        minDate:new Date(),
        maxDate:"2016-05-07"
    }
}}

More about Disabling Dates in Calendar

More about Advanced Popup Configuration in Popup Selectors


Fieldset

API Reference
  • Methods, properties and events
  • Controls Common Functionality

Overview

Fieldset is a grouping control based on HTML < fieldset > tag. Creates a section with borders to place the controls into it.

Initialization

Fieldset can be used to neatly put the controls into layout:

{view:"fieldset", body:{
    rows:[
        {view:"text", ..},
        {view:"button", ..}]
 }
}

Related sample: Multiple Fieldsets

Or, to create a control group within a form:

{view:"form", elements:[
    {view:"text", ..},
    {view:"fieldset", body:{
        rows:[
            {view:"text", ..},
            {view:"datepicker", ..}]}
    }
]}

Related sample: Fieldset

Main Properties

  • body (object) - fieldset body object that contains rows or cols array with controls;
  • label (string) - text label of the control group, integrated into border.


Available only in PRO Edition

Grid Suggest

The functionality is a feature of Webix Pro edition.

The extension is based on Webix suggest list. It redefines the default dropdown menu for richselect](Richselect), multiselect, combo, multicombo controls as well as similar editors.

Gridsuggest extension makes it possible to use Webix datatable in a dropdown menu while by default Webix list is used.

Using Gridsuggest for Form Controls

Gridsuggest can be used with select controls.

Related sample: Grid Suggest

By default combo and richselect are initialized with the following constructor:

{
    view:"combo", //or richselect
    value:1,
    options:[..]//option data
}

With gridsuggest extension you get the possibility to define view used for a dropdown menu as well as set its configuration, both for combo and richselect.

{ view:"richselect", value:1, options:{
    view:"gridsuggest",
    data:options
}}

Possible properties here are as follows:

  • view (string) - name of the view acting as a dropdown menu (here - gridsuggest);
  • data (array) - data for the options to choose from;
  • textValue (string) - data value shown in the input (acts as a string template) and, in case of combo, data value used for filtering. By default, the first data value after the ID field is taken;
  • template (function) - allows for setting a complex template for the input field;
  • width (number) - width of a dropdown popup;
  • body (object) - set of configuration options for a suggest datatable.
{ view:"richselect", options:{
    view:"gridsuggest",
    template:function(item){
        return item.name + " (" + item.color + ")";
    },
    //textColor:#name#
    data:options
}},

Such code will show a datatable with borders while the columns will be generated for all data values from the dataset except for the ID field.

Datatable can be further configured inside body object property and can take the following parameters:

  • autoConfig (boolean) - if true, enables default configuration for datatable (described above);
  • columns (array) - used instead of autoConfig, allows for setting an array of columns for the datatable.
  • header (boolean) - if false, hides datatable header. True by default;
  • borderless (boolean) - if true, removes borders around the datatable. False by default;
  • data (array) - data for the options to choose from. If you use body property for gridsuggest configuration, data should be defined inside it.

Auto config, no headers, no borders

{ view:"combo", options:{
    view:"gridsuggest",
    body:{
        autoConfig:true,
        header:false,
        borderless:true,
        data: options
    }
}}

Preset Columns

{ view:"combo", options:{
    view:"gridsuggest",
    body:{
        columns:[
            { id:"name" }, { id:"color" }
        ],
        data:options
    }
}}

Using Gridsuggest as Editor

Gridsuggest can be used as a component editor as part of combo or richselect editor.

For these needs, a popup should be previously initialized, either with default or with customized settings:

Default - that's enough

var popup = webix.ui({
   view:"gridsuggest"
});

With the custom configuration all the above-mentioned settings can be used:

Customized

var popup = webix.ui({
    view:"gridsuggest",
    body:{
        columns:[
            {id:"value", header:"Value", width:250},
            {id:"year", header:"Year", width:100}
        ]
    }
});

Then, this popup should be attached to the column in question with the help of its popup property:

{ id:"title",  editor:"combo", collection:options, popup:popup }

Related sample: Grid Suggest::Editor

Enabling scrolling

In order to enable scrolling functionality in a gridsuggest extension, you should make 2 steps:

  1. Set the scroll property to true
  2. Disable the autoheight parameter
var form = { view:"form", elements: [
    { view:"combo", name:"names", label:"Code", options:{
        view:"gridsuggest",
        data: ["A", "B", "C", "D", "E", "F", "G", "H", "J"],
        body: {
            scroll:true,
            autoheight:false,
            autofocus:true,
            yCount:5
        }
    }}
  ]
};

webix.ui(form);

Related Articles
  • Webix Data Loading Pattern
  • Templates for Webix Data Components
  • Data Editing


Icon

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

UI-related icon is a button-like borderless clickable control with an icon on it.

Initialization

{ view:"icon", icon:"envelope", align:"left"}

Main properties

  • icon (string) - icon name. Icons and their names are listed on the Font Awesome.

Icons in Webix can:

  • form a separate component (as described above);
  • indicate a button type;
  • be defined via a CSS class.

Read more about icons within Webix views in the dedicated chapter of the documentation.


Label

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Ui-related label is a non-scrollable placeholder for plain text. Like other components, it features specific label property that sets text value.

Initialization

{ view:"label", label: "Label", inputWidth:100, align:"center"}

Related sample: Attributes

Main properties

  • label (string) - defines text of the label control;
  • inputWidth (number) - defines the width of the control;
  • align (string) - positions the label with relation to the parent view.

Label control can be used to render any user HTML or icons (as well as built-in in Webix FontAwesome icons):

{ view:"label", label:"<span class='myCss'>My Label</span>"},
{ view:"label", label:"<span class='webix_icon fa-user'></span> My Label" }


Available only in PRO Edition

Multicombo

The control is available only in Webix Pro edition.

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Multicombo is an editable control that allows for choosing several options at a time from a dedicated popup list, the checksuggest.

Multicombo inherits from a standard combo control and has the following features:

  • Each option is equipped with a checkbox;
  • Each time you enter symbols in the input field the list of options is filtered;
  • To select an option, check it or click the corresponding list item. A selected option will be added to the input;
  • To remove an option from selection, click either the "cross" sign or use the "backspace" key in the input filed or uncheck the option in the list.

Initialization

{ view:"multicombo", label:"To", value:"2,3,4,13", suggest: "data/names.js"}

Related sample: MultiSelect combobox

Main properties

  • label (string) - specifies text label of a control;
  • labelPosition (string) - sets the position of the label in relation to the control container;
  • value (array/string) - defines the initially selected items of the control;
  • separator (string) - defines a delimiter for separating options in a multicombo, comma by default;
  • options or suggest (array, object) - defines a set of items to select from, or the datasource, or advanced popup configuration;
  • optionWidth (number) - defines the width of a popup list. By default, it is adjusted to the control width;
  • button (boolean) - defines whether the "Select" button will be displayed in the options list;
  • keepText (boolean) - defines whether the entered text should be kept in the input after an option is selected.

Configuring Suggest List

You can read about advanced configuration options for popup selectors in the corresponding documentation article.

Accessing Suggest List

Multiselect API allows getting popup and list objects for further usage:

var popup = multicombo.getPopup();
var list = popup.getBody();
//or
var list = popup.getList();

Manipulating Tags

In some cases, multicombo can not be shown as a multi-line input and information about selected items should be displayed only as a number of these items.

To disable multiple tags, you need to set the tagMode property to false:

{
    view:"multicombo",
    label:"Name",
    labelPosition: "top",
    value:"1,7,9,12",
    tagMode: false
    ...
}

To specify a template for the common tag, you need to use the tagTemplate property. By default the tagTemplate is set like this:

tagTemplate: function(values){
   return (values.length? values.length+" item(s)":"");
}
  • values - an array of the selected items' ids

You can customize the template the way you like:

{
    view:"multicombo",
    label:"Name",
    labelPosition: "top",
    value:"1,7,9,12",
    tagMode: false
    tagTemplate: function(values){
        return (values.length? values.length+" item(s) selected":"");
    },
}

Related sample: MultiSelect combobox


Available only in PRO Edition

Multiselect

The control is available only in Webix Pro edition.

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

UI-related multiselect is a non-editable select control that allows for selecting multiple options at a time while displaying them in the dedicated input field.

Multiselect inherits from a standard richselect and has the following features:

  • Each option is equipped with a checkbox (can be configured, see below);
  • To select an option, check it or click the corresponding list item. A selected option will be added to the input;
  • To remove an option from selection, click either the "cross" sign or use the "backspace" key in the input filed or uncheck it in the list.

Initialization

{ view:"multiselect", id:"multi", label:"Participant", options:[
    { id:1, value:"Alex Brown" },
    { id:2, value:"Dan Simons" },
    { ... }
], value:"1,3" }

Related sample: Multi-select input

Main properties

  • value (string) - the initial value to display in the input field, its ID. The string can be separated by a comma (",") to define multiple values;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
    • labelPosition (string) - defines label position related to the input field. The only possible value is "top";
  • placeholder (string) - the initial text in the text field, disappears as you start typing in it;
  • options or suggest (array, object) - defines a set of items to select from, or the datasource, or advanced popup configuration;
  • optionWidth (number) - defines the width of a popup list. By default, it is adjusted to the control width;
  • button (boolean) - if set to true, defines that multiselect's popup will be closed by click on the Select button. The details on the button's configuration are given below.

Configuring Suggest List

Webix API allows for using another suggest list for the multiselect - multisuggest:

webix.ui({
  view:"multiselect", suggest:{
    view:"multisuggest", data:[
      {id:1, value:"one"},
      {id:2, value:"two"}
      ]
    }
});

The control's popup is supplied with a "select" button out of box, but it can be changed in two ways:

  • changing the buttonText property for a particular multisuggest list:
{view:"multiselect", label:"Participant",options:{
     buttonText:"Done",
     data:[]
}}
  • modify the locale to change button text for all the multisuggests in the application (if other is not stated by buttonText, as shown above):
webix.i18n.controls.select = "Done";
webix.i18n.setLocale(); //apply the locale

Then all the multiselect instances in the app will be supplied with the "Done" word.

You can read more about advanced configuration options for popup selectors in the corresponding documentation article.

Accessing Suggest List

Multiselect API allows getting a popup object for further working:

multiselect.getPopup().getBody();
//or
multiselect.getPopup().getList();

If you use multisuggest, then its constituent parts (list and button) are accessed as:

//button object
multiselect.getPopup().getButton();
//list object
multiselect.getPopup().getList();


Available only in PRO Edition

Multitext

The control is available only in Webix Pro edition.

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

UI-related multitext is a dynamic control based on standard Webix text input. It offers the possibility to add and delete additional fields on the go.

Initialization

{ view:"multitext", id:"multi", value:'dummy@email.com, mirror@email.com', label:"Email" }

Related sample: Multi-Text input

Main properties

  • value (string) - the initial value to display in the input field. The string parts separated by a comma (",") will be put to additional input fields);
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
    • labelPosition (string) - defines label position related to the input field. The only possible value is "top";
  • placeholder (string) - the initial text in the text field, disappears as you start typing in it;
  • icon (string) - the control's icon.

Field IDs

Each field of a multitext control features its own ID. It can be either a given (for the basic field) or an auto-generated one. All the methods of a multitext object can be applied to any field object.

Adding and Removing Fields

Multitext API allows adding and removing additional fields dynamically:

var newFieldId = $$("multi").addSection();

//remove specific field
$$("multi").remove(newFieldId);
//remove all the additional fields
$$("multi").remove();

Notes:

  • Only additional fields can be removed, basic one always remains.
  • The methods can be called from any multitext object from the group.

Setting and Getting Values

Multitext features an extended API for setting and getting its values.

  • setValue and getValue methods for working with the value of the whole control;
  • setValueHere and getValueHere methods for for working with the value of the first (basic) field.


Radio

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Ui-related radio is a block of several items with the possibility to check only one of them at a time.

Initialization

{view:"radio", label:"Branch", value:1, options:[
    { id:1, value:"Master" }, //the initially selected item
    { id:2, value:"Branch" }
]}
//short form for options array
 {view:"radio", options:["Master", "Branch"]}

Related sample: Radio Button ('radio')

Main properties

  • value (string, number)
    • within options array it sets titles of radiobuttons;
    • within Radio constructor it defines the initially selected radiobutton;
  • id (string, number) - used with the radio block as well as with each of its items;
  • options (array, object) - defines the set of items to select from. Details.
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • align (string)- positions button with relation to a parent view;
  • vertical (boolean) - defines vertical arrangement of radiobuttons.

Webix radio control is based on standard HTML radio yet some skins use a FontAwesome icon to render it. To switch to a standard HTML radio, use customRadio property:

{view:"radio", customRadio:false}


RangeSlider

The control is available only in Webix Pro edition.

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Range Slider is an advanced slider control that allows selecting a specific range of values with two markers. The colored space between the markers defines the values included into the range.

Initialization

{ view:"rangeslider", label:"Level B", value:[0,50], name:"s2"}

Related sample: RangeSlider

Main Properties

  • value (string/array) - the starting and the ending values of the range;
  • label (string) - text label of the control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • name (string) - name of the control used to get its value in the form;
  • title (template, function) - text label over the slider marker


Richselect

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Ui-related richselect is a non-editable combo-box.

Visually, the richselect control consists of a text input and popup window that contains a standard list of options in its body.

Another possibility to create a component with a similar functionality is attaching a suggest list to a text field, but in this case, text field will be editable.

Initialization

//full form
{view:"richselect",
    id: "list2", label: 'richselect',
    value:1, yCount:"3", options:[
        {id:1, value:"One"}, // the initially selected item
        {id:2, value:"Two"},
        {id:3, value:"Three"}
    ]
}
...
//short  form for options array
{view:"richselect", options:["One", "Two", "Three"]}

//server options
{ view:"richselect", options:"server/data.json"}

Related sample: Non-editable Combo Box ('richselect')

Main Properties

  • value (string, number)
    • within options array it sets text value for selectable items;
    • within richselect constructor it defines the initially selected item of the control(ID in case of a long form, text value in case of a short form of initialization);
  • placeholder (string) - defines placeholder for richselect input. The control should be initialized without an initial value;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • options (array, object, string) - sets the options to choose from in a long or short form. Details.

Configuring Suggest List

Richselect control can be customized in a number of ways, e.g.:

  • options can be defined dynamically;
  • options can be loaded from serverside;
  • template can be changed..

To learn more, go to Advanced Settings of Popup Selectors article.

Accessing Suggest List

Richselect API allows for getting popup and list objects for further usage:

var popup = richselect.getPopup();
var list = popup.getBody();
//or
var list = popup.getList();

Pro Extensions for Richselect

In the Webix Pro edition the control can be extended to show either a dataview or datatable in the popup:

  • Dataview Suggest
  • Grid Suggest

Getting Current Value

In case of a full initialization form, the getValue() method for richselect will return ID of selected option rather than text. Use getText() method to get text value.

$$('field_t').getValue(); // ->returns 1

$$('field_t').getText() // -> returns "One"


Search

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

UI-related search looks like an input text field with a 'search icon' to indicate that it can be used for filtering data in a data-presenting component to get to the necessary item.

Filtering function should be written by a developer. See the attached sample for details.

Initialization

{ view:"search", placeholder:"Search..", width: 300 }

Related sample: Search Field

Main Properties:

  • placeholder (string) - a prompt text displayed in the search field;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container.


Select

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Select is a control that allows selection from several items. It is based on HTML < select > tag and looks like a dropdown list.

Initialization

//full form
{view:"select", label:"Branch", value:1, options:[
    {id:1, value:"Master" }, // the initially selected value
    {id:2, value:"Release" }
  ], labelAlign:'right'
}

//short form
{ view:"select", options:["Master", "Release"]}

//serversive options
{ view:"select", options:"server/data.json"}

Related sample: Select Box ('select')

Main properties

  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • options (array, object, string) - defines a set of items to select from;
  • value (string, number)
    • within options array it sets text values for select items;
    • within Select constructor it defines the initially selected item of the control (option ID in case of a full form, option text in case of a long form);

Select option, a list record, may contain:

  • a short string, like "Apple";
  • multi-line text with html tags. In this case, parent (e.g. toolbar) height should be increased.
{ view:"toolbar", height:100,elements:[
    { view:"select", options:[
        {id:1,value:"Some long multiline content<ul><li>item1</li><li>item 2</li></ul>"},
        {id:2,value:"Papaya" }
    ]}
]}

Related sample: Select Boxes


Segmented Button

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Segmented is an integral button with as many segments as you like. Can be used for switching between multiview cells.

Initialization

{view:"segmented", multiview:true, value:1, options:[
    { id:"1", value:"Section A" }, // the initially selected segment
    { id:"2", value:"Section B" },
    { id:"3", value:"Section C" }]
}

//short form for options array
{ view:"segmented", options:["Section A", "Section B", "Section C"]}

Related sample: Holistic Panel with Multiple Buttons ('segmented')

Main properties

  • multiview (boolean) - connects the control to the multiview cells, enables switching between these cells;
  • options (array, object) - defines the buttons (segments) within the control. Details;
  • value (string, number)
    • within options array it sets titles for button segments;
    • within Segmented constructor it defines the initially selected item for the control;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • selected (string) - defines the tab that will be visible initially.

Working with Segmented Button

Adding and Deleting Segments (Options) on the Go


Slider

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Slider is designed for setting a numeric value from a predefined range of values. It's done by dragging a marker to the left and to the right over the value line.

Negative values are possible.

Initialization

{ view:"slider", label:"Level", value:"20", min:10, max: 120, name:"s1"}

Related sample: Slider

Main Properties

  • value (number) - initial value of the control;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • name (string) - name of the control used to get its value in the form;
  • step (number) - distance to the next selectable value (1 by default);
  • min (number) - minimal value of a slider control. 0 by default.
  • max (number) - maximum value of the slider control. 100 by default.
  • title (template, function) - text label over the slider marker

Related sample: Slider: Custom Step.

Note that if you set min and max parameters, the initial control value should be within their range.

Slider Title

Slider Title is based on the current value of the control.

For simple title that displayes current value and static text, set a template via webix.template class:

{view:"slider", title:webix.template("Selected: #value#")}

For complex title that changes its text depending on the current value, define a function template:

{view:"slider", title:function(obj){
    var text = obj.value > 20 ? "Minimum level reached. " : ""; //title for values over 20
    return text + "Value: "+ obj.value;} //title for other values
}

Slider Events

Make use of slider events to set changing title for a drag marker:

  • onChange - a common event for all conrtol that fires each time control value changes. For slider it takes place as soon as you stop dragging the marker, which sets a new value.
  • onSlider Drag - fires each time you drag the marker over the line while paying attention to the changing value.
{view:"slider", on:{
    onChange:function(){
        this.define("title", "Final value " + this.getValue());
        this.refresh();
    },
    onSliderDrag:function(){
        this.define("title", "Dragging... Currently "+this.getValue());
        this.refresh();
    }
}}

Related sample: Slider: Labels

The new title is set with the help of define() method while current value of derived with getValue(). Read more about Changing Component properies.


Suggest List

API Reference
  • Suggest List API
  • Multisuggest API
  • Checksuggest API
  • Gridsuggest API
  • Datasuggest API

Overview

Suggest is a list of options for input controls that aids form filling by suggesting the necessary value on the base of already typed text. It is based on Webix list component.

Related sample: Suggest List for Input: Populating with Server-side Data

Suggest list can be used with the following components (should be configured separately):

  • standard HTML input;
  • Webix JS text field;
  • text editor within a component item.

Suggest list is already implemented in the following Webix components (but can be customized):

  • combo and richselect form controls;
  • combo and richselect component editors.

How does it work?

A popup window with a suggest list control appears each time you try to enter a value into the control or editor:

  • when you type something into an HTML input or Webix text and combo control.
  • when you click the richselect control;

Suggest list and Text input

When suggest list is combined with text control (editor) or HTML input its values are automatically filtered according to the letters you have already typed. You can select an item from the list to fill the input or ignore the suggest list and type you own text.

Suggest list and Combo

When suggest list is combined with combo control (editor) its values are automatically filtered according to the letters you have already typed. You can either select an option from the list or type the text to match any of the options. You cannot ignore the suggest list and enter you own text.

Suggest list and Richselect

When suggest list is combined with richselect control (editor) a popup appears the moment you click its non-editable input. You must obligatory choose some value from the list.

Suggest list values can be stored

  • on client side;
  • on server side.

Default timeout between key pressing and filtering equals to 1ms, still it can be modified by the dedicated property.

{
    view:"suggest",
    data:[..] //or url:"some.php",
    keyPressTimeout:100ms
}

Initialization

Suggest list can be initialized as:

1 . Separate view attached to an input with the help of the input property that points to the input's ID:

webix.ui({
    view: "suggest",
    input: "country4", // will be linked to 'country4' input
    data: [
        {id:1, value: "Albania"},
        {id:2, value: "Bhutan"},
    ... //list of suggest values can be as long as you wish
    ]
});

<input type='text' id='country4' value='Sweden' />"}

2 . The same-name property of JS text input, combo and richselect:

{view:"text", name:"country", label:"Country", value:"Belarus", suggest:[
        {id:1, value: "Albania"},
        {id:2, value: "Bhutan"},
        ...]
}

3 . The same-name property of JS combo and richselect and take the extensive configuration:

webix.ui({
    view:"richselect", suggest:{
        data:[
            {id:1, value:"One"},
            {id:2, value:"Two"} //options list
        ],
        ready: function(){
            $$("richselect_1").setValue(this.getFirstId()); //defines the initially visible option
        }
    }
});

Related sample: Suggest for richselect and combo

Note that you must select any value from a suggest list, since it's required by combo and richselect nature.

Loading data to Suggest list

Normally, a dataset for suggest items contains an array of objects, each of which may have the following properties:

  • id - item ID (if not set, will be generated automatically);
  • value - the property to display in suggest items (if another template is not set);
  • $empty - indicates that an item contains not data (blank item);
  • any other properties.

Suggest list with client-side data

On the client side the list with suggestions can be stored either of supported formats. It may be put directly into data property (as shown above) or in a variable declared beforehand.

Suggest List with JSON data

var countries = [
    {id:1, value: "Albania"},
    {id:2, value: "Bhutan"}
];

{ view:"text", label:"Country", value:"Belarus", suggest:countries}

Related sample: Suggest List for Input: Populating with Client-side Data

Suggest list with server-side data

At the same time, data can come from server side. All you need is to specify the script file that will get the data from the database.

As value of dataFeed property of the Suggest component

webix.ui({
    view: "suggest",
    input: document.getElementById("country4"),
    dataFeed:"server/data.php"
});

As value of suggest property

{ view:"text", name:"country", label:"Contry", value:"Albania", suggest:"server/data.php"}

Related sample: Suggest List for Input: Populating with Server-side Data

Suggest list is connected with an input field by suggest property included into the text constructor.

Suggest list for component editors

Component editors duplicate editing controls yet they are initialized within the component body.

Suggest can be initialized for combo and text editors. To do this, make the following steps:

  • create a suggest list as separate view or define its configuration in a JSON object and set options for it:
  • create a component, specify text editor type for it and link to the suggest:
var year_suggest_a = webix.ui({
    view: "suggest",
    data:[...]
});

//or
var year_suggest_a = {
    view: "suggest",
    data:[...]
};

webix.ui({
    view:"datatable",
    columns:[
        {id:"year", editor:"text", suggest:year_suggest_a}
    ]
});

Related sample: Datatable: Autosuggest

At the same time, you can provide all the logic by API, which allows customizing suggest behavior:

  • create a suggest list as separate view and set options for it:
  • link suggest list to the input field of the editor object with the linkInput method:
  • provide handlers for edit events.
var year_suggest_b = webix.ui({
    view: "suggest",
    data:[...]
});

var gridb = webix.ui({
    view:"datatable",
    columns:[
        {id:"year", editor:"text"}
    ]
});

gridb.attachEvent("onAfterEditStart", function(object){
    if (object.column == "year") { //only for editors in this column
        var editor = this.getEditor(object);
        year_suggest_b.linkInput(editor.getInput());
    }
});

gridb.attachEvent("onAfterEditStop", function(object){
    year_suggest_b.hide();
});

Related sample: Datatable: Autosuggest

Suggest list can as well be attached to combo and richselect editors, yet then it loses its status of 'adviser' and selection from it becomes compulsory.

webix.ui({
    view:"datatable",
    columns:[
        {id:"year", editor:"combo", suggest:{
            data:[...], //or url:""
            on:{
                //events
            }
        }}
    ]
});

Related sample: Datatable: Advanced Combo Editor

Customizing suggest list

Suggest list allows defining lots of custom settings in case of a long initialization pattern.

It works for a suggest defined as a standalone view:

{view:"suggest",
    //popup settings
    ...,
    body:{
        //list settings
    }
}}

As well as for a suggest defined as a control/editor property:

{view:"combo", options:{
    //popup settings
    ...,
    body:{
        //list settings
    }
}}
  • Popup settings include typical popup properties and suggest-specific ones, like fitMaster, or url and data;
  • List settings include typical list properties.

Note that an suggest list configuration can be set via either suggest or options property for richselect, combo, multiselect and multicombo controls.

Where can the customization be useful?

  • Advanced Configuration of Popup Selectors
  • Customizing built-in data editors

Sizing and positioning

Popup height

Suggest list is tuned to show maximum 10 items at a time. If there are more items, a scrollbar appears. If there are fewer item in the list, its height shrinks.

The number of items in the suggest list can be controlled by an yCount property of list object:

{view:"combo", suggest: {
    body:{
        yCount:5,
        data:[...]
    }
}}

Popup width

By default, a popup is adjusted to the width of a master control. To change it, set fitMaster property to false and define any desirable width or use the default 300px:

{view:"combo", suggest: {
    fitMaster:false,
    width:400,
    data:[...]
}}

Popup position

Suggest API offers the following variants of popup positioning in relation to the text field it's initialized for:

  • "bottom" (default). Doesn't require direct initialization;
  • "top";
  • "left";
  • "right".

Since we speak here about relative position, the property to set it has the same name:

{ view:"text", suggest:{ data:countries, relative:"left" }}

Related sample: Attaching Suggest List to Input

Advanced suggest lists

The functionality is available in Webix Pro edition only.

Webix offers advanced suggest controls for width extra functionality and greater visual effect:

  • checksuggest - a suggest control based on Webix list. Features checkboxes that enable multiple choice;
  • multisuggest - a suggest control based on Webix list with the ability to select multiple items at a time;
  • gridsuggest - a suggest control based on Webix datatable;
  • datasuggest - a suggest control based on Webix dataview.

Checksuggest

Checksuggest control is used in a number of PRO controls. You can find its implementations in:

  • multiselect form control;
  • multicombo form control;
  • multiselect datatable filter;
  • multicombo datatable filter;

Multisuggest

Multisuggest control is used in a multiselect component editor.

If needed, it can substitute checksuggest for the above-mentioned use cases. See Advanced Configuration of Popup Selectors for details.

Gridsuggest

Related sample: Grid Suggest

Gridsuggest can be used with form controls as well as with component editors. More about its configuration can be found in the related article.

Datasuggest

Related sample: Data Suggest

Datasuggest can be used with form controls as well as with component editors. More about its configuration can be found in the related article.


Tabbar

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

UI-related tabbar is an integral button that allows for changing between views in a multiview layout. Its tabs can be nested with images and icons.

Initialization

rows:[
    {view:"tabbar", id:'tabbar', value: 'listView', multiview:true, options: [
        { value: 'List', id: 'listView'},
        { value: 'Form', id: 'formView'},
        { value: 'Empty', id: 'emptyView'}]
    },
    //and then goes multiview
    {cells:[...]}
]

Related sample: Tabbar

Main properties

  • multiview (boolean)- if true, it links tabs to multiview cells;
  • options (array, object) - defines buttons for switching between views. Details;
  • value (string) -
    • within options array it sets titles for tabs;
    • within Tabbar constructor it defines the tab that will be shown initially on page loading.
  • type (string) - if set to "bottom", the tabbar gets other styling, more suitable for tabs placed under the multiview. It can be done by changing the order of layout rows;
  • close (boolean) - if true, the "close" functionality for each tab is provided. Each tab can be closed by clicking a dedicated icon on it.

Compare top and bottom tabbars in a sample:

Related sample: Panel with Clickable Items ('tabbar')

'Close' Button for Tabs

Tabs featuring a close property in the tab configuration gain the ability to be closed by clicking the dedicated "Cross" icon:

//all tabs can be closed
{view:"tabbar", close:true, options:[...]}

//only "Tab1" can be closed
{view:"tabbar", options:[
    {id:1, value:"Tab1", close:true},
    {id:1, value:"Tab2"}
]}

Related sample: Tabview: Close tab button

Tab Icons

Icons are defined through additional HTML provided within the tab value:

 { view:"tabbar", options: [
    { value: "<span class='webix_icon fa-film'></span>List", id: 'listView' }
 ]}

Related sample: Multiview Tabbar with Icons

More about different types of defining icons in Webix you can learn in the Icons with UI Components article.

Advanced Tabbar Usage
  • Adding and Deleting Tabs (Options) on the Go
  • Dynamic Tabbar


Dynamic Tabbar

Tabbar can take the following modifications:

  • Tabbar may have non-static tab width and quantity that are both changed dynamically on window resizing;
  • Tabs can be pushed to a related popup while retaining their default behavior.

Related sample: Dynamic Tabbar in Multiview

Everything is done fully automatically - when window size changes, tabs are minimized and then pushed to a popup. So following code is enough:

Default tabbar

{ view:"tabbar", options:["First tab", "Second Tab"] }

Customization

  • The minimal width of each tab is 100px by default. It is common for all the tabs of this tabbar and can be changed with the help of tabMinWidth property;
  • The minimal width of an area to the right that triggers a popup is 40px. By default an ellipsis icon is used. Both parameters can be changed:
    • tabMoreWidth sets the width of this area;
    • moreTemplate sets other icon/text/HTML of this area. Either function or string can be used;
  • The width of the popup is 200px by default. It can be changed with the popupWidth property;
  • The default number of list items in the popup is 7. It can be chaged with the yCount parameter. If there are more items in the popup, scroll will appear.
  • By default list items feature #value# template. Other template can be set by popupTemplate property.

Customized tabbar

{
    view:"tabbar",
    tabMinWidth:150,
    tabMoreWidth:80,
    moreTemplate:"Show more",
    //or moreTemplate:function(){ return "Show more" },
    popupWidth:250,
    popupTemplate:"#text#",
    yCount:10,
    options:[
        {id:1, value:"First Tab", text:"Some text for first tab"},
        {id:2, value:"Second Tab", text:"Some text for second tab"}
        ...
    ]
}

Note that options config for tabbar must comnpulsory include value property, otherwise it will render id on tabs and through an error. Still, there can be other properties that can be rendered in popup list with popupTemplate.

More info about Webix data templates can be found in the dedicated documentation article.


Text

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Ui-related text control is a one-line input field with a label.

Initialization

{view:"text", value:'dummy@email.com', label:"Email", labelAlign:'right'},
{view:"text", type:'password', value:'123pass', label:"Password", labelAlign:'right'}

Related sample: Text Input ('text')

Main properties

  • value (string, integer) - the initial value for a text field, can be editable or readonly on your choice;
  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
    • labelPosition (string) - defines label position related to the input field. The only possible value is "top";
  • type (string)- type of a text field, can be either "text" by default, or "password" or "email". Type is vital for HTML5 input data validation.
  • placeholder (string) - the initial text in the text field, disappears as you start typing in it;
  • suggest (array, string) - collection of suggest values, or the ID of an attached suggest list with these values.

Using HTML Attributes

At the same time, "text" properties can be set via an attributes object containing properties that coincide with HTML input tag properties. The object is used for HTML5 data validation.

  • attributes (object)
    • maxlength (number) - the maximum quantity of symbols that can be typed into the text field;
    • required (boolean) - indicates whether this field must be filled before the form can be submitted. False by default;
    • title (string) - a prompt message that appears on pointing cursor over the field.

The same is true for textarea.


Textarea

API Reference
  • Methods, properties and events
  • Shared functionality

Overview

Ui-related textarea control is a multi-line input field with a label.

Initialization

{ view:"textarea", label:"Note", labelAlign:"right", height:200, value: "type here" }

Related sample: Multiline Text Input('textarea')

Main properties

  • label (string) - text label of a control. It can be customized by:
    • labelAlign (string) - label alignment towards its container. Possible values are "left" and "right". In any way, it's placed left to the control;
    • labelWidth (number) - width of the label container;
  • width, height (integer) - defines the dimension of the text field;
  • labelAligh (string) - sets the position of a text label;
  • value (string) - sets the initial text in the field (replaced by input text later)
  • placeholder (string) - the initial text in the textarea field, disappears as you start typing in it;
  • attributes (object) - hash of properties. See text description for details.


Toggle

API Reference
  • Methods, properties and events
  • Controls Common Functionality

Overview

A two-state button that can be not only clicked but pressed. Hence, it has two states - pressed and unpressed (initial), which makes it look like checkbox that also has two states (checked and unchecked).

Toggle values can be defined separately for each state.

Initialization

{ view:"toggle", type:"iconButton", name:"s4",
    offIcon:"pause",  onIcon:"play",
    offLabel:"Disabled", onLabel:"Enabled"
}

Related sample: Toggle Button ('toggle')

Main properties

  • name (string) - read-only property, defining the toggle's name. It should be unique within a page;
  • label (string) - text on the button body, one and the same for pressed and unpressed states;
  • onLabel (string) - text label on the button in a pressed state;
  • offLabel (string) - text label on the button in an unpressed state;
  • icon (string) - icon for pressed and unpressed toggle states;
  • onIcon (string) - icon for a pressed toggle;
  • offIcon (string) - icon for an unpressed toggle.

Icons taken from the Font Awesome, so pick the necessary icon name at their site.

Toggle Types

Toggle type is defined by the type property. If it isn't defined, a standard button is displayed. For image toggles there exist the following types:

  • iconButton for a standard button with an icon;
  • image for an image with a left-hand label (if any);
  • imageButton for a standard button with an image and a left-hand label;
  • imageTop for a picture and a label below it;
  • imageButtonTop for a standard button with a picture and a label under the picture;
  • next for a button with a right-hand arrow;
  • prev for a button with a left-handed arrow.

Types coincide with those of a standard button. Check their look and feel in the image below:

type:"iconButton"
type:"image"
type:"imageButton"
type:"imageTop"
type:"imageButtonTop"

Related sample: Toggle Image Button ('toggle')


Grouplist

API Reference
  • Methods, parameters and events
  • Samples

Overview

Ui-related grouplist inherits from list and allows presenting data in groups. Data grouping is hierarchical, which means that any group item can start its own group. Hence, this component supports only XML and JSON data formats since they can arrange data in a hierarchical way.

Initialization

webix.ui({
    view:"grouplist",
    data:...
});

Related sample: Grouplist

Working with Grouplist

Rendering data in grouplist - template peculiarities.

1 . Single-value hierarchical dataset:

{id:"root", value:"Films data", open:true, data:[
        { id:"1", open:true, value:"The Shawshank Redemption", data:[
            { id:"1.1", value:"Part 1" },
            { id:"1.2", value:"Part 2", data:[
                { id:"1.2.1", value:"Page 1" },
                { id:"1.2.2", value:"Page 2" },
            ]},
            { id:"1.3", value:"Part 3" }
        ]},
        { id:"2", open:true, value:"The Godfather", data:[
            { id:"2.1", value:"Part 1" },
            { id:"2.2", value:"Part 2" }
        ]}
    ]}

Here we have two branches coming out from the root one, each of which having its own branches.

  • text values to display are stored in the value property;
  • for similar datasets we don't need template to define which data to display, as there's only one value per item;
  • data for a lower hierarchical level in stored in the data object;
  • initially expanded branches are defined by open property with true value.

2 . Multiple-value non-hierarchical dataset:

Far more often you'll need to display different data values on each level, which means that you'll need to set template as well as grouping pattern yourself.

{"id":1,"title":"The Shawshank Redemption","year":"1994","rank":"1"},
{"id":2,"title":"The Godfather","year":"1972", "rank":"2"},
{"id":3,"title":"The Godfather: Part II","year":"1974","rank":"3"}

Grouplist templating differs from that of other data-containing components. There're three properties to observe hierarchy:

  • templateItem - defined data that will be presented in the normal data record (that is at the end of hierarchical ladder);
  • templateGroup - defines data that will be presented in group header in the collapsed state;
  • templateBack- defines data that will be presented in group header in the expanded state;
  • templateCopy - not connected with data rendering yet defines the pattern according to which data is copied to clipboard.

Each grouping item features the $count property that stores the number of items in the group it forms.

    $$('grouplist1').getItem(id).$count;

Initial data grouping and (optionally) sorting can be set by data scheme with corresponding flags.

webix.ui({
    view:"grouplist",
    data:...,
    templateBack: "Year #value# <br> Results:#$count#",
    templateGroup:" Year #value#",
    templateItem:"#rank#. #title#",
    scheme:{
        $group:function(obj){
                return obj.year; //data is grouped by "year"
        },
        $sort:{ by:"value", dir:"desc" } //sorting by displayed values
    },                               //"year" or "rank" depending on heirarchy level
    ...
});

Related sample: List: Grouping

To learn more about rendering data through templates, data grouping and data sorting, consult related articles.

Getting Parent and Child Items

Grouplist API features the getOpenState() method to retrieve IDs of the items from the currently opened branches, both parent items IDs and that of its children.

var state = $$('grouplist1').getOpenState();
if(state){
    result = JSON.stringify(state);
    webix.message(result);
    }
};

The methods returns IDs of all the opened parents items (according to hierarchy ladder) as well as IDs of items belonging to the curretly opened branch.

Thus, the return object contains parent ID array and children array:

Hierarchical dataset state

{
    "parents":["root","1","1.2"],
    "branch":["1.2.1","1.2.2"]
}

Related sample: Getting Grouplist State

Working with Grouplist

  • Data Object Operations
  • Data Loading.
  • Defining Data Template.
  • Adding/Deleting Items.
  • Editing Data.
  • Data Filtering and Sorting
  • Selection
  • Paging
  • Adding Active Elements to Grouplist Items
  • Components Export to PNG
  • Data Components Export to Excel

Note that there's no built-in possibility to edit data with grouplist. You should create a prototype editlist object beforehand.

Related Articles
  • Sizing Components
  • Resizing
  • Redefinition of the Components
  • List
  • Unitlist
  • X-list
  • Grouplist CSS Image Map


HTMLform

API Reference
  • Methods, properties and events
  • Samples

Overview

Though the webix library has its own form component, there exists a possibility to create a separate form made with the help of pure HTML. This is done within the special htmlform component.

Initialization

There're three ways of embedding a form into the component:

1 . Through content property:

Content property may either point the ID of DIV container where the form lies or to document.body if it is included directly into your web page body.

HTMLform, content

<div id="areaA">
        <input type="text" name="title" value="" placeholder="Book title" /><br/>
        <input type="text" name="author" value="" placeholder="Author" /><br/>
</div>
<script type="text/javascript">
webix.ui({
    view:"htmlform",
    content: "areaA" //coincides with ID of a *div* container
    //or
    content: document.body // in case the form isn't included into any DIV
    ...
});
</script>

Related sample: Initialization in Document Body

2 . With the help of template property:

  • Template value may inlude the ID of a DIV container where form fields lie

HTMLform, template

<div id="tpl">
            <input type="text" name="title" value="" placeholder="Book title" /><br/>
            <input type="text" name="author" value="" placeholder="Author" /><br/>
</div>
<script type="text/javascript">
webix.ui({
    view:"htmlform",
    template: "html->tpl" //coincides with ID of a *div* container
        ...
});
</script>

Related sample: Initialization in Layout

  • or it points to external html-file with a form:

HTMLform, http

webix.ui({
    id: "htmlform1",
    view:"htmlform",
    template: "http->data/form.html",
    ...
});

Related sample: Using HTTP-template

3 . Initialization from HTML or XML markup

The initialization from XML markup is available in Webix Pro edition only.

In this case, standard rules of markup initialization are used and the markup slightly alters:

  • HTML: form tag receives new attributes;
    • data-view to indicate the component (here it is an htmlform);
    • standard htmlform properties with 'data' prefix (data-id, data-height, etc.);
  • XML: There're special tags with 'x:' prefix:
    • < x:ui > to indicate a webix UI constructor
    • < x:htmlform > to indicate a component you want to init.

Form elements are created accirding to standard HTML.

HTMLform, HTML markup

<form data-view="htmlform" data-id="htmlform1" data-height="350">
    <input type="text" name="title" value="" placeholder="Book title" /><br/>
    ...
</form>

HTMLform, XML markup

<html xmlns:x>
    <x:ui>
        <x:htmlform id="htmlform1" height="350">
            <input type="text" name="title" value="" placeholder="Book title" /><br/>
               ...
        </x:htmlform>
    </x:ui>
</html>

Script part of the document includes the initializing code:

webix.ready(function(){
    webix.markup.init(document);
});

Regardless of the initialization pattern, all the commom HTMLform functions work fine:

Related sample: HTML initialization : HTML form

4. Initialization from an external file loaded by Ajax.

webix.ui({
    view:"htmlform",
    src:"myform.php",
    ...
});

Working with HTMLform
  • Data Validation
  • Form and Htmlform Treatment
  • File Uploading with Form
  • Data Binding

Sending Form Data

Form data can be sent to server in either of the following ways:

1 . Using Webix Ajax helper:

webix.ajax().post("some.php", form.getValues());
//with callback
webix.ajax().post("some.php", form.getValues(), function(text, data, xhr){ });

2 . Using webix.send method that emulates HTML form submitting:

webix.send("come.php", form.getValues());

3 . Indirectly, via the bound master component or DataCollection:

The method is good when the form is used for editing the data of the main component (datatable, tree, list, etc.). In this case not the form data matters but the data of the main component. Form saves the data to the master component while the master handles the serverside part.

//data from selected list item is pushed to the form
form.bind(list);

//pushes the data back to list item
form.save()

Data binding concept is described in a separate documentation article.

Related Articles
  • UI-related Form
  • Initializing from HTML and XML


IFrame

API Reference
  • Methods, properties and events
  • Samples

Overview

Ui-related IFrame is a component that helps include an i-frame, or 'inline frame' into the page. Basically, it's a floating frame on the webpage that contains an external web document. The component, as a rule, is smaller than the page it's added into, so vertical and horizontal scrollbars appear.

You can insert more than one IFrame into the view provided that you initialize a switching control for them.

The component inherits from view.

Initialization

webix.ui({
    view:"iframe", id:"frame-body", src:"data/pageA.html"
});

Related sample: IFrame

  • src (path) - defines external site url.

Working with IFrame

Data loading

The url to show in the iFrame can be defined

  • as value of the src property (shown above);
  • as parameter of the load method.
$$("frame-body").load("http://google.com")

Switching between iframes in a single view

Simply put, this is the basics of multiview functionality.

Make use of any of the integral buttons (segmented or tabbar) to enable switching. The values for button options will be necessary URL-s.

{ view:"segmented", id:"control", options:[
    { id:"data/pageA.html", value:"pageA"},
    { id:"data/pageB.html", value:"pageB"}
]}

Then, attach a switching function to the button. The event referring to a tab mouse click is called "onAfterTabClick".

$$("control").attachEvent("onAfterTabClick",function(sid){
    $$('frame-body').define("src", sid);
});

The event fires on clicking any tab, takes its ID (sid) as parameter and sets the source for external webpage equal to this ID.

Related Articles
  • Sizing Components
  • Redefinition of Components
  • Event Handling
  • Multiview


Layout and Resizer

API Reference
  • Methods, parameters and events
  • Samples

Overview

Layout is a concept element that doesn't contain anything in itself yet determines the way 'meaningful' components are arranged. It divides the page into rows and columns where all other components are placed.

Initialization

Layout consists of rows and columns separated from each other by borders (except for a borderless layout). Rows contain an array of view objects arranged horizontally while cols is an array of vertically arranged objects. Border setting and border types are described in the corresponding chapter of the manual.

webix.ui({
    container:"layout_div",
    id:"mylayout",
    type:"space",
    rows:[
        {...},
        {cols:[
            {...},
            {...}
        ]}
    ]
})

Related sample: Layout

When setting layout, you can easily omit the view:"layout" line and start setting rows and cols at once:

webix.ui({
    type:"wide",
    rows:[
        {...}, {...}
    ]
});
  • Container property defines the ID of a DIV element where you place the layout. Though it is an optional parameter, it makes sizing and positioning simpler.
  • Layout ID should be specified if you are going to work with it later.

Horizontal and Vertical Layout

Horizontal layout:

Three-row layout

webix.ui({
    container:"layout_div", //corresponds to the ID of the div block
    rows:[
        { template:"row 1" }, //here you place any component you like
        { template:"row 2" },
        { template:"row 3" }
    ]
});

Vertical layout:

Three-column layout

webix.ui({
    container:"layout_div", //corresponds to the ID of the div block
    cols:[
        { template:"col 1" }, //here you place any component you like
        { template:"col 2" },
        { template:"col 3" }
    ]
});

Complex layout

Any row can be divided into columns and any column may contain rows. This is how simple layouts are nested into each other:

webix.ui({
    container:"layout_div", //corresponds to the id of the div block
    rows:[
        {template:"row 1"}, //here you place any component you like
        {template:"row 2"},
        { cols:[
            { template:"col 1" },
            { template:"col 2" },
            { template:"col 3" }
        ]}
    ]
});

Related sample: Limits on Resizing

Resizer Lines

With this library you can make draggable border, or so-called, resizer lines between layout rows and columns. The resizer line can be moved in both directions and change the dimensions of the components on both sides of it.

Resizer lines don't actually change the component's size. They only help users adjust the component's visual scheme to their needs.

It's recommended to set minWidth and maxWidth parameters for columns subject to resizing (minHeight and maxHeight for the rows). It prevents them from collapsing as when the minimal width or height value is achieved, the resizer line cannot be moved anymore.

webix.ui({
    container:"layout_div",
    id:"layout",
    rows:[
        {...}, //1st row, non-resizable
        {...}, //2nd row
        {view:"resizer"},
        {...}, //3rd row
        {view:"resizer"},
        {cols:[  //4th row
            { // 1st column
                width:150,
                minWidth:50,
                maxWidth:250
            },
            {view:"resizer"},
            {....}, //2nd column
            {....} //3rd column
        ]}
    ]
})

Related sample: Layout and Resizer

Responsive layout behavior depending on window/screen size is discussed separately.

Headers

Check how to make headers for different components here.

webix.ui({
    rows:[
        {   view:"template", //optional
            template:"Header for Column 1",
            type:"header"
        },
        {...}
    ]
})

Related Articles
  • Sizing Components
  • Resizing
  • Setting Borders to the Components
  • Adding Headers to Components
  • Multiview
  • Accordion
  • Scrollview
  • Carousel
  • Layout CSS Image Map


Available only in PRO Edition

Absolute Layout

The abslayout view presents a layout that allows specifying the exact location of elements inside it, without using usual rows/columns configuration.

The child elements are placed into layout's cells and their sizes are set by hardcoded values. For each child view the exact top and left positions should be specified:

webix.ui({
    container:"layout_div",
    view:"abslayout",
    cells:[
        { view:"text", label:"Name", labelAlign:"right",
            top: 100, left:350, width:200, height: 40 },
        { view:"text", label:"Email", labelAlign:"right",
            top: 100, left:550, width:200, height: 40 },
        { view:"textarea", label:"My text box", labelPosition:"top",
            top: 140, left:100, width:650, height: 100 },
        { view:"button", label:"My text box",
            top: 260, left:260, width:400, height: 40 }
    ]
}).show();

Related sample: Layout with Absolutely Positioned Elements


Available only in PRO Edition

Data Layout

The "datalayout" view is based on Layout and operates the datastore API.

It's intended for creating complex data structures, e.g. big lists with dynamic data subloading, multipage forms, etc. and allows placing several data components into one layout.

Simple mode

In order to create a simple data layout, you need to define an empty rows or cols collection that will define the arrangement of elements on the page (vertical or horizontal).

Then place configurations of the necessary views into the data configuration object. For example, a datalayout can contain several templates:

webix.ui({
    view:"datalayout",
    type:"space",
    rows:[],
    data:[
        { id:"a1", template:"A1", type:" header" },
        { id:"a2", template:"A2", type:" header" },
        { id:"a3", template:"A3", type:" header" },
        { id:"a4", template:"A4", type:" header" }
    ]
});

Pay attention that in the above example the view:"template" definition is omitted for simplicity, as specifying the view type as "template" is optional.

Related sample: Data Layout

Repeater mode

To create a more complex structure, you should specify a common template for datalayout elements as a value of its rows/cols property. It will be applied for each layout element (a row or a column).

webix.ui({
    view:"datalayout",
    type:"space",
    rows:[
        { name:"$value", type:"header", template:"#month# 2016" },
        { name:"data", view:"list", template:"#income#, #count#" }
    ],
    data:[
        { month:"January",
          data:[
            { income: 122342, count:12 },
            { income: 92342, count:8 },
            { income: 222342, count:20 }
          ]
        },
        { month:"February", data:[{ income: 2342, count:2 }] }
    ]
});

In the above example, the rows collection contains a common template that defines that two views will be shown in each datalayout element: a template view for the header and a list with data.

Each view in datalayout has the name property that defines which data elements will be passed to the view. This property can have one of the two values:

  • "$value" - presupposes that the whole data item is passed to the view, and a view "decides" what data property should be displayed;
  • "some_property" - implies that the value of a particular property in the data item will be passed and displayed in the view.

The view displays the passed data in the following way:

1) If the view is a data component, the passed data will be parsed into the view;

2) If the view is a single-value component (e.g. a label or a button), the passed data will be used as a value of this view.

Related sample: Data Layout - Repeater Mode

Loading data

Data can be loaded into datalayout in the same way as into any other data component, i.e. by:

  • parsing from a string or an array:
webix.ui({
    view:"datalayout",
    type:"space",
    rows:[
        { name:"$value", type:"header", template:"#month# 2016" },
        { name:"data", view:"list", template:"#income#, #count#" }
    ],
    data:[
        { month:"January", data:[{ income: 122342, count:12 }] },
        { month:"February", data:[{ income: 2342, count:2 }] }
    ]
});
  • loading from an external file by means of the load method or the url property:
webix.ui({
    view:"datalayout",
    id:"data",
    type:"space",
    rows:[
      { name:"$value", type:"header", template:"#month# 2016" },
      { name:"data", view:"list", autoheight:true, template:"#income#, #count#" }
    ],
    url:"data/data.js"
});

The details are given in the article Data Loading.

Operations with data

You can perform usual operations with data of Data Layout, e.g. add, update, remove elements:

  • adding new elements into layout
$$("data").add({
  "month":"April", "data":[{"income":5894,"count":4}, {"income": 1458, "count":2}]
});
  • getting and updating elements
var last = $$("data").getItem($$("data").getLastId());
if(last){
    last.month = "Hello, December";
    $$("data").updateItem(last.id, last)
}
  • removing elements
var first = $$("data").getFirstId();
if(first)
 $$("data").remove(first);

Related sample: Data Layout - CRUD operations

Complex Data Layout

You can also create a complex data layout with nested rows and columns. It can be implemented like this, for example:

Specify the layout you want to embed into the datalayout:

var subconfig = {
    isolate:true,
    rows:[
        { view:"toolbar", elements:[
            { view:"button", value:"Add record", width: 120 },
            { view:"label", name:"month" }
        ]},
        { cols:[
            { id:"l1", name:"data", view:"list", template:"#income#" },
            { },
            { id:"l2", name:"data", view:"list", template:"#count#" }
        ]}
    ]
};

Define the config of the datalayout and specify the sublayout in the rows collection. Set the datasource as well:

webix.ui({
    view:"datalayout",
    id:"data",
    type:"space",
    rows:[
        subconfig
    ],
    url:"data/data.js"
});

Related sample: Data Layout - Complex structure operations


List

API Reference
  • Methods, properties and events
  • Samples

Overview

List is a ui-related component that inherits from view and presents listed data items. The webix library offers three variations of list apart from the standard one - grouplist, x-list and unitlist.

Initialization

webix.ui({
    view:"list",
    template:"...",
    data:..//variable || path || dataset
});

Related sample: List

You can load data in any of the supported data formats.

Working with List
  • Data Object Operations
  • Data Loading.
  • Defining Data Template.
  • Adding/Deleting Items.
  • Editing Data.
  • Data Filtering and Sorting
  • Selection
  • Paging
  • Adding Active Elements to List Items
  • Components Export to PNG
  • Data Components Export to Excel

Note that there's no built-in possibility to edit data with List. You should create a prototype editlist object beforehand.

Related Articles
  • Setting Dimensions for the Components
  • Dynamic Resizing and Adjustment
  • Redefinition of the Components
  • List CSS Image Map


X-list

Overview

UI-related x-list inherits from list and differs from it in the way of data presenting: while all lists arrange items vertically, x-list offers the horizontal pattern.

Related sample: Horizontal List

Initialization

webix.ui({
    view:"list",
    scroll:"x",
    layout:"x", // responsible for horizontal arrangement
    select:true,
    data: ...
});

Working with X-list
  • Data Loading.
  • Defining Data Template.
  • Adding/Deleting Items.
  • Editing Data.
  • Data Filtering and Sorting
  • Selection
  • Paging
  • Adding Active Elements to List Items

Note that there's no built-in possibility to edit data with list. You should create a prototype editlist object beforehand.

API Reference

Methods, properties and events

Related Articles

  • Sizing Components
  • Resizing
  • Redefinition of the Components
  • List
  • Unitlist
  • Grouplist
  • XList CSS Image Map


Menu

API Reference
  • Methods, properties and events
  • Samples

Overview

UI-related pulldown Menu inherits from list and lets users select the necessary item from the list of grouped items (submenus). Each element of a submenu can start its own submenu.
A dynamic Submenu becomes visible only when you put a mouse pointer over the corresponding item of the main menu (on 'onMouseOver' event) and hides as soon as you remove mouse pointer ("onMouseOut").

Initialization

Menu object is stored in the data property.

webix.ui({
    view:"menu",
    id:"my_menu",
    subMenuPos:"right",
    layout:"y",
    data:[ //menu data
        { value:"Translate...", submenu:["English", "Slavic...", "German"]},
        { $template:"Separator" },
        { value:"Post...", submenu:[ "Facebook", "Google+", "Twitter" ]}
    ],
    type:{
        subsign:true,
        height:50
    }
});

Related sample: Basic Menu

Submenu configuration may include:

  • subMenuPos (string) - sets position of pulldown submenus that will appear on mouse over;
  • submenuConfig (object) - sets common configuration for all the submenus in this menu regardless of their nesting level;
  • layout (string) - sets the arrangement of menu items: x (default) for a horizontal menu, y for a vertical one;
  • $template (string) - flag that indicates a separator between groups of menu items. Possible types are as follows:
    • "Separator" - a grey separating line;
    • "Spacer" - an empty item with white background that doesn't change on mouse over.
  • type - object that contains setting for menu items, namely:
    • subsign (boolean) - sets an arrow for an item containing a submenu;
    • height and width (number) of each item;
  • openAction (string) - alters the way of submenu opening - "click". If set, you should first click a menu item to enable submenu opening and hiding on "onMouseOver" and "onMouseOut" events. To hide submenus, you need to click somewhere outside the menu;
  • template - (string, function) - rules of data presentation. See Data templates article for details;
  • data (object) - the inline data desired format. See Loading data article for details
  • autowidth - (boolean) adjusts the width of pulldown subitems according to the length of their text, false by default

Related sample: Showing Menu on Mouse Click (dropping down on hover is disabled)

Working with Menu Items

Configuring Menu Items

A menu/submenu item can be a text item including the one that starts its own submenu and any Webix component specified by ID.

Menu items are stored in the data array, each item being an object. Submenu items are stored in the submenu array. Each menu item may have the following attributes:

  • id - item id.If omitted, it's given an auto-generated one;
  • value - defines text value for an item;
  • href - defines a link for an item;
  • config - defines configuration of a child submenu popup (if any). The configuration overrides the one defined via submenuConfig;
  • badge - sets an orange information circle that notifies about the number of new activities for this menu item (e.g. messages).

The easiest way to define menu items is to pass them as a simple array:

{ view:"menu", data:["Google", "Facebook", "Twitter"] }

Or an associative one:

{ view:"menu", data:[
    { id:1, value:"Google"},
    { id:2, value:"Facebook"},
    { id:3, value:"Twitter"}
]}

Links in Menu Items

Each menu and submenu item can be supplied with a link specified in the data object by href and target (optional) attributes:

view:"menu",
data:[
    { id:"1", value:"Imitation of Spenser", href: "#verse1", target:"_blank"},
    { id:"2", value:"The Human Seasons", href: "#verse2"}
]

If not specified, target will be set as empty string.

Related sample: Menu hrefs

Badges in Menu Items

Badges add info circles to menu items with the number of entities you'd like to associate with this or that item (e.g. messages):

view:"menu",
data:[
    { id:"1",value:"Translations", badge:"1"},
    { id:"2",value:"Posts", badge:"12" },
    { id:"3",value:"Info", badge:"24" }
]

Related sample: Menu with Badges

Separators in Menu

To separate one group of items from another one in vertical menu, use the property $template with one the possible values:

  • "Spacer" - adds horizontal space between menu items;
  • "Separator" - add a horizontal grey line between menu items.

Spacer in vertical menu

view:"menu",
layout:"y",
data:[
    { id:"1", value:"Translations", icon:"qrcode", badge:20 },
    { id:"2", value:"Posts", icon:"file-word-o", badge:3 },
    { $template:"Spacer" },
    { id:"3", value:"Help", icon:"support"},
]

Related sample: Vertical Menu

Separator in vertical menu

view:"menu",
layout:"y",
data:[
    { value:"Translate..." },
    { value:"Post...", submenu:[ "Facebook", "Google+", "Twitter" ]},
    { $template:"Separator" },
    { value:"Info" }
]

Related sample: Basic Menu

Customizing Submenus

Submenu items can be set as an array of values:

{ id:"2",value:"Translate...", submenu:[ "English", "Slavic", "German" ]},

Or, as an array of menu objects:

{ id: "1.2", value:"Slavic...", submenu:[
    {id: "1.2.1", value:"Belarusian"},
    {id: "1.2.2", value:"Russian"},
    {id: "1.2.3", value:"Ukrainian"}
]}

Any nested submenu (a popup) can be configured separately with the help of a config attribute of its parent:

view:"menu",
submenuConfig:{
    width:400
},
data:[
    { id:"2",value:"Custom...",
        config:{
            width:500,
            on:{
                onItemClick:function(id){
                    webix.message("Submenu click: "+id);
                }
            }
        },
        submenu:[ "Facebook", "Google+", "Twitter" ]
     }
]

This configuration overrides common configuration for submenus defined by submenuConfig.

Related sample: Configuring Submenus

Automatic setting of Submenus' width

To change the width of Submenus automatically, according to the length of their labels, use the autowidth property with the true value in the menu's configuration:

webix.ui({
    container:"areaA",
    view:"menu",
    autowidth:true,
    data:[
        { id:"1",value:"Short...",
            submenu:[ "FB", "G+", "TW" ]},
        { id:"2",value:"Medium...",
            submenu:[ "Facebook", "Google+", "Twitter" ]},
        ...
    ]
});

Related sample: Autowidth for Submenus

Webix Component as Menu Item

Submenu parameter may point as well to any Webix component that has been initialized previously:

webix.ui({
    id:"details1",
    view:"context", width:300, height:200,
    body:{ content:"html1" }
});

webix.ui({
    view:"menu",
    data:[
        { value:"HTML 4", submenu:"details1" },
        { value:"HTML 5", submenu:"details2" }
    ]
});

Related sample: HTML Elements as Menu Items

The same way you can initialize Webix submenu component separately and then point to it within submenu property:

webix.ui({
    view:"submenu", id:"test", data:[
        { id:"1.1", value:"English"},
        { id:"1.3", value:"German"}
    ]
});

webix.ui({
    view:"menu",
    data:[
        { id:"1", value:"Translate...", submenu:"test"},
        { id:"2", value:"Post..."
    ]
});

Each submenu item can take its own submenu component.

MenuBar

Menu takes after a toolbar in appearance, so the best way to create a menubar is to initialize menu and toolbar in neighbouring columns:

webix.ui({
    cols:[ menu, toolbar ]
});

Related sample: Menu in Toolbar

Hiding and Disabling Menu Items

Hiding

To hide and show menu item, you should apply hideItem() and showItem() to the menu component while specifying item ID as function parameter.

The event that triggers function execution can be checkbox state change in the Webix tree populated with the same data as menu, provided that checkbox item ID = related menu item ID.

$$("tree1").attachEvent("onItemCheck",function(id,state){
    if (state) //if checked
        $$("top_menu").hideItem(id);
    else
        $$("top_menu").showItem(id);
});

As a result, only "unchecked" menu items are shown.

Related sample: Hiding Menu Items

Disabling

To disable menu item, you should apply special disableItem() and enableItem() functions to menu passing ID of the necessary item into them. The methods can be triggered by changing state of a checkbox which ID equals to the ID of the corresponding menu item.

$$("tree1").attachEvent("onItemCheck",function(id,state){
    if(state) //if checked
        $$("top_menu").disableItem(id);
    else
        $$("top_menu").enableItem(id);
});

In essence, disabling and enabling is performed via CSS classes, that's why menu items get a template that helps display normal and disabled item differently:

view:"menu",
template:function(obj){
    if(obj.disabled)
        return "<span class='disabled'>"+obj.value+"</span>";
    return obj.value;
}

Related sample: Disabling Menu Items

Event Handling with Menu and Submenu Items

All menu and submenu items can be accessed by their IDs.

1 . Any item can be accessed directly with getMenuItem() method that takes item ID as parameter and returns item object:

//getting menu item value by its ID
$$('menu1').getMenuItem(id).value;

Related sample: Basic Menu

2 . At the same time, menu items can be derived through submenu object returned by getSubMenu() method for an item with the specified ID. If there's no submenu for an item - an object of the calling component will be returned.

var menu = $$("menu1").getSubMenu(id);
var item = menu.getItem(id).value;

Related sample: HTML Elements as Menu Items

Both methods can be used in either of menu inner events, for instance, click events:

  • onMenuItemClick - fires on clicking all menu items regardless of hierarchy level. Ignores disabled items;
  • onItemClick - standard event that fires on clicking any item of the same hierarchy level. Fires for disabled item as well.

General "onMenuItemClick" handler

view:"menu",
data:[...],
on:{
    onMenuItemClick:function(id){
        webix.message("Click: "+this.getMenuItem(id).value);
    }
}

Related sample: Basic Menu

Submenu specific "onItemClick" handler

view:"menu",
data:[
    { id:"1",value:"Custom...",
        config:{
            width:250,
            on: { onItemClick:function(id){
                webix.message("Submenu click: "+id);
            }}
        },
        submenu:{...}
    }
]

Related sample: Configuring Submenus

Related Articles
  • Event Handling
  • ContextMenu
  • Menu CSS Image Map


Multiview

API Reference
  • Methods, properties and events
  • Samples

Overview

Multiview helps you efficiently use space on the page by placing different views into one and the same area. Only one view is visible at a time. The others are accessible with the help of dedicated buttons.

Multiview inherits from layout and if combined with a switching control like a tabbar, forms a tabview.

Initialization

Multiview with three views

webix.ui({
  view: "multiview",
  cells: [
    {id: "listView", view: "list", .... },
    {id: "formView", view: "htmlform", .... },
    {id: "emptyView" }
  ]
});

Related sample: Multiview Tabbar with Icons

The direct initialization of the component (view:"multiview") is optional and you can just init cells and the view will be automatically recognized.

webix.ui({
  cells:[
    {id: "listView", view: "list", .... },
    {id: "formView", view: "htmlform", .... },
    {id: "emptyView"}
  ]
});

Working with Multiview

Adjusting tab dimensions

The dimensions of multiview cells are adjusted to their content. By default, the whole multiview (all the cells) take the size of smallest cell. To adjust it to the biggest cell, use fitBiggest property:

webix.ui({
  view: "multiview",
  cells: [
    ...
  ],
  fitBiggest:true
});

Managing animation

My default multiview cells are switched with horizontal animation of a "slide" type. To disabled animation, or chnge animation type, configure the animate property:

webix.ui({
  view: "multiview",
  cells: [
    ...
  ],
  animate:false
});

Related sample: Disabling Animation

Learn more about animation types in the Animation article.

Switching between views

1 . Tabbar and Segmented Integral Buttons.

Here switching is implemented with the help of special library controls that have built-in switching functionality as soon as they are bound with multiview cells by ID of these cells.

2 .Tabview Functionality.

Multiview built-in means of changing the view cells. Look very much like the tabbar from the previous point.

3 . Functions for Switching Actions.

Here you use common methods (show and back) and create custom buttons each of which can take you to the necessary view. Show() method in conjunction with its counterpart hide() are as well used for changing visibility of UI components.

Saving inactive views

When dealing with iframe content, e.g. WYSIWYG editors (CKEditor), Multiview removes inactive views when they become hidden.

To solve this problem, set the keepViews config property to true.

webix.ui({
  view: "multiview",
  cells: [
    ...
  ],
  keepViews:true
});

History API

Learn how to "memorize" the currenty opened tab in the related article.

Related Articles
  • Sizing Components
  • Resizing
  • Setting Borders to the Components
  • Controls
  • Tabview Functionality
  • Layout
  • Scrollview
  • Accordion
  • Carousel


Controls to Switch Between View Cells

There are two buttons to switch between multiview cells at your disposal - tabbar and segmented.

Table 1 Switch controls
view:"segmented"
view:"tabbar"
view:"tabbar", multiview:true

Both of them are integral buttons that can contain as many options as you need. It is the option values that are connected to the IDs of multiview cells, which enables switching.

The difference between the buttons lies in their design. See Controls Guide to learn more about them.

In case of three views you should make three switching possibilities, i.e put three elements into the options array of either of the stated controls. Make sure that option IDs correspond to the IDs of the view cells. It ensures that every time you click on the necessary tab/button segment, the view changes to the corresponding one.

Note that you don't need to attach "switching" functions to the tabs. Everything is done automatically as soon as you set the multiview parameter to a true value.

webix.ui({
    rows:[
        { cells:[ {id:"listView", ... },
             {id:"formView", ... },
             {id:"emptyView", ... }]
        },
        { view:"tabbar", value: 'listView', multiview:true,
            options: [
                {value: 'List', id: 'listView'},
                {value: 'Form', id: 'formView'},
                {value: 'Empty', id: 'emptyView'}
             ]
        }
    ]
});

Related sample: Tabbar

The initially visible tab is set by the tabbar/segmented value property that contains the ID of the necessary tab.

Related Articles

  • Tabview Functionality
  • Functions to Control Switching


Common Functions to Switch Between Views

When switching views programmatically, you can refer either to the cells and view in them or to the switching controls.

Setting Value for the Tabbar/Segmented/Tabview

Either of the controls as well as tabview have common initialization pattern where tabs are stored in the options array:

{view:"tabbar", id:"tabbar1", multiview:true, options:
        [{id:"1", value:"Tab1"}, {id:"2", value:"Tab2"}]
}

Tabs are connected to the multiview cells, so if you set the value for button, the dedicated view will be opened:

$$("tabbar1").setValue("2"); //the 2nd tab with "Tab2" value will be set

Showing the Necessary View

These functions are used to show the specified view:

  • show(); - makes the specified view visible. Is called from the needed view;
  • back(); - switches to the view you've come from. Is called from the multiview object.

To enable switching between views you can:

  • make use of a JS button from this lib or a standard HTML button and attach the function to it;
  • trigger the switching function on any event in the app. For instance, "onItemClick" event allows clicking any component (not necessarily a button) and make the specified view visible.

Two-Cell Multiview

webix.ui({
    view:"multiview",
    id:"views",
    cells:[
        { id:"listView", view:"list" },
        { id:"formView", view:"form" }
           ]
 })

 //html button
 <input type='button' onclick='$$("cell_a").show()' value="show cell A">

//list item clicking enables the switching
$$("listView").attachEvent("onItemClick",function(id){
        $$('formView').show();

//back navigation - fires alongside with a form-saving function
function save(){
        $$("formView").save();
        $$("views").back();
       }

Related sample: 'Show/Back' Navigation

Nested Multiview

If a cell is a multiview itself, i.e. contains several cells of its own, the switching function requires true argument to get to these lower-level views.

rows:[
     { cells:[ //1st cell
              {
               id:"listView",
               view:"list"},
              {
                id:"chartView", //2nd cell
                cells:[
                     {
                      view:"chart", 1st sub-cell
                      type:"bar"},
                      {
                        view:"chart", //2nd sub-cell
                        type:"donut"}
                      ]
              }
           ]
     }]

To switch from listView to any of ChartView cells, you need to call the show(true); function:

<input
    type='button'
    onclick='$$("chart1").show(true)'
    value="show chart1 and parents"
>

At the same time, if you switch between chart1 and chart2 that lie on the same level, you needn't refer to the parent view and can do with the show(); function.

Related sample: Nested Multiviews

Related Articles

  • Tabview Functionality
  • Controls to Switch Between View Cells


Available only in PRO Edition

Organogram

API Reference
  • Methods, properties and events
  • Samples

Overview

Organogram is an organizational chart component that can be used for creating hierarchical diagrams representing relations between people in an organization or showing different elements of some complex structure.

It inherits API from TreeStore and DataStore. The component's appearance can be easily customized. The component items can include various HTML-elements, e.g. photos, and can be styled according to the user's needs.

Creating Organogram

  • Initializing Organogram on a page
  • Loading Data into Organogram
  • Selecting Items
 Teaches you how to create Organogram on the page, adjust it and load with data.

Look-and-feel

  • Customizing Organogram
  • Styling Organogram
 Covers techniques for fine-tuning the Organogram appearance: applying templates, customizing chart items, styling the component.

Others

  • Event Handling with Organogram
  • Organogram General How-Tos
 Discusses event handling with Organogram and the most obvious points of the component's customization.


Available only in PRO Edition

Initializing Organogram on a page

A new HTML file and related code files

To begin with, create a new HTML file and include the related Webix code files in it.

Required code files are:

  • webix.css
  • webix.js

A basic html page with the included code files

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Organogram</title>
    <script src="../codebase/webix.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="../codebase/webix.css" type="text/css" charset="utf-8">
</head>
<body>
    <script>
        //here you will place your JavaScript code
    </script>
</body>
</html>

Placing Organogram on a page

Next, you should create a div container to place your organogram into.

<div id="box" style="width:900px;height:450px;"></div>

Object constructor

Now you can initialize the component. To create a new Organogram object, you need to use the next constructor:

Organogram constructor

orgChart = new webix.ui({view:"organogram"});

If you want to place the component into the container, you should specify the container property inside of the view constructor:

Basic Organogram configuration

orgChart = new webix.ui({
    container:"box",
    view:"organogram"
});

Related sample: Organization Chart


Available only in PRO Edition

Loading Data into Organogram

Webix Organogram can get data in the following predefined data formats:

  1. JSON (default);
  2. XML.

Details and examples of data formats in tree-like structures

JSON

[
    { id:"1", value:"Manager", data:[
        { id:"1.1", value:"Store Manager" },
        { id:"1.2", value:"Office Assistant" , data:[
            { id:"1.2.1", value:"Dispatcher", data:[
                { id:"1.2.1.1", value:"Drivers" }
            ] }
        ] }
     ]}
]

XML

<data>
    <item id="1" value='Manager'>
        <item id="1.1" value='Store Manager'></item>
        <item id="1.2" value='Office Assistant'>
            <item id="1.2.1" value='Dispatcher'>
                <item id="1.2.1.1" value='Drivers'></item>
            </item>
        </item>
    </item>
</data>

There are two main ways you can specify the data source for Organogram:

  1. Define the data set in the object initialization;
  2. Use parse or load methods.

Both methods lead to the same result.

If you load XML data you need to set the datatype property in the constructor config or the second parameter of the parse / load method to the name of the expected data type, i.e. 'xml'.

Loading from inline dataset

If you want to specify the data set directly on the page, you can use:

  1. property data
  2. method parse

Specifying data inline

chart_data = [
    {id:"root", value:"Board of Directors",  data:[
        { id:"1", value:"Managing Director", data:[
            {id:"1.1", value:"Base Manager", data:[
                { id:"1.1.1", value:"Store Manager" },
                { id:"1.1.2", value:"Office Assistant", data:[
                    { id:"1.1.2.1", value:"Dispatcher", data:[
                        { id:"1.1.2.1.1", value:"Drivers" }
                    ] }

                ] },
                { id:"1.1.3", value:"Security" }
            ]},
            { id:"1.2", value:"Business Development Manager", data:[
                { id:"1.2.1", value:"Marketing Executive" }
            ]},

            ...
        ]}
    ]}
];

var orgChart = new webix.ui({
  view:"organogram",
  ...
  data: chart_data
});

//or
orgChart.parse(chart_data)

Related sample: Organization Chart

Loading from a data file

To load data from a file on the server, you can use:

  1. property url
  2. method load

Remember, in case of XML data you should specify the data type explicitly as 'xml':

orgChart = new webix.ui({
  view: "organogram",
  ...
  url: "data/data.xml",
  datatype: "xml"
});
//or
orgChart.load('data/data.xml', 'xml');

Loading from a database

As the Organogram component is based on the TreeStore, you can also load data from a database on the server. For the details, read the article Loading Data into Tree.


Available only in PRO Edition

Selecting Items

You can select items within the Organogram component.

By default, selection is disabled in Organogram. To activate it you should set the select parameter to true.

Enabling selection in Organogram

orgChart = new webix.ui({
  view: "organogram",
  ...
  select: true
})

Related sample: Organization Chart

Related methods

getSelectedId | method | returns the selected cells ids
select | method | selects the specified item
selectAll | method | selects all items
isSelected | method | checks whether the specified item is selected or not
unselect | method | cancels selection of the specified item
unselectAll | method | removes selection from all items

Related events

onAfterSelect | event | fires after a cell is selected
onBeforeSelect | event | fires before a cell is selected
onSelectChange | event | fires when selection is changed in DataTable


Available only in PRO Edition

Customizing Organogram

The dimensions of items in Organogram, their arrangement and content, as well as the position of the component in relation to the container can be customized with the help of the item type.

Common configuration

The following properties can be set in the type to customize the whole component:

  • autowidth - boolean, adjusts the container to fit the chart width
webix.ui({
    view: "organogram",
    autowidth: true,
    ...
});
  • autoheight - boolean, adjusts the container to fit the chart height
webix.ui({
    view: "organogram",
    autoheight: true,
    ...
});

Items configuration

The appearance of Organogram items can also be changed by setting the following properties in the type parameter:

  • lineColor - color of the line that connects items in organogram
webix.ui({
    view: "organogram",
    type: {
        lineColor: "#90caf9"
    },
    ...
});
  • width - the width of an item in pixels, must be a fixed number
webix.ui({
    view: "organogram",
    type:{
         width: 120
    },
    ...
});
  • height - the height of an item, "auto" by default, fits to the content's height
webix.ui({
    view: "organogram",
    type:{
       height: 100
    },
    ...
});
  • padding - the space between the organogram and the container borders
webix.ui({
    view: "organogram",
    type:{
        padding: 20
    },
    ...
});
  • marginX - horizontal space between two items
webix.ui({
    view: "organogram",
    type:{
        marginX: 20
    },
    ...
});
  • marginY - vertical space between two items
webix.ui({
    view: "organogram",
    type:{
        marginY: 20
    },
    ...
});
  • template - defines inner html for each item, "#value#" by default
{
    template: webix.template("#value#")
}

If you want to set any other html content for some item you should redefine the template property. For example, let's set images for chart items:

var orgChart = new webix.ui({
    container:"testA",
    view:"organogram",
    template: function(obj){
        var image = obj.img;

        if(image){
            html = "<img src='"+image+"' class='photo'>";
        }
        return (image||"")+obj.value;
    }
});

You can also apply a custom template to specify elements of the list. Let's mark the list items by the mark ">". To parse this sign correctly, we will set it as a "&gt;" html character code.

var orgChart = new webix.ui({
    container:"testA",
    view:"organogram",
    template: function(marks){
        var html = "";
        if(marks && marks.list_item){
            html = " &gt; ";
        }
            return html;
    }
});

Related sample: Templates

Creating list blocks

There's a possibility to make a list block inside of an item.

To create a list block, you need to specify the $type property with the value "list" in the parent of the items that you want to turn into a list.

Let's have a look at the organogram in the above picture. The items of the 4th level are united into lists.

For example, to unite the child items of the "Research" item ("Base research" and "Collaborative research with industries"), we should set the $type property with the value "list" in its definition.

The same actions should be performed with the "Development", "Teaching" and "Traning" items and their child items.

The code will look like this:

var orgChart = new webix.ui({
    container:"testA",
    view:"organogram",
    data: [
        {id:"1", value:"Center Director", data:[
            { id:"1.1", value:"Research &amp; Development", data:[
                { id:"1.1.1", value:"Research", $type: "list", data:[
                    { id:"1.1.1.1", value:"Base research" },
                    { id:"1.1.1.2", value:"Collaborative research with industries" }
                ]},
                { id:"1.1.2", value:"Development", $type: "list", data:[
                    { id:"1.1.2.1", value:"Faculty development workshops" },
                    { id:"1.1.2.2", value:"Student development" }
                ]}
            ]},
            ...
        ]}
    ]
});

Related sample: Lists

Customizing List Blocks

By default, list items in the block are placed into a standard HTML list. To separate them visually and show their dependence on one and the same parent, define the following values within the Organogram type:

  • listMarginX - space between the vertical line and block items;
  • listMarginY - space between two block items in the line.

webix.ui({
    view:"organogram",
    type:{
        listMarginX: 20,
        listMarginY: 20
    }
});

Related sample: Lists Blocks


Available only in PRO Edition

Styling Organogram

You can customize any element of Webix Organogram. All you need to do is to redefine the needed attributes of the related css class in the <style> block of your page. The untouched attributes will take default values.

<style>

    .webix_organogram{
        background-color: #2196f3;
    }

</style>

In the above example we redefined only the background color. All the other attributes defined in the '.webix_organogram' class took the default values.

CSS classes and the related elements
  • .webix_organogram - css rule for container of the organizational chart
  • .webix_organogram_item - css rule for all chart items
  • .webix_organogram_level_1 - css rule for the items of the 1st level
  • .webix_organogram_level_2 - css rule of the items of the 2nd level
  • ...
  • .webix_organogram_level_[n] - css rule for the items of the n level
  • .webix_organogram_list - css rule for list block
  • .webix_organogram_list_item - css rule for items inside list block
  • .webix_selected - css rule for the items in selected state

Custom styling

You can also redefine the default styles or apply your own css rules for chart items.

Use the $css property in item data to specify item style in one of the two ways:

  1. create new css rule in <style> block and apply it to the necessary items
  2. specify css style directly in the item definition

To illustrate the described techniques, we will define the .item_top css rule and apply it to the item of the 1st level. For the item of the 2nd level we'll set specific css properties directly in the data set.

Finally, we'll redefine the .webix_selected rule to change background color of selected items.

<style>
    // "top" ccs rule definition
    .item_top{
        background-color: #ffe0b2;
        border-color: #ffcc80;
    }
    // the style for selected item
    .webix_selected{
        background-color: #2196f3 !important;
        border-color: #2196f3 !important;
    }
</style>

<script>
orgChart = new webix.ui({
    container:"box",
    view:"organogram",
    data:[
        {id:"root", value:"Board of Directors", $css: "item_top",  data:[
            {id:"1", value:"Managing Director",
              $css:{background: "#ffe0b2", "border-color": "#ffcc80"}, data:[
                {id:"1.1", value:"Base Manager"},
                { id:"1.2", value:"Business Development Manager"}
                ...
            ]}
        ]}
    ]
});
</script>

You can see the result in the picture below:

Related sample: Styling


Available only in PRO Edition

Event Handling with Organogram

Organogram supports various events that can be used to provide a custom behaviour for your organogram.

There are 2 ways you can add a handler to the event:

  • through the method attachEvent();
  • through the parameter on.

Event names are case-insensitive

Method attachEvent()

You can attach several handlers to the same event and detach them using two respective methods:

A general way to attach/detach the event handler

// to attach event
var myEvent = $$("orgChartId").attachEvent("onItemClick", function () {
// event handler code
})

//to detach event
$$("orgChartId").detachEvent(myEvent);

Parameter 'on'

With the help of parameter on you can also attach any event(s) to an Organogram object. But in contrast to using the attachEvent method you can't detach the attached events later.

Attaching the event handler through parameter 'on'

webix.ui({
    view:"organogram",
    ...
    on: {
        onitemClick: function (id) {
            alert("item has just been clicked");
       }
    }
);

Cancelable Events

All events with the subword 'onbefore' can be cancelled.
To cancel some event you should return false within the appropriate event handler.

Cancelling the event handler

var myEvent = $$("orgChartId").attachEvent("onBeforeSelect", function (id) {
    ... // some event handler code
    return false;
})

Accessible objects and data

Inside the event handler you can refer to the holder component through the keyword this.
Besides, most event handlers get incoming argument(s), like the id of a data item (see organogram events to know exactly what arguments are passed inside event handler).

Btw, using the id of a data item you can access this item itself and all its properties. For example:

Referring within the event handler

$$("orgChartId").attachEvent("onAfterSelect",function(id){
  var level = this.getItem(id).$level;
})

Related sample: Events


Available only in PRO Edition

Organogram General How-Tos

How to create list blocks?

To create a list block, you need to specify the $type property with the value "list" in the parent of the items that you want to turn into a list.

In the example below, we will unite the "Base research" and "Collaborative research with industries" items into a list. For this purpose, we will set the $type property with the value "list" in their parent item called "Research".

The same actions will be performed with the "Development" value and its child items.

The code will look like this:

var orgChart = new webix.ui({
    container:"testA",
    view:"organogram",
    data: [
        {id:"1", value:"Center Director", data:[
            { id:"1.1", value:"Research &amp; Development", data:[
                { id:"1.1.1", value:"Research", $type: "list", data:[
                    { id:"1.1.1.1", value:"Base research" },
                    { id:"1.1.1.2", value:"Collaborative research with industries" }
                ]},
                { id:"1.1.2", value:"Development", $type: "list", data:[
                    { id:"1.1.2.1", value:"Faculty development workshops" },
                    { id:"1.1.2.2", value:"Student development" }
                ]}
            ]},
            ...
        ]}
    ]
});

Related sample: Lists

How to add an image into an item?

To add an image for an item, you should redefine the template property:

var orgChart = new webix.ui({
    container:"testA",
    view:"organogram",
    template: function(obj){
        var image = obj.img;

        if(image){
            html = "<img src='"+image+"' class='photo'>";
        }

        return (image||"")+obj.value;
    }
});

Related sample: Templates

How to specify a custom style for items?

You can also redefine the default styles or apply your own css rules for chart items.

Use the $css property in item data to specify item style in one of the two ways:

  1. create new css rule in <style> block and apply it to the necessary items
  2. specify css style directly in the item definition

To illustrate the described techniques, we will define the .item_top css rule and apply it to the item of the 1st level. For the item of the 2nd level we'll set specific css properties directly in the data set.

Finally, we'll redefine the .webix_selected rule to change background color of selected items.

<style>
    // "top" ccs rule definition
    .item_top{
        background-color: #ffe0b2;
        border-color: #ffcc80;
    }
    // the style for selected item
    .webix_selected{
        background-color: #2196f3 !important;
        border-color: #2196f3 !important;
    }
</style>

<script>
orgChart = new webix.ui({
    container:"box",
    view:"organogram",
    data:[
        {id:"root", value:"Board of Directors", $css: "item_top",  data:[
            {id:"1", value:"Managing Director",
              $css:{background: "#ffe0b2", "border-color": "#ffcc80"}, data:[
                {id:"1.1", value:"Base Manager"},
                { id:"1.2", value:"Business Development Manager"}
                ...
            ]}
        ]}
    ]
});
</script>

Related sample: Styling


Available only in PRO Edition

PDF Viewer

PDF Viewer is a tool for displaying the content of PDF files on the screen.

Related sample: Pdf Viewer

The viewer is recommended for use with the dedicated toolbar that contains buttons for paging and zooming. Viewer and toolbar are initialized in separate layout rows:

  • the first one with the toolbar;
  • the second one with the viewer itself.

Thus, the default constructor of PDF viewer with toolbar looks as follows:

webix.ui({
    type:"space",
    rows:[
        { view:"pdfbar", id:"toolbar" },
        { view:"pdfviewer", id:"pdf", toolbar:"toolbar", url:"files/WebixDocs.pdf"}
    ]
});

Configuration parameters are:

  • toolbar:
    • id - (string) the id of the PDF toolbar;
  • viewer:
    • id (string) - the id of the viewer;
    • toolbar (string) - the id of the related pdf toolbar;
    • url (string) - the url of the pdf file to browse in the viewer.

Pdfbar structure

Toolbar is supplied with the following fully functional controls:

  • navigation arrows (previous and next page);
  • current page label;
  • "all pages" label;
  • zoom in and out icons;
  • zoom mode selector;
  • download button.

If you need, you can use the viewer and the toolbar separately, by using their public API methods.

PDF viewer API reference

Methods

load()

loads a pdf file into the viewer

parameters:

  • url - (string) the url of the pdf file to load
$$("pdfviewer").load(url);

parse()

parses the contents of uploaded File or base64 string into the viewer:

Base64 string

var base64data = ..decoded base64 data..;
$$("pdf").parse({data:base64data});

Uploaded file

{view:"uploader", width:200, height:45, type:"form", value:"Choose a PDF file to upload", accept:"application/pdf", on:{
    onBeforeFileAdd:function(upload){
        $$("pdf").parse(upload.file);
    return false;
    }
}}

Related sample: PDF File Uploading and Downloading

nextPage()

renders the page that follows the viewed one

$$("pdfviewer").nextPage();

prevPage()

renders the page that precedes the viewed one

$$("pdfviewer").prevPage();

renderPage()

renders the specified page in the viewer

parameters:

  • page - (number) the number of the page
$$("pdfviewer").renderPage(2);

setScale()

sets a new value for a zooming scale

parameters:

  • scale - (string, number) a new scale value
  • update - (boolean) if true, update scale value on the related toolbar

The "scale" parameter can be set as:

1) string value:

  • 'page-actual' - the page scale is equal to 100%
  • 'page-width' - the page size is extended to the width of the view
  • 'page-height' - the page size is extended to the height of the view
  • 'page-fit' - the page's size is adjusted to the size of the view area, width or height
  • 'auto' - the page's size is automatically adjusted to the size of the view area

2) number value:

  • integer number: 1 is equal to 100%
  • float number: 0.5 is equal to 50%
$$("pdfviewer").setScale(0.4, true);
// or
$$("pdfviewer").setScale('page-actual', true);

zoomIn()

zooms the viewed page in

$$("pdfviewer").zoomIn();

zoomOut()

zooms the viewed page out

$$("pdfviewer").zoomOut();

download()

downloads viewer contents as PDF file

$$("pdfviewer").download();

Events

onBeforeLoad

fires before loading of the PDF file begins

$$("pdfviewer").attachEvent("onBeforeLoad", function(){ ... });

onAfterLoad

fires after the PDF file is fully loaded

$$("pdfviewer").attachEvent("onAfterLoad", function(){ ... });

onPageRender

fires after a page is rendered in the viewer body

parameters:

  • pageNum - (number) the number of the page
$$("pdfviewer").attachEvent("onPageRender", function(pageNum){ ... });

onScaleChange

fires after the page has been zoomed

parametes:

  • scale - (number) new value of the scale
  • update - (boolean) flag that indicates whether the related PDF toolbar should be updated
$$("pdfviewer").attachEvent("onScaleChange", function(scale, update){ ... });

PDF toolbar API reference

setMasterPage()

sets the page to show in the viewer

  • page - (string, number) the value of the page that should be displayed in the viewer

Possible values are "prev", "next" or page number.

$$("toolbar").setMasterPage("prev");
// or
$$("toolbar").setmasterPage(3);

setMasterScale()

applies a new scale value to the viewer

parameters:

  • scale - (string, number) a new scale value

The possible values of the "scale" parameter coincide with the same parameter of the setScale() method.

$$("toolbar").setMasterScale(0.3);
// or
$$("toolbar").setMasterScale('page-actual');

setPage()

sets the current page in the toolbar

parameters:

  • page - (number) the number of the page that should be displayed
$$("toolbar").setPage(2);

setScale()

sets a new value for the toolbar scale

parameters:

  • scale - (string, number) a new scale value

Possible string values are:

  • 'page-actual' - the page scale is equal to 100%
  • 'page-width' - the page size is extended to the width of the view
  • 'page-height' - the page size is extended to the height of the view
  • 'page-fit' - the page's size is fit to the size of the view area
  • 'auto' - the page's size is automatically fit to the size of the view area

Possible number values are:

  • integer numbers: 1 is equal to 100%
  • float numbers: 0.5 is equal to 50%
$$("toolbar").setScale(0.4);
// or
$$("toolbar").setScale('page-width');

setValues()

sets values of toolbar controls, namely the number of pages in the document and the scale in use

parameters:

  • pages - (number) the number of pages
  • scale - (string, number) the scale value
$$("toolbar").setValues(15,"auto-width");
//or
$$("toolbar").setValues(10,"page-actual");

zoom()

applies zooming to the viewer (in or out); it is called on a toolbar button click ("+" or "-")

parameters:

  • direction - (string) the direction of zooming - "in" or "out"
$$("toolbar").zoom("in");

download()

applies downloading to the viewer to get its contents as PDF file

$$("toolbar").download();


Popup

API Reference
  • Methods, properties and events
  • Samples

Overview

Popup is a variant of a ui-related window. Unlike it, the popup disappears as you click somewhere outside it. Popup is be used to alert some info as well can form a popup menu.

Initialization

Popup consists of body (both taking either view or text template) without the head section.

The component should be made visible with the show() method you call during the component initialization (if, of course, you want the popup to appear on page loading).

webix.ui({
    view:"popup",
    id:"my_popup",
    body:{
        template:"Some text"
    }
}).show();

Related sample: Popup Window

Popup Sizing and Positioning

For adequate work, you need to specify the dimensions of your popup as well as its offsets (top and left). Otherwise, the component occupies the whole screen or sticks to its top left corner respectively.

webix.ui({
    view:"popup",
    width: 400, height:300,
    top:200, left: 300
}).show();

There exist more positioning options. All of them are described in a separate documentation article.

Creating a Popup Menu

Related sample: Popup Menu

To create a popup menu that will appear on button click, you should create a button with popup property that takes popup ID as value.

The popup is hidden initially. Toolbar and popup are initialized within different webix.ui containers.

Popup Menu

webix.ui({
       view:"toolbar",
       elements:[
            {view:"button", label: 'Menu', popup:"my_pop"},
            ...
        ]
});

webix.ui({
       view:"popup",
       id:"my_pop",
       body:{
            view:"list",
        ...}
}).hide();

Related sample: Popup Menu

Related Articles
  • Window
  • Window and Popup Positioning
  • Control Guide
  • Toolbar
  • Changing Visibility of Components
  • Popup CSS Image Map


Available only in PRO Edition

Portlet

API Reference
  • Methods, properties and events
  • Samples

Overview

Portlet is a layout component that allows placing other widgets inside of it. You can easily drag this or that portlet anywhere you want on the page. Thus, it's possible to change the app's structure in a simple way, without writing any extra code.

Initialization

As any other component, Portlet can be initialized in a container or as a full-screen view.

To initialize a portlet in a div container, you should create a container first:

<div id="divA" style="width:600px;height:400px;"></div>

Then, in order to place the component into the container, specify the container property inside of the view constructor, as it's shown in the example below.

Portlet consists of a body (taking either a view or a text template) without the head section. A header can also be added. You'll find the details below.

webix.ui({
    container:"divA",
    type:"space",
    view:"portlet", body:{
        template:"Drag and drop portlets"
    }
});

Related sample: Portlet: Move cells

Moving portlets

You can move portlets by the handler. While dragging a portlet, possible positions for dropping are defined by highlighting. A portlet can be placed as a column or as a row.

Related sample: Portlet: Move cells

Dragging by the header

In order to drag a portlet you can use not only the handler, but also the portlet header. Just set some string value for the header property in the porlet definition:

webix.ui({
    type:"space",
    view:"portlet", header:"Drag me", body:{
        template:"Drag and drop portlets"
    }}
});

Related sample: Portlet: Drag Header

Modes of moving portlets

Replacing portlets

Instead of simply moving a portlet to a new position, it's also possible to replace the target portlet with the moved one. This mode is enabled by specifying the mode property with the value "replace":

webix.ui({
    type:"space",
    view:"portlet", mode:"replace", body:{
        template:"Drag and drop portlets"
    }}
});

Related sample: Portlet: Replace cells

One direction moving

There are two modes that allow portlets move either only in the horizontal direction or in the vertical one. They are called "cols" and "rows", respectively. In the "cols" mode portlets are moved only along the x-axis. In the "rows" mode portlets can only be placed along the y-axis.

webix.ui({
    type:"space",
    rows:[
        { template:"Only X-snap here", type:"header"},
        { type:"wide", cols:[
            { view:"portlet", mode:"cols", body:{
                template:"A col 1"
            }},
            { view:"portlet", mode:"cols", body:{
                template:"B col 2",
            }},
            { view:"portlet", mode:"cols", body:{
                template:"C col 3"
            }},
        ]
        }
    ]
});

Related sample: Portlet: One direction

Adding other components

It's very easy to add other component into a portlet. All you need to do is to specify the view name, data source and any other necessary properties in the portlet's body:

webix.ui({
    type:"space",
    rows:[
        { template:"Only X-snap here", type:"header"},
        { type:"wide", cols:[
            { view:"portlet", mode:"cols", body:{
                view:"tree", data:smalltreedata
            }},
            { view:"portlet", mode:"cols", body:{
                view:"list", data:small_film_values_set, select:true, autoheight:true
            }},
            { view:"portlet", mode:"cols", body:{
                view:"datatable", data:small_film_set, autoConfig:true, autoheight:true
            }},
        ]
        }
    ]
});

Related sample: Portlet: Drag Components


Property Sheet

API Reference
  • Methods, properties and events
  • Samples

Overview

Property sheet is a list of properties. Ui-related property sheet inherits from view.

Initialization

{ view:"property",  id:"sets", width:300,
    elements:[
       { label:"Layout", type:"label"},
       { label:"Data url", type:"text", id:"url"},
       { label:"Data type", type:"select", options:["json","xml","csv"], id:"type"},
       { label:"Use JSONP", type:"checkbox", id:"jsonp"}
    ]
};

Related sample: Property Sheet: Basic Initialization

The elements with label gets header CSS. If there's no type the element is non-styled and non-editable.

Working with Property Sheet

Property Sheet Values

The elements of a property sheet can be treated together, you can get and set their values just like you do it with form and HTMLform.

  • setValues();
  • getValues();
  • HTMLform and Form Treatment
$$("sets").setValues({
    width:250,
    height:480,
    url:"http://Webix.com/data",
    type:"json"
});

var values = $$("sets").getValues();

Complex Values

Property sheet can take complex values in the complexData mode:

webix.ui({
    view:"property",
    id:"sets",
    complexData:true,
    elements:[
        { label:"Width", type:"text", id:"layout.width" },
        { label:"Height", type:"text", id:"layout.height"}
    ]
});

$$("sets").setValues({
    layout:{
        width:250,
        height:480
    }
});

Related sample: Property sheet::Data with complex properties

The names of property elements should be concatenated from the data names within the values.

Editing Data in Property Sheet Elements

Each element features a built-in editor specified by type property. Possible values coincide with editor types and include:

  • color - an editor for colors, colorboard appears on editing;
    • Related sample: Property Sheet: Colorpicker
  • text - a standard editor for text values;
  • password - a text editor for passwords;
  • select - for selection among several text values with the help of an HTML 'select' control;
  • combo - for selection among several values with the help of Webix combo control. Input is editable;
  • richselect - for selection among several values with the help of Webix richselect control. Input is non-editable;
  • checkbox - for two-state values.

Select editors features options in their configuration that can be defined in the following ways:

elements:[
    { type:"select", options: ["json","xml","csv"]},
    { type:"select", options: [
        {id:1, value:"json"},
        {id:2, value:"xml"},
        {id:3, value:"csv"}
    ]}
]

Customizing Editor Collection

Besides, other editors types can be registered for the elements with the help of the registerType() method. During registering the new element type, you should specify its appearance and behavior.

'Toggle' editor for two-state values

$$("sets").registerType("toggle",{
    template:function(value, config){
        return "<input type='button' class='webix_toggle_button_custom' value='"+
          value+"' style='margin:0px; width:95%; height:20px; font-size:12px; '>";
    },
    click:{
        webix_toggle_button_custom:function(e, id){
            var data = this.getItem(id);
            if (data.options[0] == data.value)
                data.value = data.options[1];
            else
                data.value = data.options[0];

            this.editStop();
            this.refresh(id);
            this.callEvent("onCheck",[id, data.value]);
        }
    },
    editor:"inline-text"
});

And then use it:

webix.ui({
    view:"property", id:"sets", elements:[
        { label:"Data type", type:"toggle", options:["json","xml"], id:"type"}
    ]
});

Related sample: Property Sheet: Custom Editors

Using Custom Popup Editors

Popup editors are based on Webix popup window and can be registered with either default or custom logic:

Default Popup

//including the editor into the property sheet
webix.ui({
    view:"property", id:"sets", elements:[
        { label:"Color front",  type:"popup", popup:"myColorF", id:"colorF" },
        ...
    ]
});

//defining its appearance
webix.ui({
    id:"myColorF",
    view:"popup",
    body:{ view:"textarea", width:300, height:100 }
});

//registering the new type
prop.registerType("popup",{
    editor:"popup"
});

Custom Popup

// standard popup editors is extended with new functions
webix.editors["popup-ra"] = webix.extend({
    focus:function(){ },
    getValue:function(node){
        return this.getInputNode(node).data.edit;
    },
    setValue:function(node, value){
        this.getPopup(node).show(node);

        this.getInputNode(node).data.edit = value;
        this.getInputNode(node).refresh();
    }
}, webix.editors["popup"]);

//new type is registered
prop.registerType("popup-ra",{
    editor:"popup-ra"
});

Related sample: Property Sheet: Custom Editors

Related Articles
  • Data Object Operations
  • Sizing Components
  • Resizing
  • Redefinition of the Components
  • Property Sheet CSS Image Map


Available only in PRO Edition

RangeChart

API Reference
  • Methods, parameters and events
  • Samples

Overview

RangeChart is a component that allows presenting data in a detailed way. It can be useful if you work with big amounts of data and need to display some particular data parts.

RangeChart is based on Chart component and inherits its API. RangeChart can be built upon any Webix chart that possesses a horizontal scale: line, spline, area and stackedArea, bar and stackedBar. However, it is not obligatory to initialize scales.

Visually, the related frame limits the amount of data for future processing. Frame values are always rounded to the next bigger value. It means that if you set a frame handler to some intermediate section between scale marks, it will be moved to that nearest point the value of which is bigger.

Related sample: Chart Frame :: Basic usage

Initializing Range Chart

To initialize a RangeChart, you need to define its configuration, like the one given below:

webix.ui({
    view:"rangechart",
    height: 80,
    id:"range",
    type:"line",
    value:"#sales#",
    frameId:"time",
    item: { radius :0 },
    range:{ start:30, end:50 },
    data: data
});

In general, all properties of a standard chart can be used to configure RangeChart, e.g:

  • height - sets the height of the range chart
  • id - the id of the range chart
  • type - sets the type of the chart
  • value - defines values for the vertical axis
  • item - defines markers that present chart's data items
  • data - specifies the dataset that will be loaded to the range chart

and two RangeChart-specific properties:

  • frameId - specifies a property in the data item, that will be used for the frame (id by default)
  • range - sets the data range that should be selected in the frame

In the range object you should specify either ids or indexes of the starting and the ending data items of the range.

What is more, you can set the id of the starting item and the index of the ending one and vice versa. The important thing is that there are always should be one starting value and one ending value of the range. Thus, you can set the range as:

range:{ sindex:29, end:50 }

Setting Frame Range

The frame isn't set automatically and depends on data. So, it should be specified only after data are loaded to the RangeChart.

For example, you can set the frame range in the ready handler. The frame is specified by the setFrameRange method.

webix.ui({
  view: "rangechart",
  ...
  ready:function(){
    this.setFrameRange({
        start:30,
        end:40
    });
});

As parameters the setFrameRange() method takes either ids or indexes of the starting and the ending data items of the range.

Notice that the priority of ids is higher than that of indexes. It means that in case difference between their values is great, the position of data range will be counted using the ids values.

In order to get the set frame range, you should use the getFrameRange method. It returns the object of the data range selected in the frame.

var range = rangechart.getFrameRange();

The configuration of the returned object looks like this:

{
    start: 30,
    sindex:29,
    end: 40,
    eindex:39
}

You can also get the data included into the frame range. For this purpose, make use of the getFrameData method.

It returns an array of data objects that are included into the range.

var data = rangechart.getFrameData();

Related sample: Chart Frame :: Basic usage

Working with RangeChart

RangeChart can be used to control data displayed within another data component, e.g. chart. For instance, each time when a range is changed in the RangeChart (master), changes are applied to the slave data component.

For example, let's consider an example with two charts. To begin with, you need to use the on property and specify the handler for the onAfterRangeChange event.

Inside of the handler function remove all data items from the slave chart using its clearAll() method. Finally, call the getFrameData() method of RangeChart to get the enclosed data and apply the parse() method to the slave chart to populate it with a new dataset.

var chart = {
    view:"chart",
    id:"dchart",
    type:"line",
    value:"#sales#",
    xAxis:{ template:"#time#" },
    yAxis:{},
    item:{
        borderColor: "#1293f8",
        color: "#ffffff"
    }
};

var range = {
    view:"rangechart",
    height: 80,
    id:"range",
    type:"line",
    value:"#sales#",
    frameId:"time",
    data:  data,
    on: {
        onAfterRangeChange:function(){
            $$("dchart").clearAll();
            $$("dchart").parse(this.getFrameData());
        }
    },
    ready:function(){
        this.setFrameRange({start:30, end:40);
    }
};


Scrollview

API Reference
  • Methods, parameters and events
  • Samples

Overview

Scrollview inherits from view and makes any of the nested components scrollable, either in horizontal or in vertical mode. It is handy in case of long homogenious data items, like text templates.

Initialization

It's reasonable to use the scrollview just as a sccrolling container while text into is stored in HTML.

<div id="mybox1">Some very long article-1</div>
<div id="mybox2">Some very long article-2</div>
<div id="mybox3">Some very long article-3</div>
...

Then you can put these 'long articles' into the scrollview and form a very long list where you can scroll to any article you wish: HTML content is nested into UI component with the help of a dedicated data template:

webix.ui{(
        view:"scrollview",
        id:"verses",
        scroll:"y", //vertical scrolling
        body:{
            rows:[
                {id:"verse_1", template:"html->my_box1"}, // corresponds to the dedicated div ID
                {id:"verse_2", template:"html->my_box2"}
                {...}
            ]}
    })

Related sample: Scrollview

Scrollview features a body object property where items (text templates, components) are stored in either rows or cols array for vertical or horizontal item arrangement respectively.

Working with Scrollview

Within scrollview as well as within any component with a scrollbar you can:

  • scroll to a definite position of the component;
  • define your position - how far you have scrolled away from the top and left border of the scrollview;
  • enable and disable scrolling and specify scrolling directions.

Read more about scroll control in the corresponding article of the documentation.

Related Articles
  • Setting Borders to the Components
  • Adding Headers to Components
  • Sizing Components
  • Resizing
  • Layout
  • Multiview
  • Carousel
  • Accordion


Sidemenu

API Reference
  • Methods, properties and events
  • Samples

Overview

The Sidemenu widget inherits from Window and can be bound to any side of the screen (top, bottom, right, left). You can place any other view or even a complex layout inside of Sidemenu.

Initialization

To initialize Sidemenu, you need to define all the necessary parameters in the webix.ui() constructor. Don't forget to set the necessary width/height values and specify the desired position of the Sidemenu (the details are given below):

webix.ui({
    view: "sidemenu",
    id: "menu",
    width: 200,
    position: "left",
    body:{
        view:"list",
        borderless:true,
        scroll: false,
        template: "<span class='webix_icon fa-#icon#'></span> #value#",
        data:[
            {id: 1, value: "Customers", icon: "user"},
            {id: 2, value: "Products", icon: "cube"},
            {id: 3, value: "Reports", icon: "line-chart"},
            {id: 4, value: "Archives", icon: "database"},
            {id: 5, value: "Settings", icon: "cog"}
        ]
    }
});

Related sample: Left position

Sidemenu sizing and positioning

You can specify the necessary width and height of Sidemenu, depending on its position. Sidemenu can appear from the top, bottom, left or right sides of the screen.

If you use the "left" or "right" Sidemenu position, you can specify the width dimension. In the case of "top" or "bottom" Sidemenu, the height dimension can be set. The dimension which is not set directly (height for the left/right Sidemenu and width for the top/bottom Sidemenu) will be automatically adjusted to the size of the screen.

For example:

webix.ui({
    view: "sidemenu",
    position: "right",
    width: 200,
    body:{
        ...
    }
});

Related sample: Right position

Customizing size and position

You can customize Sidemenu's size and position in the necessary way. It's done with the help of the state function that takes as a parameter an object containing the position and size values that will be set as Sidemenu properties:

  • top ;
  • left;
  • width;
  • height.

For example, if there's a toolbar in an application and left Sidemenu should be shown below it, you need to increase the "top" property of the state object by the toolbar height and decrease the "height" one by the same value:

webix.ui({
    view: "sidemenu",
    width: 200,
    position: "left",
    state:function(state){
        // get the toolbar's height
        var toolbarHeight = $$("toolbar").$height;
        // increase the 'top' property
        state.top = toolbarHeight;
        // decrease the 'height' property
        state.height -= toolbarHeight;
    };
});

Related sample: Left position

Hiding/showing Sidemenu

You can hide and show Sidemenu by clicking a button. For this purpose, the hide and show methods should be used.

webix.ui({
    {view: "toolbar", id:"toolbar", elements:[
        {
            view: "icon", icon: "bars",
            click: function(){
                if( $$("menu").config.hidden){
                    $$("menu").show();
                }
                else
                    $$("menu").hide();
            }
        },
        {}
    ]}
});

webix.ui({
    view: "sidemenu",
    id: "menu",
    width: 200,
    position: "left",
    body:{
        ...
    }
});

In the above code we've defined the icon button that has the "bars" type from the Font Awesome collection. On clicking the icon, we check, whether the menu is hidden. If the menu is initially hidden, it will be shown on the icon's click. If it's shown, it will be hidden.


Tabview

API Reference
  • Methods, properties and events
  • Samples

Overview

Tabview is a hybrid component that is made of a multiview and tabbar.

Tabview allows for quick initialization of a multiview with a built-in ability to switch between the views.

It also features dedicated methods to add and remove views together with the corresponding tabs.

Initialization

There's no need to create a multiview and switching buttons for it. Everything lies within one and the same "tabview" component with cells property that contains collections of views.

Tabview

webix.ui({
  view: "tabview",
  cells: [
    {
      header: "List",
      body: {
        id: "listView",
        view: "list", ...
      }
    },
    {
      header: "Form",
      body: {
        id: "formView",
        view: "form", ...
      }
    }
  ]
});

Related sample: Tabview

Each tabview cell features:

  • header - string with a heading for the cell, displayed as tab title;
  • body - configuration object for the component that is placed in this cell.

Note that switching between views is enabled automatically via a tabbar control. For more customization, use a multiview component and choose the needed switching method.

Working with Tabview

The hybrid nature of a tabview allows configuring each of its parts separately:

  • through the same-name object properties in the initial configuration:

These configuration objects may contain native properties of multiview and tabbar that need to be redefined. If the configurations are omitted, default values will be used.

webix.ui({
    view:"tabview",
    id:"my_tabview",
    cells: [],
    tabbar:{
        ...
    },
    multiview:{
        ...
    }
});
  • by accessing multiview and tabbar objects to work with them dynamically:
var tabbarObj = $$("my_tabview").getTabbar();
var multiviewObj = $$("my_tabview").getMultiview();

All the API methods, events and properties of a ui.tabbar and ui.multiview respectively are applicable to these objects.

Enabling animation

By default the switching of tabview tabs is not animated. Since animation is a multiview feature, it can be enabled within multiview configuration.

view:"taview",
cells:[],
multiview:{
    animate:true
}

The animate property may take an object with advanced animation settings.

Setting icons for tabs

Icons for the tabbar tabs are set via additional HTML in the tab header:

view: "tabview",
cells: [
  { header: "<span class='webix_icon fa-film'></span>List",
    body:{}
  }
]

Related sample: Multiview Tabbar with Icons

More about different types of defining icons in Webix you can learn in the Icons with UI Components article.

Defining tabs that can be closed

Closing functionality is a tabbar feature.

To make all tabs closable, close property should be set to true in the tabbar configuration:

view: "tabview",
tabbar: {
  close:true
}

To make a separate tab closable, use the close proerty in its configuration:

view: "tabview",
cells: [
  { header:"List",
    close:true,
    body:{...}
  }
]

Related sample: Tabview: Close tab button

Responsive tabbar

Tabbar default feature. If the tabs are wider than the available space, some of them are pushed to a popup list and can be reached though the related menu.

Everything is done fully automatically, though customization options for tab and popup width, icons, etc. are available through the tabbar configuration:

view: "tabview",
tabbar: {
  popupWidth: 300,
  tabMinWidth: 120
}

More in detail in the dedicated documentation article.

Adjusting tab dimensions

The width of each tab can be set separately:

view: "tabview",
cells:[
  { header:"List", width:150, body:{...} },
  { header:"Form", width:250, body:{...} },
]

If tabs are of different width and height, they usually take the size of the smallest tab once the user switches to it.

To avoid this behavior, you should use the fitBiggest property in the multiview configuration object:

view: "tabview",
multiview: {
  fitBiggest:true
}

Related sample: Tabview: Fit Active vs Fit Biggest

Adding and removing cells dynamically

The functionality is described in detail in the Adding and Deleting Multiview Cells Dynamically article.

Related Articles
  • Multiview
  • Common Functions to Switch Between Views
  • Controls to Switch Between View Cells
  • Adding and Deleting Multiview Cells Dynamically


Template

API Reference
  • Methods, properties and events
  • Samples

Overview

Ui-related template looks like a non-editable area for rendering plain text or a single data record. Its content is set with the help of the same-name template parameter.

Initialization

Simple template

The template property of the component sets its content:

webix.ui({
  view: "template",
  template: "Default template with some text inside" // text content
});

Related sample: Default Template

External Template

Template's content can as well be taken from an HTML node pointed to by:

  • the content property that links to a visible container:
<div id="myDiv">Default Template with some text inside</div>
webix.ui({
  view: "template",
  content: "myDiv"
});

Related sample: Default Template

  • the template property that points to the container ID prefixed by "html->". The container should be invisible initially:
<div id="my_box1" style='display:none;'>Some text here</div>
{ template: "html->my_box1", autoheight: true },

Related sample: Autosizing to Content

As a result, contents from HTML is placed inside the view.

Loaded Template

{ view: "template", src: "loadtext.php" }

Notes

Specifying the view type as "template" is optional. The following code works as well.

webix.ui({
  container: "layout_div",
  rows: [
    { template: "Default Template with some text inside" },
    { ... }
  ]
})

The same-name property of the component, template, is also used by Webix data components. It allows setting pattern to display texts and render data items from multiple datasets alongside with adding styling to them. The Data Templates article covers all the rules of templating.

Template Content

The template content is set with the template property, which can be:

  • plain text:
{ template: "Plain text" }
  • text with HTML markup:
 {template: "Text with <b>HTML</b> markup" }
  • an individual data item specified by the data property:
{ template: "#title#", data: { title: "Image One", src: "imgs/image001.jpg" } }
// shows "Image One"

If a template is used as an individual data item (as shown above) the data fields should be interpolated in either of the two ways:

  • using a string template containing data keys between hash signs to define which fields from the data record should be displayed;
  • using a template function that takes the data record (obj) as parameter:
{
  data: {title: "Image One", src: "imgs/image001.jpg" },
  template: function (obj) {
    // obj is a data record object
    return '<img src="'+obj.src+'"/>'
  }
}

Related sample: Carousel Initialization

The rules of data templating can be studied in detail in the dedicated documentation article.

Changing Template Text Dynamically

Dymanic content setting can be implemented with the help of:

  • a setHTML method to change text or HTML content of a template;
  • a define method used in lots of the components to reset property values;
  • a setValues method that allows to define template data;
  • a template-specific setContent method that can set the contents of an existing HTML node as template value.

Template Types

Default

The default template is a white non-editable area with some text or HTML content. It's surrounded by a grey border.

{ view: "template", template: "Text" }

Clean

The clean template looks very much like the default one, but has no borders.

{ view: "template", template: "Text", type: "clean"}

Header

Header template is used to set headers for layout rows/columns. Looks like a blue bar above the main contents.

webix.ui({
  rows: [
    { view: "template", template: "Header Template", type: "header" },
    { view: "...", ... }
  ]
});

Note that headers of accordionitems are set in a different way.

Section

Section template places header within the line that encircles a row/column thus making it possible to neatly divide the webpage into blocks. As there's a line in this template type, it would be nice to resort to borderless layout design.

{view: "template", template: "Header template", type: "section" }

Related sample: Template Types


Toolbar

API Reference
  • Methods, properties and events
  • Samples

Overview

Ui-related toolbar inherits from layout. It is the place to nest all the possible controls including, buttons, labels, icons, checkboxes, combos, etc. For the full list of controls please refer to the library's Controls Guide.

Initialization

Toolbar controls are put into the elements array and are arranged into a horizontal line.

To distinguish between horizontal and vertical control arrangement, use cols and rows arrays respectively.

A three-button toolbar

webix.ui({
    view:"toolbar",
    id:"myToolbar",
    cols:[
        { view:"button", id:"LoadBut", value:"Load", width:100, align:"left" },
        { view:"button", value:"Save", width:100, align:"center" },
        { view:"button", value:"Info", width:100, align:"right" }]
});

Related sample: Buttons: Alignment

Specify the ID of a toolbar as well as ID-s of all the necessary controls if you want to work with them later.

There exists a possibility to specify common configuration for all controls included into this or that toolbar.

Working with Toolbar

Image Buttons

Related sample: Buttons: Type 'image'

Differently-sized buttons can be included into the toolbar with the help of a custom function:

webix.ui({
    container:"areaD",
    view:"toolbar",
    cols: buttons(48) /*here you specify the parameter you want to
                        pass to the function defined later*/
});

function buttons(size){
    return  [
    { view:"button", type:"image"+size,
        image:"../common/imgs/"+size+"/save.gif", width:size+7},
    { view:"button", type:"image"+size,
        image:"../common/imgs/"+size+"/copy.gif", width:size+7}
    ];
}

More info about how to manipulate button groups.

Icon Buttons

Icons can be nested into all the library conponents. Within toolbar, icon buttons look definitely stylish.

Related sample: Buttons: Type 'icon'

Learn more about icon types in the dedicated chapter of the manual.

Related Articles
  • Controls
  • Tabview Functionality
  • Toolbar CSS Image Map


Available only in PRO Edition

TreeMap

API Reference
  • Methods, properties and events
  • Samples

Overview

UI-related TreeMap inherits from view and allows visualizing hierarchical structures in a space-limited way - as a set of nested rectangles. It takes most part of API from TreeStore.

Initialization

To initialize TreeMap on the page, you need to specify the necessary configuration:

webix.ui({
    view:"treemap",
    select: true,
    template: function(item){
        return item.label||"";
    },
    value: "#value#",
    data: [
        { id:"1", label: "Technology", data:[
            { id:"1.1", value:"50" },
            { id:"1.2", value:"30" },
            { id:"1.3", value:"20" }
        ]},
        { id:"2", label: "Healthcare", data:[
            { id:"2.1", value:"80" },
            { id:"2.2", value:"10" },
            { id:"2.3", value:"60" },
            ...
        ]},
        ...
    ]
});

Related sample: Initialization

Configuration settings

There are main configuration parameters that you can set to configure the TreeMap in the needed way:

  • template - (function) defines html content displayed in rectangles
webix.ui({
    view:"treemap",
    template: function(item){
        return item.category|| "";
    }
});
  • value - (string,function) a template that specifies the area of an item rectangle
webix.ui({
    view:"treemap",
    value: "#value#"
});
  • type - (object) defines the peculiarities of the TreeMap rendering

For example, you can set the cssClass function or the template one inside of the type property:

webix.ui({
    view:"treemap",
    type:{
        cssClass: function(item){
            // css config
        },
        template: function(item){
            return item.category|| "";
        }
    }
});
  • activeItem - (boolean) specifies if childs of the branches will be rendered in the TreeMap, false by default
webix.ui({
    view:"treemap",
    activeItem:true
});
  • subRender - (boolean) defines if the sub-elements should be rendered for the first-level branches, true by default
webix.ui({
    view:"treemap",
    subRender: false
});
  • headerTemplate - (string) sets the template for the header label
webix.ui({
    view:"treemap",
    headerTemplate: "#category#"
});
  • branch - (string) sets the id of a sub-branch that will expand showing its sub-elements
webix.ui({
    view:"treemap",
    branch: "2.1"
});

Styling TreeMap

Besides the correlation of rectangles' size, you can also define colors for items to show a separate dimension of the data.

For example, you can set color graduation for the TreeMap elements, depending on the number of comments they have. You should define a cssClass method in the TreeMap type to specify rectangles' styles depending on the comments' number:

webix.ui({
    view:"treemap",
    value: "#views#",
    type:{
        cssClass: function(item){
            var css,
            comments = item.comments;

            if(!this.isBranch(item.id)){
                if(comments > 30)
                    css = "item3";
                else if(comments > 20)
                    css = "item2";
                else if(comments > 10)
                    css = "item1";
                else
                    css = "item0";
            }
            return css;
        },
    },
    url: "data/data_colors.json"
});

In the above example the cssClass parameter sets a function that takes an element object as a parameter. We want to color only leaves (items with no sub-items), so we check if the element is not a branch.

Elements are colored according to the next logic: the more comments the items have, the more saturated their color will be.

The colors that correspond to this or that rule are specified in the css style definition:

<style>
    .item0{ background: #bbdefb; }
    .item1{ background: #90caf9; }
    .item2{ background: #64b5f6; }
    .item3{ background: #42a5f5; }
</style>

Related sample: Colors

One-Level Rendering

You can set the mode in which only first-level branches are displayed in the Treemap. But if values are set only for leaves items, you need to calculate them for branches in order to define rectangles style.

For this purpose, we need to count the average number of comments in our example. Let's specify the getCss function with the appropriate configuration:

function getCss(item){
    var color = "",
    comments = item.comments,
    id = item.id,
    num = 0, sum = 0;

    if(this.isBranch(id)){
        // average number of comments in a branch
        this.data.eachLeaf(id,function(item){
            sum += item.comments*1;
        num++;
        });
        comments = sum/num;
    }

    if(comments > 30)
        color ="#26a69a";
    else if(comments > 20)
        color ="#4db6ac";
    else if(comments > 10)
        color ="#80cbc4";
    else
        color ="#b2dfdb";

    return { background: color};
}

The isBranch() method checks whether an item is a branch. And the eachLeaf() method allows looping through all leaves to get the sum of elements' comments and getting the average number as a result.

Thus, we get the average number of comments in a branch and can use this number in the template of the value parameter.

The defined getCss() method should be set as the cssClass property to apply css styling to rectangles:

webix.ui({
    view:"treemap",
    type:{
        cssClass: getCss
    },
    activeItem: true,
    subRender: false,
    headerTemplate: "#category#",
    template: function(obj){
        return obj.$level == 1? obj.category: "";
    },
    value: "#views#",
    url: "data/data.json"
});

The key parameters here are:

  • activeItem - (boolean) specifies if childs of the branches will be rendered in the TreeMap, false by default

  • subRender - (boolean) defines if the sub-elements should be rendered for the first-level branches, true by default

Related sample: One-Level Rendering

Handling Events

Since TreeMap component inherits its API from TreeStore, it supports the handling of almost the same events. You can check the full list of events in the API reference.

TreeMap supports various events that can be used to provide a custom behaviour for treemap.

There are 2 ways you can add a handler to the event:

  • through the method attachEvent();
  • through the parameter on.

Event names are case-insensitive

Method attachEvent()

You can attach several handlers to the same event and detach them using two respective methods:

A general way to attach/detach the event handler

// to attach event
var myEvent = $$("treemap").attachEvent("onItemClick", function () {
// event handler code
})

//to detach event
$$("treemap").detachEvent(myEvent);

Parameter 'on'

With the help of parameter on you can also attach any event(s) to a TreeMap object. But in contrast to using the attachEvent method you can't detach the attached events later.

Attaching the event handler through parameter 'on'

webix.ui({
    view:"treemap",
    ...
    on: {
        onitemClick: function (id) {
            alert("item has just been clicked");
       }
    }
);

Cancelable Events

All events with the subword 'onBefore' can be cancelled.
To cancel some event you should return false within the appropriate event handler.

Cancelling the event handler

var myEvent = $$("treemap").attachEvent("onBeforeSelect", function (id) {
    ... // some event handler code
    return false;
})

Accessible objects and data

Inside the event handler you can refer to the holder component through the keyword this.
Besides, most event handlers get incoming argument(s), like the id of a data item (see treemap events to know exactly what arguments are passed inside event handler).

Btw, using the id of a data item you can access this item itself and all its properties. For example:

Referring within the event handler

$$("treemap").attachEvent("onAfterSelect",function(id){
  var level = this.getItem(id).$level;
})

Related sample: Events

Setting header

You can specify the displaying of branches' titles in the header of the treemap. The titles are set using the headerTemplate property in the component's configuration:

webix.ui({
    view:"treemap",
    headerTemplate: "#category#"
});

In our example, the item's category is taken as the value of the headerTemplate property. So, a Treemap with an opened first-level branch will look like this:

Now if we click on the "Health Economics" sub-branch of the "Healthcare" category, the header will be displayed as the "Main Category> SubCategory":

Related sample: Header


Tree

API Reference
  • Methods, properties and events
  • Samples
Overview

Tree is a pure JavaScript component for building various tree hierarchies.
It's a powerful and customizable tool with lots of features: support for XML, JSON data sources, static and dynamic loading, multitree drag-and-drop, inline editing, optional checkboxes, state saving, filtering, sorting, copying etc.

Confused where to start? Read article 'Quick start with Tree' to kick things off.

Guides

Managing data

  • Loading Data into Tree
  • Items Selection
  • Editing in the Tree
  • Filtering in the Tree
  • Sorting in the Tree
 Teaches you how to treat data in the tree to present the desired set of items.

Nodes manipulations

  • Adding nodes
  • Deleting nodes
  • Expanding/collapsing branches
  • Updating the tree
  • Saving the tree state
 Says about means you've got to manipulate with the tree branches and leaves: CRUD operations, tree state storage, etc.

Look-and-feel

  • Node templates
  • Adding Active Elements to Nodes
  • Styling
  • Checkboxes in Tree
 Covers techniques for fine-tuning the tree appearance: use of data templates, adding checkboxes, icons, lines to items, redefining the default CSS classes, etc.

Others

  • Copy-pasting data
  • Drag-and-drop
  • Events handling
 Describes the remaining procedures related to the tree but not mentioned in the chapters above: work with the clipboard, support for internal/external dnd and handling events.


Quick start with Tree

This is a tutorial that will walk you through creating a basic application containing Tree. You will learn how to initialize Tree customize it and populate with data.

The final code of the tutorial can be used as the start point while creating applications using Tree.

Related sample: Quick start with DataTree

A new HTML file and related code files

To start, create a new HTML file and include the related Webix code files in it.

Required code files are:

  • webix.css
  • webix.js

A basic html page with the included code files

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Quick start with Tree</title>
    <script src="../codebase/webix.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="../codebase/webix.css" type="text/css" charset="utf-8">
</head>
<body>
    <script>
        //here you will place your JavaScript code
    </script>
</body>
</html>

Placing Tree on a page

On the next step, you should create a div container where you then place your tree.

<div id="box" style="width:400px;height:200px;"></div>

Object constructor

After you have prepared the site for the tree you can move to its initialization.
To create a new Tree object you need to use the next constructor:

Tree constructor

tree = new webix.ui({ view:"tree" })

The only mandatory parameter you should specify inside the constructor:

  • container - the HTML container for Tree. We created it on the previous step.

Basic Tree configuration

tree = new webix.ui({
        container:"box",
        view:"tree",
});

General settings

On the previous step, we have defined primary configuration for Tree. For more available settings, read other articles in this documentation, such as:

  • Node templates - available templates for customizing data content;
  • Items Selection - describes how to enable selection in the tree;
  • Sorting in the Tree and Filtering in the Tree - says about means for sorting and filtering.

Loading data

There are different ways to load data into Tree (read about them in chapter Loading Data into Tree ).
We will use the easiest of the ways and specify data directly in the constuctor with the help of the data property:

Loading data into the tree

tree = new webix.ui({
    container:"testA",
    view:"tree",
    data: [
        {id:"root", value:"Cars", open:true, data:[
            { id:"1", open:true, value:"Toyota", data:[
                { id:"1.1", value:"Avalon" },
                { id:"1.2", value:"Corolla" },
                { id:"1.3", value:"Camry" }
            ]},
            { id:"2", open:true, value:"Skoda", data:[
                { id:"2.1", value:"Octavia" },
                { id:"2.2", value:"Superb" }
            ]}
        ]}
    ]
});

Congratulations! Now you can run your app and it'll produce Tree shown at the very beginning.

Related sample: Quick start with DataTree

What's next

What can we suggest you to do next?

  • Check the code sample of the mentioned above example (use the link above);
  • Read about possible data formats and how you can get data from database;
  • Find out about nodes manipulations (adding, deleting nodes etc.);
  • Check other supplied samples.


Getting/setting the node

Tree provides a set of methods for manipulating the node value and retrieving the node id.

Getting the node object/value

To get the node object, you should use method getItem:

Getting the node object

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"part1", value:"Part 1" },
            { id:"part2", value:"Part 2" }
        ]}
    ]
});

//'node' variable will contain an object of the related tree node
var node = tree.getItem('branch1');

//you can access data members directly
var value = node.value; // ->"The Shawshank Redemption"

Item object has the following properties:

  • id - (string) the item id
  • value - (string) the item value
  • $level - (number) the level of nesting (one-based numbering)
  • parent - (string) the id of the item's parent
  • $count - (number) the number of childs
  • open - (boolean) defines whether the node is collapsed or expanded (just for parent nodes)

For example, variable node from the code snippet above looks as in:

node = {
    $count: 2,
    $level: 1,
    $parent: 0,
    id: "branch1",
    open: true,
    value: "The Shawshank Redemption"
}

Setting the node value

To change the current value of a node (the node title), you should use the following technique:

Changing the node title

tree = new webix.ui({ view:"tree",...});

var nodeObj = tree.getItem(node_id);
nodeObj.value = new_value;

tree.refresh();
//or
tree.updateItem(node_id, nodeObj);

Methods refresh and updateItem lead to one and the same result and don't have any specificity.

Getting the node index

To get the index of a node in the branch (zero-based numbering) you should use the getBranchIndex method:

Getting the node index

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"1.1", value:"Part 1" },
            { id:"1.2", value:"Part 2" }
        ]}
    ]
});

var index  = tree.getBranchIndex('1.1'); // -> 0
var index1 = tree.getBranchIndex('1.2'); // -> 1

There is also the getIndexById method to get the node index but we don't suggest using it. It's a common method that is inherited by all data-containing components from the DataStore class and not intended for using with tree-like data structures.

Getting the node id

To get the id of a node you can use one of the following methods:

Table 1 Methods for getting the node id
Method | Description
getIdByIndex | returns the item id by its index
getParentId | returns the id of the parent node
getFirstChildId | returns the id of the first child of the specified branch. If there are not any, returns null
getNextSiblingId | returns the id of the next sibling of the specified node
getPrevSiblingId | returns the id of the previous sibling of the specified node

Getting the parent node id

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"part1", value:"Part 1" },
            { id:"part2", value:"Part 2" }
        ]}
    ]
});

var parent = tree.getParentId('part1'); // -> 'branch1'


Loading Data into Tree

Webix Tree can get data in the following predefined data formats:

  1. JSON (default);
  2. XML.

Details and examples of data formats in tree-like structures

There are two main ways you can specify the data source for Tree:

  1. Define the data set in the object initialization;
  2. Use one of the parse or load methods.

Both methods lead to the same result.

If you load XML data you need to set the datatype property in the constructor config or the second parameter of the parse / load method to the name of the expected data type, i.e. 'xml'.

Loading from inline dataset

If you want to specify the data set directly on the page, you can use:

  1. property data
  2. method parse

Specifying data inline

treedata = [
  { id: "1", value: "Book 1", data: [
    { id: "1.1", value: "Part 1" },
    { id: "1.2", value: "Part 2" }
  ]},
  { id: "2", value: "Book 2", data: [
    { id: "2.1", value: "Part 1" }
  ]}
];

tree = new webix.ui({
  view: "tree",
  ...
  data: treedata
});

//or
tree.parse(treedata)

Related sample: Tree: JSON Dataset

Loading from a data file

To load data from a file on the server, you can use:

  1. property url
  2. method load

Remember, in case of XML data you should specify the data type explicitly as 'xml':

tree = new webix.ui({
  view: "tree",
  ...
  url: "data/data.xml",
  datatype: "xml"
});
//or
tree.load('data/data.xml', 'xml');

Related sample: Tree: JSON Dataset

Loading linear (list-like) data

It's possible to load plain (list-like) data into the tree. The tree structure is achieved by means of grouping. Grouping is specified through the $group key of the scheme parameter.

tree = new webix.ui({
  view: "tree",
  scheme: {
    $group: "#make#",
  },
  data: [
    { id: 1, value: "Avalon", make: "Toyota" },
    { id: 2, value: "Corolla", make: "Toyota" },
    { id: 3, value: "Camry", make: "Toyota" },
    { id: 4, value: "Octavia", make: "Skoda" },
    { id: 5, value: "Superb", make: "Skoda" }
  ]
});

Related sample: Tree: Plain JSON Data with Client-side Grouping

Loading from a database

To load data from a database on the server you should deal with both client and server sides.

On the client side

You should either define a url property or call the load method that would point to a server REST API endpoint.

Static loading from a server database. Client-side code.

tree = new webix.ui({
  ...
  url: "data/tree_data.php"
});
//or
tree.load("data/tree_data.php");

On the server side

  • you can write the server logic by yourself;
  • or you can use dhtmlxConnector

If using dhtmlxConnector, the related server-side script will look like this:

Static loading from a MySQL database on the server. Server-side code.

require_once("../connector-php/codebase/data_connector.php");  // includes the connector file
$conn = mysql_connect('localhost', "root","");  // creates a connection
mysql_select_db("sampleDB");  // selects a database

$data = new TreeDataConnector($conn, "MySQL");  //initializes the connector object
// loads data from the specified database table
$data->render_table("packages_tree","id","value, state","","parent_id");

Related sample: Dynamic Loading


Details and Examples of Data Formats

Expected data formats

JSON

[
    { id:"1", open:true, value:"Toyota", data:[
        { id:"1.1", value:"Avalon" },
        { id:"1.2", value:"Camry" },
        { id:"1.3", value:"Corolla" }
    ]},
    { id:"2", value:"Skoda", data:[
        { id:"2.1", value:"Octavia" },
        { id:"2.2", value:"Superb" }
    ]}
]

XML

<data>
    <item value='Toyota' open='1'>
        <item value='Avalon'></item>
        <item value='Camry'></item>
        <item value='Corolla'></item>
    </item>
    <item value='Skoda'>
        <item value='Octavia'></item>
        <item value='Superb'></item>
    </item>
</data>

Available data keys/attributes

You can define the following attributes/keys in the data set:

Attribute | Description
value | the item value (the title of the related node)
open | defines whether the branch will be opened initially
css | the name of a css class that will be applied to the data item
checked | checks the check box related to the item ( if exists)
intermediate | sets the 3rd state of the check box related to the item ( if exists)
webix_kids | the flag of dynamic loading

JSON data. Using simplified form

You can use the simplified form of JSON and specify data as in:

[
    { value:"Toyota", open:true, data:[
        "Avalon", "Camry", "Corolla"
    ]},
    { value:"Skoda", data:[
        "Octavia", "Superb"
    ]}
]

Related sample: Tree: JSON Dataset

Compare simplified format with the standard form.

Custom JSON format

To use custom attributes in JSON data set you can define your custom JSON format (read details in article Data Drivers).

When you specify a custom format, don't remember to set the expected data type to the name of a new format

Here is a simple example:

var myjson = webix.DataDriver.myjson = webix.copy(webix.DataDriver.json);

myjson.child=function(obj){
    if (obj.$level == 1)
        return obj.cars;
};

tree = new webix.ui({ view:"tree", datatype:"myjson", ... });

the 'child' function defines which object properties should store sub-items

As a result, your data will look as in:

//full form
[
    { id:"1", open:true, value:"Toyota", cars:[
        { id:"1.1", value:"Avalon" },
        { id:"1.2", value:"Camry" },
        { id:"1.3", value:"Corolla" }
    ]},
    { id:"2", value:"Skoda", cars:[
        { id:"2.1", value:"Octavia" },
        { id:"2.2", value:"Superb" }
    ]}
]
//simplified form
[
    { value:"Toyota", open:true, cars:[
        "Avalon", "Camry", "Corolla"
    ]},
    { value:"Skoda", cars:[
        "Octavia", "Superb"
    ]}
]

Related sample: Tree: JSON Dataset

Custom XML format

To use custom tags you can define your custom XML format (read details in article Data Drivers).

When you specify a custom format, don't remember to set the expected data type to the name of a new format

Here is a simple example:

var myxml = webix.DataDriver.myxml = webix.copy(webix.DataDriver.xml);
myxml.records = "/cars/car";

myxml.child = "model";

tree = new webix.ui({   view:"tree", datatype:"myxml", ... });

the 'records' property defines the root tags
the 'child' property (also can be a function that takes the data object as a parameter) defines which tag should store sub-items

As a result, your data will look as in:

<cars>
    <car value='Toyota' open='1'>
        <model value='Avalon'></model>
        <model value='Camry'></model>
        <model value='Corolla'></model>
    </car>
    <car value='Skoda'>
        <model value='Octavia'></model>
        <model value='Superb'></model>
    </car>
</cars>

Related sample: Tree: XML Dataset


Tree Nodes manipulations

Adding nodes

Generally, to add a node (parent or child) you should use the add method. At what position the element will be added depends on parameters you pass to the method.

Method add accepts 3 parameters:

  • obj - the item object
  • pos - the position that the new item should have after being inserted into the tree (zero-based numbering).
    Note,
    • 0 - the item will be added as the first child (start position)
    • -1 - the item will be added as the last child (end position)
  • parent - (optional) the parent node id. If it's not specified, the item will be added to the root of the tree

Note, you can use the getBranchIndex() method to get the position of a node by its id (read more).

Table 1 Adding nodes
Nesting level Example
Root node
tree = new webix.ui({ view:"tree",... });

tree.add({ value:"New item"}, 0);
Child node (1st child)
tree=new webix.ui({view:'tree',..});

var parentId= tree.getSelectedId();
tree.add( {value:"New item"}, 0, parentId);
Child node (2nd child)
tree=new webix.ui({view:'tree',..});

var parentId = tree.getSelectedId();
var pos = tree.getBranchIndex("node2"); //'node2' is the 'Skoda' item's id

tree.add( {value:"New item"}, pos, parentId);

Deleting nodes

To delete a node (parent or child) you should use the remove method and specify the id of the required node there:

Deleting the currently selected node

tree = new webix.ui({ view:"tree",... });

var nodeId = tree.getSelectedId();
tree.remove(nodeId);

Selecting nodes

To select a specific node you should call the select method:

Selecting a node

tree = new webix.ui({ view:"tree",... });

tree.select("node2");// 'node2' is the item id

For more details, read article Items Selection.

Expanding/collapsing branches

Tree nodes are collapsed and expanded

  • by clicking on a "+/-" icon or a node (default behavior);
  • by clicking on a node text provided that activeTitle ptoperty is defined for the tree.
view:"tree",
activeTitle:true, //false by default
data:[...]

Related sample: Tree: JSON Dataset

Tree provides several methods to manage 'open'/'close' state of a node. They are:

Table 1 Managing 'open'/'close' state of a node
Method | Description
open | opens the branch with the specified id
close | closes the branch with the specified id
openAll | opens all branches in the tree
closeAll | closes all branches in the tree
isBranchOpen | checks whether the specified branch is opened
getOpenItems | returns ids of the opened branches

Checking whether the currently selected branch is opened

tree = new webix.ui({ view:"tree",... });

var nodeId = tree.getSelectedId();
tree.isBranchOpen(nodeId);

Filtering nodes

To filter the tree nodes you should call the filter method:

Filtering the tree

tree = webix.ui({ view:'tree', ...});

tree.filter("#value#", "abc");//leaves in the tree just items that contain text 'abc'

Related sample: Filtering

Read more on the topic in article Filtering in the Tree.

Sorting nodes

To filter the tree nodes you should call the sort method:

Ascending sort in the tree

tree = webix.ui({ view:'tree', ...});

tree.sort("#value#", "asc");//sorts all nodes (parent, child)

Related sample: Sorting

Read more on the topic in article Sorting in the Tree.

Updating the tree

To update the tree you may call one of 2 appropriate methods:

  • update
  • refresh

Methods lead to one and the same result and don't have any specificity.

tree.refresh();
//or
tree.updateItem(node_id, nodeObj);


Items Selection

Tree provides an ability to select leaves and branches within it.

Single-item selection

By default, selection is disabled in Tree. To activate it you should set the select parameter to true.

Enabling selection in Tree

tree = new webix.ui({
  view: "tree",
  ...
  select: true
})

Related sample: Selection

Multiple selection

To enable multiple selection in Tree, you should set parameter select to multiselect.

Enabling multi-selection in Tree

tree = new webix.ui({
  view: "tree",
  ...
  select: "multiselect"
})

Related sample: Multiline Selection

Related methods

getSelectedId | method | returns the selected cells
moveSelection | method | moves selection in the specified direction
select | method | selects the specified item
selectAll | method | selects all items
isSelected | method | checks whether the specified item is selected or not
unselect | method | cancels selection of the specified item
unselectAll | method | removes selection from all items

Related events

onAfterSelect | event | fires after a cell is selected
onBeforeSelect | event | fires before a cell is selected
onSelectChange | event | fires when selection is changed in DataTable


Node templates

To customize data presented in the nodes' titles you can use templates. Data template for the tree is set by property template.

With templates you can present almost any content in the tree: images, links, numbers, strings, dates etc.

By default, tree uses the following template for its items:

Default tree template

webix.ui({
    view:"tree",
    template:"{common.icon()} {common.folder()}<span>#value#<span>"
});

It means that each item features:

  • an expand/collapse node icon;
  • a folder/file icon that will automatically change depending on whether a node has children or not;
  • data value from the datasource.

More about Webix pattern of data interpolation you can find in the Data templates article.

Predefined Templates

Webix tree and treetable offers a set of predefined helpers that aid in item rendering and contain tree-specific elements like item icons, expand/collapse icons and checkboxes.

  • {common.icon()} - '+'/'-' icons for collapsed/expanded nodes
  • {common.folder()} - an icon of the folder or file. The folder can be closed or open depending on a node state;
  • {common.checkbox()} - a checkbox;
  • {common.treetable()} - (treetable only) - a combination of common.icon() and common.folder() in one line.

All of them are the methods of a common object that is accessable by all of the tree items and defined within tree/treetable Type mixin.

String definition

If you set a template by a string, you can include the tree-specific helpers via string:

Specifying the template parameter as a string

webix.ui({
    view:"tree",
    template:"{common.icon()} {common.checkbox()} {common.folder()} <span>#value#</span>",
});

Related sample: 2-state Checkboxes

The tree above will render items featuring an expans-collapse icon, checkbox and file/folder icon.

Function definition

If you set a template via a function, you can include the tree-specific helpers via functions, and they are functions in essense:

Specifying the template parameter as a function

webix.ui({
    view:"tree",
    template:function(obj, common){
        return common.icon(obj, common) + common.checkbox(obj, common)
            +common.folder(obj, common)+"<span>"+obj.value+"</span>",
    }
});

The input parameters of the helpers function are:

  • item object with the following properties:
    • item properties from the dataset;
    • helper properties that are added to tree items during data loading and exist only on client-side to maintain tree integrity:
      • $level - (number) the level of nesting (one-based numbering);
      • $parent - (string) the ID of thr item's parent;
      • $count - (number) the number of childs;
      • open - (boolean) defines whether the node is collapsed or expanded (only for parent nodes).
  • common object that provides 4 functions:
    • icon(obj, common) - draws the '+'/'-' icons for collapsed/expanded states of nodes
    • folder(obj, common) - draws an icon of the folder
    • checkbox(obj, common) - draws a check box
    • treetable(obj, common) (treetable only) - combines common.icon() and common.folder() in one line.

Benefits of function definition

Template function add more freedom in item template definition as numerous conditions can be taken into an account.

Let's assume, you want to show items that have the nesting level greater than 2 in italic font. In thic case you can specify the data template as in:

webix.ui({
  view:"tree",
  template: function(obj, common){
    if (obj.$level>2) {
       return common.icon(obj,common)+common.folder(obj,common)+"<i>"+obj.value+"</i>";
    } else {
       return common.icon(obj,common)+common.folder(obj,common)+obj.value;
    }
  }
});

You can also define additional common elements within the component type.

Predefined Templates: Use Cases

{common.icon()}

webix.ui({
    view:"tree",
    template:"{common.icon()} #value#"
})

{common.folder()}

webix.ui({
    view:"tree",
    template:"{common.folder()} #value#"
});

{common.checkbox()}

webix.ui({
    view:"tree",
    template:"{common.checkbox()} #value#"
});

{common.icon()} {common.checkbox()}

webix.ui({
    view:"tree",
    template:"{common.icon()}{common.checkbox()} #value#"
});

{common.icon()}{common.folder()} or {common.treetable()}

webix.ui({
    view:"tree",
    template:"{common.icon()}{common.folder()} #value#"
});

The same for [treetable](desktop/treetable.md) can be rendered via:

webix.ui({
  view:"treetable",
  columns:[
    { id:"value",
      template:"{common.treetable()} #value#"
    },
    {...}
  ]
});

{common.icon()}{common.folder()}{common.checkbox()}

webix.ui({
    view:"tree",
    template:"{common.icon()}{common.folder()}{common.checkbox()} #value#"
});

Changing Predefined Templates

The above mentioned template methods are parts of the tree type, a set of methods used for rendering tree items.

Tree type can be extended or altered:

webix.ui({
    view:"tree",
    type:{
        folder:function(obj){
            if(obj.$level == 1)
                return "<span class='webix_icon fa-folder-open'></span>";
            if (obj.$level == 2)
                return "<span class='webix_icon fa-video-camera'></span>";
        }
    }
});

webix.ui({
    view:"tree",
    type:{
        my_folder:function(obj){
            //code
        }
    }
});

Related sample: Custom Type

If you need to apply this type to several trees, you can define the type object separately and then refer to it by its name:

webix.type(webix.ui.tree, {
   name:"awesome",
   folder:function(obj){
       //code
    }
});

var tree2 = webix.ui({
   view:"tree",
   type:"awesome",
});

Related sample: Custom Type

More about type implementation for data components can be found in the Type implementation article.


Checkboxes in the tree

In this chapter we will talk about checkboxes in tree nodes: how to add, customize them or provide the 3-state behaviour.

Adding checkboxes to nodes

Tree provides a predefined template for check boxes, which is - {common.checkbox()}
(read more about templates in chapter Node templates).

So, to add checkboxes to tree nodes you should specify the template property like this:

Adding checkboxes to tree nodes

tree = new webix.ui({
    view:"tree",
    template:"{common.icon()} {common.checkbox()} {common.folder()} #value#"
    ...
});

{common.icon()} template adds '+'/'-' icons to the nodes, {common.folder()} - adds folder icons.

Related sample: 2-state Checkboxes

3-state checkboxes

In addition to standard 2-state behaviour, Tree supports 3-state checkboxes.

Table 1 Types of checkbox behaviour
Behaviour Description
2-state (standard)
  • When the user checks/unchecks a parent node - this only node is checked/unchecked
  • When the user checks/unchecks a child node - this only node is checked/unchecked
3-state
  • When the user checks/unchecks a parent node - this parent node and all its child nodes (of each nesting level) are checked/unchecked
  • When the user checks/unchecks a child node - this only node is checked/unchecked

To provide 3-state behaviour for tree checkboxes you should set the threeState property to true:

Activating 3-state behaviour for checkboxes

tree = new webix.ui({
    view:"tree",
    template:"{common.icon()} {common.checkbox()} {common.folder()} #value#",
    threeState: true
    ...
});

Related sample: 3-state Checkboxes

Manipulations with checkboxes

Checkboxes can be programmatically checked and unchecked as well as it is possible to get checked items and define, whether the item is currently checked or not.

  • checkItem(id)/ uncheckItem(id) - checks/unchecks tree node with the specified ID;
  • getChecked() - returns an array of IDs of the checked items;
  • isChecked(id) - helps find out whether the specified node is checked at the moment.
tree.checkItem(tree.getSelectedId());

tree.uncheckItem(tree.getSelectedId());

Checkboxes can be used for component refreshing just from browser.

Generally, components are refreshed by applying the refresh() method to them, yet it can be called each time tree checkbox changes. The item wth this checkbox will be refreshed:

webix.ui({
    view:"datatable",
    checkboxRefresh:true
});


Sorting in the Tree

Tree allows you to sort nodes on the client side. Note, along with the parent nodes, child nodes are sorted as well.

Data is sorted as strings and by levels, starting from the latest nesting level.

Common

Sorting in Tree can be invoked by calling the sort method. The method can be called on some event or action, i.e. button click or page load.

Sorting Tree on button click

<input type='button' onclick='tree.sort("#value#", "asc");'>

<script type="text/javascript" charset="utf-8">
    tree = webix.ui({ view:'tree', ...})
</script>

Related sample: Sorting

Custom sorting functions

If you want to apply a custom sorting behaviour, you should define the related logic in a function and invoke this function in the sort method.

This function is called for each pair of adjacent values and return 1,-1 or 0:

  • 1 - an object with the first value in pair must go before the second one;
  • -1 - the second object goes before the first one;
  • 0 - the order of both objects doesn't change.

Let's assume you have a tree like this:

And want to sort only car makes and keep the childs as they are. As the default sorting affects all nodes you need to provide a custom logic. It may look as in:

Sorting the tree by one level

<input type='button' value='sort car makes' onclick='tree.sort(sortMakes)'>

<script>
function sortMakes(a,b){
        if (a.$level == 2)
        {
            a = a.value;
            b = b.value;
            return a>b?1:(a<b?-1:0);
        }
        else{
            return 0;
        }
}
...
</script>

Note, Tree sorts data by levels starting from the lastest nesting level, i.e. at first car models of each make are sorted, then car makes themselves.

Related sample: Custom Sorting


Filtering in the Tree

Tree allows you to filter nodes on the client side.

Filtering is Tree can be invoked by calling the filter method. The method can be called on some event or action, i.e. button click or page load.

Sorting Tree on button click

<input type='button' onkeypress='tree.filter("#value#", this.value);'>

<script type="text/javascript" charset="utf-8">
    tree = webix.ui({ view:'tree', ...})
</script>

Related sample: Filtering

Filtering modes

The library provides special property filterMode to define how the tree items will be filtered.

The filterMode property is an object that can contain 3 attributes:

  • showSubItems - (boolean) defines whether the tree should display children of the filtered items (true) (even if they don't match the filtering condition). The default value - true.
  • openParents - (boolean) - defines whether parents of the filtered items should be expanded (even if they don't match the filtering condition) so that user can effortlessly see the result of filtering. True by default.
  • level - (number) sets the nesting level to filter items from (one-based numbering).

Using the filterMode parameter

webix.ui({
    view:"tree",
    filterMode:{
        showSubItems:false,
        level:2
    }
});

Related sample: Filtering

Custom filtering function

For example, if you add an input and button to the page and want to filter Tree by clicking on it, you code may look like this:

Custom filtering function

<input type="text"><input type="button" value='filter' onclick='filterText(this);'>

<script>
    function filterText(node){
        var text = node.previousSibling.value;
        if (!text) return tree.filter();

        tree.filter(function(obj){  //tree is a Tree instance
            return obj.year == text;
        })
    }
</script>


Editing in the Tree

Initially, Tree is a non-editable component. But you can easily make Tree editable by extending it with a special class - EditAbility.

Generally, the technique of making Tree editable looks like this:

  • Create a new component and inherit it from ui.tree and EditAbility classes.
  • Specify 3 parameters (inherited from EditAbility) in the constructor:
    • editable - enables editing in the component
    • editor - sets the type of the editor
    • editValue - the data property that will be edited

By default, editors are opened on a single click.

Making Tree editable

webix.protoUI({
    name:"edittree"
}, webix.EditAbility, webix.ui.tree);

var tree = new webix.ui({
    view:"edittree",
    ...
    editable:true,
    editor:"text",
    editValue:"value"
});

Related sample: Editing in Tree

Types of editors

There are various types of data editors in the Webix library. You can use any of them in different components. To get more details read the article Data Editors.

Below we'll describe 2 most frequently used editors for the tree:

  • text
  • select

text

A basic text editor.

Specifying the 'text' editor for the tree

webix.protoUI({
    name:"edittree"
}, webix.EditAbility, webix.ui.tree);

var tree = new webix.ui({
    view:"edittree",
    editable:true,
    editValue:"value",
    ...
    editor:"text"
});

Related sample: Editing in Tree

select

A dropdown list.

Specifying the 'select' editor for the tree

webix.protoUI({
    name:"edittree"
}, webix.EditAbility, webix.ui.tree);

var tree = new webix.ui({
    view:"edittree",
    editable:true,
    editValue:"value",
    ...
    editor:"select",
    options:["The Shawshank Redemption", "The Godfather"]
});

Denying editing specific items

To deny editing specific items, branches, levels etc. you can use the onBeforeEditStart event inherited from EditAbility. The event fires right before the user opens the editor and gets the id of the edited item as a parameter.
To deny editing of a item - return false for it within the appropriate event handler.

Making editable only the 2nd nesting level

webix.protoUI({
    name:"edittree"
}, webix.EditAbility, webix.ui.tree);

var tree = new webix.ui({
    view:"edittree",
    ...
    editable:true,
    editor:"select",
    editValue:"value",
    data: [
        { id:"1", open:true, value:"The Shawshank Redemption", data:[
            { id:"1.1", value:"Part 1" },
            { id:"1.2", value:"Part 2" },
            { id:"1.3", value:"Part 3" }
        ]},
        { id:"2", value:"The Godfather", data:[
            { id:"2.1", value:"Part 1" },
            { id:"2.2", value:"Part 2" }
        ]}
    ]
});
//only film parts (i.e. 'Part1', 'Part2') can be edited
tree.attachEvent("onBeforeEditStart", function(id){
    if ( this.getItem(id).$level != 1)
        return false;
});


Copy-Pasting Tree Data

To enable the possibility to copy/paste Tree data by the CTRL+C/CTRL+V keyboard shortcuts you should use parameter clipboard.

The parameter can have one of 3 values:

  1. 'modify' ( or true. It's the default value);
  2. 'insert';
  3. 'custom'.

Each of the types has its specificity and define its behavior of copying.

Setting the desired behavior of copying

tree = new webix.ui({
    view:"tree",
    ...
    clipboard:"insert"
});

Related sample: Pasting New Items

'Modify' copying

It's the default type and can be also specified by setting the true value.

The type of copying can be characterized as in:

  • When you copy the selected node in the tree, you copy the node title (doen't matter it's a parent or child node);
  • When you paste a text to the tree, it will be pasted as the title of the selected node.

Setting the 'modify' behavior of copying

tree = new webix.ui({
    view:"tree",
    ...
    clipboard:true
});

Related sample: Pasting Items' Titles

'Insert' copying
  • When you copy the selected node in the tree, you copy the node's title (doesn't matter whether it's a parent or a child node);
  • When you paste a text to the tree, it will be added as a child item of the selected node.

Setting the 'insert' behavior of copying

tree = new webix.ui({
    view:"tree",
    ...
    clipboard:"insert"
});

Related sample: Pasting New Items

Custom copying

The 'custom' value allows you to specify a custom logic for the paste operation.

To apply a custom 'paste' behaviour to the tree:

  • Set the clipboard parameter to "custom".
tree = new webix.ui({
    view:"tree",
    ...
    clipboard:"custom"
});

This command will cancel the predefined behaviour for the paste operation.

  • Specify custom logic in the onPaste event handler.
//the code does nothing but alerts messages
tree.attachEvent("onPaste", function(text) {
    webix.message("Node is pasted: " + text);
});

Tree invokes the onPaste event when the user presses CTRL+V keys combination.

Related sample: Custom Clipboard Operations


Styling DataTree

You can use CSS in conjunction with Tree nodes to archieve the desired look-and-feel.

In this article you will know how:

  • to fine-tune the style of a whole tree or specific nodes;
  • to add tree lines;
  • apply templates;
  • customize icons.

Styling a whole tree

To apply some style to a whole tree you can use the css parameter.

<style>
    .my_style  {
        font-style: italic;
        color:blue;
    }

</style>

<script>
    webix.ui({
        view:"tree",
        css:"my_style",
        ...
    })
</script>

Styling specific nodes

Generally, to style a specific item you can use the css attribute inside the data source.

<style>
    .my_style{
        background-color:#FFAAAA;
    }
</style>

<script>
grid = new webix.ui({
    view:"tree",
    data: [
       {id:"root", value:"Films data", open:true, data:[
       { id:"1", open:true, value:"The Shawshank Redemption", data:[
            { id:"1.1", value:"Part 1" },
                { id:"1.2", value:"Part 2", $css:"my_style" },
                { id:"1.3", value:"Part 3" }
            ]},
            { id:"2", value:"The Godfather", open:true, data:[
                { id:"2.1", value:"Part 1" },
                { id:"2.2", value:"Part 2", $css:"my_style" }
            ]}
        ]}
    ]
});
</script>

Adding lines

To add lines to tree nodes, set the type parameter to the 'lineTree' value.

Adding lines to tree nodes

tree = new webix.ui({
    view:"tree",
    ...
    type:"lineTree"
});

Related sample: Lines

Note, you still have a possibility to define your custom style for lines and apply it through the css parameter (see details in the first part).

Templates

One of ways to fine-tune the style of the tree is define some template for it.

Using templates for styling

webix.ui({
    view:"tree",
    template:"{common.icon()}{common.folder()}<div style='color:blue;'>#value#</div>"
});

Read more about using templates in chapter Node templates.

Custom Folder and Files Icons

The look-and-feel of tree icons is set via CSS classes applied to definite parts of it and you can change it in the same way by:

  • redefining existing Webix CSS classes. It changes icons for all tree nodes;
  • setting custom images as icons to desired tree nodes. For these needs, icons are stored in the dataset and applied via
    • custom CSS classes;
    • node templates.
  • modifying tree type to add extra helpers that will render the needed node elements (including FontAwesome Icons).

Redefining existing Webix CSS classes

Study Tree CSS image map to learn how classes are distributed. There you'll find that folder and file feature the following CSS:

  • webix_tree_folder - applied to folders in a close state;
  • webix_tree_folder_open - applied to folders in the open state;
  • webix_tree_file - applied to files (elements with no children).

The simplest way to change folder and file icons for all tree nodes is to redefine default ones setting new background image and position:

//customizing all folders and files in a tree
.webix_tree_folder{
    background-image: url("icons/folder.png");
    background-position: 0px 4px;
}
.webix_tree_file{
    background-image: url("icons/file.png");
    background-position: 0px 4px;
}

Related sample: Custom Folders

Using Custom Images as Icons

To set icons to desired tree nodes, you should store their titles in the data source:

If icon titles are stored under an icon property in the dataset, they are applied as webix_icon__name CSS class:

var data_with_icon = [
    { id:"root", value:"Films data", icon:"home", open:true, data:[
        { id:"1", icon:"puzzle", value:"Part 1" }]
    }
];
webix.ui({
    view:"tree",
    data:data_with_icon
});

The root item gets webix_icon_home CSS class. All you have to do is to set the rule for this class:

.webix_tree_home{
    background-image: url("icons/home.png")
}

Related sample: Icons

If icon titles are stored under an image property in the dateset, they are applied within a node template:

var data_with_icon = [
    { id:"root", value:"Films data", image:"home", open:true, data:[
        { id:"1.1", image:"puzzle", value:"Part 1" }]
    }
];

webix.ui({
    view:"tree",
    template:"<img src='icons/#image#.png' style='...'> #value#",
    data:data_with_icon
});

Related sample: Custom Icons

You can study Webix tree node templates in detail separately.


Drag-and-drop support

Tree has built-in support for internal/external drag-and-drop.

Common use

To enable drag-and-drop support for a tree, set the drag parameter to true:

Enabling drag-and-drop support for Tree

tree = new webix.ui({
    view:"tree",
    ...
    drag:true
})

Related sample: Enabling Drag-and-drop in Tree

The 'order' mode

There is a special drag-and-drop mode - 'order'.

In such a mode, items can't be dragged out of the tree container boundaries. Also, while dragging an item the remaining items are automatically rearranged so that when you drop the item to the final destination the remaining items won't need to do any rearrangements.

To enable the d-n-d support and activate the 'order' mode, just set the drag parameter to order.

Activating the 'order' mode for items

webix.ui({
        view:"tree",
        ...
        drag:'order'
});

Related sample: The 'order' DnD Mode

The 'source-target' mode

When you have several trees on the page, you may want to set specific tree(s) as the source of dnd (to drag items from) and specific tree(s) as the target of dnd (to drag items to).

  • To set a tree as the dnd source (the user can drag items from the tree but can't drag to it), you should set the drag parameter to source.
  • To set a tree as the dnd target (the user can drag items to the tree but can't drag from it), you should set the
    drag parameter to target.

Using the 'source-target' mode

//you can drag items only from treeA to treeB.
//Dragging within treeA is denied. Dragging from treeB to treeA is denied.
treeA = new webix.ui({
    view:"tree",
    ...
    drag:"source"
});

treeB = new webix.ui({
    view:"tree",
    ...
    drag:"target"
});

Related sample: Custom Dropping Behaviour

Advanced

Information stated in the Common part is enough in most cases. The current part should be used just if you want to customize existing drag-and-drop behaviour.

The part will describe the next things:

  • Custom text of the dragging items;
  • Denying dragging specific items;
  • Custom dropping behaviour;
  • Related events and the order in which these events are invoked.

Custom text of the dragging items

To redefine the text displaying for the dragging item(s), you should use the onBeforeDrag event.
The desired template is set through the context.html property. You can use any HTML while specifying the value for the property.

Displaying a custom text for dragging items

treea.attachEvent("onBeforeDrag", function(context, ev){
    context.html = "&nbsp;&nbsp;"+context.source.length+" item(s)";
});

Related sample: Custom Text of the Dragging Items

Denying dragging specific items

To deny dragging specific items you can use the onBeforeDrag event and return false each time you want to block the operation.

Denying dragging even items

tree.attachEvent("onBeforeDrag", function(context, ev){

    if (tree.getItem(context.source).$level == 2){
        return true;     // allows dragging items with the 2nd nesting level
    }
    return false;        // denies dragging in any other case
});

From now on, each time d-n-d is started, the item level will be checked, and the item can be dragged only if its level equal to 2.

Custom dropping behaviour

To specify custom behaviour for the 'drop' operation you can use the onBeforeDrop event.

Let's assume you want to specify the following behaviour:

  • When you drag item(s) to the closed folder, the item is inserted as a subling;
  • When you drag item(s) to the opened folder, the item is inserted as a child.

Custom dropping behaviour

tree.attachEvent("onBeforeDrop", function(context, ev){
    if (this.getItem(context.target).$count && this.getItem(context.target).open){
        //drop as the first child
        context.parent = context.target;
        context.index = 0;
    } else {
        //drop as the next subling
        context.index++;
    }
});

Related sample: Custom Dropping Behaviour
Related sample: Custom Dropping Behaviour. Denying Dropping

Related events

In the default scenario there is no need to use any of the mentioned events, because Tree will process all the operations on its own. Use the events only when the default behavior needs customizing.

The following events are generated while d-n-d process:

  • onBeforeDrag - fires before the mouse button is pressed and moved over a draggable item
  • onBeforeDragIn - fires before a dragged element is moved over the droppable area
  • onDragOut - fires when a dragged element is moved outside of the droppable area
  • onBeforeDrop - fires before a dragged element is released over the droppable area
  • onAfterDrop - fires after drag-n-drop was finished

Events order

Let's assume you have 2 same trees and drag an item from the 1st tree to the 2nd one.

So, here is the order in which events are invoked in trees:

  1. onBeforeDrag fires in tree1.
    Returning 'false' from the event handler will block the current dnd operation.
  2. onBeforeDragIn / onDragOut fire in tree1 as you drag the item within the tree1's container.
    Returning 'false' from the event handler will deny dropping to the related tree.
  3. onBeforeDragIn / onDragOut fire in tree2 as you drag the item within the tree2's container.
    Returning 'false' from the event handler will deny dropping to the related tree.
  4. onBeforeDrop fires in tree2.
    Returning 'false' from the event handler will block the current dnd operation.
  5. onAfterDrop fires in tree2.


Event handling with Tree

Tree supports various events that can be used to provide a custom behaviour for your tree.

There are 2 ways you can add a handler to the event:

  • through the method attachEvent();
  • through the parameter on.

Event names are case-insensitive

Method attachEvent()

You can attach several handlers to the same event and detach them using two respective methods:

A general way to attach/detach the event handler

// to attach event
var myEvent = $$("treeId").attachEvent("onItemClick", function () {
// event handler code
})

//to detach event
$$("treeId").detachEvent(myEvent);

Parameter 'on'

With the help of parameter on you can also attach any event(s) to a Tree object. But in contrast to using the attachEvent method you can't detach attached events later.

Attaching the event handler through parameter 'on'

webix.ui({
  view:"tree",
  ...
  on: {"itemClick": function () {alert("item has just been clicked");}}
);

Cancelable Events

All events with subword 'onbefore' can be cancelled.
To cancel some event you should return false within the appropriate event handler.

Cancelling the event handler

var myEvent = $$("treeId").attachEvent("onBeforeSelect", function () {
  ... // some event handler code
  return false;
})

Accessible objects and data

Inside the event handler you can refer to the holder component through keyword this.
Besides, most event handlers get incoming argument(s), like the id of a data item (see tree events to know exactly what arguments are passed inside event handler).

Btw, using the id of a data item you can access this item itself and all its properties. For example:

Referring within the event handler

$$("treeId").attachEvent("onAfterSelect",function(id){
  parentId = this.getItem(id).parent;
})


Treetable

API Reference
  • Methods, properties and events
  • Samples

Overview

Ui-related treetable inherits from view. Being a hybrid between DataTable and tree it shares a number of their properties and methods.

Initialization

Note that you need to set {common.treetable()} template for a column that should display the tree. Otherwise, you'll get standard datatable.

webix.ui({
    view:"treetable",
    columns:[
        { id:"id",  header:"", width:50},
        { id:"value", header:"Film title", template:"{common.treetable()} #value#"},
        { id:"chapter", header:"Mode",  width:200}
    ],
    data: "..." //dataset, variable or path
})

Related sample: Basic initialization

Tree table is populated with hierarchical data coming in XML and JSON data formats. IDs of the coulmns must coincide with data keys from the initial dataset

Working with Treetable

Common tasks here include the following and coincide with those of the datatable and tree:

1 . Data Loading including Dynamic Loading of large datasets in portions by scrolling and branches opening;

Related sample: Static and dynamic loading

2 . Filtering - built-in and custom filtering in various filter modes;

Related sample: Filtering in TreeTable

3 . Selection by cells, row and columns in multiselect and blockselect modes;

Related sample: Selecting items in TreeTable

4 . Item Editing by click or dblclick or any custom action;

Related sample: Editing data in TreeTable

5 . Using Math in Treetable - built-in logic for storing data as mathematic formulas as well as editing these formulas directly in treetable.

Related sample: Using formulas

6 . Data Grouping - built-in logic for preseting hierarchical data in a tree-like manner;

Related sample: Aggregating data while grouping

7 . Data Export to Excel and PNG

Related sample: Export to Excel

8 . Copy-Paste Operations

Related sample: Different copy-paste modes

Related Articles
  • Data Object Operations
  • Adding Active Elements to Nodes
  • Tree
  • Node templates
  • Sizing Components
  • Resizing
  • Redefinition of the Components
  • Treetable CSS Image Map


Unitlist

API Reference
  • Methods, properties and events
  • Samples

Overview

Unitlist presents data in groups derived from initial non-hierarchical dataset. Data items are sorted and then united by common values.

Initialization

List items are groupped by title

webix.ui({
    view:"unitlist",
    sort:{
        by:"#title#",
        dir: 'asc'
    },
    uniteBy:function(obj){
        return obj.title.substr(0,1);
    },
    type:{//setting item properties, optional
        height:50,
        headerHeight:30,
    },
    template:"#title#</br>#year#<br/>#votes#",
    data: set
});

Related sample: Unitlist

  • The uniteBy property groups data according to the specified criterion, the unit value (here it's the first letter to the data item title);
  • In addition it sets unit headers (unit values) and, additionally, sets template for them;
  • Sorting is applied to unit headers as well as to data items within the units.

Unit header template

view:"unitlist",
uniteBy:function(obj){
    return "<span style='background-color:"+obj.color+";'>"+
            obj.title.substr(0,1)+"</span>";
}

Working with Unitlist

Working with Unit Values

Unitlist API makes it possible to get text values of unit headers (unit values) as well as get data items that comply with this or that unit criterion.

  • getUnits() - returns JS array of unit values defined by the uniteBy property. The values are arranged in the alpabetical order, numbers first;
  • getUnitList(id) - returns the ID (or, more often, IDs) of data records united by "unit" criterion.
var units = $$('list').getUnits(); // -> // -> [1, C, M, T]

var unit = $$('unit').getInputNode().value; //getting value of the combo box text field
var id = $$("list").getUnitList(unit);

Related sample: Working with UnitList Items

If you know the ID of any data item, you can easily get to all its properties:

var title = $$("list").getItem(id).title;

If there're several data items that comply to the unit value criterion, they are returned in a JS array, and should be treated accordingly.

Common Functionality:

  • Data Loading.
  • Defining Data Template.
  • Adding Active Elements to Unitlist Items
  • Adding/Deleting Items.
  • Editing Data.
  • Data Filtering and Sorting
  • Selection
  • Paging
  • Components Export to PNG
  • Data Components Export to Excel

Note that there's no built-in possibility to edit data with unitlist. You should create a prototype editlist object beforehand.

Related Articles
  • Data Object Operations
  • Sizing Components
  • Resizing
  • Changing Component Properties
  • List
  • Grouplist
  • X-list
  • Unitlist CSS Image Map


Uploader

API Reference
  • Methods, properties and events
  • Samples

Overview

Uploader is a component that allows users to upload files. It allows browsing directories on your machine to choose the necessary file(s) and send them to server.

Uploader can be used standalone as well as integrated into form or UI component (in an "invisible" mode for the latter).

Initialization

webix.ui({
    view:"uploader",
    id: "uploader_1",
    value:"Upload file",
    link:"mylist",
    upload:"php/upload.php"
})

Related sample: Basic List Uploader

Working with Uploader
  • Uploading Files
  • Configuring Uploader
  • Progress Bar for Uploader
  • Uploader and Form Integration
  • Binding Uploader to Any Page Element


Window

API Reference
  • Methods, properties and events
  • Samples

Overview

Window is a ui-related component that looks like a standard on-screen window. It inherits from view but differs from other components in its character. It lies not within your app's layout but as if above other components. The same is true about popup.

Initialization

webix.ui({
    view:"window",
    id:"my_win",
    head:"My Window",
    body:{
        template:"Some text"
    }
})

Related sample: Windows: Basic Initialization

Comments:

  • Standard window contains head and body sections. However, head can be omitted if you don't need it;
  • To make window visible, you should apply show() method after its initialization;
  • A movable window contains move:true property in its constructor;
  • By default windows are non-modal. When such window is focused, it can be closed with an 'Esc' hotkey. Modality is described below.

Working with Window

Head

Head differs from window body in style and may contain:

  • a text header that is set as string value of head property;
  • a toolbar with controls. The most common are text label and "Close" button.
{view:"button", label:"Close", width:70, click:("$$('my_win').close();")}
        // "my_win" is your window's ID

Please note that there exist two functions to remove a window from the screen - close() and hide(). The first one completely removes the window from the app and there will be no way to show it back.

If you want to change the window's visibility rather than remove it, use hide(). Later on, it can appear on the page on calling show() method for it.

Body

This section may contain any view to match your needs.

Text template is set by initializing template component. It can be defined without direct initialization: {template:"some text"}.

Window with Datatable

webix.ui({
    view:"window",
    body:{
        view:"datatable",
        ...
    }
})

Related sample: Window with a Component Inside

Window Sizing and Positioning

The must-have parameters for the window are width and height. If you don't set them, the window will occupy the whole screen.

Furthermore, Webix window features various methods for setting its position. All of them are described in a separate documentation article.

Window Resizing

Window can be resized by user in browser with the help of a resizer icon in the right bottom corner of the window.

To enable this possibility, you need to include the resize property with the true value into the window's configuration.

Related sample: Windows: Resize

Window Modality

Modality is a feature of the ui-component that can affect the work of the application and control user-app interaction. Alert and Confirm message boxes are modal windows in their essence, as they prevent the workflow on the application main window.

The appearance of such window on the page prevent users from working with the app until they perform action required by this window (enter data, press the button, etc.. ).

UI-related Window is non-modal by default. Its modality is set with the help of the same-name property:

{view:"window", modal:true}

When a modal window is initialized, the app area is greyed out to indicate that it is disabled while you "communicate" with the window.

Related articles
  • Popup
  • Window and Popup Positioning
  • Message Boxes
  • Changing Visibility of Components
  • Window CSS Image Map


Popup and Window Positioning

By default window and popup (provided that they don't occupy the whole screen) will be placed in the upper left corner of the screen sticked to browser borders. To avoid this, position should be set.

Absolute Positioning

Left and top offset can be defined right in the component constructor:

webix.ui({
    view:"window"
    width:300,
    height:200,
    top:100,
    left:100
}).show();

At the same time, position can be set dynamically, by passing these parameters into its show(); function:

webix.ui({
    view:"window",
    ...
}). show({
    x:300, //left offset from the right side
    y:50 //top offset
});

Related sample: Window Offset

Another way is to use setPosition():

$$('my_window').setPosition(100, 100); //left and top offset

Relative Positioning

Relative positioning is achived with the help of position property. It takes the following values:

  • center - to place window or popup at the center of the screen;
  • top - to place window or popup at the top of the screen with center horizontal alignment. Also, "top" positioning adds slide animation: the window will slide from the top of the screen when shown and slide back when closed.
webix.ui({
    view:"window",
    position:"center" //or "top"
    //..window config

})

Related sample: Window: Centralization

Positioning Relative to HTML Node

Show() method allows specifying an HTML node near which a window will be shown.

$$("window").show(node);

By default, such pattern places the window below the node. To redefine this, pass position object as well:

$$("window").show(node, {pos:"top"});

Possible position values here are top, bottom (default), left and right.

To shift a window in relations to the node, pass its vertical and horizontal positions together with pos:

$$("window").show(node, {pos:"top", x:10, y:10});

Setting Position via State Object

By default, position is set in two way depending on window size:

  • If a window or popup is non-sized, it occupies the whole screen with top, bottom, left and right offsets being 0;
  • If a window or popup features custom size (width and height properties in its constructor), it is placed in the left upper corner of the screen with its top and left offsets being 0.

This default position can be changed or amended with the help of state object used in the function of the position property:

webix.ui({
    view:"window",
    head:"",
    body:{...},
    position:function(state){
        state.left = 20; //fixed values
        state.top = 20;
        state.width -=60; //relative values
        state.height +=60;
    }
});


Video

API Reference
  • Methods, properties and events
  • Samples

Overview

Webix video is a UI component designed for embedding video files into the application. It is based on HTML5 video tag to provide support for most popular video formats: MP4, WebM and Ogg.

Related sample: Video view init

Initialization

The component inherits from Webix view and is initialized with the help of webix.ui() constructor.

//<div id="video_div" style="width:300px; height:200px;"></div>

webix.ui({
    view:"video",
    id:"video1", //used to work with the component later
    container:"video_div",
    src: ["data/movie.ogv","data/movie.mp4"]
});

Video source defined by src property can be either a single video file or an array of several ones. In case of multiple src browsers will use the first supported format, which ensures that your video will be recognized regardless of the client side browser.

Video component can be initialized inside an HTML container (as above) as well as inside Webix window:

webix.ui({
    view:"window",
    head:"My Video",
    body:{
        view:"video",
        src:"..." //or [...]
    }
});

Related sample: Video view init

Customizing Video Player

Not much customization is possible, but still:

  • controls property can be used to disable player controls by setting its value to false. By default controls are enabled (true);
  • autoplay property can be used to start playing the video right after the component initialization. Default value is false.
view:"video",
src:[],
autoplay:true

Related sample: Autoplay

Working with Video

HTML5 video can be controlled programmatically using methods and properties of video DOM element:

  • play() and pause() methods to control the video;
  • paused - read-only property that stores video state.

To get the object of video DOM element, use the getVideo() method of Webix video component.

Let's get rid of prebuilt controls and assign play-and-pause function to a Webix button:

Related sample: Video API

UI - window with toolbar

webix.ui({
    view:"window",
    body:{
        view:"video",
        id: "video1",
        src:".."
        controls: false //removing default controls
    },
    head:{
        view:"toolbar", elements:[ //assigning a custom function to the button
            {view: "button", id: "playButton", value: "Play", click: playPause}
        ]
    },
}).show();

Logic

function playPause(){
    //getting video object
    var video = $$("video1").getVideo();

    //palying video if it's paused
    if (video.paused){
        video.play();
        $$("playButton").setValue("Pause")
    }
    else{
        //otherwise - pausing video
        video.pause();
        $$("playButton").setValue("Play")
    }
}

Alongside with playing and pausing the video, we change button text value with its setValue to correspond video state.


Start

UI Extensions

Except for a main line of UI components, the library provides a number of helpful extensions to simplify your development. Most of the extensions are task-oriented and intended to accomplish a certain purpose. They are already quite configurable and need only initializing on the page to start serving.

Pivot Table

A pivot table that helps you to summarize large numeric data sets in one spot.

Pivot Chart

A pivot chart that helps you to research and analyze large quantities of data and the relationships between them.

Map

An integration extension that allows you to add 3-rd party web maps to the app: Google Maps, Yandex Maps, Here Maps.

Chart

An integration extension that allows you to add 3rd-party charts to the app: Raphael, D3.

Text Editor

An integration extension that allows you to add 3rd-party editors to the app: Mercury, TinyMCE, Code Mirror, NicEdit.

Scheduler

An integration extension that allows you to add a 3rd-party event calendar to the app: dhtmlxScheduler of the DHTMLX library.

Mobile Scheduler

An integration extension that allows you to add the mobile version of the scheduler to the app.

Kanban Board

An integration extension that helps you to visualize and optimize your workflow.

File Manager

An integration extension that helps you to navigate folders and files in a handy way.

Sidebar

A component that helps you to create a hierarchical collapsible menu with a vertical navigation bar.

SpreadSheet

A component that allows creating various customizable tables that keep data locally.


Pivot Table

Webix Pivot is a fully client-side Javascript datatable with extended filtering capabilities to allow for well-organized visual reports made over large and complex datasets at a high speed. With Pivot you can easily compare, filter and sort data within one table as well as change the analysis pattern on the flow.

External resources
  • You can download Webix Pivot from http://webix.com/pivot/
  • There are online samples at docs.webix.com/samples

Guides
  • Structure and Usage
  • Initialization
  • Loading Data
  • Configuring Pivot
  • Localization
  • Customizing Pivot
 The guides will introduce Webix Pivot to you. You will learn about structure specificity, the peculiarities of initialization, data loading and configuration of the widget. Here you will also find the necessary information on how it's possible to localize and customize Pivot and its elements.


Structure and Usage

Webix Pivot consists of two functional parts:

  • Webix datatable with configurable columns, rows and filters;

Pay attention to the [click to configure] area of the datatable upper left corner. It is highlighted each time you mouse over it while clicking this area will make a configuration window show up.

  • Configuration window.

The window reflects current Pivot structure and contains five sections. The elements inside sections are based on the data item properties from the dataset and can be dragged to change Pivot structure:

Sample data

[
  {"name": "China", "year": 2005, "continent": "Asia", "form": "Republic",
  "gdp": 2256.919, "oil": 59.615, "balance": 134.098},
  ...
]
  • Fields contain all data properties (such as name, year, continent, form, etc. from the sample dataset) EXCEPT for those in Rows, Columns or Filters.
  • Fields dragged or initially set to Columns area define the x-scale of Pivot, namely the upper headers of the datatable;
  • Fields dragged or initially set to Rows define the y-scale of Pivot, namely the treetable to the left;
  • Fields dragged or initially set to Values define which data will be loaded as well as set the lowest row of datatable headers;
  • Fields dragged or initially set to Filters define data properties that will be used as filters for the datatable.

Balance among Sections

You cannot drag one and the same element to different sections; instead, use each element either for setting a row, or a column or for filtering or don't use it at all (it remains in Fields). However, Values section is more independent since elements dragged to it are still available in other sections except Filters.

Data Operations

Current data operations come together with values they are assigned to in the Values section. Right there they can be changed with a couple of clicks.

  • Sum - sums all values of this property and shows the sum;
  • Max - picks and shows the max value of this property;
  • Min - picks and shows the min value of this property;
  • Count - counts the number of occurrencies of this property and shows it.

In addition to the above-mentioned prebuilt operation types, you can as well create a custom one.

Filtering Options

Webix Pivot uses two filters:

  • text - filtering is performed by symbols you type in the text field. It supports base math comparison operators, so you can type something like "< 100", "> 2.5" or "= 12".
    If there is no operator, a filter will use text match for filtering;
  • select - filtering is performed by options that are automatically gathered from the dataset (all unique values of this property). For instance, if you choose Continents, all unique continent names from the dataset become options.


Initialization

Since Pivot tool comes as an add-on to Webix library you need to include both Webix and Pivot scripts and CSS files on your page to make everything work. Make sure you specify relative paths to these files:

<html>
 <head>
  <!-- js files -->
  <script src="codebase/webix.js" type="text/javascript"></script>
  <script src="codebase/pivot.js" type="text/javascript"></script>
  <!-- css files -->
  <link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
  <link rel="stylesheet" href="codebase/pivot.css" type="text/css" charset="utf-8">
 </head>
 <body>
   <div id = "testA"></div>  <!-- containter for Pivot -->
 </body>
</html>

The initialization of Pivot doesn't differ from that of other Webix components and is done with webix.ui() constructor function where you enumerate all the necessary properties:

webix.ui({
    view: "pivot",
    container: "testA",
    id: "pivot",
    max: true,
    structure: {
        rows: ["form", "name"],
        columns: ["year"],
        values: [
            { name: "gdp", operation: "sum"},
            { name: "oil", operation: "sum"}
        ],
        filters: []
    }
});

Properties
  • id - string, number - component ID, should be unique within a page. In Webix, any component is referred to by its ID, $$("id"), to perform various operations with it;
  • container - string - ID of an HTML container Pivot will be put to (optional);
  • fieldMap - object - can be used to define custom labels for fields (optional). The details are described in the Renaming fields section of Pivot configuration;
  • max - boolean - enables or disables GREEN highlighting of a cell(s) with the the biggest value in a row (optional);
  • min - boolean - enables or disables RED highlighting of a cell(s) with the least value in a row (optional);
  • data or url - string - defines dataset (see the details in the Loading Data article);
  • structure - object - defines initial display and analysis pattern;

Structure Object

  • rows - array of fields that will be used as pivot's rows and displayed in the treetable on the left;
  • columns - array of fields that will be used as pivot's columns and will be displayed above the datatable area;
  • values - array of fields that will be used as pivot's data (will be displayed in datatable cells);
  • filters - array of fields that will be used as filters and will be displayed above the datatable columns.


Loading Data

Pivot supports both inline and external (including serverside) data in any of the Supported Data Types: XML, JSON, JSArray and CSV.

Inline Data

Inline Data (JSON)

var pivot_dataset = [
    {"name": "China", "year": 2005, "form": "Republic", "gdp": 181.357, "oil": 1.545 },
    {"name": "China", "year": 2006, "form": "Republic", "gdp": 212.507, "oil": 1.732 },
    //...
]

To load inline data during component init, make use of data property:

webix.ui({
    view: "pivot",
    id: "pivot",
    data: pivot_dataset
});

To load inline data after component init on some event, for instance, use the parse function:

$$("pivot").parse(pivot_dataset);

External Data

Either you get data from an external file or by a serverside script, you should use the following pattern.

If you load the data during component init, specify the path to this file/script as value of url

{
    view: "pivot",
    url: "../load.php" // or "../data.json"
}

If you load data after the component has been initialized (e.g. on some event), use the load function:

$$("pivot").load("../load.php");
//or
$$("pivot").load("../data.json");

In essence, Pivot complies to standard Webix Data Loading rules.

Data export

You can export result to PDF or Excel:

webix.toPDF($$("myPivot"));
webix.toExcel($$("myPivot"));


Configuring Pivot

Getting and Setting Configuration Object

You can get and set the pivot configuration object as follows:

//get current configuration
var config = pivot.getStructure();

//set configuration
pivot.setStructure(config);

Format of a config object is the same as "structure" parameter of the constructor:

var config = {
    rows: ["form", "name"],
    columns: ["year"],
    values: [
        { name: "gdp", operation: "sum"},
        { name: "oil", operation: "sum"}
    ],
    filters:[]
}

Related sample: Setting/Getting structure

Defining Operations on Data

Operations are set within Pivot structure object in values array. Name refers to data item property:

view: "pivot",
structure: {
    values: [
        { name: "gdp", operation: "sum" }, //gdp values will be summed
        { name: "oil", operation: "max" } //max oil value will be shown
    ]
}

There are 4 prebuilt operations over data:

  • sum - default, shows the sum of values of this property;
  • max - shows the max value of this property found in the dataset;
  • min - shows the min value of this property found in the dataset;
  • count - shows the number of occurencies of this property in the dataset.

If needed, you can add your own operation:

pivot.operations.abssum = function(data) {
    // data - array of values which need to be processed
    var sum = 0;
    for (var i = 0; i < data.length; i++) {
        var num = window.parseFloat(data[i], 10);
        if (!window.isNaN(num))
        sum += Math.abs(num);
    }
    return sum;
};

And use it as:

values:[ name:"oil", operation:"abssum"]

Related sample: Defining custom functions

Sum counters for columns and rows

To calculate the total sum for each row, total column can be set:

view:"pivot"
totalColumn: "sumOnly",
...

To calculate the total sum per column, footer can be defined:

view:"pivot"
footer: "sumOnly",
...

Related sample: Total Column and Footer

The "sumOnly" value of both properties forces the summing function to process only rows/columns that contain sums already.

Filters

Filters are set within Pivot structure object in filters array. Name refers to data item property used for filtering:

view:"pivot",
structure: {
    filters: [
        { name: "name", type:"select" },
        { name: "continent", type: "text" }
    ]
}

There are two types of filters:

  • select - filters by options automatically gathered from a dataset (all unique values of this property). For instance, if you choose Continents, then all unique continent names from the dataset become options;
  • text - filters by symbols in the text field. It supports base math comparison operators, so you can type something like "< 100", "> 2.5" or "= 12"
    If there is no operator, filter will use text match for filtering.

Renaming fields

By default, Pivot uses data item properties for column names. But if you have dataset structured like below, the default pattern becomes unsuitable:

[{ a1:100, a2:1.34 }, ...]

In this case, you can use fieldMap property to set beautiful names for columns instead of a1 and a2:

webix.ui({
    view: "pivot",
    fieldMap: { "a1" : "GDP", "a2" : "Grow ratio" },
    //...
});

Related sample: Custom field titles

Setting readonly mode

In order to disable changing of the pivot configuration settings, you can specify the readonly config property with the "true" value:

webix.ui({
    view: "pivot",
    readonly:true,
    //...
});

Related sample: Readonly mode

Specifying Header Sorting

You can enable header sorting in Pivot by specifying the sort property with the "string" value in the column configuration:

webix.ui({
    view: "pivot",
    id: "pivot",
    structure:{
        rows: ["year"],
        columns: [{id:"form",sort:"string"}, {id:"continent",sort:"string"}],
        values: [{name:"balance", operation:"sum"}]
    }
});

It's also possible to define the sorting direction in the column. By default, the direction is ascending. You can change it by setting the sortDir property with the "desc" value in the column configuration:

structure:{
    rows: ["year"],
    columns: [
               {id:"form",sort:"string", sortDir:"desc"},
               {id:"continent",sort:"string"}
             ],
    values: [{name:"balance", operation:"sum"}]
}

Related sample: Sorted Header


Localization

By defaut, all names and titles in Pivot are defined in English, but you can set any other language by specifying a custom locale for the page.

webix.i18n.pivot = {
    columns: "Columns",
    count: "count",
    fields: "Fields",
    filters: "Filters",
    max: "max",
    min: "min",
    operationNotDefined: "Operation is not defined",
    pivotMessage: "[Click to configure]",
    rows: "Rows",
    select: "select",
    sum: "sum",
    text: "text",
    values: "Values",
    windowTitle: "Pivot Configuration",
    windowMessage: "[move fields into required sector]"
};

//and then init Pivot and see you custom names
webix.ui({
    view:"pivot",
    //...
});

Related sample: Localization


Customizing Pivot

Getting Datatable Object

You can access the DataTable object by using the next code:

var datatable = $$("pivot").$$("data");

It allows you to use any of datatable events or API methods. At the same time, it's not recommended to redefine datatable properties.

//attach event to selection
datatable.attachEvent("onAfterSelect", function (id) {
    webix.message("selected row: "+id);
});

//or get the ID of the currently selected item.
var sel = datatable.getSelectedId();

Popup customization

Accessing Popup

The onPopup event fires after a popup for configuring Pivot is created. The handler function takes one parameter:

  • popup - (object) the popup object
pivot.attachEvent("onPopup", function(popup){
    // your code
});

"Fields" sorting

The "Fields" list can be sorted by applying "$sort" scheme. The ascending order is default. So, you can define only "text" as a keyword:

webix.ui({
    view: "pivot",
    on:{
        onPopup: function(popup){
            popup.$$("fields").define("scheme",{
                $sort: {
                    by: "text"
                }
            });
        }
    }
});

Adding scrolls to all lists

By default, only the "Fields" and "Values" lists are scrollable. Here is how you can add scrolls to all lists:

webix.ui({
    view: "pivot",
    on:{
        onPopup: function(popup){
            // scroll for "Filters"
            popup.$$("filters").define("scroll",true);
            // scroll for "Columns"
            popup.$$("columns").define("scroll",true);
            // scroll for "Rows"
            popup.$$("rows").define("scroll",true);
        }
    }
});

Changing Pivot Structure

The Pivot structure selected in the Popup can be customized with the help of the onBeforeApply event.

The event is fired on the "Apply" button click and its handler takes the structure object with chosen "filters", "rows", "columns" and "values" as a parameter.

For example, you can specify header sorting before applying the selected structure:

webix.ui({
    view: "pivot",
    on:{
        onBeforeApply: function(structure){
            var columns = structure.columns;
            // apply header sorting
            for(var i =0; i < columns.length; i++){
                if(typeof cols[i] == "string"){
                    cols[i] = {id: cols[i], sort: "string"};
                }
                else
                    cols[i].sort = "string";
            }
        }
    }
});

Prerender Customization

Pivot allows changing the configration of filtering views and the datatable with the help of the onBeforeRender Event. The event takes an object with 3 properties as a parameter:

  • filters - an array with configurations of views in toolbar. For example, if you set up a filter with select type, there will be configuration for the "select" control;
  • header - an array with configuration for all columns of pivot datatable;
  • data - json dataset for the datatable.

Pivot fires the onBeforeRender event before it's rendered. So, this event can be used to customize filters, columns array of datatable and its data source.

Let's consider a couple of examples:

1) changing text in columns header from "value (min)" to "min of value":

webix.ui({
    view: "pivot",
    on:{
        onBeforeRender: function(config){
            // get columns collection
            var columns = config.header;
            // change text of value columns
            for(var i=1; i < columns.length; i++){
                var h = columns[i].header;
                var text = h[h.length-1].text.replace(/(\w+)\s\((\w+)\)/,'$2 of $1');
                h[h.length-1].text = text;
            }
        }
    }
});

2) setting different colors for columns:

webix.ui({
    view: "pivot",
    on:{
        onBeforeRender: function(config){
            var columns = config.header;
            for(var i=1; i < columns.length; i++){
                columns[i].cssFormat = function(value){
                    var css = "";
                    if(value <0)
                        css = { "color":"red" };
                    else if(value >0 )
                        css = { "color":"green" };
                    return css;
                };
            }
        }
    }
});


Pivot Chart

Webix Pivot Chart is fully client-side Javascript tool for graphical representation of data. A plenty of configuration options allows users to use the tool for understanding, analyzing and researching large quantities of data and the relationships between them.

External resources
  • You can download Webix Pivot Chart from http://webix.com/pivot/chart.html
  • There are online samples at docs.webix.com/samples

Design and Usage

Webix Pivot Chart consists of two functional parts:

  1. Webix chart reflecting specified data properties and conditions:

  2. Configuration window (appeares when the user clicks the 'Settings' icon):

Configuration Window

The window reflects the current Pivot Chart structure and contains four sections. The elements inside sections are based on the data item's properties from the dataset and can be dragged to change Pivot Chart structure:

Sample data

[
    {"name": "China", "year": 2005, "continent": "Asia", "form": "Republic",
    "gdp": 2256.919, "oil": 59.615, "balance": 134.098},
    //...
]
  • 'Fields' block presents all data properties of the dataset (such as name, year etc.) EXCEPT for those that are selected in the Filters and Group By blocks.
  • Fields dragged or initially set in the Values block define which data will be loaded to the chart. Each data property in the Values block presents an individual graph (see details).
  • A field dragged or initially set in the Group By block defines a data property that Values's properties will be grouped by. For example, if the user sets the "balance" property as Values's value (the 'sum' operation) and the "year" property as Group by's value then the chart will display the total balance of all countries for each year. Note, only one data property can be specified in the Group By block.
  • Fields dragged or initially set in the Filters block define data properties that will be used as filters for the chart. For each data property in the Filters block, Pivot Chart creates an individual input in the header of the chart (nearby the 'Settings' button) (see details).

Balance among Sections

You cannot drag one and the same element to different sections; instead, use each element either for grouping or for filtering or don't use it at all (it remains in Fields). However, Values section is more independent since elements dragged to it are still available in other sections except Filters.

Data Operations

Current data operations come together with values they are assigned to in the Values section. Right there they can be changed with a couple of clicks.

  • Sum - sums all values of this property and shows the sum;
  • Max - picks and shows the max value of this property;
  • Min - picks and shows the min value of this property;
  • Count - counts the number of occurrencies of this property and shows it.

In addition to the above-mentioned prebuilt operation types, you can as well create a custom one.

Filtering Options

Webix Pivot Chart uses two filters:

  • text - filtering is performed by symbols you type in the text field. It supports base math comparison operators, so you can type something like "< 100", "> 2.5" or "= 12".
    If there is no operator, a filter will use text match for filtering;
  • select - filtering is performed by options that are automatically gathered from the dataset (all unique values of this property). For instance, if you choose Continents, then all unique continent names from the dataset become options.

Logarithmic scale

When difference between compared values is significant, smaller values can be hardly recognizable on the chart. To prevent it and make all values available for analysis, you can use the logarithmic scale instead of the default linear one.
To enable the logarithmic scale, check the "Logarithmic scale" checkbox in the configuration window.

Initialization

Since Pivot Chart tool comes as an add-on to Webix library you need to include both Webix and Pivot Chart scripts and CSS files on your page to make everything work. Make sure you specify relative paths to these files:

<html>
 <head>
  <!-- js files -->
  <script src="codebase/webix.js" type="text/javascript"></script>
  <script src="codebase/pivotchart.js" type="text/javascript"></script>
  <!-- css files -->
  <link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
  <link rel="stylesheet" href="codebase/pivotchart.css" type="text/css" charset="utf-8">
 </head>
 <body>
   <div id = "testA"></div>  <!-- containter for Pivot Chart-->
 </body>
</html>

The initialization of Pivot Chart doesn't differ from that of other Webix components and is done with webix.ui() constructor function where you enumerate all the necessary properties:

webix.ui({
    container:"testA",
    id:"pivot",
    view:"pivot-chart",
    structure:{
        groupBy: "continent",
        values: [
            {name:"balance", operation:"max", color: "#eed236"},
            {name:"oil", operation:"max", color: "#36abee"}
        ],
        filters:[{name:"year", type:"select"}]
    },
    url: "../common/data.json"
});

Properties

  • id - string, number - component ID, should be unique within a page. In Webix, any component is referred to by its ID, $$("id"), to perform various operations with it;
  • container - string - ID of an HTML container Pivot Chart will be put to (optional);
  • fieldMap - object - can be used to define custom labels for fields (optional) (details);
  • data or url - string - defines dataset (details);
  • structure - object - defines initial display and analysis pattern (details);
  • chart - object - defines the chart configuration options that you want to redefine, i.e. object with a set of redefined properties (details);
  • chartType - string - sets the default chart type;
  • chartMap - object - can be used to redefine default types of a chart ('bar', 'line', 'radar') or add a new one ('stacked bar' or 'area') (details);
  • filterWidth - number - sets the width of filters (both input and label) in the header of the chart;
  • filterLabelWidth - number - sets the width of the filters' labels;
  • filterLabelAlign - string - sets the horizontal alignment of the filters' labels;
  • editButtonWidth - number - sets the width of the "Settings" button;
  • singleLegendItem - boolean - specifies whether the legend should be displayed if it contains only 1 item;
  • palette - array - specifies the pop-up color pallete of the Values' values
    palette:[ ["#e33fc7","#a244ea",...],["#d3ee36","#eed236",.. ],.. ] - each inner array specifies a row in the pallete

Structure Object

  • values - array of fields that will be used as pivot's data (will be displayed in datatable cells);
  • filters - array of fields that will be used as filters and will be displayed above the datatable columns;
  • groupBy - the name of the field that will be used to group values by.

Loading Data

Pivot Chart supports both inline and external (including server-side) data in any of the supported data types: XML, JSON, JSArray and CSV.

Inline Data

Inline Data (JSON)

var pivot_dataset = [
    {"name": "China", "year": 2005, "form": "Republic", "gdp": 181.357, "oil": 1.545},
    {"name": "China", "year": 2006, "form": "Republic", "gdp": 212.507, "oil": 1.732},
    //...
]

To load inline data during component init, make use of data property:

webix.ui({
    view:"pivot-chart",
    id:"pivot",
    data:pivot_dataset
});

To load inline data after component init on some event, for instance, use the parse function:

$$("pivot").parse(pivot_dataset);

External Data

Either you get data from an external file or by a server-side script,use the following pattern:

  • If you load the data during component init, specify the path to this file/script as value of url:
{
    view:"pivot-chart",
    url:"../load.php" // or "../data.json"
}
  • If you load data after the component has been initialized (e.g. on some event), use the load function:
$$("pivot").load("../load.php");
//or
$$("pivot").load("../data.json");

In essence, Pivot Chart complies to standard Webix Data Loading rules.

Configuring Pivot Chart

Defining chart properties

To redefine the default properties of the chart, such as a legend or width of bars, you can use the chart object. Any property that you specify in the chart object will redefine the analogous one in the default configuration object:

view:"pivot-chart",
chart: {
    scale: "logarithmic",
    barWidth: 25,
    legend: {
        layout: "x",
        align: "center",
        valign: "bottom"
    }
}

Note, you can use any property available for the Chart component (a list of properties).

Defining Operation on Data

Operations are set within Pivot Chart structure object in values array. Name refers to data item property, color - to the color of the related graph:

view:"pivot-chart",
id:"pivot",
structure:{
    values:[
        {name:"gdp",operation:"sum",color:"#eed236"},//gdp values will be summed
        {name:"oil",operation:"max",color:"#36abee"}//max oil value will be shown
    ]
}

There are 4 prebuilt operations over data:

  • sum - default, shows the sum of values of this property;
  • max - shows the max value of this property found in the dataset;
  • min - shows the min value of this property found in the dataset;
  • count - shows the number of occurencies of this property in the dataset.

If needed, you can add your own operation:

view:"pivot-chart",
groupMethods:{
    abssum: function(template, data){
        data = data || this;
        var summ = 0;
        for (var i = 0; i < data.length; i++)
            summ+= Math.abs(template(data[i])*1);
        return summ;
    }
},

And use it as:

values:[ name:"oil", operation:"abssum"]

Filters

Filters are set within Pivot Chart structure object in filters array. Name refers to data item property used for filtering:

view:"pivot-chart",
structure:{
    values:[
        {name:"name",type:"select"},
        {name:"continent", type:"text"}
    ]
}

There are two types of filters:

  • select - filters by options automatically gathered from a dataset (all unique values of this property). For instance, if you choose Continents, then all unique continent names from the dataset become options;
  • text - filters by symbols in the text field. It supports base math comparison operators, so you can type something like "< 100", "> 2.5" or "= 12"
    If there is no operator, filter will use text match for filtering.

Renaming fields

By default Pivot Chart uses data item properties for column names. But if you have dataset structured like below, the default pattern becomes unsuitable:

[{ a1:100, a2:1.34 }, ...]

In this case, you can use the fieldMap property to set beautiful names for columns instead of a1 and a2:

webix.ui({
    view:"pivot",
    fieldMap:{ "a1" : "GDP", "a2" : "Grow ratio" },
    //...
});

Adding chart types

By default, Pivot Chart gives users a possibility to present data in 3 types of a chart: 'bar', 'line', 'radar'. If you need you can redefine the default types or add a new one.

Note, just types 'stacked bar' and 'area' can be additionally added to the Pivot Chart.

To add a new chart's type to Pivot Chart, use the chartMap property:

Adding a new chart's type

view:"pivot-chart",
chartMap: {
    "Area Radar": function(color){ //adds a new chart type 'Area Radar'
        return {
            type: "radar",
            alpha: 0.4,
            disableItems: true,
            fill: color,
            line:{
                color: color,
                width:1
            }
        }
    },
    "Line": function(color){ //redefines the default 'Line' type
        type:"line",
        offset:false,
        preset:"plot"
    }
}

The chart's type is identified by its name ("Area Radar" and "Line" in the code above). The names of the default types you can check in the 'Chart type' control of the Configuration window.

Setting readonly mode

In order to disable changing of the Pivot Chart configuration settings, you can specify the readonly config property with the "true" value:

webix.ui({
    view: "pivot-chart",
    readonly:true,
    //...
});

Related sample: Read-Only

Localization

By defaut all names and titles in Pivot Chart have English names, but you can change it by setting a custom locale for the page.

webix.i18n.pivot = {
    apply: "Anwenden",
    bar: "Balken",
    cancel: "Abbrechen",
    groupBy: "Gruppieren nach",
    chartType: "Diagramm Typ",
    count: "zahl",
    fields: "Felder",
    filters: "Filtern",
    logScale: "Logarithmischen Skala",
    line: "Linien",
    max: "max",
    min: "min",
    operationNotDefined: "Operation ist nicht definiert",
    radar: "Netzdiagramm",
    select: "auswahl",
    settings: "Einstellungen",
    sum: "summe",
    text: "text",
    values: "Werte",
    valuesNotDefined: "Werte oder Gruppenfeld ist nicht definiert",
    windowMessage: "[ziehen Felder auf gewunschten Sektor]"
};

//and then init Pivot Chart and see you custom names
webix.ui({
    view:"pivot",
    //...
});

API

Getting and Setting Configuration Object

//get current configuration
var config = $$("pivot").getStructure();

//set configuration
$$("pivot").setStructure(config);

Format of a config object is the same as "structure" parameter of the constructor:

var config = {
    groupBy: "year",
    values: [{name:"balance", operation:"sum", color: "#eed236"}],
    filters:[{name:"name", type:"select"}]
}

Data export

You can export result to PDF or Excel:

$$("pivot").toPDF();
$$("pivot").toExcel();

Getting Chart Object

You can access the Chart object by using the next code:

var chart = $$("pivot").$$("chart");

This allows you use any of Chart events or API methods.


Intermediate

Text Editor Integration

JS files for these components aren't included in the lib package and should be taken from https://github.com/webix-hub/components

Webix library supports integration of popular text editors in the application with the help of its own components. For now, the following text editors can be included:

  • Mercury;
  • NicEdit;
  • Tinymce;
  • CodeMirror;
  • CKEditor.

To embed any of the editors into your web page, you should link not only to Webix, but also to a special JavaScript file from the components folder. This file will connect you to the chosen editor as well load extra required files for it.

Note that in documentation samples files are linked in another way, but in your apps you should follow the patterns described below.

Mercury Text Editor

Mercury is a fully featured HTML5 editor with full HTML, simple, markdown, snippet and image areas to get the utmost from in-browser content editing.

Learn more about Mercury text editor

Related sample: Mercury text editor

Component Initialization:

Link to the library

<script type="text/javascript" src="./mercury.js"></script>

JS code

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    id: "editor",
    view: "mercury-editor",
    value: "..." //text and HTML markup
});

NicEdit Text Editor

NicEdit is a simple and fast WYSIWYG editor for websites. Being extremely lightweight it makes any element/HTML container editable or converts standard textareas to rich text editing fields.

Learn more about NiceEdit text editor

Related sample: NiceEdit text editor

Component Initialization

Link to the library

<script type="text/javascript" src="./nicedit.js"></script>

JS code

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    id: "editor",
    view: "nic-editor",
    value: "..." //text and HTML markup
});
</script>

TinyMCE Text Editor

TinyMCE is a platform independent web based Javascript HTML WYSIWYG editor control. It has the ability to convert HTML TEXTAREA fields or other HTML elements to editor instances.

Learn more about TinyMCE text editor

Related sample: TinyMCE text editor

Component Initialization

Link to the library

<script type="text/javascript" src="./tinymce.js"></script>

JS code

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    id: "editor",
    view: "tinymce-editor",
    value: "..." //text and HTML markup
});
</script>

Codemirror Text Editor

CodeMirror is a JavaScript component that provides a code editor in a browser. When a mode is available for the language you are coding in, it will color your code, and optionally help with indentation.

Learn more about Codemirror text editor

Related sample: Codemirror text editor

Component Initialization

Link to the library

<script type="text/javascript" src="./codemirror.js"></script>

JS code

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    id: "editor",
    view: "codemirror-editor",
    mode: "javascript",
    value: "..." //text and HTML markup
});

Note that here an extra property appears - mode that denotes a language you are coding in.

CKEditor Text Editor

CKEditor is a ready-for-use WYSIWYG editor that brings word processor features directly to your web pages. It is suitable for editing plain texts as well as HTML markup.

Learn more about CKEditor text editor

Related Sample: Ckeditor Text Editor

Component Initialization

Link to the library

<script type="text/javascript" src="./ckeditor.js"></script>

JS code

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    id: "editor",
    view: "ckeditor",
    value: "..." //text and HTML markup
});

Common Methods:
  • setValue(value); - sets text for the editor (equal to value property, but allows doing it dynamically). The function is called from the component referring to its ID.
$$("editor").setValue("<p>some text or code snippet</p>");
  • getValue(); - gets the current editor text with current formatting. Formatted text pieces are wrapped into corresponding HTML tags;
$$("editor").getValue(); // returns e.g "some<b> text</b> "
  • getEditor(); - gets the editor object so that you can use its specific API (exept for Mercury editor).
$$("editor").getEditor();
  • focus(); - in case of several editors on the page this method allows placing cursor mark into the desired editor.
$$("editor").focus();


Intermediate

Chart Integration

JS files for these components aren't included into the lib package and should be taken from https://github.com/webix-hub/components

Except for built-in charts, Webix offers a possibility to integrate with third-party charts of the following libraries:

  • D3 JS Library
  • JastGage Javascript Plugin
  • Raphael JavaScript Library
  • SigmaJS Library

Note that third-party scripts are included to documentation samples in another way, but you should follow the linking pattern described below.

D3 Charts

D3 charts helps manipulate documents based on data and offers powerful visualization tools and a data-driven approach to DOM manipulation.

One of its implementations, Bubble chart, displays data in the area of circles that pack hundreds of values into a small space. It looks like a bundle of multicolored balloons.

Related sample: D3 Bubble Chart

Component Initialization

Firstly, you should include D3 JS file from the package into your document in addition to Webix files:

<script type="text/javascript" src="./d3.js"></script>

And then init the view:

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    view:"d3-chart",
    url:"...",
    ready:function(){...};
});
  • url - specifies data source for the chart (data file or script);
  • ready - function that is executed when the component is fully loaded. It contains the code of the needed chart (available on their site).

Justgage Gauges

JustGage JS is a handy JavaScript plugin for generating and animating nice gauges. It is based on Raphaël library for vector drawing.

Related Sample: JustGage Chart

Component Initialization

Firstly, you should include JustGage JS file from the package into your document in addition to Webix files:

<script type="text/javascript" src="./justgage.js"></script>
<!-- Raphael JS will be autoloaded -->

And then initialize the view:

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    view:"justgage-chart",
    value:25,
    title:"Positive",
    height:300,
    min: 0,
    max: 100
});
  • Full list of a Justgage gauge object properties can be found on their site.

Raphael Charts

Raphael JS lib offers a number of visualization tools that help working with with vector graphics on the web.

For instance, its dot chart encodes data in the area of circles placed on the coordinate system.

Related sample: Raphael Chart

Component Initialization

Firstly, you should include Raphael JS file from the package into your document in addition to Webix files:

<script type="text/javascript" src="./raphael.js"></script>

And then init the view:

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    view:"raphael-chart",
    url:"...",
    ready:function(){...};
});
  • url - specifies data source for the chart (data file or script);
  • ready - function that is triggered when the component is fully loaded. It contains the chart's source code available on the Raphael library site.

Sigma Charts

Sigma is JS library that aids in drawing graphs using the HTML canvas element. It offers several graph types.

Related sample: Sigma Chart

Component Initialization

Firstly, you should include Sigma JS files from the package into your document in addition to Webix files:

<script type="text/javascript" src="./sigma.js"></script>

And then initialize the view:

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    view:"sigma-chart",
    url:"./data/les_miserables.gexf"
});
  • URL property specifies a path to a data file or script that will generate data.

The look-and-feel of a Sigma chart is defined by a currently used plugin. By default, Webix-integrated Sigma chart uses Fisheye plugin described in a tutorial on Sigma JS site. At the same time, you can easily change the plugin within the component source code in a private _after_render() function:

_render_once:function(){
    webix.require([
        "sigma/sigma.js", //sigma lib file
        "sigma/plugins/sigma.parseGexf.js", //GEXF extension
        "sigma/plugins/sigma.fisheye.js" //plugin
   ],function(first_init){ ...}); //chart initializing
}

In our Github package you'll also find forceAtlas2 Sigma plugin as well as you can write your own one and place it to the plugin folder and include into the sigma-chart Webix component in the way described above.

In addition, the support for GEXF data is provided by default.


Advanced

Maps Integration

JS files for these components aren't included in the lib package and should be taken from https://github.com/webix-hub/components.

Webix library allows to embed geographical maps into the app with the help of its own components. Four maps are supported:

  • Google Map
  • Nokia Map
  • OpenStreet Map
  • Yandex Map

Ui-related maps inherit from view.

Initialization

1 . First of all, you need to add a special file to the head section of your document. The script helps connect to thirdparty applications without linking to them directly:

The extensions are taken from https://github.com/webix-hub/components. Note that in documentation samples they are linked in another way, but you should follow the patterns below:

  • For Google Map

<script type="text/javascript" src="./googlemap.js"></script>

Related sample: Google Map

  • For Nokia Map

<script type="text/javascript" src="./nokiamap.js"></script>
<script src="http://js.api.here.com/se/2.5.3/jsl.js" type="text/javascript" charset="utf-8"></script>

Additionally, you should have a Nokia Account registered. Once you register, they send you "appID" and "authenticationToken" keys that you need to specify:

webix.ready(function(){
    nokia.Settings.set( "appId", "..."); //instead of dots enter your keys!
    nokia.Settings.set( "authenticationToken", "...");

    webix.ui({
        //then init map
    });
});

Related sample: Nokia Map

  • For OpenStreet Map

<script type="text/javascript" src="./openmap.js"></script>

Related sample: OpenStreet Map

  • For Yandex Map

<script type="text/javascript" src="./yandexmap.js"></script>

Related sample: Yandex Map

2 . Secondly, choose where on page the map will be initialized. You can render it into any HTML element defined as the map's container:

// <div id="mydiv"></div>
webix.ui({
    container:"mydiv",
    ..//map config
});

Additionally, you can put the map into Webix Window:

webix.ui({
    view:"window", id:"mapwin",
    body:{ ... }, //map config
    head:{....}, //place for toolbar
    top:50, left:50,
    width:600, height:500 // dimensions and positioning of the window
}).show();

3 . Thirdly, create a map and assign properties to it according to your needs. All map constructors identical differing only in the map view name.

Map Initialization

{
    view:"yandex-map", // or "nokia-map", "google-map", "open-map"
    id:"map",
    zoom:6,
    center:[ 48.724, 8.215 ]
}

Map Properties

Map's properties define the initial position of the map:

  • id - string - defines the component unique ID;
  • zoom - number - defines how close you'd like to be to the Earth surface;
  • center - array - sets the center of the map. It's an array of two elements ( latitude and longtitude ) with comma delimiter.

Related sample: Google Map

Working with Maps

To make online maps interactive you should refer to the API reference each of the services provides.

For instance, the GoogleMap API for javascript-based applications offers a rich colection of map options, controls, overlays, services, layers, etc. that you can use while working with a google-map intergrated into our library.

For instance, to show the necessary map piece on request, you can use the following function with the desired lat, lng and zoom:

function show_position(lat, lng, zoom) {
    var myLatlng = new google.maps.LatLng(lat, lng);
    $$('map').map.setOptions({
        zoom: zoom,
        center: myLatlng,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    });
}
  • google.maps.map class features lots of methods, one of them being setOptions() that allows for defining the area on the map;
  • google.maps.LatLng class is a point on the map defined by latitude and longtitude coordinates;
  • mapTypeId is a property of google.maps.mapOptions object, that allows setting a map type (HYBRID, ROADMAP, SATELLITE, TERRAIN).

Related Articles

  • Setting Dimensions for the Components
  • Redefinition of the Components


Intermediate

Scheduler and Gantt Integration

Both Scheduler and Gannt are nice planning tools from DHTMLX JS library. While Scheduler is an event calendar, the Gantt is a chart to display a long-term project schedule.

JS files for these components aren't included into Webix lib package and should be taken from https://github.com/webix-hub/components.

DHTMLX Scheduler

Scheduler is Javascript feature-rich event calendar that can create and display events as well as show a schedule for a day, week and month. Full info about it can be found in the dedicated section of DHTMLX site.

Scheduler Initialization

To include Scheduler into your app, you need to add a link to a dedicated library file into your document head section. Note that in a documentation sample this file is included in another way, but in your real app you should the pattern below:

<script type="text/javascript" src="./scheduler.js"></script>

And then init the view:

//path from which extra libraries are autoloaded
webix.codebase = "./";

webix.ui({
    view:"webix-scheduler",
    date:new Date(2010,0,5),
    mode:"week",
    init:function(){...}, //scheduler config
    ready:function(){
        scheduler.parse("..events data..")
    }
});

Related sample: Scheduler

Scheduler properties

  • date (function) - defines the start date of the scheduler. In the sample above, it is th 5the of January, 2010; If you pass no parameters into the new Date() constructor, the component will show current date;
  • mode (string) - defines the type of presentation - day, week or month;
  • init - specifies a function to be executed on component initializing. The property may include:
    • scheduler.config.xml_date - defines data format, e.g. "%Y-%m-%d %H:%i";
    • scheduler.config.first_hour (integer) - specifies an hour to start the day;
    • scheduler.config.multi_day (boolean) - allows/forbids creating events that last several days.
  • ready - specifies a function to be executed when the component is fully loaded;
  • parse (string) - XML string with predefined events.

Check Scheduler Documentation for more details.

Read more about date formatting methods in the corresponding chapter of the manual.

DHTMLX Gantt Chart

DHTMLX Gantt is a chart for visualizing project schedule that allows for easy setting and showing dependencies between tasks. It's highly customizable and features flexible API.
Full into about it can be found in the dedicated section of DHTMLX site.

Gantt Initialization

To include Scheduler into your app, you need to add a link to a dedicated library file into your document head section.

<script type="text/javascript" src="./gantt.js"></script>

And then init the view:

 webix.ui({
    view:"dhx-gantt",
    init:function(){...},
    ready:function(){
        gantt.parse(tasks); //adding tasks
    }
});

Related sample: Gantt Chart

Gantt Properties

  • init - functions to execute on initialization;
  • ready - specifies a function to be executed when the component is fully loaded.

Related Articles

  • Text Editor Integration
  • Chart Integration
  • Integration with Geographical Maps


Mobile Scheduler

Webix Scheduler was developed to be used in mobile web apps that run in Webkit-based browsers on mobile devices (iOS, Android, Blackberry). You can download Webix Scheduler by this link.

Initializating & Configuring Scheduler

  • Creating Scheduler on a Page
  • Loading and Saving Data
  • Customizing "Edit" Form
  • Specifying Templates
  • Sizing Elements
  • Date Formats
  • Styling Scheduler

Managing Scheduler

  • Localizing Scheduler
  • Read-only Mode
  • Recurring Events
  • Dynamic Loading
  • Changing Scheduler's Structure
  • Handling Events

Other

  • General How-Tos
  • Tips for dhtmlxScheduler's users


Creating Scheduler

To use Scheduler in your application you should make 2 steps:

  1. Include related CSS and JS files into your HTML file.
  2. Call the object constructor.

Included files

You need to include 4 files. They are:

<!-- js files -->
<script src="codebase/webix.js" type="text/javascript"></script>
<script src="codebase/scheduler.js" type="text/javascript"></script>
<!-- css files -->
<link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
<link rel="stylesheet" href="codebase/scheduler.css" type="text/css" charset="utf-8">

Initialization

To initialize the component you should use the following code:

//webix.ready() function ensures that the code will be executed when the page is loaded
webix.ready(function(){
    //the method allows to adjust a main view to screen size
    webix.ui.fullScreen();
    //object constructor
    webix.ui({
    view: "scheduler",
        id: "scheduler"
    });
    //the method load() lets you populate the event calendar with data
    $$("scheduler").load("../common/mobile.xml","scheduler");
});

Related sample: Initialization

Basic configuration properties

Here is a list of configuration properties with examples of usage. All of them have default values, but you can redefine them if you need.

  • scheduler.config.init_date - (date object) the initial date of the scheduler (by default, the current date)
scheduler.config.init_date = new Date(2014,5,1);
  • scheduler.config.multi_day - (boolean) enables rendering of multi-day events (true by default)
scheduler.config.multi_day = true;
  • scheduler.config.multi_day_limit - (numeric) sets the maximum number of visible items in a multi-day list (3 by default)
scheduler.config.multi_day_limit = 4;
  • scheduler.config.server_utc - (boolean) enables converting server-side dates from utc to a local time zone (and backward) while sending data to the server (false by default)
scheduler.config.server_utc = true;
  • scheduler.config.separate_short_events - (boolean) allows preventing short events from overlapping ( true by default)
scheduler.config.separate_short_events = false;
  • scheduler.config.recurring - (boolean) enables the recurring view (false by default)
scheduler.config.recurring = true;


Loading and Saving Data in Mobile Scheduler

Mobile Scheduler supports data loading from JSON and XML data sources. By default, data is loaded into Scheduler in JSON format.

{
    id: 7,
    text: "some_text",
    start_date:"2014-05-11 00:00",
    end_date:"2014-05-18 00:00"
    ...
}

Each data item (event) should have a unique id property and the following obligatory parameters:

  • text - {string} the item's (event's) title
  • start_date - {string} the start date of the event
  • end_date - {string} the end date of the event

XML formats

There are two possible xml data types:

  • "xml" - event items are described as <item> tags and properties as tag attributes
$$("scheduler").load("events.php","xml");

Here is an example of "xml" data source:

<data>
<item id="2" start_date="2014-05-24 00:00:00"
       end_date="2014-06-08 00:00:00" text="French Open"></item>
<item id="3" start_date="2014-06-10 00:00:00"
       end_date="2014-06-13 00:00:00" text="Aegon Championship"></item>
<item id="4" start_date="2014-06-21 00:00:00"
       end_date="2014-07-05 00:00:00" text="Wimbledon"></item>
</data>
  • "scheduler" - event items are described as <event> tags and properties as subtags

You can use "scheduler" data type (xml datasource), if you are going to use Connector for data loading and saving.

$$("scheduler").load("events.php","scheduler");

In case of "scheduler" data type, the xml has the following format:

<data>
    <event id="2">
        <start_date>
            <![CDATA[ 2014-05-24 00:00:00 ]]>
        </start_date>
        <end_date>
            <![CDATA[ 2014-06-08 00:00:00 ]]>
        </end_date>
        <text>
            <![CDATA[ French Open ]]>
        </text>
        <details>
            <![CDATA[ Philippe-Chatrier Court Paris, FRA ]]>
        </details>
    </event>
    <event id="3">
        <start_date>
            <![CDATA[ 2014-06-10 00:00:00 ]]>
        </start_date>
        <end_date>
            <![CDATA[ 2014-06-13 00:00:00 ]]>
        </end_date>
        <text>
            <![CDATA[ Aegon Championship ]]>
        </text>
        <details>
            <![CDATA[ The Queens Club London, ENG ]]>
        </details>
    </event>
</data>

Related sample: Initialization

If you have a big data source, you can enable Dynamic Loading in Mobile Scheduler and data will be loaded by parts: months or years.

Saving data

There are several ways of saving data in Webix. The details on saving data are given in the Data Saving article.

To save data in scheduler you can make use of DataProcessor and set the save property:

webix.ready(function(){
    webix.ui({
        view: "scheduler",
        id: "scheduler",
        save: ".../events.php"
    });
    $$("scheduler").load("events.php");
});

You can find more information in the chapter Saving Data with Connectors.

Related sample: Data saving

Or you can implement your own saving solution by using events.


Customizing the "Edit" Form

Whenever you need to edit events' details, make use of the "Edit" form.

For customizing the "Edit" form you should use the 'scheduler.config.form' object. In this object you must specify all the controls you want the form to contain inside.

Into 'scheduler.config.form' you can put any Form control (read about the controls in the related article Form Controls).

By default, 'scheduler.config.form' looks like:

scheduler.config.form = [
    {
        view:"text",
        id:'text',
        label:scheduler.locale.labels.label_event,
        labelWidth: 90,
        name:'text'
    },
    {
        view:"datetext",
        id:'start_date',
        label:scheduler.locale.labels.label_start,
        name:'start_date',
        labelWidth: 90,
        dateFormat:scheduler.config.form_date
    },
    {
        view:"datetext",
        id:'end_date',
        label:scheduler.locale.labels.label_end,
        name:'end_date',
        dateFormat:scheduler.config.form_date
    },
    {
        view:"checkbox",
        id: "allDay",
        name: "allDay",
        label: scheduler.locale.labels.label_allday,
        labelWidth: 100,
        value:0},
    },
    {
        view:"textarea",
        id: "details",
        name:"details",
        label: scheduler.locale.labels.label_details,
        labelWidth: 90,
        height:150
    }
];

There are 3 mandatory controls which you can't remove (you are also not allowed to change or remove their parameters' 'ids' as they're used in the scheduler code files):

  • text
  • start_date
  • end_date

Two last default controls are optional and you can remove them if needed:

  • allDay
  • details

Related sample: Custom form


Specifying Templates

You can redefine any content in the scheduler in the following way:

scheduler.templates.day_event = function(obj,type){
    return obj.text;
}

There is a set of templates that can be used to change the display of dates and titles.
Beware! The templates' definitions should go before the code line with scheduler initialization.

Below you can find the list of all available templates and their default definitions.

Available templates:

  • scheduler.templates.day_event - specifies an event in the 'Day' view;
  • scheduler.templates.day_event_style - specifies a css class for events in the 'Day' view;
  • scheduler.templates.multi_day_event - the template for events in the multi-day list of the 'Day' view;
  • scheduler.templates.multi_day_event_style - specifies a css class for multi-day events in the "Day" view;
  • scheduler.template.week_title - specifies the title of the 'Week' view;
  • scheduler.templates.event_class - specifies an additional css class that will be applied to the events in the lists of the 'Day','Week' and 'Month' views;
  • scheduler.templates.event_date - the content of day headers in the "Week" view;
  • scheduler.templates.event_marker - specifies a marker in the "Week" and "Month" views;
  • scheduler.templates.event_time - the content of the time part of event items in the "Week" and "Month" views;
  • scheduler.templates.event_title - specifies the content of an event item in the "Week" view;
  • scheduler.templates.month_event_title - specifies the content of an event item in the "Month" view;
  • scheduler.templates.calendar_event - the template for days with events in the "Month" view;
  • scheduler.templates.new_event_data - specifies the default event properties. Used when a user creates new events;
  • scheduler.templates.selected_event - the template for an event in the "Selected Event" view.

"Day" view

"Week" view

"Month" view

"Selected event" view

Related sample: Templates

scheduler.templates.day_event

Specifies an event in the 'Day' view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.
    For details on the parameter see the API article "type"
scheduler.templates.day_event = function(obj,type){
    return obj.text;
}

scheduler.templates.multi_day_event

The template for events in the multi-day list of the "Day" view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.
    For details on the parameter see the API article "type"
scheduler.templates.multi_day_event = function(obj,type){
    return obj.text;
}

scheduler.templates.day_event_style

Specifies a css class for events in the 'Day' view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.
    For details on the parameter see the API article "type"
scheduler.templates.day_event_style = function(obj){
    var style = "";
    if(obj.color){
        var rgb = webix.color.toRgb(obj.color);
        style += ";border-color:"+obj.color+";";
        style += "background-color:rgba("+rgb.toString()+",0.3);";
        var hsv = webix.color.rgbToHsv(rgb[0],rgb[1],rgb[2]);
        hsv[2] /= 1.6;
        var color = "rgb("+webix.color.hsvToRgb(hsv[0],hsv[1],hsv[2])+")";
        style += "color:"+color;
    }
    return style;
};

scheduler.templates.multi_day_event_style

Specifies a css class for multi-day events in the "Day" view

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.
    For details on the parameter see the API article "type"
scheduler.templates.multi_day_event_style = function(obj){
    var style = "";
    if(obj.color){
        var rgb = webix.color.toRgb(obj.color);
        style += ";background-color:rgba("+rgb.toString()+",0.3);";
        var hsv = webix.color.rgbToHsv(rgb[0],rgb[1],rgb[2]);
        hsv[2] /= 1.6;
        var color = "rgb("+webix.color.hsvToRgb(hsv[0],hsv[1],hsv[2])+")";
        style += "color:"+color;
    }
    return style;
};

scheduler.templates.week_title

Specifies the title of the "Week" view.

Parameters:

  • date - Date object (selected date).
    For details on the parameter see the API article "type"
scheduler.templates.week_title = function(date){
    var start = webix.Date.weekStart(date);
    var end = webix.Date.add(start,6,"day",true);
    var format = webix.i18n.headerWeekFormatStr;
    return format(start)+"&nbsp;-&nbsp;"+format(end);
};

scheduler.templates.event_class

Specifies an additional css class that will be applied to events in the lists of the 'Week' and 'Month' views.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.
    For details on the parameter see the API article "type"
//The template doesn't have the default definition.
//Below you can find a usage example that illustrates
//how to highlight the text of the TODAY's events
<style>
.today .webix_event_text{
      color:red !important;
}

</style>
...
scheduler.templates.event_class =  function(obj, type){
  return (webix.Date.datePart(obj.start_date).valueOf()==
        webix.Date.datePart(new Date()).valueOf())?"today":""
}

scheduler.templates.event_date

Specifies the content of day headers in the "Week" view

Parameters:

  • date - the date which needs to be formatted
scheduler.templates.event_date = function(value){
    var date = webix.Date.datePart(new Date(value));
    var today = webix.Date.datePart(new Date());
    var className = ((date.valueOf() == today.valueOf())?" today":"");
    date = webix.i18n.weekDateFormatStr(date);
    return "<span class='webix_unit_header_inner"+className+"'>"+date+"</span>";
};

scheduler.templates.event_marker

Specifies a marker in the 'Week' and 'Month' views.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.

For details on the parameter see the API article "type"

scheduler.templates.event_marker = function(obj,type){
    var style = "";
    if(obj.color){
        var rgb = webix.color.toRgb(obj.color);
        style += ";border-color:"+obj.color+";";
        style += "background-color:rgba("+rgb.toString()+",0.9);";
    }
    return "<div class='webix_event_marker' ><div style='"+style+"'></div></div>";
};

scheduler.templates.event_time

The content of the time part of event items in the "Week" and "Month" views.

Parameters:

  • obj - an event object
scheduler.templates.event_time = function(obj){
    var start = obj.start_date,
        end = obj.end_date,
        start0 = webix.Date.datePart(start,true).valueOf(),
        end0 = webix.Date.datePart(end,true).valueOf();

    if( start0 == start.valueOf() && end0 == end.valueOf())
        return scheduler.locale.labels.label_allday;
    else
        return webix.i18n.timeFormatStr(start);
};

scheduler.templates.event_title

Specifies the content of an event item in the 'Week' view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.

For details on the parameter see the API article "type"

scheduler.templates.event_title = function(obj,type){
    var className, html, time;

    time = scheduler.templates.event_time(obj);
    html = "<div class='webix_event_time'>"+time+"</div>";
    html += type.marker(obj,type);
    html += "<div class='webix_event_text'>"+obj.text+"</div>";
    className = scheduler.templates.event_class(obj,type);
    return "<div class='webix_event_overall "+className+"'>"+html+"</div>";
};

scheduler.templates.month_event_title

Specifies the content of an event item in the "Month" view

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation.
    For details on the parameter see the API article "type"
scheduler.templates.month_event_title = function(obj,type){
    var className, html, time;

    time = scheduler.templates.event_time(obj);
    html = "<div class='webix_event_time'>"+time+"</div>";
    html += type.marker(obj,type);
    html += "<div class='webix_event_text'>"+obj.text+"</div>";
    className = scheduler.templates.event_class(obj,type);
    return "<div class='webix_event_overall "+className+"'>"+html+"</div>";
};

scheduler.templates.calendar_event

The template for days with events in the 'Month' view.

Parameters:

  • date - the date which needs to be formatted
scheduler.templates.calendar_event = function(day){
  var html = "<div class='webix_cal_day_event'>"+day.getDate()+"</div>";
  html += "<div class='webix_cal_event_marker'></div>";
  return html;
};

scheduler.templates.new_event_data

Specifies the default event properties. Used when a user creates new events.

scheduler.templates.new_event_data= function(){
    var hours = (webix.Date.add(new Date(),1,"hour",true)).getHours();
    //coreData refers to the currently selected date
    var start = webix.Date.copy(this.coreData.getValue());
    start.setHours(hours);
    var end = webix.Date.add(start,1,"hour",true);
    return {start_date:start,end_date:end};
};

scheduler.templates.selected_event

The template for an event in the "Selected Event" view.

Parameters:

  • obj - the event object
scheduler.templates.selected_event : function(obj){
    var html = "", fts="", fte="", from, to, labels;
    var start = obj.start_date,
        end = obj.end_date,
        start0 = webix.Date.datePart(start,true),
        end0 = webix.Date.datePart(end,true);

    if(!start) return html;
    html = "<div  class='selected_event "+scheduler.templates.event_class(obj)+"'>";
    html += "<div class='event_title'>"+obj.text+"</div>";

    labels = scheduler.locale.labels;
    from = labels.label_from;
    to = labels.label_to;

    if(start0.valueOf() == end0.valueOf()){
        var fd = webix.i18n.dateFormatStr(start);
        fts = webix.i18n.timeFormatStr(start);
        fte = webix.i18n.timeFormatStr(end);
        html += "<div class='event_text'>"+fd+"</div>";
        html += "<div class='event_text'>"+from+" "+fts+" "+to+" "+fte+"</div>";
    }
    else{
        var fds = webix.i18n.longDateFormatStr(start);
        var fde = webix.i18n.longDateFormatStr(end);
        /*if not "all-day" event*/
        if(!(start0.valueOf() == start.valueOf() && end0.valueOf() == end.valueOf())){
            fts = webix.i18n.timeFormatStr(start)+" ";
            fte = webix.i18n.timeFormatStr(end)+" ";
        }
        html += "<div class='event_text'>"+from+" "+fts+fds+"</div>";
        html += "<div class='event_text'>"+to+" "+fte+fde+"</div>";
    }
    if(obj.details&&obj.details !== ""){
        html += "<div class='event_title'>"+labels.label_details+"</div>";
        html += "<div class='event_text'>"+obj.details+"</div>";
    }
    html += "</div>";
    return html;
};


Sizing Elements

You can easily configure the sizes of the scheduler's elements.

To set the desired option, just write it as it's stated in this documentation.
Beware! Configuration options should go before the code line with scheduler initialization.

scheduler.xy.confirm_height = 300;
scheduler.xy.confirm_width = 300;
//configuration options should go before the scheduler constructor
webix.ready(function(){
    webix.ui.fullScreen();
    webix.ui({
        view: "scheduler",
        id: "scheduler"
    });
    $$("scheduler").load("../scheduler/mobile.xml","scheduler");
});

Dimension configuration
  • scheduler.xy.all_day - the width of the "All day" label in the "Edit" form
  • scheduler.xy.confirm_height - (number) the height of the confirm window (231 by default)
  • scheduler.xy.confirm_width - (number) the width of the confirm window (250 by default)
  • scheduler.xy.day_tab - (number) the width of the 'Day' tab in the bottom tabbar (60 by default)
  • scheduler.xy.icon_back - (number) the width of the 'Back' button (70 by default)
  • scheduler.xy.icon_cancel - (number) the width of the 'Cancel' button (80 by default)
  • scheduler.xy.icon_done - (number) the width of the 'Done' button (90 by default)
  • scheduler.xy.icon_edit - (number) the width of the 'Edit' button (90 by default)
  • scheduler.xy.icon_save - (number) the width of the 'Save' button (90 by default)
  • scheduler.xy.icon_today - (number) the width of the 'Today' button in the bottom tabbar (55 by default)
  • scheduler.xy.list_header_height - (number) the height of a grey header with date in the 'Week' view (50 by default)
  • scheduler.xy.list_height - (number) the height of a row in the 'Week' view (50 by default)
  • scheduler.xy.min_event_height - (number) the minimal event's height in the 'Day' view
  • scheduler.xy.month_list_height - (number) the height of a row in the 'month' view (50 by default)
  • scheduler.xy.month_tab - (number) the width of the 'Month' tab in the bottom tabbar (68 by default)
  • scheduler.xy.scale_height - (number) the height of a row in the 'Day' view (20 by default)
  • scheduler.xy.scale_width - (number) the total width of the hour and minute columns in the 'day' view. The width is divided equally between the columns (40 by default)
  • scheduler.xy.week_tab - (number) the width of the 'Week' tab in the bottom tabbar (60 by default)

"Day" view

"Week" view

"Month" view

Start(end) date edit form

"Edit" form

"Selected event" view


Date Formats

You've got the possiblity to configure date formats of the scheduler without effort.

To set the desired option, just write it as it's stated in this documentation.
Beware! Configuration options should go before the code line with scheduler initialization.

scheduler.config.day_header_date = "%d.%m.%Y";
//configuration options should go before the constructor
webix.ready(function(){
    webix.ui.fullScreen();
    webix.ui({
        view: "scheduler",
        id: "scheduler"
    });
    $$("scheduler").load("../scheduler/mobile.xml","scheduler");
});

Related sample: Date formatting

Configuration options
  • scheduler.config.all_day_date - (string) the format of presenting all-day events in the 'Selected event' view (by default, ”%l, %d %F %Y”)
  • scheduler.config.calendar_date - (string) the date format of the header in the 'Month' view (by default, ”%F %Y”)
  • scheduler.config.calendar_hour - (string) the format of hours in the 'Start(end) date edit form' (by default, ”%H:%i”)
  • scheduler.config.day_header_date - (string) the date format of the header in the 'Day' view (by default, ”%d.%m.%Y”)
  • scheduler.config.form_all_day - (string) the format of dates of the 'start', 'end' fields in the 'Edit form' in case the 'All day' option is checked (by default, ”%d-%m-%Y” )
  • scheduler.config.form_date - (string) the format of dates of the 'start', 'end' fields in the 'Edit form' in case the 'All day' option isn't checked (by default, ”%d-%m-%Y %H:%i”)
  • scheduler.config.hour_date - (string) the format of the time in the 'Week' and 'Month' views (by default, ”%H:%i”)
  • scheduler.config.item_date - (string) the default date format for events in the 'Selected event' view (by default, )
  • scheduler.config.parse_date - (string) the date format in data files. Used by the parser to recognize dates (by default, ”%Y-%m-%d %H:%i”)
  • scheduler.config.scale_hour - (”%H” or ”%h”) the format of the hours in the 'Day' view (by default, ”%H”)
  • scheduler.config.week_header_date - (string) the date format of the header in the 'Week' view ("%d.%m.%Y")
  • scheduler.config.week_date - (string) the date format of day titles in the 'Week' view ("%D, %d %M")

"Day" view

"Week" view

"Month" view

Edit form

Selected event view

Start(end) date edit form

Date format

Format string can contain any separator character and any element from the following list:

  • %y - the year as a two-digit number ( 00 to 99 );
  • %Y - the year as a four-digit number ( 1900–9999 );
  • %m - the month as a number with a leading zero ( 01 to 12 );
  • %n - the month as a number without a leading zero ( 1 to 12);
  • %M - the month as an abbreviation ( Jan to Dec );
  • %F - the month as a full name ( January to December );
  • %W - the ISO-8601 week number of the year. Weeks start on Monday;
  • %d - the day as a number with a leading zero ( 01 to 31 );
  • %j - the day as a number without a leading zero ( 1 to 31 );
  • %D - the day as an abbreviation ( Sun to Sat );
  • %l - the day as a full name ( Sunday to Saturday );
  • %h - the hour based on the 12-hour clock with a leading zero ( 01 to 12 );
  • %H - the hour based on the 24-hour clock with a leading zero ( 00 to 23 );
  • %g - the hour based on the 12-hour clock without a leading zero ( 1 to 12 );
  • %G - the hour based on the 24-hour clock without a leading zero ( 0 to 23 );
  • %i - the minute as a number with a leading zero ( 00 to 59 );
  • %s - the second as a number without a leading zero ( 00 to 59 );
  • %a - displays am (for times from midnight until noon) and pm (for times from noon until midnight);
  • %A - displays AM (for times from midnight until noon) and PM (for times from noon until midnight).

For example, if you want to present 1st June 2011 as 01/06/2011, you should specify ”%d/%m/%Y”.


Styling Scheduler

It's possible to customize any element of Webix Scheduler.
All you need to do is to redefine the needed attributes of the related css class in the <style> block of your page. The untouched attributes will take default values.

<style>
    .webix_bottombar{
        background:#6699FF !important;
     }

</style>

In the above example we redefined only the background color. All the other attributes defined in the '.webix_bottombar' class took the default values.

CSS classes and the related elements

Main Toolbar

  • .webix_bottombar - the toolbar
  • .webix_bottombar .webix_el_label - the 'Today' button
  • .webix_bottombar .webix_el_label.add - the '+' (add) button
  • .webix_bottombar .webix_el_segmented - the tabbar
  • .webix_el_segmented .webix_segment_0 - the first tab
  • .webix_el_segmented .webix_selected.webix_segment_0 - the first tab in the selected state
  • .webix_el_segmented .webix_segment_1 - the second tab
  • .webix_el_segmented .webix_selected.webix_segment_1 - the second tab in the selected state
  • .webix_el_segmented .webix_segment_N - the last tab
  • .webix_el_segmented .webix_selected.segment_N - the last tab in the selected state

'Day' view

  • .webix_dayevents_event_item - the container of an event
  • .webix_topbar - the top toolbar
  • .webix_dayevents_scale_item - the container of a single scale item
  • .webix_dayevents_scale_top - the half an hour separator
  • .webix_dayevents_scale_hour - the container inside of the scale item that divides an hour into halves
  • .multi_day_events - the container for multi-day events
  • .multi_day_events .webix_list_item - a multi-day event item

'Week view'

  • .webix_topbar - the top toolbar
  • .webix_scheduler .events .webix_list_item - the container for an event's elements
  • .webix_scheduler .webix_unit_header - the event's header with the date
  • .webix_list_item .webix_event_time - the container with the time of an event
  • .webix_list_item .webix_event_marker div -the round marker of an event
  • .webix_list_item .webix_event_text - the container with the text of an event

'Month' view

  • .webix_calendar - the style of the calendar's container
  • .webix_cal_prev_button - the 'previous' icon on the top toolbar
  • .webix_cal_next_button - the 'next' icon on the top toolbar
  • .webix_cal_month_name - the toolbar title
  • .webix_cal_header - the container of the week header
  • .webix_cal_day - the container for a day
  • .webix_cal_day.webix_cal_event - the style of weekends
  • .webix_cal_outside - the style for days outside the current month's date range
  • .webix_cal_select .webix_cal_day_inner - the style of the selected day
  • .webix_cal_event_marker - an event marker (for days with events)

The styles of an event's items (see the image of Week View):

  • .day_events - the style of the events' list container
  • .webix_scheduler .events .webix_list_item - the container for an event's elements
  • .webix_list_item .webix_event_time - the container with the time of an event
  • .webix_list_item .webix_event_marker div -the round marker of an event
  • .webix_list_item .webix_event_text - the container with the text of an event

'Selected Event' View

  • .selected_event - the container with an event
  • .selected_event .event_title - the title of an event
  • .selected_event .event_text - the description of an event
  • .webix_scheduler .webix_subbar - the toolbar
  • .webixtype_base - the 'Edit' button
  • .webix_el_label.button - the 'Back' button
  • .webixtype_danger - the 'Delete' button

Edit form

  • .webix_scheduler .webix_subbar - the toolbar
  • .webixtype_base - the 'Save' button
  • .webix_el_label.button - the 'Cancel' button
  • .webix_control .webix_inp_label - the style of an element's label (ex. “Event”,”Start”,”End”)
  • .webix_control.webix_el_text - an event's title
  • .webix_control.webix_el_datetext - the elements with "Start" and "End" dates
  • .webix_control.webix_invalid - the style of a field with invalid data
  • .webix_control.webix_el_checkbox - the "All day" checkbox element
  • .webix_control.webix_el_textarea - the textarea style (the “Notes” field)

Confirm window

  • .webix_modal_box - a window container
  • .webix_popup_title - the window's title
  • .webix_popup_text - the window's message
  • .webix_popup_button.confirm div - the "Yes" button
  • .webix_popup_button div - the "No" button

Event styling

It is possible to apply different styling to events in the scheduler. It's implemented with the help of templates.

The "event_class" template is applied to events in all 3 views: Day, Week and Month.

For example you can set different styles for event markers, depending on properties in event data:

<style>
.my_calendar .webix_event_marker div{
    background-color: rgba(102, 204, 255, 0.9);
    border-color: #66ccff;
}

.calendar2 .webix_event_marker div{
    background-color: rgba(0, 204, 204, 0.9);
    border-color: #00cccc;
}

</style>
<script>
// template for class name of event container
    scheduler.templates.event_class =  function(obj, type){
        return (!obj.group?"my_calendar":"calendar"+obj.group);
};
</script>

Related sample: Event styling

There is a possibility to apply different colors to events using the color property in the event's data. This property is applied to the event's background in the Day view and event markers in the Week and Month views. However, you can use any other property for styling events.

$$("scheduler").parse([{id:"1", text:"Event 1", color:"#66ccff",...},...],"json");

Related sample: Event colors

The default coloring rules can also be changed in the following templates:

  • scheduler.templates.day_event_style - returns css text that will be applied to the event container in the 'Day' view

  • scheduler.templates.multi_day_event_style - returns css text that will be applied to multi-day event in the 'Day' view

  • scheduler.templates.event_marker - returns css text that will be applied to markers in the 'Week' and 'Month' views


Localizing Scheduler

Basic principles

The mobile version as well as the desktop one allows you to adapt the scheduler to a particular language and a region.

To localize the scheduler to some language you should know the following:
All locale's parameters for the mobile version are contained in the scheduler.locale.labels object and to redefine the parameters you should 'rewrite' this object.

For 'rewriting' you should use the technique below:

scheduler.locale.labels = labels;

where labels is any object variable that contains the redefined parameters.

var labels = {
    icon_today : "...",
    ...
}

In order to localize dates (week days and months) you should follow the instruction given in the article Date and Number Localization.

Localization params for scheduler

The table below presents all localization parameters available for the mobile version of the scheduler.

scheduler.locale.labels = {
    list_tab: "List",
    day_tab: "Day",
    month_tab: "Month",
    icon_today: "Today",
    icon_save: "Save",
    icon_done: "Done",
    icon_delete: "Delete event",
    icon_cancel: "Cancel",
    icon_edit: "Edit",
    icon_back: "Back",
    icon_close: "Close form",
    icon_yes: "Yes",
    icon_no: "No",
    confirm_closing: "Your changes will be lost, are your sure ?",
    confirm_deleting: "The event will be deleted permanently, are you sure?",
    label_event: "Event",
    label_start: "Start",
    label_end: "End",
    label_details: "Notes",
    label_from: "from",
    label_to: "to",
    label_allday: "All day",
    label_time: "Time"
};

Related sample: Locale

Recurring events

Recurring events use the same technique, but take another locale object - scheduler.locale.labels.recurring.

Localization parameters for recurring events:

scheduler.locale.labels.recurring = {
    none: "Never",
    daily: "Daily",
    day: "day(s)",
    every: "Every",
    weekly: "Weekly",
    week: "week(s) on",
    each: "Each",
    on_day: "on the",
    monthly: "Monthly",
    month: "month(s)",
    month_day: "on what day of the month",
    week_day: "on what day of the week",
    yearly: "Yearly",
    year: "year(s) in",
    counters: ["the first","the second","the third", "the fourth", "the fifth"],
    never: "Never",
    repeat: "Repeat",
    end_repeat: "End repeat",
    endless_repeat: "Endless repeat",
    end_repeat_label: "Repeat will end by"
};


Mobile Scheduler in Read-only Mode

The mobile scheduler can be used in 2 modes:

  • Edit (by default)
  • Read-only

To activate the read-only mode you should set the scheduler.config.readonly option to true. Beware! The option should go before the code line with scheduler initialization.

From now on, users can't modify events. The 'Add', 'Edit', 'Delete event' buttons, allowing to do it, will be hidden.

scheduler.config.readonly = true;
webix.ready(function(){
    webix.ui.fullScreen();
    webix.ui({
        view: "scheduler",
        id: "scheduler"
    });
    $$("scheduler").load("../php/events.php","scheduler");
});

Related sample: Read-only


Recurring Events

Enabling functionality

You can set a repetition period for events in the scheduler. For this purpose, you should enable the recurring events functionality, by means of using the following configuration property:

scheduler.config.recurring = true;

Once the recurring events are enabled, the "Edit form" starts looking like shown below:

To set a single event in this form, the user must choose the option Never in the Repeat field.

Related sample: Recurring view

Format details

A recurring event is stored in the database as a single record that contains all fields of regular events + 2 additional:

  • rec_type - defines the logic of repetition;
  • event_length - the actual time length of an event in seconds.

However, the fields start_date and end_date slightly change their meaning:

  • start_date - the start date of the first event in a series in the format 'yyyy-mm-dd hh:mm:ss' (format details);
  • end_date - the end date of the last event in a series in the format 'yyyy-mm-dd 00:00:00' (format details).

For example, a recurring event that starts on January 3, 2013 at 10:00, repeats every day and ends on January 13, 2013 at 12:00 will be presented in the db as follows:

id:1,
start_date:"2013-01-03 09:00:00",
end_date:"2013-01-13 00:00:00",
text:"some_text",
details:"",
rec_type:"day____",
event_length:"7200"

The client side gets data from the rec_type field as a string of the following format:

[type]_[count]_[day]_[count2]_[days]#[extra]

  • type - the type of repetition: 'day','week','month','year';
  • count - the interval between events in the “type” units;
  • day and count2 - define the day of a month (first Monday, third Friday, etc.);
  • days - a comma-separated list of the affected week days;
  • extra - the extra info that can be used to change presentation of recurring details.

Examples of the rec_type data:

  • day_3___ - each three days;
  • month_2___ - each two month;
  • month_1_1_2_ - the second Monday of each month;
  • week_2___1,5 - Monday and Friday of each second week;

The double or triple underline indicates that the related parameters of the string are omitted.

webix.ready(function(){
    webix.ui.fullScreen();
    webix.ui({ view:"scheduler", id:"scheduler"});

    var data = [
        {
            id:1,
            start_date:"2012-06-01 09:00:00",
            end_date:"2092-02-01 09:00:00",
            text:"going to the job",
            details:"",
            rec_type:"week_1___1,2,3,4,5",
            event_length:"7200"
        },
                ...
    ];

    $$("scheduler").parse(data);
});

Repetition variations

As it was mentioned above, the Repeat field allows setting 4 different repetition steps:

  • 'daily'

  • 'weekly'

  • 'monthly'

  • yearly'

You can also set the date of repetition's end:

Customizing the 'Edit' form

The recurring 'Edit form' uses the same customization technique as the standard form does.

There's only a difference in the 'scheduler.config.form' template. For recurring events it will look like:

scheduler.config.form = [
    {
        view: "text",
        label: scheduler.locale.labels.label_event,
        name: 'text',
        labelWidth: 90
    },
    {
        view: "datetext",
        label: scheduler.locale.labels.label_start,
        id: 'start_date',
        name: 'start_date',
        dateFormat: scheduler.config.form_date,
        labelWidth: 90
    },
    {
        view: "datetext",
        label: labels.label_end,
        id: 'end_date',
        name: 'end_date',
        dateFormat: scheduler.config.form_date,
        labelWidth: 90
    },
    {
        view: "checkbox",
        id: 'allDay',
        name: 'allDay',
        label: scheduler.locale.labels.label_allday,
        value: 0,
        labelWidth: 100
    },
    {
        view: "rectext",
        label: scheduler.locale.labels.recurring.repeat,
        id: 'rec_type',
        name: 'rec_type',
        readonly: true,
        labelWidth: 90
    },
    {
        view: "textarea",
        label: scheduler.locale.labels.label_details,
        id: 'details',
        name: 'details',
        height: 110,
        labelWidth: 90
    },
    {
        view: "text",
        hidden: true,
        id: 'event_length',
        name: 'event_length'
    }
];


Dynamic Loading in Mobile Scheduler

By default, Scheduler loads all data at once.

It may cause some problems when you are using big event collections. In such situations you may use the dynamic loading mode and load data by parts. Date range depends on the chosen mode of loading.

To enable the dynamic loading, you should call the setLoadMode method before data loading:

scheduler.setLoadMode("month");

// load data
scheduler.load("some.php",)

As a parameter, the method takes the loading mode that defines the size of the data to load - month or year. For example, if you set the 'year' mode, the scheduler will request data just for the selected year and load remaining ones on demand.

The generated requests look like:

some.php?from=DATEHERE&to=DATEHERE
  • where DATEHERE - a valid date value in the format defined by the configuration property scheduler.config.dyn_load_date ("%Y-%m-%d").

If you are using Data Connector at the server side, you don't need to do any additional server-side operations to parse the data:

scheduler.setLoadMode("month");
// if you are using Scheduler Connector,
// you need to set the second parameter in "load" method
scheduler.load("some.php","scheduler")

Related sample: Dynamic loading (connector)


Advanced

Changing Scheduler's Structure

The mobile scheduler has a multiview-based architecture. For details see the related article of documentation - Building App Architecture.

Please remember that you can customize just toolbars of the scheduler.

So in this article we will concentrate on toolbars. Below you can find all the available toolbars and their default definitions.

For detailed information on toolbar see the appropriate article of Webix documentation - Toolbar.

Multiview

The main multiview of the scheduler contains 3 views:

  • Selected event view;
  • Edit form;
  • Start(end) date edit form;
  • Sub-multiview (supplemented by the bottom toolbar):
    • Day;
    • Week;
    • Month.

'Day' view

In the “Day” view, the toolbar contains navigation buttons and the label displaying the selected date.

scheduler.config.day_toolbar = [
    {view:'label', id:"prev", align:"left",
      label:"<div class='webix_cal_prev_button'><div></div></div>"},
    {view:'label', id:"date", align:"center", width:200},
    {view:'label', id:"next", align:"right",
      label:"<div class='webix_cal_next_button'><div></div></div>"}
];

'Week' view

scheduler.config.week_toolbar = [
    {view:'label',name: 'prevWeek', id:"prevWeek", width: 40, align:"left",
      label:"<div class='webix_cal_prev_button'></div>"},
    {view:'label',id:"weekTitle",align:"center"},
    {view:'label',id:"nextWeek", align:"right",
      label:"<div class='webix_cal_next_button'></div>",width: 40}
];

'Month' view

In the “Month” view the toolbar is a part of calendar integrated to the view (not an individual component). So if you want to customize this toolbar, please, refer to the related Calendar documentation.

'Selected Event' view

Here, the toolbar contains 2 buttons: “Back” and “Edit” (the buttons are hidden in the read-only mode).

scheduler.config.selected_toolbar = [
    {view:'label',width:scheduler.xy.icon_back,css:"cancel",name:"back",id:"back",
      align:"center", label:scheduler.locale.labels.icon_back},
    {view:'button', inputWidth:scheduler.xy.icon_edit, name:"edit", id:"edit",
      align:"right", label:scheduler.locale.labels.icon_edit}
];

Start(end) date edit form

The toolbar contains 2 buttons: “Cancel” and “Done” and the label that displays which date is edited: start or end (the view is hidden in the read-only mode).

scheduler.config.date_toolbar = [
    {view:'label', width:scheduler.xy.icon_cancel, name:"cancel_date",id:"cancel_date",
      css:"cancel", align:"center",label:scheduler.locale.labels.icon_cancel},
    {view:'label',id:"datetype",align:"center"},
    {view:'button', width: scheduler.xy.icon_done, name:"done", id:"done",align:"right",
      label:scheduler.locale.labels.icon_done}
];

Edit form

The toolbar of the "Edit" form has 2 buttons: “Cancel” and “Save”.

scheduler.config.form_toolbar = [
    {view:'label', width:scheduler.xy.icon_cancel, name:"cancel",
      id:"cancel",css:"cancel",align:"center",label:scheduler.locale.labels.icon_cancel},
    {view:'button', inputWidth:scheduler.xy.icon_save, name:"save",
      id:"save",align:"right",label:scheduler.locale.labels.icon_save}
];

Main bottom toolbar

The main scheduler toolbar contains 3 controls:

  • “Today” button
  • a tabbar with the “Day”, "Week" and “Month” tabs
  • “Add” button
scheduler.config.bottom_toolbar = [
    {view:"label",id:"today", name:"today", label:scheduler.locale.labels.icon_today,
      inputWidth:scheduler.xy.icon_today, align:"center",width:scheduler.xy.icon_today+6},
    {view:"segmented", id:"buttons", value:"week", align:"center",
      multiview:true, options:[
        {id:"day", value:scheduler.locale.labels.day_tab, width:scheduler.xy.day_tab},
        {id:"week", value:scheduler.locale.labels.week_tab, width:scheduler.xy.week_tab},
        {id:"month",value:scheduler.locale.labels.month_tab, width:scheduler.xy.month_tab}
     ]},
    {view:"label", css:"add",name:"add",id:"add", align:"center",label:"&nbsp;+&nbsp;",
      width:45},
    {view:"label", label:"",width:45, batch:"readonly"}
];

Adding new elements to the toolbar and event handling

If you want to add some custom button to one of the mentioned toolbars, you need to redefine the structure of that toolbar. Clicks on the default buttons are handled automatically. But for new buttons you should define the “click” event handlers.

Let's assume you want to add a new button "Location" to the Selected Event view.

The definition of your new toolbar can be implemented as follows:

scheduler.config.selected_toolbar = [
    {view:'label', width:70, css:"cancel",name:"back",id:"back", label: "Back"},
    {view:'label', inputWidth:120, css:"cancel", id:"location", align:"right",
      label:"<span class='webix_icon fa-map-marker'></span>Location", click:"showLocation"},
    {view:'button', inputWidth: 70, width:90, name:"edit", id:"edit", label: "Edit"}
];

To show the event location on a button click, you need to define some handler function, for example:

function showLocation(){
    var eventId = $$("scheduler").getCursor();
    var location = $$("scheduler").getItem(eventId).location;
    webix.alert(location);
}

In the function you could be confused by the method getCursor. This method is a part of 'binding' functionality that's used by the scheduler. You can read about the mentioned functionality in the related Webix documentation - Data Binding and Syncing.

Related sample: Custom form

Accessing elements of the scheduler

The scheduler includes different components: lists, toolbars, a form, etc. To access any of them you can use the $$(schedulerId).$$(componentId) construction.

The ids of the toolbars' buttons can be found above, in the toolbars' descriptions. And here are the ids of components from the multiview of the scheduler:

  • 'event' - the 'Selected Event' view
    • 'eventBar' - the top toolbar
    • 'eventTemplate' - the template with the data of an event
  • 'form' - the 'Edit form' view
    • 'editBar' - the toolbar
    • 'editForm' - the form with the details of an event
  • 'tabViews' - the sub-multiview containing Day, Week and Month views
    • 'bottomBar' - the bottom toolbar
    • 'day' - the 'Day' view
      • 'dayBar' - the top toolbar
      • 'dayList' - the list with events
    • 'week' - the 'Week' view
      • 'weekBar' - the top toolbar
      • 'weekEventsList' - the list with events
    • 'month' - the 'Month' view
      • 'calendar' - the calendar
      • 'calendarDayEvents' - the list with events of the selected day

For example, if you want to show the 'Month' view initially, you need to call the show() method for the 'month' view and select the 'month' button of the tabbar control on the bottom toolbar:

$$('scheduler').$$('month').show();
$$('scheduler').$$('buttons').setValue('month');
  • where 'month' and 'buttons' are the ids of the appropriate components of the scheduler.

For details on the mentioned components you can read the article UI Components.

A custom view

It's possible to add a custom view to the main multiview of the scheduler. All you need to do is to add view configuration to the scheduler.config.views array. Beware, view configuration should go before the code line with scheduler initialization.

For example, if you'd like to add 'list' view, it can be done as follows:

scheduler.config.views.push({
    view:"list",
    id:"mylist",
    ...
});


Handling Events with Mobile Scheduler

Attaching Event Handler

The user can add any user-defined handler to any of the available events. To do this, the user can use the attachEvent method with the following parameters:

  • evName - name of the event;
  • evHandler - user-defined event handler.
webix.attachEvent(evName, evHandler);

Several handlers can be attached to one and the same event, and all of them will be executed. The names of the events are case-insensitive.

Detaching Event Handler

There is a simple way of removing an event-handler:

webix.detachEvent(id); // unique id of the event handler

Add, Delete and Update Event Handling

To handle CRUD operations you can set onAfterAdd, onAfterDelete and onStoreUpdated event handlers for Scheduler's datastore. You can get datastore by Scheduler's "data" property.

onAfterAdd

fires after an event has been added into scheduler

$$("scheduler").data.attachEvent("onAfterAdd",function(itemId){
    var eventObj = this.getItem(itemId);
    // your code here
});
  • itemId - {string} the id of the newly added event

onAfterDelete

fires after an event has been deleted

$$("scheduler").data.attachEvent("onAfterDelete",function(itemId){
    // your code here
    return true;
});
  • itemId - {string} the id of the deleted event

onStoreUpdated

fires when the data store has been updated

$$("scheduler").data.attachEvent("onStoreUpdated",function(itemId,item,operation){
    if(operation == "update"){
       // your code here
    }
    return true;
});
  • itemId - {string} the id of the event object
  • item - {object} the event object
  • operation - {string} type of the operation

Handling event choosing

onBeforeEventShow

To process the behavior of the component on choosing an event, you can use the onBeforeEventShow event.

This event is fired by Scheduler when an event is chosen in one of the calendar lists. If this event returns false, a form with event details won't be shown:

$$("scheduler").attachEvent("onBeforeEventShow",function(eventId){
   // your code
   return true;
});


Mobile Scheduler General How-Tos

How to add an event?

Scheduler data are loaded via parse or load methods. If you need to add a single event you can use the add method and pass event object in it:

$$("scheduler").add(
   {
     id:3,
     start_date:"2015-06-01 09:00:00",
     end_date:"2015-06-01 10:00:00",
     text:"Meeting"
   }
);

How to remove an event?

Use the remove method to remove an event by its id:

$$("scheduler").remove(eventid);

How to change event properties?

To change event properties you need to do the following:

  • get the event object
  • change properties of the event object
  • redraw the event
var event = $$("scheduler").getItem(eventId);
event.text = "Meeting";
$$("scheduler").refresh(eventId);

How to hide a button?

You can use the hide method to hide a certain view in Scheduler. Here you may find details about Scheduler structure.

For example, if you want to hide the "add" button, you can do the following:

$$("scheduler").$$("add").hide();

How to handle event choosing?

When an event is chosen in one of the lists, Scheduler fires the "onBeforeEventShow" event. If this event returns false, a form with event details won't be shown:

$$("scheduler").attachEvent("onBeforeEventShow",function(eventId){
   // your code
   return true;
});


Tips for dhtmlxScheduler's users

1) Webix Scheduler as well as dhtmlxScheduler allows defining date formats. The details are given in the article Date Formats.

2) Scheduler supports multi-day and recurring events, too.

3) Webix Scheduler also allows applying templates to its views. Read more in the article Specifying Templates.

4) Elements' sizes are customizable, too. This feature is described in the Sizing Elements article.

5) If you are going to use dhtmlxConnector to load and save data, you should do the following:

  • define "scheduler" as "DataDriver" in the load method:
...
$$("scheduler").load("data/events.php","scheduler");
...
  • set the save property of the scheduler to apply connector for data saving:
...
webix.ui({
    view: "scheduler",
    id: "scheduler",
    save: "connector->data/events.php"
});
...


Kanban Board

Webix Kanban board is a tool that is intended for viewing work in progress and controlling the flow of work.
With this widget, your team will be aware of what each of the members should be working on.

Webix Kanban board is rather flexible and can have any number of columns and rows. It's also easily customizable via HTML Templates. Fully written in JavaScript and CSS this component can be integrated in any web application or web page.

Configuring Kanban

  • Creating Kanban Board on a Page
  • Loading and Saving Data in Kanban Board
  • Data Visualization in Kanban Board
  • Customizing Kanban's structure
 Discusses the main points of Kanban Board initialization and customization.

Working with Kanban

  • Adding and Deleting Items
  • Working with Data
  • Editing Items
  • Handling Events with Kanban Board
  • Kanban Board API Reference
  • Kanban Board General How-Tos
 Describes possible operations with Kanban Board and its elements.


Creating Kanban Board on a Page

In order to start using Kanban Board you need to initialize it on the page. It requires 2 simple steps:

  1. Include the necessary JS and CSS files into HTML file.
  2. Call the object constructor.

Included files

There are 4 files that you need to include:

<!-- js files -->
<script src="codebase/webix.js" type="text/javascript"></script>
<script src="codebase/kanban/kanban.js" type="text/javascript"></script>
<!-- css files -->
<link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
<link rel="stylesheet" href="codebase/kanban/kanban.css" type="text/css" charset="utf-8">

Initialization

Use the following code to initialize Webix Kanban Board:

//webix.ready() function ensures that the code will be executed when the page is loaded
webix.ready(function(){
    //object constructor
    webix.ui({
        view:"kanban",
        type:"space",
        //the structure of columns on the board
        cols:[
            { header:"Backlog",
                body:{ view:"kanbanlist", status:"new" }},
            { header:"In Progress",
                body:{ view:"kanbanlist", status:"work" }},
            { header:"Testing",
                body:{ view:"kanbanlist", status:"test" }},
            { header:"Done",
                body:{ view:"kanbanlist", status:"done" }}
        ],
        //url to the file with data collection
        url: "tasks.php"
    });
});

Related sample: Basic Init of Kanban Board


Loading and Saving Data in Kanban Board

Data can be loaded from different sources. However, Kanban stores data items as json objects:

{
    id: 1,
    status: "new",
    text: "Kanban board documentation",
    tags: "kanban,webix",
    $index: 0,
    ...
}

Each data item possesses a unique id property and a set of other properties:

  • status - {string} the item's status, defines the list in which an item will be shown (obligatory)
  • text - {string} the item's (task's) title
  • tags - {string} a comma-separated list of tags
  • $index - {numeric} the task's position in the list that the item relates to

Kanban Board supports all data formats of the Webix library.

There are 2 main ways you can specify data source for Kanban Board:

  1. To define the data set in the object constructor.

  2. To use the url property.

Both ways lead to one and the same result and don't have any specificity.

Loading from inline dataset

If you want to specify the data set directly on the page, you can use the data property.

webix.ready(function(){
    webix.ui({
        view:"kanban", type:"space",
        cols:[
            { header:"Backlog",
                body:{ view:"kanbanlist", status:"new" }},
            ...
        ],
        //data collection                                           data: [                                                         { id:1, text:"Task 1", status: "new"},                                  { id:2, text:"Task 2", status: "new"}                                   ]                                                       });
});

Loading from a data file

To load data from a file, you can use the url property. The url refers to the JSON object that will be loaded into the board after its initialization.

webix.ready(function(){
    webix.ui({
        view:"kanban",
        type:"space",
        cols:[
            { header:"Backlog",
                body:{ view:"kanbanlist", status:"new" }},
            ...
        ],
        //url to the file with data collection                  url: "tasks.php"                                    });
});

Saving data

There are a lot of ways to save data in Webix. You can find the detailed description in the Data Saving article.

For example, in the case of using DataProcessor you can set the property:

webix.ready(function(){
    webix.ui({
        view:"kanban", type:"space",
        cols:[
            { header:"Backlog",
                body:{ view:"kanbanlist", status:"new" }},
            ...
        ],
        url: "tasks.php",                                       save: "../tasks_save.php"                           });
});

Related sample: Load and Save

More information about Kanban data loading you can find in DataStore docs.


Data Visualization in Kanban Board

You can represent various HTML-elements in the Kanban Board.

Data items of Kanban Board are sorted by their status and displayed in the corresponding lists.

Each KanbanList allows configuring dimensions and templates of its items. It is implemented in the type of KanbanList:

// define a type for KanbanList views with a set of templates
webix.type(webix.ui.kanbanlist,{
    name: "cards",   // type name        icons:[{id: "edit", icon: "edit"}],
    templateBody: function(obj){
        return (obj.img?"<img src='imgs/"+obj.img+"'/>":"")+obj.text;
    }
});

// create a Kanban board
//and apply "cards" type for lists
webix.ui({
    view:"kanban",
    cols:[
        {
           header:"Backlog",
           body:{
              view:"kanbanlist",
              status:"new",
              type: "cards"  // set type                }
        },
        ...
    ]
});

Related sample: Templates

You can set the following properties in the type:

  • 'width' - the width of a list item ('auto' or fixed number in pixels),
  • 'height' - the height of a list item ('auto' or fixed number in pixels),
  • 'template' - data template that defines inner html for each item. The default definition of this property applies many other templates: icons, text, avatar,
  • 'templateBody' - template for main content of items. It is applied in the main 'template' and displays an item's text by default,
  • 'templateFooter' - template for content below the item's body (it is applied in the main 'template' and displays an item's tags and icons),
  • 'icons' - the array of icons. The icons are taken from the Font Awesome collection
  • 'templateIcons' - template for icons representation (is applied in the 'templateFooter')
  • 'templateTags' - template for tags representation (is applied in the 'templateFooter')
  • 'tagDelimiter' - string that defines tags delimiter in datasource (',' by default)
  • 'templateAvatar' - template for an item's avatar (an assignee's photo or other data)
  • 'templateNoAvatar' - this template is applied if the 'templateAvatar' doesn't set html content for the element that shows an assignee's information.

A template can be specified either in the format of string or in the format of function. Below you'll find the description of all available templates.

Main templates

Avatar templates

Width and height of an item

width

Specifies the width of an item in the list.

{
   width:"auto"
}

"auto" is the default width value. However, you can set a fixed value and show more than one item in list rows:

webix.type(webix.ui.kanbanlist,{
   name: "cards",
   width: 120
   ...
});

You can read more here.

height

Specifies the height of an item in the list.

{
   height:"auto"
}

the 'height' property as well as 'width' can be defined as a fixed value.

template

Defines inner html for each item. The default definition of this property applies many other templates: icons, text, avatar.

template: function(obj, t){
   var avatar, content;
   avatar = t.templateAvatar(obj,t)||t.templateNoAvatar(obj,t);
   avatar = '<div class="webix_kanban_user_avatar">'+avatar+'</div>';
   content = '<div class="webix_kanban_body">'+t.templateBody(obj,t)+'</div>';
   content += '<div class="webix_kanban_footer">'+t.templateFooter(obj,t)+ '</div>';
   var style = 'style="border-left-color:'+obj.color+'"';
   return avatar+'<div class="webix_kanban_list_content" '+style+'>'+content+'</div>';
}

Pay attention that you shouldn't redefine the main template in order not to lose data. Otherwise, you'll have to specify data collection by yourself.

templateBody

Defines the main content of items, displays an item's text by default

webix.type(webix.ui.kanbanlist,{
    name: "cards",
    // displays images and text property in item content
    templateBody: function(obj,common){
        var html = "";
        if(obj.image)
            html += "<img class='image' src='../common/imgs/"+obj.image+"'/>";
        html += "<div>"+obj.text+"</div>";
        return html;
    },
    ...
});

templateFooter

Defines the content below the item's body, displays an item's tags and icons

{
    templateFooter: function(obj,common){
        var tags = common.templateTags(obj,common);
        return (tags?tags:"&nbsp;")+ common.templateIcons(obj,common);
    },
    ...
}

icons

Specifies an array of icons for Kanban Board

You need to specify icons array in the type for Kanban Lists. In the definition of each icon you can set the following properties:

  • id - icon id,
  • icon - name of a font icon in Font Awesome collection,
  • tooltip - title for an icon element,
  • show - function that takes an item object as a param and returns true/false value -to show/hide an icon for a certain item
  • template - text that will be displayed next to the icon
  • click - onClick event handler for the icon
webix.type(webix.ui.kanbanlist,{
    name: "cards",
    icons:[
        {
            id: "comments",
            tooltip: "Comments",
            icon:"comment-o",
            show: function(obj){
                return !!obj.comments
            },
            template:"#comments.length#",
            click: function(e,id){
                var item = this.getItem(id);
                ...
            }
        },
        {
            id: "edit",
            icon:"edit",
            tooltip: "Edit Task",
            click: function(e,id){
                var item = $$("myBoard").getItem(id);
                ...
            }
        }
    ]
});

webix.ui({
    view:"kanban",
    ...
    cols:[
        {
            header:"Backlog",
            body:{
                view:"kanbanlist",
                status:"new",
                type: "cards"
            }
        },
        ....
    ]
});

templateIcons

Defines icons representation

templateIcons: function(obj,common){
    var icons = [], icon = null, id, html, text;
    for (var i = 0; i < common.icons.length; i++){
        icon = common.icons[i];
        if(!icon.show || icon.show(obj)){
            id = icon.id||icon.icon;
            html = '<span webix_icon_id="'+id+'" class="webix_kanban_icon">';
            html += '<span class="fa-'+icon.icon+' webix_icon"></span>';
            if(icon.template){
                text = webix.template(icon.template)(obj);
                html += '<span class="webix_kanban_icon_text">'+text+'</span>';
            }
            html += '</span>';
            icons.push(html);
        }
    }
    return '<div  class="webix_kanban_icons">' +icons.join(" ")+'</div>';
},
...

templateTags

Defines tags representation

templateTags: function(obj,common){
    var html = '';
    if(obj.tags){
        var tags = obj.tags.split(common.tagDemiliter);
        for (var i = 0; i < tags.length; i++){
            html += '<span class="webix_kanban_tag">'+tags[i]+'</span>';
        }
    }
    return '<div class="webix_kanban_tags">'+(html||"&nbsp;")+'</div>';
}

templateAvatar

Specifies an item's avatar

webix.type(webix.ui.kanbanlist,{
    name: "cards",
    // avatar template
    templateAvatar: function(obj){
        var html = '';
        if(obj.personId){
            html = '<img class="avatar" src="../common/imgs/'+obj.personId+'.jpg" />';
        }
        return html;
    },
    ...
});

templateNoAvatar

Applied if the 'templateAvatar' doesn't set html content for the element that shows an assignee's information

{
    templateNoAvatar: "<span class='webix_icon fa-user'></span>"
}

Related sample: Templates


Customizing Kanban's structure

Kanban Board has a layout structure. It means that it consists of rows and columns that can be combined in different ways.

A column has a header with its name and a body which can contain either a KanbanList view or other rows- or cols-layouts (to create a more complex structure).

In order to specify rows on the board the property rows is used and the cols property is used to define columns.

A simple Kanban Board may look as:

In case your working process consists of many stages, you may need to make a more complex Kanban board to reflect the full flow of work.

Splitting columns

Let's imagine that you want to make a Kanban Board consisting of 4 columns, besides:

  • the 1st, 2nd and 4th columns contain KanbanLists
  • the 3rd column has a cols-layout inside (2 columns)
  • each of the columns has 2 rows:
    • the upper rows contain subheaders
    • the lower rows have lists inside

The scheme of the board will look as:

To implement this scheme we'll use the code below:

webix.ready(function(){
    webix.ui({
        view:"kanban", type:"space",
        cols:[
            {
                header:"Backlog",
                body:{ view:"kanbanlist", status:"new" }
            },
            {
                header:"In Progress",
                body:{ view:"kanbanlist", status:"work" }
            },
            {
                header:"Testing", gravity: 1.3,
                body:{

                    cols:[
                            {
                                rows:[
                                        { template:"Ready to test", height:40},
                                        { view:"kanbanlist", status:"ready"}
                                ]
                            },
                            {
                                rows:[
                                        { template:"In test", height:40},
                                        { view:"kanbanlist", status:"test"}
                                ]
                            }
                         ]
                }},
            {
                header:"Done",
                body:{ view:"kanbanlist", status:"done" }
            }
        ],
            data:base_task_set
    });
});

The result will be the following:

Related sample: Layout

Creating a complex structure

For example, you need to create a Kanban board's structure consisting of 3 columns, besides:

  • the 1st and the 3rd columns contain lists
  • the 2nd column has a rows-layout:
    • the upper row has a list inside
    • the lower row contains three columns with lists

The picture below illustrates the idea:

The code snippet below creates the Kanban Board described in the above-mentioned scheme:

webix.ready(function(){
    webix.ui({
        view:"kanban",
        type:"space",

            cols:[
                {
                    header:"Backlog",
                    body:{ view:"kanbanlist", status:"new"}
                },
                {
                    header:"Ready", gravity: 3,
                    body:{
                        type: "wide",
                        rows:[
                            {
                                view:"kanbanlist",
                                status:"ready",
                                xCount: -1,
                                type:{ width: 150 },
                                gravity: 0.3
                            },
                            {
                                cols:[
                                    {
                                        header:"In Progress",
                                        body:{ view:"kanbanlist", status:"work"}
                                    },
                                    {
                                        header:"Testing",
                                        body:{ view:"kanbanlist", status:"test"  }
                                    },
                                    {
                                        header:"Done",
                                        body:{ view:"kanbanlist", status:"done"  }
                                    }
                                ]
                            }
                        ]
                    }
                },
                { header:"Done",
                    body:{ view:"kanbanlist", status:"complete" }}
            ],
            data:task_set
    });
});

You can see the result of the code's work in the following picture:

As you can see, tasks in the upper row of the 2nd column are placed next to each other.

The following section of the article gives the details on creating such a configuration.

Related sample: Rows and Columns

Changing structure of Kanban lists

By default, all kanban lists have items that are aligned one by one in a column.

However, in some cases we need to show more than one item per row (like in the above example).

Such a configuration can be created by means of setting a fixed width for list items and resetting the xCount property (-1 value).

webix.ready(function(){
    webix.ui({
        view:"kanban",
        type:"space",
            {
                header:"Ready", gravity: 3,
                body:{
                    type: "wide",
                    rows:[
                        {
                            view:"kanbanlist",
                            status:"ready",
                            xCount: -1,                                             type:{ width: 150 }                                 }
                    ]
                }
             },
            data:task_set
    });
});

Creating swimlanes

It is possible to assign a complex value to a status property of a Kanban list. That will allow to implement swimlanes in your Kanban board.

For example, lets take a Kanban board with To Do, In Progress and Done columns containing lists with new, work and done statuses. The In Progress column should contain tasks for development and design teams. So, instead of one list we may set two lists with complex statuses that consist of two properties: status and team.

webix.ui({
    view:"kanban",
    cols:[
     {
         header:"To Do",
         body:{ view:"kanbanlist", status:"new"}
     },
     {
         header:"In progress",
         body:{
             rows:[
                 { template: "Development", height: 27},
                 { view: "kanbanlist", status: { status: "work", team: 1 }},
                 { template: "Design", height: 27},
                 { view: "kanbanlist", status: { status: "work", team: 2 }}
             ]
         }
     },
     {
         header:"Done",
         body:{ view:"kanbanlist", status:"done" }
     }
    ],
    data:[
        { id:1, status:"work", team: 1, text:"SpreadSheet NodeJS" },
        { id:1, status:"work", team: 2, text:"New skin" }
    ]
});

Each loaded data item (task) will be placed into a list the "status" values of which correspond to "status" and "team" properties of the task.

Related sample: Complex status (Swimlanes)

You can use any names of data properties within the complex status of a Kanban list and these names will be used to filter data items.

But it is advised to have a status name among them and use a status property in item data. It ensures correct work of a Kanban board when moving the task into another Kanban list with a simple status.


Adding and Deleting Items

Adding and deleting can be implemented in the form of events that fire on user actions. You can set handlers on button clicks that will call the corresponding methods: add or remove.

Adding new items

Basic syntax will look as follows:

// get random id
var itemId = webix.uid();

// add an item to Kanban board
$$("myBoard").add({
    id: itemId,
    text: "Kanban docs",
    status: "new",
    ...
});

An added item should contain the 'status' property in order to be added in one of canban lists.

Related sample: Adding New Items

You can add an empty item and then open the edit form for it, giving a user the possibility to set necessary values.

Deleting items

To remove an item you should apply the remove() method to it:

// delete an item
$$("myBoard").remove(itemId);

An example of deleting a selected item is given below:

var itemId = $$("myBoard").getSelectedId();
if(itemId)
   $$("myBoard").remove(itemId);
else
   webix.message("No item is selected!");

All items can be removed from Kanban board via the clearAll mehtod:

$$("mylist").clearAll();

More information about adding and removing items you can find here.

Related sample: Adding New Items


Working with Data

Kanban board is based on DataStore, non-hierarchical (inline) store. That's why it supports all the DataStore API, including methods, events and properties.

In this chapter you'll find the description of main Kanban features inherited from DataStore that allow managing data. Specific Kanban API is listed in the articles Kanban Board API Reference and Handling Events with Kanban Board.

Getting the item object

To get the data item object, you should use the getItem method:

webix.ui({
    view:"kanban",
    id: "myBoard",
    ...
    data:[
        {id:"task1", text:"Drag-n-drop support", status: "new", $order: 0},
        {id:"task2", text:"Uploader for the form", status: "work", $order: 0},
        ...
    ]
});

//'task' variable will contain an object of the related kanban record
var task = $$("myBoard").getItem("task1");

//you can access data members directly
var title = task.text;//-> "Drag-n-drop support"

The getItem() method returns the object of the data item that possesses a unique id and a set of other properties:

  • status - {string} the item's status, defines the list in which the item will be shown (obligatory)
  • text - {string} the item's(task's) title
  • tags - {string} a comma-separated list of tags (optional)
  • $index - {numeric} the task's position in the list that the item relates to (optional)

Checking the existence of an item

To check whether a specific item exists in the data set, you should use the exists method:

var myBoard = webix.ui({
    view:"kanban",
    ...
    data:[
        {id:"task1", text:"Drag-n-drop support", status: "new", $order: 0},
        {id:"task2", text:"Uploader for the form", status: "work", $order: 0}
    ]
});

myBoard.exists("task1");// -> true
myBoard.exists("task2222");// -> false

Changing data properties of an item

To change the current value of some item's property, you should use the following technique:

var task = myBoard.getItem("task1");
task.text = "Ticket 225";

myBoard.refresh("task1");
//or
myBoard.updateItem("task1", task);

Methods refresh and updateItem lead to one and the same result and don't have any specificity.

Iterating data items

To iterate through the collection of data items, you should use the each method of the DataStore class.

var myBoard = webix.ui({
    view:"kanban",
    ...
    data:[
        {id:"task1", text:"Drag-n-drop support", status: "new", $order: 0},
        {id:"task2", text:"Uploader for the form", status: "work", $order: 0},
        ...
    ]
});

var titles =[];
myBoard.data.each(function(obj){ titles.push(obj.text); });
//-> titles=["Drag-n-drop support", "Uploader for the form"]

The code is equal to a standard 'for'-loop:

for(i = 0; i<data.length; i++ ){
    titles.push(obj.text);
}

Filtering

If you need to show only a part of loaded data, depending on a certain rule, you can apply the filtering technique to Kanban board.

It is possible to filter data by a single property. Let's assume that we need to show only tasks assigned to a certain person:

var myBoard = webix.ui({
    view:"kanban",
    ...
    data:[
        {id:"task1", text:"Drag-n-drop support", status: "new", personId: "1", ...},
        {id:"task2", text:"Uploader for the form", status: "work", personId: "2", ...},
        ...
    ]
});

$$("myBoard").filter("#personId#","1");

Or you can set complex filtering rules. In this case you need to set a function that will return true or false value. If function returns true for an item, this item will be displayed:

var myBoard = webix.ui({
    view:"kanban",
    ...
    data:[
        {id:"1", text:"Task 1", status: "new", personId: "1", projectId: "22", ...},
        {id:"2", text:"Task 2", status: "work", personId: "2", projectId: "22", ...},
        ...
    ]
});

$$("myBoard").filter(function(task){
    return task.personId == "1" && task.projectId == "22";
});

Related sample: Filtering


Editing Items

Changing an item's properties

To change properties of an item, you should use the following technique:

// get item data by item id
var task = myBoard.getItem("task1");
// set new values
task.text = "Ticket 225";
task.status = "work";
task.color = "red";
...
// apply changes
myBoard.updateItem("task1", task);

You can read the details on the getItem and updateItem methods.

Editing via a Form

Webix Form and Board Binding

Form and Kanban Board can be bound to each other to ensure select-based synchronous changing of their data, which allows editing data on the Board:

  • select a kanban's item the data of which you want to show in Form (use setCursor method);
  • form will be filled with the item's data that you can edit;
  • form saving will send changed data back to the component.
// binding Form to Kanban data
$$("myForm").bind($$("myBoard"));

// select an item for editing
function editItem(itemId){
   $$("myBoard").setCursor(itemId);
}

// data saving
function saveData(){
   $$("myForm").save();
}

Related sample: Load and Save

You can study data binding separately.


Handling Events with Kanban Board

Attaching Event Handler

The user can add any user-defined handler to any of the available events. To do this, the user can use the attachEvent method with the following parameters:

  • evName - name of the event;
  • evHandler - user-defined event handler.
webix.attachEvent(evName, evHandler);

Several handlers can be attached to one and the same event, and all of them will be executed. The names of the events are case-insensitive.

Detaching Event Handler

There is a simple way of removing an event-handler:

webix.detachEvent(id); // unique id of the event handler

List of supported events

Below you can find the full list of events available for Kanban API:

  • onListItemClick - fires on an item click
  • onListItemDblClick - occurs on an item double-click
  • onListIconClick - fires on clicking icon button in the item footer
  • onAvatarClick - occurs on an avatar click
  • onListBeforeSelect - fires before item selection started
  • onListAfterSelect - occurs after an item is selected
  • onListBeforeContextMenu - fires on item right click before native context menu displayed
  • onListAfterContextMenu - fires after the context menu was called in the item area
  • onListBeforeDrag - fires before the mouse button is pressed and the cursor is moved over a draggable item
  • onListBeforeDragIn - fires before a dragged item is moved over the droppable list
  • onListBeforeDrop - fires before a dragged element is released over the droppable list
  • onListAfterDrop - fires after drag-n-drop has been finished
  • onBeforeStatusChange - occurs before an item is dropped to a list with different status
  • onAfterStatusChange - fires after an item is dropped to a list with different status

onListItemClick

fires on an item click

$$("myBoard").attachEvent("onListIconClick", function(itemId,ev,node,list)){
    // your code
};

params:

  • itemId - {string} the id of the clicked item
  • ev - {event object} a native event object
  • node - {element} the target HTML element
  • list - {object} the list object where click has happened

Related sample: Item Click

onListItemDblClick

fires when an item has been double-clicked

$$("myBoard").attachEvent("onListItemDblClick", function(itemId,ev,node,list)){
    // your code
};

params:

  • itemId - {string} the id of the clicked item
  • ev - {event object} a native event object
  • node - {element} the target HTML element
  • list - {object} the list object where doulble-click has happened

Related sample: Item DoubleClick

onListIconClick

fires on clicking any icon in the list item

$$("myBoard").attachEvent("onListIconClick", function(iconId, itemId,ev,node,list)){
    // your code
    return false;
};

params:

  • iconId - {string} the id of the icon
  • itemId - {string} the id of the clicked item
  • ev - {event object} a native event object
  • node - {element} the target HTML element
  • list - {object} the list object where click has happened

returns:

{bool} if an event handler returns false, onListItemClick handler will not be called.

Related sample: Icon Click

onAvatarClick

fires on clicking an avatar in the item

$$("myBoard").attachEvent("onAvatarClick", function(itemId,ev,node,list)){
    // your code
};

params:

  • itemId - {string} the id of the clicked item
  • ev - {event object} a native event object
  • node - {element} the target HTML element
  • list - {object} the list object where click has happened

returns:

{bool} if an event handler returns false, onListItemClick handler will not be called

Related sample: Avatar Click

onListBeforeSelect

fires before an item selection started

$$("myBoard").attachEvent("onListBeforeSelect", function(itemId,selection,list)){
    // your code
};

params:

  • itemId - {string} the item id
  • selection - {boolean} true - if to select, false - to unselect
  • list - {object} the list that contains the item

returns:

{bool} if an event handler returns false, the item will not be selected

Related sample: Item Click

onListAfterSelect

fires after an item has been selected

$$("myBoard").attachEvent("onListAfterSelect", function(itemId,list)){
    // your code
};

params:

  • itemId - {string} the item id
  • list - {object} the list that contains the item

Related sample: Item Click

onListBeforeContextMenu

fires on an item right click, before native context menu displayed

$$("myBoard").attachEvent("onListBeforeContextMenu", function(itemId,ev,node,list)){
    // your code

    // block native context menu
    webix.html.preventEvent(ev);
};

params:

  • itemId - {string} the id of the clicked item
  • ev - {event object} a native event object
  • node - {element} the target HTML element
  • list - {object} the list object where click has happened

Related sample: onContext event

onListAfterContextMenu

fires after the context menu was called in the item area

$$("myBoard").attachEvent("onListAfterContextMenu", function(itemId,ev,node,list)){
    // your code

};

params:

  • itemId - {string} the id of the clicked item
  • ev - {event object} a native event object
  • node - {element} the target HTML element
  • list - {object} the list object where click was happened

onListBeforeDrag

fires before the mouse button is pressed and the cursor is moved over a draggable item

$$("myBoard").attachEvent("onListBeforeDrag", function(context,ev,list)){
    if(...){
        return false;
    }
    return true;
};

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object
  • list - {object} the list object where the event has happened

returns:

{bool} returning false will prevent dragging of the element

Related sample: DND Events in Kanban

onListBeforeDragIn

fires before a dragged element is moved over the droppable list

$$("myBoard").attachEvent("onListBeforeDragIn", function(context,ev,list)){
    if(...){
        return false;
    }
    return true;
};

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object
  • list - {object} the list object where the event has happened

returns:

{bool} returning false will prevent dropping of the element

Related sample: DND Events in Kanban

onListBeforeDrop

fires before a dragged element is released over the droppable list

$$("myBoard").attachEvent("onListBeforeDrop", function(context,ev,list)){
    if(...){
        return false;
    }
    return true;
};

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object
  • list - {object} the list object where the event has happened

returns:

{bool} returning false will prevent further drag-and-drop processing

onListAfterDrop

fires after drag-n-drop has finished

$$("myBoard").attachEvent("onListAfterDrop", function(context,ev,list)){
    // your code
};

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object
  • list - {object} the list object where the event has happened

Related sample: DND Events in Kanban

onBeforeStatusChange

fires before an item is going to be dropped into the list with different status

$$("myBoard").attachEvent("onBeforeStatusChange", function(itemId,newStatus)){
    var status = this.getItem(itemId).status;
    if(...){
        return false;
    }
    return true;
};

params:

  • itemId - {string} the item's id
  • status - {string} a new item's status
  • list - {object} the list object where the event has happened
  • context - {object} drag-n-drop context object
  • ev - {event object} a native event object

returns:

{bool} returning false will prevent further drag-and-drop processing

onAfterStatusChange

fires after an item has been dropped into the list with a different status

$$("myBoard").attachEvent("onListAfterDrop", function(itemId,newStatus)){
    // your code
};

params:

  • itemId - {string} the item id
  • status - {string} a new item's status
  • list - {object} the list object where the event has happened
  • context - {object} drag-n-drop context object
  • ev - {event object} a native event object


Kanban Board API Reference

Kanban board is a view based on Layout and DataStore and it supports their methods, properties and events. However, there are two specific methods in Kanban:

  • getOwnerList - gets List that displays an item
  • eachList - calls a function for each list in Kanban board

getOwnerList

Method returns Kanbanlist view that displays an item

var list = $$("myBoard").getOwnerList("task1");

params:

  • itemId - {string} the item's id

eachList

Iterates over all lists in Kanban and calls a function for them

$$("myBoard").eachList(function(list,status){
   if(list){
      list.define("type","edit");
      list.render();
   }
});

params:

  • func - a function that will be called for each kanban list, takes two arguments:
    • list - KanbanList object
    • status - the list's status


Kanban Board General How-Tos

This article is dedicated to the most obvious questions that may arise during the creation of Kanban Board.

How to add icons to Kanban Board?

You need to specify icons array in the type for Kanban Lists. The description of the used properties is given in the article Data Visualization in Kanban Board.

webix.type(webix.ui.kanbanlist,{
    name: "cards",
    icons:[
        {
            id: "comments",
            tooltip: "Comments",
            icon:"comment-o",
            show: function(obj){
                return !!obj.comments
            },
            template:"#comments.length#",
            click: function(e,id){
                var item = this.getItem(id);
                ...
            }
        },
        {
            id: "edit",
            icon:"edit",
            tooltip: "Edit Task",
            click: function(e,id){
                var item = $$("myBoard").getItem(id);
                ...
            }
        }
    ]
});

webix.ui({
    view:"kanban",
    ...
    cols:[
        {
            header:"Backlog",
            body:{
                view:"kanbanlist",
                status:"new",
                type: "cards"
            }
        },
        ....
    ]
});

Related sample: Icons

How to define tags for tasks?

There are 2 variants of specifying tags:

1) by setting the tags property in the item data. For example, in your datasource it can be something as in:

webix.ui({
   view: "kanban",
   cols:[..],
   data: [{ id: "1", tags: "tag1,tag2,tag3", ...},...]
});

2) by setting tags dynamically

// get an item
var item = $$("myBoard").getItem("1"); // '1' is the item's id
// set the 'tags' property
item.tags = "tag1,tag2,tag3";
// update the item
$$("myBoard").updateItem("1");

If you need to use custom logic for tags rendering, you can redefine the templateTags.

How to add an avatar for a task's assignee?

You need to specify templateAvatar in the type for Kanban Lists.

For example you can show <img> elements:

webix.type(webix.ui.kanbanlist,{
    name: "cards",
    // avatar template
    templateAvatar: function(obj){
        if(obj.personId){
            return '<img class="avatar" src="../common/imgs/'+obj.personId+'.jpg" />';
        }
        return "";
    },
    ...
});

Related sample: Member Avatar

Related sample: Avatar Click

How to customize the task's content?

The tasks' content is specified in the templateBody. By default, only an item's text is displayed in the body.

For example, if you need to show images in tasks you can redefine templateBody like this:

webix.type(webix.ui.kanbanlist,{
    name: "cards",
    // template for item body
    // show the item's image and text
    templateBody: function(obj){
        var html = "";
        if(obj.image)
            html += "<img class='image' src='../common/imgs/"+obj.image+"'/>";
        html += "<div>"+obj.text+"</div>";
        return html;
    },
    ...
});

Related sample: Templates

How to change the color of the task's border?

The default color of the tasks' left border is specified in the css class .webix_kanban_list_content. Set the necessary color in the border-left property:

kanban.css

.webix_kanban_list_content {
  ...
  border-left: 3px solid #27ae60;
}

You can redefine this css rule and set a new color for all tasks in your Kanban board.

However, if you need to set a new color for a separate item, you need to define the color property in the item's data. So, there will be something like this in your datasource:

webix.ui({
   view: "kanban",
   id: "myBoard",
   ...,
   data: [...,{ id: "3", color: "red", ...},...]
});

The color of the left border can also be changed dynamically by means of updating the item:

// get an item
var item = $$("myBoard").getItem("3"); // '3' is the item's id
// set a new 'color' property
item.color = "red";
// update the item
$$("myBoard").updateItem("3");

How to change the status of an item?

The status of an item can be changed in two ways:

1) by dragging an item to a different column

2) by applying a new value to the item's 'status' property:

// get an item
var item = $$("myBoard").getItem("1");  // '1' is the item's id
// set the 'status' property
item.status = "work";
// update the item
$$("myBoard").updateItem("1");

How to forbid dragging items from/to a column?

In case you need to forbid moving tasks from/to particular columns, you should make use of Kanban Events.

For example, you may ban dragging to columns that aren't situated next to the source column. Thus, tasks will be dragged only between two neighbouring columns.

To implement this idea, the onListBeforeDragIn event can be used.

The handler function will take 3 parameters:

  • dragContext - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • e - {event object} a native event object
  • list - {object} the list object where the event has happened
//specifying event handler
function onBeforeDragIn(dragContext,e,list){

    // item id
    var item =this.getItem(dragContext.start);

    // if we move an item from one list to another
    if(dragContext.from != dragContext.to){
        //the status of the source column
        var statusFrom = dragContext.from.config.status;
        //the status of the target column
        var statusTo = dragContext.to.config.status;
        //assigning indices to statuses
        var statusIndex = {"new":0,"work":1, "test": 2, "done":3};
        //getting difference between the source and target columns' indices
        //if it's more than 1, the item won't be moved
        var diff = Math.abs(statusIndex[statusFrom] - statusIndex[statusTo]);
        if(diff>1){
            return false;
        }
    }
    return true;
}

webix.ready(function(){
    webix.ui({
        view:"kanban",
        id: "myBoard",
        on:{
            onListBeforeDragIn: onBeforeDragIn,
        },
     });
});

Related sample: DND Events in Kanban

How to set the background color to the item?

To apply a specific css class for an item you can set the $css property for it. This class will be added to className of item element:

webix.ui({
    view:"kanban",
    data: [
       { id:"1", status:"new", text:"Task 1", $css: "critical", ... },
       ...
    ]
});

Here is an example of setting a new background color for an item with the 'critical' $css property:

<style>
  .critical .webix_kanban_list_content{
    background-color: #fff2c1;
    border-color:  #e0d7b7;
    border-left-color:  #f5cf3d;
  }
</style>

Related sample: Item styling


File Manager

Webix File Manager is intended for viewing folders and files and navigating through them in a handy way.

This tool lets you perform all habitual operations with files and folders (copy/paste, rename, delete), as well as drag-n-drop them. Moreover, it's possible to upload and download files and search for necessary files and folders.

Apart from files, File Manager allows working with any kind of hierarchical data and can be easily integrated into a web app.

Configuring File Manager

  • Creating File Manager on a Page
  • Loading and Saving Data in File Manager
  • Data Visualization in File Manager
  • File Manager Structure
  • Localizing File Manager
 Discusses the main points of File Manager initialization and customization.

Working with File Manager

  • Manipulating Items
  • Handling Events with File Manager
  • File Manager API Reference
  • File Manager General How-Tos
 Describes possible operations with File Manager and its elements.


Creating File Manager on a Page

There are two simple steps you need to complete to initialize File Manager on a page:

  1. Include the necessary JS and CSS files into HTML file.
  2. Call the object constructor.

Included files

You need to include 4 files on a page:

<!-- js files -->
<script src="codebase/webix.js" type="text/javascript"></script>
<script src="codebase/filemanager.js" type="text/javascript"></script>
<!-- css files -->
<link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
<link rel="stylesheet" href="codebase/filemanager.css" type="text/css" charset="utf-8">

Initialization

The code below initializes File Manager and populates it with data:

//webix.ready() function ensures that the code will be executed when the page is loaded
webix.ready(function(){
    //object constructor
    webix.ui({
        view:"filemanager",
        id:"files"
    });
    // loading data source
    $$("files").load("data/files.php");
});

Related sample: Basic init


Loading and Saving Data in File Manager

Data can be loaded in different formats, including json (the default one) and xml. The data item should include at least 5 properties:

  • id - {string} the unique id of the item
  • value - {string} the name of a file or a folder
  • type - {string} the type of a file
  • date - {number} time of the file/folder modification in Unix format
  • size - {number} file size in bytes

An example of json data item is given below:

{
    id:     "base1",
    value:  "Product1.jpg",
    type:   "image",
    date:   1420717913,
    size:   4500
},

You can use a data source in json, xml or other format supported by Webix TreeStore. Data can be generated via any server-side script. In the data source you can use information from a real file system or records from a database.

Requests to the server side

When some action is executed (upload, download, etc.) with files, File Manager sends a POST Ajax request to the corresponding server-side script specified in the "handlers" property of FileManager configuration:

webix.ready(function(){
    var fManager = new webix.ui({
        view:"filemanager",
        handlers:{
            "upload"    : "data/saving.php",
            "download"  : "data/saving.php",
            "copy"      : "data/saving.php",
            "move"      : "data/saving.php",
            "remove"    : "data/saving.php",
            "rename"    : "data/saving.php",
            "create"    : "data/saving.php"
        }
    });
    fManager.load("data/get.php");
});

The request contains several parameters:

  • action - the name of the executed action
  • source - the id of the file or the folder that the action has been executed with
  • target - (optional) the id of the parent folder (for example, in the case of "copy" action) or the new name of the file ("rename" action)
  • upload - (optional) a file that will be uploaded (for the "upload" action)

For example, if we copy a file with the id "myfile1" into the folder with the id "folder2", the request contains the following parameters:

{
    action: "copy",
    source: "myfile1",
    target: "folder2"
}

File Manager is a purely client-side widget, therefore you can implement any logic at the backend. You can find several demos that implement PHP data in the File Manager package.

Related sample: Actions Processing

Dynamic loading

Dynamic loading presupposes the loading of long serverside datasets in smaller portions. Initially, the data fills the File Manager to some extent and later on it's fetched on demand.

There are two methods of loading data into File Manager dynamically:

1) "branch" mode

The initially loaded data can contain a minimum number of folders, e.g. only first-level folders. Folders that should be filled on demand must contain the webix_branch attribute. If such a folder contains at least one child folder of its own, you should additionally provide webix_child_branch attribute for this folder.

To enable dynamic loading, you need to define the "branch" attribute of the "handlers" property in the FileManager configuration and provide the url of the server-side script that will fetch the data when some branch is expanded:

webix.ui({
    view:"filemanager",
    id:"files",
    handlers:{
        "branch": "../common/data_branch.php",
        ...
     }
});

$$("files").load("../common/data.php");

Let's consider the following example of json data generated by "data.php" that loads the initial tree structure:

  • FileManager contains two folders on the first level. The content of both folders should be loaded dynamically;
  • The first folder contains only files;
  • The second one includes files and subfolders.
{
    id: "Files":,
    ...
    data:[
       {
          id: "documents",
          value: "documents",
          type: "folder",
          size: 0,
          date: 1440421612,
          webix_branch: 1
       },
       {
          id: "images",
          value: "images",
          type: "folder",
          size: 0,
          date: 1440421625,
          webix_branch: 1,
          webix_child_branch: 1
       }
    ]
}

When the content of the folder should be dynamically loaded (e.g. on expanding the branch), FileManager executes a script set by the "branch" parameter. The request contains several parameters:

  • action - the name of the dynamic loading mode
  • source - the id of the folder that requests for data

For example, if we open the folder with the "documents" id to view its content, the following parameters should be sent:

{
    action: "branch",
    source: "documents"
}

Serverside response should contain two properties:

  • parent- (string) id of the folder where we load new data
  • data - (array) the loaded data

An example of response for the "documents" folder from the above request is:

{ parent: "documents", data: [ ...array of child items... ] }

Related sample: Dynamic Branch Loading

2) "files" mode

The whole tree structure (folders) is loaded initially. The files of a particular folder will be dynamically loaded only when a folder will be opened for viewing. You should add the webix_files attribute for the folders that have files which should be loaded on demand.

To enable dynamic loading, you need to define the "files" attribute of the "handlers" property in the FileManager configuration and provide the url of a server-side script that will load data when some folder will be opened:

webix.ui({
    view:"filemanager",
    id:"files",
    handlers:{
        "files": "../common/data_dyn.php",
        ...
     }
});

$$("files").load("../common/data.php");

Let's consider the following example of json data generated by "data.php" that loads the initial tree structure:

  • FileManager contains one folder on the first level;
  • This folder includes two subfolders and files;
  • The subfolders contain files;
  • The files of the folder and subfolders should be loaded dynamically.
{
    id: "Files":,
    ...
    data:[
       {
          id: "documents",
          value: "documents",
          type: "folder",
          size: 0,
          date: 1440421612,
          webix_files: 1,
          data:[
            {
              id: "documents/projects",
              value: "projects",
              type: "folder",
              size: 0,
              date: 1440421625,
              webix_files: 1

            },
            {
              id: "documents/images",
              value: "images",
              type: "folder",
              size: 0,
              date: 1440421625,
              webix_files: 1
            }
          ]
       }
    ]
}

When files should be dynamically loaded, FileManager sends a request to the script set in the "files" parameter. The request contains several parameters:

  • action - the name of the dynamic loading mode
  • source - the id of the folder that requests for the data

For example, if we open the folder with the "documents" id to view its content, the request contains the parameters below:

{
    action: "files",
    source: "documents"
}

A JSON response should contain two properties:

  • parent - (string) id of the folder where we load new data
  • data - (array) the loaded data

An example of response for the "documents" folder from the above request is:

{ parent: "documents", data: [ ...array of child items... ] }

Related sample: Dynamic File Loading

Server-side searching for content

You can implement server-side searching for a file or a folder in FileManager. As data is loaded by portions, searching is mostly performed in the dynamic loading mode.

To process a search request, FileManager sends a POST Ajax request to the server-side script specified in the "search" attribute of the "handlers" property of FileManager configuration:

webix.ui({
    view:"filemanager",
    id:"files",
    handlers:{
        "search": "../common/data_branch.php",
        ...
     }
});

...

The request contains several parameters:

  • action - the name of the action
  • source - the id of the folder where data has been searched
  • text - the text that the content should include

For example, if you are searching files/folders that include "report" in their names, the request parameters will be the following:

{
    action: "search",
    source: "documents",
    text:   "report"
}

An example of response can be as follows:

[
   { id: "documents/reports", type: "folder",...},
   { id: "documents/reports/report2015.doc", ...},
   ...
]


Data Visualization in File Manager

Data items visualization in File Manager is rather flexible, so you can easily customize it by means of redefining the corresponding templates.

Thus, it's possible to specify the necessary date format, set desired icons or change an item's name presentation.

The following templates are available:

  • templateName - the template applied for the folder/file's name
  • templateSize - the template applied for the file size
  • templateDate - the template applied for the format of folder/file's date of modification
  • templateCreate - the template for a newly created folder
  • templateIcon - the template for icons used in "Files" and "Table" view modes. The icons are customizable
  • templateType - the template for the type of a file
  • icons - an array of icons. The icons are taken from the Font Awesome collection

templateName

Specifies how the folder/file's name will be displayed in File Manager.

templateName: function(fileObj,common){
    return fileObj.value
}

templateSize

Specifies the file size.

templateSize: function(obj,common){
    var value = obj.size;
    var isInt = (parseInt(value,10) == value);

    // get size label
    var labels = webix.i18n.filemanager.sizeLabels; // ["B","KB",...]
    var sizeIndex = 0;
    while(value/1024 >1){
        value = value/1024;
        sizeIndex++;
    }
    var label = labels[sizeIndex];

     // locale format
    var getFormatedValue = webix.Number.numToStr({
        decimalDelimiter:webix.i18n.decimalDelimiter,
        groupDelimiter:webix.i18n.groupDelimiter,
        decimalSize : isInt?0:webix.i18n.groupSize
    });

    return getFormatedValue(value)+""+label;
},

templateDate

Specifies the format of folder/file's date of modification.

templateDate: function(obj){
    var date = obj.date; // 'date' property is Unix time
    if(typeof(date) != "object"){
        date = new Date(parseInt(obj.date,10)*1000);
    }
    return webix.i18n.fullDateFormatStr(date);
},

templateCreate

Specifies properties for a newly created folder.

templateCreate: function(){
    return {value: "newFolder", type: "folder", date: new Date()};
},

templateType

Specifies the type of a file.

templateType: function(obj){
   var types = webix.i18n.filemanager.types;
   return types&&types[obj.type]?types[obj.type]:obj.type;
}

templateIcon

A customizable template for icons in "Files" and "Table" view modes.

templateIcon: function(obj,common){
    return "<span class='webix_icon webix_fmanager_icon fm-"
        +(common.icons[obj.type]||common.icons["file"])+"'></span>";
}

Related sample: Icons

Icons

The "icons" collection allows specifying FontAwesome icons for the templateIcon. You can specify icons that correspond to the loaded file types. If the collection does not contain an icon for the loaded type, FileManager will set the "default" icon type.

By default, the following icons are set:

icons: {
    folder: "folder",
    doc: "file-word-o",
    excel: "file-excel-o",
    pdf: "file-pdf-o",
    pp: "file-powerpoint-o",
    text: "file-text-o",
    video: "file-video-o",
    image: "file-image-o",
    code: "file-code-o",
    audio: "file-audio-o",
    archive: "file-archive-o",
    file: "file-o"
}


File Manager Structure

File Manager Layout

File Manager consists of several Webix views.

The main layout includes two rows: a row with a toolbar and the second row with a sublayout that contains Tree and mode views. Thus, the structure of File Manager is:

  • Toolbar:
    • Menu button
    • Spacer
    • Back and Forward group of buttons
    • LevelUp button
    • Path view
    • Search control
    • Modes button
  • bodyLayout with 3 columns:
    • treeLayout consists of 2 parts - treeToolbar and Tree:
      • treeToolbar contains 4 elements:
        • hideTree button
        • Spacer
        • expandAll button
        • collapseAll button
      • Tree
    • Resizer view
    • 'Files' and 'Table' view modes

The layout of File Manager is rather flexible. It means that you can customize it according to your preferences.

For example, if you want to swap one toolbar element with another one or even to remove it, the functionality of File Manager will remain untouched.

You can find more information concerning the possibilities of customizing File Manager views in the article File Manager General How-Tos.

Toolbar

Toolbar is based on Webix Toolbar view.

{
    id:         "toolbar",
    css:        "webix_fmanager_toolbar",
    paddingX:   10,
    paddingY:   5,
    margin:     7,
    cols:[
       // buttons
    ]
}

You can use the $$("toolbar") method to refer to its object:

var toolbar = $$("fmanager").$$("toolbar");

Menu button

The Menu button is based on Webix Button control. It is used to activate the Actions menu.

{
   id:      "menu",
   view:    "button",
   type:    "htmlbutton",
   css:     "webix_fmanager_menu",
   label:   "<div class='webix_fmanager_bar_icon'></div>",
   width:   37,
   tooltip: webix.i18n.filemanager.actions
}

You can get the reference to its object in the following way:

var menu = $$("fmanager").$$("menu");

Spacer

The spacer is used to separate buttons.

{
    id:     "menuSpacer",
    width:  75
}

To refer to its object use the $$("menuSpacer") method:

var spacer = $$("fmanager").$$("menuSpacer");

Back and Forward buttons

The Back and Forward buttons are based on Webix Button. They let move back and forward through the navigation history.

//the Back button
{
    id:      "back",
    view:    "button",
    type:    "htmlbutton",
    css:     "webix_fmanager_back",
    label:   "<div class='webix_fmanager_bar_icon'></div>",
    width:   37,
    tooltip: webix.i18n.filemanager.back
}

//the Forward button
{
    id:     "forward",
    view:   "button",
    type:   "htmlbutton",
    css:    "webix_fmanager_forward",
    label:  "<div class='webix_fmanager_bar_icon'></div>",
    width:  37,
    tooltip: webix.i18n.filemanager.forward
}

To refer to the object of the buttons, use the $$("back") and $$("forward") buttons, respectively:

//for the Back button
var bback = $$("fmanager").$$("back");

//for the Forward button
var bforward = $$("fmanager").$$("forward");

LevelUp button

The Level Up button is based on Webix Button. It selects the parent folder of the selected item (file/folder):

{
    id:      "up",
    view:    "button",
    type:    "htmlbutton",
    css:     "webix_fmanager_up",
    label:   "<div class=\"webix_fmanager_bar_icon \"></div>",
    width:   37,
    tooltip: webix.i18n.filemanager.levelUp
}

You can get the reference to its object in the following way:

var levelUp = $$("fmanager").$$("up");

Path view

The Path view displays the path to the currently selected item (file/folder).

{
    id: "path"
    view: "path",
    borderless: true
}

To refer to its object use the $$("path") method:

var path = $$("fmanager").$$("path");

Search control

The Search element is based on Webix Search control and allows searching for files and folders, the names of which contain the entered letter combinations:

{
    id:       "search",
    view:     "search",
    gravity:  0.3,
    minWidth: 80,
    css:      "webix_fmanager_search",
    icon:     "webix_fmanager_icon"
}

You can use the $$("search") method to refer to its object:

var search = $$("fmanager").$$("search");

Modes button

The Modes button presents a segmented button, based on Webix Segmented Button control. It lets switch between two modes of displaying folders and files: "Files" and "Table".

{
    id:      "modes",
    view:    "segmented",
    width:   70,
    value:   settings.mode,
    css:     "webix_fmanager_modes",
    options: [
      // options
    ]
}

The options are specified as an array:

[
  {
    id: "files",
    width: 32,
    value: "<div class='webix_fmanager_bar_icon webix_fmanager_files_mode'></div>"
  },
  {
    id: "table",
    width: 32,
    value: "<div class='webix_fmanager_bar_icon webix_fmanager_table_mode'></div>"
  }
]

To refer to its object use the $$("modes") method:

var modes = $$("fmanager").$$("modes");

bodyLayout

bodyLayout includes 3 columns: a layout with Tree, Resizer view and a column with "Files" and "Tree" view modes.

treeLayout

treeLayout includes a treeToolbar and Tree.

treeToolbar

treeToolbar includes 4 elements: the hideTree button, the spacer, the expandAll and collapseAll buttons:

hideTree button

The hideTree button hides/shows the Tree panel.

{
   id:      "hideTree",
   view:    "button",
   type:    "htmlbutton",
   css:     "webix_fmanager_toggle",
   label:   "<div class="webix_fmanager_bar_icon"></div>",
   width:   30,
   tooltip: webix.i18n.filemanager.hideTree
}

expandAll button

The expandAll button expands the collapsed Tree.

{
    id:      "expandAll",
    view:    "button",
    type:    "htmlbutton",
    css:     "webix_fmanager_expand",
    label:   "<div class='webix_fmanager_bar_icon'></div>",
    width:   30,
    tooltip: webix.i18n.filemanager.expandTree
}

collapseAll button

The collapseAll button collapses the Tree remaining just the root folder visible.

{
    id:      "collapseAll",
    view:    "button",
    type:    "htmlbutton",
    css:     "webix_fmanager_collapse",
    label:   "<div class='webix_fmanager_bar_icon'></div>",
    width:   30,
    tooltip: webix.i18n.filemanager.collapseTree
}

Tree

The Tree is based on Webix Tree. It displays the hierarchy of folders and allows navigating through them.

{
    id: "tree",
    width: 230,
    view: "filetree",
    select: true,
    filterMode:{
        showSubItems:false,
        openParents:false
    },
    type: "FileTree",
    // mouse navigation
    navigation: true,
    scroll: true,
    // editing options
    editor:"text",
    editable: true,
    // disable editing on double-click
    editaction: false,
    // drag-n-drop
    drag: true,
    // tab 'key' navigation
    tabFocus: true,
    // context menu
    onContext:{}
}

Tree uses "FileTree" data type that configures folder icons for nodes:

webix.type(webix.ui.tree,{
    name: "FileTree",
    folder: function(obj, common){
        if (obj.icon)
            return "<div class='webix_icon icon fa-folder'></div>";
        if (obj.$count && obj.open)
            return "<div class='webix_icon icon fa-folder-open'></div>";
        return "<div class='webix_icon icon fa-folder'></div>";
    }
});

You can get the reference to tree object in the following way:

var tree = $$("fmanager").$$("tree");

Resizer view

Resizer is a draggable border between the Tree and the File views. It is based on Webix Resizer.

{
    view:"resizer",
    width:2
}

View modes

These are 2 modes of viewing files of the selected folder: "Files" and "Table". By default, the "Table" mode is active.

Files mode

"Files" mode is based on Webix Dataview.

{
    id: "files",
    view: "fileview",
    type: "FileView",
    select: "multiselect",
    // editing options
    editable:true,
    editor:"text",
    editValue:"value",
    // disable editing on double-click
    editaction: false,
    // drag-n-drop
    drag: true,
    // mouse navigation
    navigation: true,
    // tab 'key' navigation
    tabFocus: true,
    // context menu
    onContext:{}
}

"Table" mode is based on Webix DataTable component.

{
    id: "table",
    view: "filetable",
    css: "webix_fmanager_list",
    columns: "columns",
    // editing options
    editable: true,
    // disable editing on double-click
    editaction: false,
    select: "multiselect",
    // drag-n-drop
    drag: true,
    // mouse navigation
    navigation: true,
    resizeColumn:true,
    // tab 'key' navigation
    tabFocus: true,
    // context menu
    onContext:{}
}

Actions menu

The Actions menu displays actions that can be applied to selected files or folders. It appears by clicking the Menu button or by clicking the right mouse button:

The Actions menu is based on Webix ContextMenu. That's why you can operate its items via TreeStore API.

To refer to the Actions menu, you can apply the getMenu() method to File Manager:

var actions = $$("fmanager").getMenu();

By default, the Actions menu contains the following data array:

[
    {
        id: "copy",
        method: "markCopy",
        icon: "copy",
        batch:"item",
        value: webix.i18n.filemanager.copy // "Copy"
    },
    {
        id: "cut",
        method: "markCut",
        icon: "cut",
        batch:"item",
        value: webix.i18n.filemanager.cut // "Cut"
    },
    {
        id: "paste",
        method: "pasteFile",
        icon: "paste",
        value: webix.i18n.filemanager.paste // "Paste"
    },
    {   $template:"Separator" },
    {
        id: "create",
        method: "createFolder",
        icon: "folder-o",
        value: webix.i18n.filemanager.create // "Create Folder"
    },
    {
        id: "remove",
        method: "deleteFile",
        icon: "times",
        batch:"item",
        value: webix.i18n.filemanager.delete // "Delete"
    },
    {
        id: "edit",
        method: "editFile",
        icon: "edit",
        batch:"item",
        value: webix.i18n.filemanager.rename // "Rename"
    },
    {
        id: "upload",
        method: "uploadFile",
        icon: "upload",
        value: webix.i18n.filemanager.upload  // "Upload"
    }
]

The properties of actions are the following:

  • id - {string} the id of an action
  • method - {string} the name of the method that is used to implement the action
  • icon - {string} an icon from the Font Awesome collection used for the action
  • batch - {string} group that menu item belongs to. Possible value are:
    • "item" - the item will be seen only for data items not empty space;
    • "root" - the item will be seen for the root item only;
    • if batch is not set, the item will be shown for empty space and all items other than root
  • value - {string} the action title

You can reload data using the following approach:

var actions = $$("fmanager").getMenu();
actions.clearAll();
var newData = [{id: "copy", ...},...];
actions.parse(newData);

The add method allows adding a new action to menu:

actions.add({id: "myAction", icon: "file", value: "My Action"});

It is possible to set a click handler for the added action using onItemClick event handler:

actions.attachEvent("onItemClick", function(id){
   if(id == "myAction"){
       // some code here
   }
});

To remove an existing action, you can call the remove method for it:

actions.remove("upload");

It is possible to customize the Actions menu with the help of menuFilter function that can filter menu items before showing a menu on the page.

view:"filemanager",
id: "fmanager",
menuFilter:function(obj){
    //obj - menu item obj

    var context = $$("fmanager").getMenu().getContext();
    //dataId - id of the clicked data item
    var dataId = context.id;

    if(..some condition ..)
        return false;
    return true;
}

The function should return true to show the item, false to hide it.


Localizing File Manager

You can localize File Manager according to the peculiarities of a certain language.

The properties that can be localized are the following:

  • names of actions ("Copy", "Paste", etc.)
  • column titles
  • date formats

Date formats

Date can be easily localized by setting one of the build-in locales.

All locales are stored in webix.i18n.locales object. By default, the library uses the "en-US" locale:

webix.i18n.locales["en-US"]={
  ...
};

Titles localization

File Manager titles are stored in the webix.i18n.filemanager object:

webix.i18n.filemanager = {
    actions: "Actions",
    back: "Back",
    forward: "Forward",
    levelUp: "Level Up",
    name: "Name",
    size: "Size",
    type: "Type",
    date: "Date",
    copy: "Copy",
    cut: "Cut",
    paste: "Paste",
    upload: "Upload",
    remove: "Delete",
    create: "Create Folder",
    rename: "Rename",
    location: "Location",
    select: "Select Files",
    sizeLabels: ["B","KB","MB","GB"],
    iconsView: "Icons View",
    tableView: "Table View",
    hideTree: "Hide Tree",
    showTree: "Show Tree",
    collapseTree: "Collapse Tree",
    expandTree: "Expand Tree",
    saving: "Saving...",
    errorResponse: "Error: changes were not saved!",
    replaceConfirmation: "Would you like to replace existing files?",
    createConfirmation: "The folder already exists. Would you like to replace it?",
    renameConfirmation: "The file already exists. Would you like to replace it?",
    yes: "Yes",
    no: "No",
    types:{
        folder: "Folder",
        doc: "Document",
        excel: "Excel",
        pdf: "PDF",
        pp: "PowerPoint",
        text: "Text File",
        video: "Video File",
        image: "Image",
        code: "Code",
        audio: "Audio",
        archive: "Archive",
        file: "File"
    }
};

There are 2 ways of applying a custom locale:

1) redefine default titles according to your locale directly in the webix.i18n.filemanager object;

2) set a certain locale in the following way:

  • include the chosen locale library into your page:
<script src="../../../codebase/i18n/ru.js" type="text/javascript"></script>
  • define 'filemanager' titles in the webix.i18n.locales[localeName] object:
webix.i18n.locales['ru-RU'].filemanager = {
    name: "Имя",
    size: "Размер",
    ...
};
  • apply the created locale with the help of the setLocale method:
webix.i18n.setLocale('ru-RU');

Related sample: Localization


Manipulating Items

You can perform various actions with files and folders in File Manager. The actions are presented in the popup menu called "Actions". It is activated by right-clicking on a folder/file in the Tree or Files view or by clicking the Menu button on the toolbar.

However, you can also customize actions by means of redefining the corresponding methods.

Copying folders/files

To copy a folder/file, use the copyFile() method:

fmanager.copyFile(source,target);

Moving folders/files

To move a folder/file, use the moveFile() method:

fmanager.moveFile(source,target);

Deleting folders/files

To delete a folder/file, use the deleteFile() method:

fmanager.deleteFile(ids);

Renaming folders/files

To rename a folder/file, use the renameFile() method:

fmanager.renameFile("file1","newFile.txt");

Creating a new folder

To create a folder, use the createFolder() method. You need to pass an id of the folder where you want to create a new folder and templateCreate will apply other properties automatically:

fmanager.createFolder("folder1");

Downloading files

To download a file, you need to call the download() method and pass the file id to it:

fmanager.download("myfile");

Uploading files

To open a file upload dialog, use the uploadFile() method:

fmanager.uploadFile("myfolder");


Handling Events with File Manager

Attaching Event Handler

The user can add any user-defined handler to any of the available events. To do this, the user can use the attachEvent method with the following parameters:

  • evName - name of the event;
  • evHandler - user-defined event handler.
webix.attachEvent(evName, evHandler);

Several handlers can be attached to one and the same event, and all of them will be executed. The names of the events are case-insensitive.

Detaching Event Handler

There is a simple way of removing an event-handler:

webix.detachEvent(id); // unique id of the event handler

List of supported events

The File Manager API includes the following groups of events:

1) Actions handling events

  • onBeforeMarkCopy - fires before an item has been copied
  • onBeforeCreateFolder - fires before a new folder has been created
  • onBeforeMarkCut - fires before an item has been cut
  • onBeforeDeleteFile - fires before an item is deleted
  • onBeforeEditFile - fires when the Rename action is chosen in the popup menu
  • onBeforePasteFile - fires before an item has been pasted
  • onBeforeUploadFile - fires on the "upload" action click

2) Drag-n-drop Events

  • onAfterDrop - fires after drag-n-drop has been finished
  • onBeforeDrag - fires before drag-n-drop has started
  • onBeforeDragIn - fires before a dragged item is moved over the droppable area
  • onBeforeDrop - fires before a dragged item is released over the droppable area

3) Editing events

  • onAfterEditStop - fires after the editor is closed
  • onBeforeEditStop - fires before editing is finished

4) Other

  • onErrorResponse - fires if an error has occured during some operation
  • onBeforeRun - fires on file double-click or on enter click
  • onFolderSelect - fires on selecting a folder in the Tree view
  • onViewInit - fires during the initialization of an object with the mode configuration

onBeforeMarkCopy

fires before an item has been marked for copying

$$("fmanager").attachEvent("onBeforeMarkCopy", function(ids){
    // your code
    return true;
});

params:

  • ids - {string} the ids of the copied items

returns:

  • {bool}- returning false will prevent copying

Related sample: Copy, Cut, Paste Events

onBeforeCreateFolder

fires before a new folder has been created

$$("fmanager").attachEvent("onBeforeCreateFolder",function(id){
    // your code
    return true;
});

params:

  • id - {string} the id of the target folder/file (where a new folder is going to be created)

returns:

  • {bool} - returning false will prevent creating

onBeforeMarkCut

fires before an item has been marked for cutting

$$("files").attachEvent("onBeforeMarkCut", function(ids){
    // your code
    return true;
});

params:

  • ids - {string} the ids of the copied items

returns:

  • {bool} - returning false will prevent cutting operation

Related sample: Copy, Cut, Paste Events

onBeforeDeleteFile

fires before an item is deleted

$$("fmanager").attachEvent("onBeforeDeleteFile",function(id){
    // your code
    return true;
});

params:

  • id - {string} the id of the item to delete

returns:

  • {bool} - returning false will prevent deleting

onBeforeEditFile

fires when the Rename action is chosen in the popup menu

$$("fmanager").attachEvent("onBeforeEditFile",function(id){
    // your code
    return true;
});

params:

  • id - {string} the id of the edited item

returns:

  • {bool} - if an event handler returns false, onBeforeEditFile handler will not be called.

Related sample: Editing Events

onBeforePasteFile

fires before an item has been pasted

$$("fmanager").attachEvent("onBeforePasteFile", function(ids){
    // your code
    return true;
});

params:

  • ids - {string} the id of the target folder/file

returns:

  • {bool} - returning false will prevent pasting

Related sample: Copy, Cut, Paste Events

onBeforeUploadFile

fires on "upload" action click

$$("fmanager").attachEvent("onBeforeUploadFile",function(targetId){
    // your code
    return true;
});

params:

  • targetId - {string} the id of an folder where an new file will be uploaded

returns:

  • {bool} - returning false will prevent opening the upload file dialog

onAfterDrop

fires after drag-n-drop has been finished

$$("fmanager").attachEvent("onAfterDrop",function(context,ev){
    // your code
    return true;
});

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object

Related sample: DND Events in File Manager

onBeforeDrag

fires before drag-n-drop has started

$$("fmanager").attachEvent("onBeforeDrag",function(context,ev){
    // your code
    return true;
});

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object

returns:

  • {bool} - returning false will prevent dragging of the element

Related sample: DND Events in File Manager

onBeforeDragIn

fires before a dragged item is moved over the droppable area

$$("fmanager").attachEvent("onBeforeDragIn",function(context,ev){
    // your code
    return true;
});

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object

returns:

  • {bool} - returning false will prevent dropping of the element

Related sample: DND Events in File Manager

onBeforeDrop

fires before a dragged item is released over the droppable area

$$("fmanager").attachEvent("onBeforeDrop",function(context,ev){
    // your code
    return true;
});

params:

  • context - {object} drag-n-drop context object with a set of properties:
    • from - the source object,
    • to - the target object,
    • source - the ID of the dragged item(s),
    • target - the ID of the drop target, null for drop on empty space,
    • start - the ID from which DnD started
  • ev - {event object} a native event object

returns:

  • {bool} - returning false will prevent further drag-and-drop processing

Related sample: DND Events in File Manager

onAfterEditStop

fires after the edtor is closed

$$("fmanager").attachEvent("onAfterEditStop",function(id,state,editor,view){
    // your code
    return true;
});

params:

  • id - {string} the id of the edited item
  • state - {object} contains two properties:
    • old - the old value
    • value - a new value
  • editor - {object} editor object
  • view - {string} the view where editing occurs

Related sample: Editing Events

onBeforeEditStop

fires before editing is finished

$$("fmanager").attachEvent("onBeforeEditStop",function(id,state,editor,view){
    var newValue = state.value
    if(...){
        return false;
    }
    return true;
});

params:

  • id - {string} the id of the edited item
  • state - {object} contains two properties:
    • old - the old value
    • value - a new value
  • editor - {object} editor object
  • view - {string} the view where editing occurs

returns:

  • {bool} - returning false will prevent editing

Related sample: Editing Events

onErrorResponse

fires if an error has occured during some operation

$$("files").attachEvent("onErrorResponse", function(requestData,response){
    var action = requestData.action;
    // your code
    return true;
});

params:

  • requestData - {object} the data sent with the request
  • response - {string} the server response

Related sample: onErrorResponse Event

onBeforeRun

fires before a selected file is downloaded

$$("fmanager").attachEvent("onBeforeRun",function(id){
    webix.confirm({
        text:"Do you want to download this file?",
        ok:"Yes",
        cancel:"No",
        callback:function(result){
            if(result)
                $$("files").download(id);
        }
    });
    return false;
});

params:

  • id - {string} the id of the downloaded item

returns:

  • {bool} - if an event handler returns false, onBeforeRun handler will not be called.

Related sample: onBeforeRun event

onFolderSelect

fires on selecting a folder in the Tree view

$$("fmanager").attachEvent("onFolderSelect",function(id){
    // your code
});

params:

  • id - {string} the id of the selected folder

Related sample: Folder Selection

onViewInit

fires during the initialization of an object with the mode configuration

$$("fmanager").attachEvent("onViewInit": function(id, config){
    // disable multi-selection for "table" and "files" views
    if (id == "table" || id == "files"){
        config.select = true;
    }
});

params:

  • id - {string} the view id
  • config - {object} the object with view configuration

Related sample: Changing View Configuration


File Manager API Reference

Methods
  • copyFile - copies a selected file/folder
  • createFolder - creates a new folder
  • deleteFile - deletes items by their ids
  • download - downloads a selected file
  • editFile - opens editor for a certain item in the active view (Tree or Files view)
  • getActive - gets ids of active items
  • getActiveView - gets the reference to the active view (Tree or Files view)
  • getCurrentFolder - gets the name of the folder selected in Tree
  • getMenu - gets the popup menu object
  • getPath - gets an array of folders' ids in a path
  • getPathNames - gets an array of folders' names in a path
  • getSearchData - gets an array of items (files, folders) that contains text in their names
  • getSelectedFile - gets a string or an array with file (folder) name(s) selected in the "table" view
  • getUploader - gets the uploader object
  • goBack - goes back in the navigation history
  • goForward - goes forward in the navigation history
  • hideSearchResults - hides search results
  • hideTree - hides the Tree panel
  • levelUp - selects the parent folder
  • markCopy - preselectes files/folders for copy operation
  • markCut - preselectes files/folders for move operation
  • moveFile - moves a selected file/folder
  • pasteFile - pastes files/folders that were selected for copying or moving
  • renameFile - renames a folder/file
  • setPath - selects a certain folder and sets path values for it
  • showSearchResults - searches text in the active folder and displays results on the screen
  • showTree - shows the Tree panel
  • uploadFile - opens a file upload dialog

copyFile

copies a selected file/folder

fmanager.copyFile(source,target);

params:

  • source - {string, array} the copied items ids
  • target - {string} the id of the folder where the items are copied to

createFolder

creates a new folder

fmanager.createFolder(targetId);

params:

  • targetId - an id of parent folder where a new folder will be created (templateCreate is applied automatically)

deleteFile

deletes items by their ids

fmanager.deleteFile(ids);

params:

  • ids - {string, array} the ids of items that will be deleted

download

downloads a selected file

fmanager.download(id);
  • id - {string} the id of the downloaded file

editFile

opens editor for a certain item in the active view (Tree or Files view)

fmanager.editFile(id);

params:

  • id - id of the file/folder for editing

getActive

gets ids of active items

var ids = fmanager.getActive();

returns:

  • {string} - the ids of active views

getActiveView

gets the reference to the active view (Tree or Files view)

var view = fmanager.getActiveView();

returns:

  • {object} - the object of the active view

getCurrentFolder

gets the name of the folder selected in Tree

var folder = fmanager.getCurrentFolder();

returns:

  • {string} - the name of the selected folder

getMenu

gets the popup menu object

var menu = fmanager.getMenu();

returns:

  • {object} - the popup menu object

getPath

gets an array of folders' ids in a path

var pathIds = fmanager.getPath();

// or

var pathIds = fmanager.getPath(id);

params:

  • id - {string} the id of the selected folder (optional)

returns:

  • {array} - an array of folders' ids

getPathNames

gets an array of folders' names in a path

var pathNames = fmanager.getPathNames();

// or

var pathNames = fmanager.getPathNames(id);

params:

  • id - {string} the id of the selected folder (optional)

returns:

  • {array} - an array of folders' names

getSearchData

gets an array of items (files, folders) that contains text in their names

var result = fmanager.getSearchData(id,text);

params:

  • id - {mixed} the id of the folder where the text is searched
  • text - {string} searched text

returns:

  • {array} - an array of items

getSelectedFile

gets a string or an array with file (folder) name(s) selected in the "table" view

var selected = fmanager.getSelectedFile(id,text);

returns:

  • {string/array} - selected file(nested folder) name(s)

getUploader

gets the uploader object

var uploader = fmanager.getUploader();

returns:

  • {object} - the uploader object

goBack

goes back in the navigation history

fmanager.goBack(step);

params:

  • step - {number} the number of steps back (1 by default)

goForward

goes forward in the navigation history

fmanager.goForward(step);

params:

  • step - {number} the number of steps forward (1 by default)

hideSearchResults

hides search results

fmanager.hideSearchResults();

hideTree

hides the Tree panel

fmanager.hideTree();

levelUp

selects the parent folder

fmanager.levelUp(id);
  • id - {string} the id of the selected file/folder

markCopy

preselectes files/folders for copy operation

fmanager.markCopy(id);
  • id - {string,array} ids of files for copying

markCut

preselectes files/folders for move operation

fmanager.markCut(id);
  • id - {string,array} ids of files for moving

moveFile

moves a selected file/folder

fmanager.moveFile(source,target);

params:

  • source - {string} the moved file's id (or an array of ids in case of multiple files)
  • target - {string} the id of the folder where the file(s) is moved to

pasteFile

pastes files/folders that were selected for copying or moving

fmanager.pasteFile(id)

params:

  • id - {mixed} the id of the folder where copyed or cut files will be pasted

renameFile

renames a folder/file

fmanager.renameFile(id,name,property);

params:

  • id - {string} the id of the folder/file that should be renamed
  • name - {string} a new filename
  • property - {string} "value" by default, the property of a file/folder object that contains filename

setPath

selects a certain folder and sets path values for it

fmanager.setPath(id);

params:

  • id - {string} a folder id

showSearchResults

searches text and displays results on the screen

fmanager.showSearchResults(text);

params:

  • text - {string} searched text

showTree

shows the Tree panel

fmanager.showTree();

uploadFile

opens a file upload dialog

fmanager.uploadFile(target);
  • target - the id of the folder where a file will be uploaded

Properties
  • disabledHistory - the flag that disables the tracking history
  • handlers - a collection of server scripts for action handling
  • icons - a collection of icons
  • mode - the initially selected mode ("table" by default)
  • modes - an array with modes names
  • readonly - the readonly mode for File Manager
  • structure - the configuration of File Manager views
  • templateCreate - a template for a newly created folder
  • templateDate - a template applied for the format of folder/file's date of modification
  • templateIcon - a template for icons that can be customized (used in "files" and "table" views)
  • templateName - a template applied for the folder/file's name
  • templateSize - a template applied for the file size
  • uploadProgress - an object with configuration of progress bar that appears during the upload

disabledHistory

disables tracking history ("false" by default)

webix.ui({
    view:"filemanager",
    id:"files",
    disabledHistory: true
    ...
});

handlers

specifies the collection of server scripts for action handling

webix.ui({
    view:"filemanager",
    handlers:{
        "upload"    : "data/saving.php",
        "download"  : "data/saving.php",
         ...
    }
});

icons

defines icons for File Manager

webix.ui({
    view:"filemanager",
    id:"files",
    icons: {
        folder: "folder",
        doc: "file-word-o",
        ...
    }
});

mode

defines the id of the initially selected mode ("table" by default)

webix.ui({
    view:"filemanager",
    id:"files",
    mode: "files"
    ...
});

modes

specifies an array of modes in the File view

webix.ui({
    view:"filemanager",
    id:"files",
    modes: ["files","table"]
    ...
});

readonly

sets readonly mode for File Manager

webix.ready(function(){
    webix.ui({
        view:"filemanager",
        readonly: true,
        url:"../common/data.php"
    });
});

structure

sets the configuration of File Manager views

webix.ui({
    view:"filemanager",
    id:"files",
    structure:{
       ...
    }
    ...
});

Related sample: Adding New Mode

templateCreate

defines a template for a newly created folder

templateCreate: function(){
    return {value: "newFolder", type: "folder", date: new Date()};
}

templateDate

defines a template applied for the format of folder/file's date of modification

webix.ui({
    view:"filemanager",
    templateDate: function(obj){
        var date = obj.date;
        if(typeof(date) != "object"){
           date = new Date(parseInt(obj.date,10)*1000);
        }
        return webix.i18n.fullDateFormatStr(date);
    }
});

templateIcon

defines a template for icons that can be customized (used in "files" and "table" views)

templateIcon: function(obj,common){
    return "<span class='webix_icon webix_fmanager_icon fa-"
        +(common.icons[obj.type]||common.icons["file"])+"'></span>";
},

templateName

defines a template applied for the folder/file's name

templateName: function(fileObj,common){
    return fileObj.value
}

templateSize

defines a template applied for the file size

templateSize: function(obj,common){
    var value = obj.size;
    var isInt = (parseInt(value,10) == value);

    // apply locale formating
    var getFormatedValue = webix.Number.numToStr({
        decimalDelimiter:webix.i18n.decimalDelimiter,
        groupDelimiter:webix.i18n.groupDelimiter,
        decimalSize : isInt?0:webix.i18n.groupSize
    });
    value = getFormatedValue(value);

    // get size label
    var labels = webix.i18n.filemanager.sizeLabels; // ["B","KB",...]
    var sizeIndex = 0;
    while(value/1024 >1){
        value = value/1024;
        sizeIndex++;
    }
    var label = labels[sizeIndex];

    return value+""+label;
},

uploadProgress

defines an object with configuration of progress bar that appears during the upload

webix.ui({
    view:"filemanager",
    id:"files",
    uploadProgress: {
        type:"top",
        delay:3000,
        hide:true
    }
});


File Manager General How-Tos

How to make File Manager readonly?

To activate the readonly mode, you need to set the readonly property to true in File Manager configuration:

webix.ready(function(){
    webix.ui({
        view:"filemanager",
        readonly: true,
        url:"../common/data.php"
    });
});

From now on, users won't be able to manipulate items. The Menu button will be hidden.

Related sample: Read-only mode

How to hide a view?

It is possible to hide any view of File Manager by calling the hide method. For example, imagine that you need to remove the Menu button and the spacer between the Menu and Back buttons.

To implement this task, use the following technique:

webix.ready(function(){
    webix.ui({
        view:"filemanager",
        id:"files",
    });
    $$("files").load("../common/data.php");

     // hide the Menu button
     $$("files").$$("menu").hide();
     // hide the spacer between the Menu and Back buttons
     $$("files").$$("menuSpacer").hide();
});

Related sample: Hiding Buttons

How to add a custom action?

The add method allows adding a new action to menu:

var actions = $$("fmanager").getMenu();
actions.add({id: "myAction", icon: "file", value: "My Action"});

To process clicks on the new action you can set onItemClick event handler for actions view:

actions.attachEvent("onItemClick", function(id){
   if(id == "myAction"){
       // some code here
   }
});

How to add a new mode?

To create a custom mode of displaying files in the Files view, you need to define a new mode configuration and apply the onViewInit event.

For example, it's possible to create a new mode based on the List view as follows:

webix.ui({
    view:"filemanager",
    id:"files",
    // specify mode selected by default
    mode: "custom",
    // all available modes including a new mode
    modes:["files","table","custom"],
    // object with configuration for new views of File Manager
    structure:{
        // specify the view of the new mode
        "custom": {
            view: "list",
            template: function(obj,common){
                return common.templateIcon(obj,common)+obj.value;
            },
            select: "multiselect",
            editable:true,
            editaction: false,
            editor:"text",
            editValue:"value",
            drag: true,
            navigation: true,
            tabFocus: true,
            onContext:{}
        }
    },
    on:{
        "onViewInit": function(name, obj){
           if (name == "modes"){
               obj.width += 32;
               obj.options.push({
                  id: "custom",
                  width: 32,
                  value: "<span class='webix_fmanager_mode_option webix_icon fa-file'/>"
               });
           }
        }
    }
});

Related sample: Adding New Mode

How to add a new column in "table" mode?

You can add a new column into the "table" view. For this purpose you should use the onViewInit event (described in the above example) to customize the view and insert column configuration into the "columns" array of the table.

Here is an example of inserting a new column after the "Date" column:

var fManager = new webix.ui({
   view: "filemanager",
   on:{
       "onViewInit": function(name, config){
           if( name == "table" ){
              // an array with columns configuration
              var columns = config.columns;
              // configuration of a new column
              var newColumn = {
                id: "new",
                header:"Extension",
                fillspace: 1,
                template: function(obj,common){
                    return obj.ext||""; // "ext" property of files
                }
             };
             // insert a column
             webix.toArray(columns).insertAt(newColumn,3);
          }
       }
    }
});

Related sample: Adding New Column

How to customize existing views?

To illustrate this possibility, let's turn off multiple selection for the 'table' and 'files' views".

We can use the onViewInit event to customize configuration of exiting views:

webix.ready(function(){
    webix.ui({
        view:"filemanager",
        id:"files",
        on:{
            "onViewInit": function(name, config){
                // disable multi-selection for "table" and "files" views
                if (name == "table" || name == "files"){
                    config.select = true;
                }
            }
        }
    });

    $$("files").load("../common/data.php");
});

Related sample: Changing View Configuration


Sidebar

Webix Sidebar is a Tree-based component which is used for creating menus with hierarchical structure.

Sidebar menu can be collapsed into a navigation bar with only icons of the menu items visible. On hovering an icon, a popup with the related item is shown with its subitems.

On clicking a Sidebar menu item, either the related content is shown in the right part of the screen or selectable subitems are displayed.

Creating a Sidebar Menu

Files to include

You need to include the following files on your page:

<!-- js files -->
<script src="codebase/webix.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" src="//cdn.webix.com/components/sidebar/sidebar.js"></script>

<!-- css files -->
<link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
<link
    rel="stylesheet"
    type="text/css"
    href="//cdn.webix.com/components/sidebar/sidebar.css"
>

Initialization

To initialize the Sidebar and load it with data, you need to use the code as in:

// webix.ready() function ensures that the code will be executed when the page is loaded
webix.ready(function(){
    // object constructor
    webix.ui({
        view: "sidebar",
        // setting the data source
        data: menu_data
    });
});

Data source

Sidebar can load data from various sources in different formats. You can find more information in the Loading Data into Tree article.

The Sidebar data configuration contains the description of menu items, corresponding icons and subitems. It can look like this:

var menu_data = [
    {id: "dashboard", icon: "dashboard", value: "Dashboards",  data:[
        { id: "dashboard1", value: "Dashboard 1"},
        { id: "dashboard2", value: "Dashboard 2"}
    ]},
    {id: "layouts", icon: "columns", value:"Layouts", data:[
        { id: "accordions", value: "Accordions"},
        { id: "portlets", value: "Portlets"}
    ]},
    {id: "tables", icon: "table", value:"Data Tables", data:[
        { id: "tables1", value: "Datatable"},
        { id: "tables2", value: "TreeTable"},
        { id: "tables3", value: "Pivot"}
    ]},
    ...
];

Related sample: SideBar Menu

How to add the Menu button

Adding the Menu button in the left top corner allows collapsing the menu items into a vertical navigation bar with icons. In this state menu items will be shown by hovering the mouse pointer over the icons.

Let's create a layout with a toolbar and two columns. We'll place a button on the toolbar and put a sidebar in the left column, the right column will serve as a template for some content that could be shown on an item's click.

webix.ui({
    rows: [
        { view: "toolbar", elements: [
            {   view: "button",
                type: "icon",
                icon: "bars",
                width: 37,
                align: "left",
                css: "app_button",
                click: function(){
                    $$("$sidebar1").toggle()
                }
            },
        ]},
        {
            cols:[
                {
                    view: "sidebar",
                    data: menu_data
                },
                {
                    template: ""
                }
            ]
        }
    ]
});

The applied button uses the "bars" icon from the Font Awesome collection. You can set its position using the align property and specifying a CSS style, like this one:

.app_button button{
    padding:0;
    text-align: center;
}

To collapse/expand the menu on the button click, we define the click handler in which we put the toggle() function. The details are given in the API reference.

The image below shows how an expanded Sidebar menu collapses on the Menu button click:

Data Visualization

Sidebar allows configuring the templates of its items. The Data Templates are described in the Type Implementation of Sidebar:

webix.type(webix.ui.tree, {
    name:"sideBar",
    height: "auto"
    ...
});

name

defines the Sidebar name

{
    name:"sideBar"
}

height

specifies the height of an item in the Sidebar

{
    height: "auto"
}

css

specifies the CSS class applied to the Sidebar

{
    css: "webix_sidebar"
}

template

defines the appearance of the Sidebar in the collapsed and expanded states

template: function(obj, common){
    if(common.collapsed)
        return common.icon(obj, common);
    return common.arrow(obj, common)+common.icon(obj, common) +"<span>"+obj.value+"</span>";
}

arrow

defines the presentation of arrows, depending on the level of the related Sidebar items

arrow: function(obj, common){
    var html = "";
    var open = "";
    for (var i=1; i<=obj.$level; i++){
        if (i==obj.$level && obj.$count){
            var icon = " fa-angle-"+(obj.open?"down":"left");
            html+="<span class='webix_sidebar_dir_icon webix_icon"+icon+"'></span>";
        }
    }
    return html;
},

icon

specifies a template for rendering Font Awesome icons next to the items of Sidebar

icon:function(obj, common){
    if(obj.icon)
        return "<span class='webix_icon webix_sidebar_icon fa-"+obj.icon+"'></span>";
    return "";
}

API Reference

Sidebar inherits the most part of API from the Tree component. Follow the ui.tree API page to find the necessary method,event or property.

Besides, Sidebar has its own methods and properties. You can find them in the list below:

Methods

getPopup()

returns the popup's object

sidebar.getPopup();

returns:

  • {object} the popup's object

getPopupTitle()

returns a Template view with a popup title (a branch's name)

sidebar.getPopupTitle();

returns:

  • {object} a Template view containing the popup title

getPopupList()

returns a List view of SideBar's Popup

sidebar.getPopupList();

returns:

  • {object} a List view containing child items

collapse()

collapses the sidebar into a navigation bar

sidebar.collapse();

expand()

expands the sidebar from the collapsed state

sidebar.expand();

toggle()

collapses an expanded Sidebar and expands a collapsed Sidebar

sidebar.toggle();

Properties

collapsed

defines if the Sidebar will be shown in the collapsed state or in the expanded one

  • value - {boolean} true for collapsed state, false for the expanded one
webix.ui({
    view: "sidebar",
    collapsed:true
});

position

sets the sidebar's position

Parameters:

  • value - {string} a new sidebar's position ("right" or "left")
webix.ui({
    view: "sidebar",
    position:"right"
});


SpreadSheet

API Reference
  • Methods, properties and events
  • Samples
Overview

Webix SpreadSheet is a component intended for creating tables and performing various operations with their data and appearance.

Webix SpreadSheet represents a web-tool for making tables online and keeping all the data locally. Thus, all the information in your reports and accounts will be kept secure and always at hand. The ready-made document can be exported into an Excel file, and you can import an Excel document into SpreadSheet as well.

The component includes all the necessary functionality for handy work with data presented in the tabular form. You can edit and format the content of cells, resize cells, apply diverse styles, fonts and borders' types, align text and merge cells in rows and columns. Mathematical functions are also included. The component can be localized according to the rules of various languages.

Guides

Configuring SpreadSheet

  • Creating SpreadSheet on a Page
  • Customizing SpreadSheet
  • Loading and Saving Data in SpreadSheet
  • Localizing SpreadSheet
  • Configuring Spreadsheet
 Discusses the main points of SpreadSheet initialization and customization.

Working with SpreadSheet

  • Math Operations in SpreadSheet
  • Data Export
  • Excel File Import
  • Handling Events with SpreadSheet
  • SpreadSheet General How-Tos
 Describes possible operations with SpreadSheet and its elements.


Creating SpreadSheet on a Page

Files to include

You need to include the following files in the head section of your document:

<script src="codebase/webix.js" type="text/javascript"></script>
<script src="codebase/spreadsheet.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="codebase/webix.css">
<link rel="stylesheet" type="text/css" href="codebase/spreadsheet.css">

Initialization

To initialize SpreadSheet and load it with data, use the code as in:

//webix.ready() function ensures that the code will be executed when the page is loaded
webix.ready(function(){
    //object constructor
    webix.ui({
        view:"spreadsheet",
        //loaded data object
        data: base_data
    });
});

Related sample: Basic Init of Spreadsheet


Customizing SpreadSheet

SpreadSheet consists of two main parts: a toolbar with instruments panel and a stylized datatable.

The full structure of SpreadSheet can be presented:

  • Toolbar:
    • the Undo/Redo buttons
    • Font section: the Font-family and Font-size selectors
    • Text section: the Font-weight buttons and the Font color selector (colorboard)
    • Cell section: the Background color selector, the Borders selector with colorboard and the Merge button
    • Align section: the Horizontal and Vertical Align buttons and the Word Wrap button
    • Format section with the Format selector of the cell's content
  • DataTable

Toolbar

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

To refer to the toolbar object, firstly you need to specify the toolbar's id in the toolbar configuration.

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

Then you can address to the toolbar via the corresponding id.

spreadsheet.$$("bar");

Customizing toolbar's buttons

The settings for 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 this or that block.

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

The button blocks' names correspond to the properties defined in the localization files that specify the language of its lables.

Removing a block or a button

In case you want to remove some block or button specified in the default configuration, you need just not to define them in the buttons object.

Adding a custom block or a button

To add your own block of buttons into the toolbar, you should specify its name as a property in the "buttons" configuration. The value of this property is an array of buttons.

To add a custom button, you should specify its name in the array of buttons of the corresponding block.

If you don't want to show the block's name, add the "$" sign before the block's name.

 buttons: {
    "$title": [{
        view: "label", width: 150, label: "My SpreadSheet"
    }],
    "undo": ["undo","redo"],
    "text": ["font-weight","font-style","text-decoration","color"],
    "My Block": [{
        view: "button", name: "my-button", width: 100, label: "My Button",
        tooltip: "Click this button", click: function(){webix.message("Click")}
    }]
 }

Related sample: Custom configuration of the toolbar

Customizing Datatable

The datatable part of SpreadSheet features the same functionality that the Datatable widget does. So, you can customize the datatable in SpreadSheet in various ways.

You can refer to the datatable object as follows:

spreadsheet.$$("cells");

For example, you can attach a context menu with some actions for datatable cells and call the handler function on the right click.

webix.ready(function(){
    webix.ui({
        view:"spreadsheet",
        id:"ss",
        math:true,
        data:base_data
    });

    webix.ui({
        view:"contextmenu",
        data:["Cut", "Copy", "Paste", "Delete"],
        click:function(id, event){
            var cell = this.getContext().id;
            webix.message(id+" on row "+cell.row+" of the column "+cell.column);
    }).attachTo( $$("ss").$$("cells"));
});

Related sample: Context menu


Loading and Saving Data in SpreadSheet

Data Loading Format

SpreadSheet loads data in JSON format: an object that includes 4 parameters:

  • data
  • sizes
  • spans
  • styles

An example of the object for loading is given below:

var base_data = {
  "styles": [
    ["wss1",";;center;;;;;;;;;"],
    ["wss2",";#6E6EFF;center;;;;;;;;;"],
    ["wss3","#FFFFFF;#6E6EFF;center;;;;;;;;;"]
    ...
  ],
  "sizes": [
    [0,1,125],
    [0,3,158],
    [0,4,137]
  ],
  "data": [
    [1,1,"Report - July 2016","wss5"],
    [1,2,"","wss5"],
    [1,3,"","wss5"],
    [2,1,"Region","wss20"],
    [2,2,"Country","wss20"],
    [2,3,"Sales - Group A","wss12"],
    [2,4,"Sales - Group A","wss12"],
    [2,5,"Total","wss13"]
    ...
  ],
  "spans": [
    [1,1,5,1]
  ]
};

The Data parameter

The "data" parameter contains data elements set as arrays of 4 elements:

  • the number of the row
  • the number of the column
  • the cell's content
  • the CSS class of the cell
"data": [
    [1,1,"Report - July 2016","wss5"],
    [1,2,"","wss5"],
    [1,3,"","wss5"],
    [2,1,"Region","wss20"],
    [2,2,"Country","wss20"],
    [2,3,"Sales - Group A","wss12"],
    [2,4,"Sales - Group A","wss12"],
    [2,5,"Total","wss13"]
  ]

The Styles parameter

The "styles" parameter contains styles descriptions presented as arrays of two elements:

  • the style's name
  • a string containing the styles of the CSS rule
"styles": [
    ["wss1",";;center;;;;;;;;;"],
    ["wss2",";#6E6EFF;center;;;;;;;;;"],
    ["wss3","#FFFFFF;#6E6EFF;center;;;;;;;;;"]
],

The Sizes parameter

The "sizes" parameter is optional and includes a collection of sizes that are applied to specific rows and columns.

It contains descriptions of sizes, presented as arrays of 4 parameters:

  • the number of the row or 0
  • the number of the column or 0
  • the size of an element (a row or a column)

The column's size is specified as [0, column_number, column_width], e.g. [0,3,30].

The row's size is set as [row_number, 0, row_height], e.g. [2,0,70].

"sizes": [
  [1,0,60],
  [0,3,158],
  [0,4,137]
],

The Spans parameter

The "spans" parameter defines the values of spans. It's an array of arrays the elements of which are the following:

  • the number of the row that starts the span
  • the number of the column that starts the span
  • the number of columns in a span
  • the number of rows in a span

For example:

"spans": [
    [1,1,5,1]
]

Loading Data

Data is loaded into SpreadSheet the same as into other Webix components.

To load data from server, you can use either the load method or the url parameter.

  • using the load method:
webix.ui({
    id:"ssheet",
    view:"spreadsheet"
});
$$("ssheet").load("data.js");
  • using the url parameter
webix.ui({
    view:"spreadsheet",
    url:"data.js"
});

To load data from an inline data source, you can use either the parse method:

webix.ui({
    id:"ssheet",
    view:"spreadsheet"
});
$$("ssheet").parse(data,"json");

or the data parameter and specify the dataset directly in the spreadsheet configuration:

webix.ui({
    view:"spreadsheet",
    data:[
        {
            "styles": [
                ["wss1",";;center;;;;;;;;;"],
                ["wss2",";#6E6EFF;center;;;;;;;;;"]
                ...
            ],
            "sizes": [
                [0,1,125],
                [0,3,158]
                ...
            ],
            "data": [
                [1,1,"Report - July 2016","wss5"],
                [1,2,"","wss5"]
                ...
            ],
            "spans": [
                [1,1,5,1]
            ]
        };
    ]
});

Saving Data

On each change (editing or formatting) in a cell of SpreadSheet, a POST Ajax request for saving changes is sent to the corresponding server-side script (handler) specified in the "save" property of the SpreadSheet configuration.

If you change several cells at a time, requests are sent for each of them.

webix.ready(function(){
    webix.ui({
        view:"spreadsheet",
        url: "server/get.php",
        resizeCell: true,
        save: {
            data:"server/data.php", // if data is changed
            sizes:"server/sizes.php", // if cells' sizes are changed
            spans:"server/spans.php", // if cells are merged or splitted
            styles:"server/styles.php" // if styles are changed or a new one created
        }
    });
});

You can also send requests to handlers in one common request:

webix.ready(function(){
    webix.ui({
        view:"spreadsheet",
        url: "server/get.php",
        resizeCell: true,
        save:"/server"
    });
});

In this case, paths to the necessary handlers will be added automatically:

  • data => /server/data
  • styles => /server/styles
  • sizes => /server/sizes
  • spans => /server/spans

Parameters of requests differ depending on the operation handler:

  • data.php
{
    row:3,
    column:9,
    value: 230,
    style:"wss561"
}
  • sizes.php
// for a column
{
    row:0,
    column:7,
    size:179
}
// for a row
{
    row:1,
    column:0,
    size:60
}
  • spans.php
{
    row:1,
    column:9,
    x: 2,
    y: 2
}
  • styles.php
{
    name:"wss562",
    text:"#000000;#ff0000;left;'PT Sans', Tahoma;15px;;;;top;;no,#434343;;;;;"
}

SpreadSheet is a purely client-side widget, therefore you can implement any logic at the backend. You can find several demos that implement PHP data in the SpreadSheet package.

There are also packages for implementing Node.js and .Net data available on github.


Localizing SpreadSheet

You can easily localize SpreadSheet, by defining all the necessary language settings.

It's possible to localize the following properties:

  • labels on the instruments panel
  • tooltips for instruments

Labels and tooltips of SpreadSheet instruments' are stored in the webix.i18n.spreadsheet object:

webix.i18n.spreadsheet = {
    "labels": {
        // formats
        "common": "Common",
        "currency": "Currency",
        "number": "Number",
        "percent": "Percent",
        // titles
        "undo": "Undo/Redo",
        "font": "Font",
        "text": "Text",
        "cell": "Cell",
        "align": "Align",
        "format": "Format"
    },
    "tooltips": {
        "color": "Font color",
        "background": "Background color",
        "font-family": "Font family",
        "font-size": "Font size",
        "text-align": "Horizontal align",
        "vertical-align": "Vertical align",
        "borders": "Borders",
        "borders-no": "Clear borders",
        "borders-left": "Left border",
        "borders-top": "Top border",
        "borders-right": "Right border",
        "borders-bottom": "Bottom border",
        "borders-all": "All borders",
        "borders-outer": "Outer borders",
        "borders-color": "Border color",
        "align-left": "Left align",
        "align-center": "Center align",
        "align-right": "Right align",
        "align-top": "Top align",
        "align-middle": "Middle align",
        "align-bottom": "Bottom align",
        "span": "Merge",
        "wrap": "Text wrap",
        "undo": "Undo",
        "redo": "Redo",
        "format": "Format",
        "font-weight": "Bold",
        "font-style": "Italic",
        "text-decoration": "Underline"
    }
};

To apply a custom locale, you can follow one of the two ways:

1) redefine default labels and tooltips according to your locale directly in the webix.i18n.spreadsheet object;

2) set a certain locale as described below:

  • include the chosen locale library into your page:
<script src="../../../codebase/i18n/ru.js" type="text/javascript"></script>
  • define 'spreadsheet' labels and tooltips in the webix.i18n.locales[localeName] object:
webix.i18n.locales['ru-RU'].spreadsheet = {
    "labels":{
       "common": "Общий",
       "currency": "Валюта",
       ...
    },
    "tooltips":{
       "color": "Цвет текста",
       ...
    }

};
  • apply the created locale with the help of the setLocale method:
webix.i18n.setLocale('ru-RU');

Related sample: Localization of Spreadsheet


Configuring Spreadsheet

The SpreadSheet component can be easily configured according to your needs. You can enable work with math operations, cells resizing, specify the exact number of rows and columns in the spreadsheet.

Resizing cells

To enable resizing of cell, you need to set the resizeCell property with the true value in the Spreadsheet configuration:

webix.ui({
    view:"spreadsheet",
    data: base_data,
    resizeCell:true
});

Math operations

Math functionality is also enabled in the configuration of the component. Just set the math property to true.

webix.ui({
    view:"spreadsheet",
    data: base_data,
    math:true
});

To get more information about math in SpreadSheet, read the Math Operations in SpreadSheet article.

Enabling formula editor

You can add an inline editor of formulas in Spreadsheet. It allows creating a new formula and edit the existing one in a cell.

There's the liveEditor property in the Spreadsheet API that will let you to switch the editor on. You just need to set it to true in the config.

webix.ui({
    view: "spreadsheet",
    data: base_data,
    liveEditor: true
});

You can find a more detailed description of the editor in the corresponding section.

Setting the count of rows and columns

If you need to specify a certain number of columns or rows in the SpreadSheet, make use of the columnCount and rowCount properties.

webix.ui({
    view:"spreadsheet",
    data: base_data,
    // setting the number of columns
    columnCount:10,
    // setting the number of rows
    rowCount:20
});

Related sample: Reset Spreadsheet

Adding subbar

To show some additional elements/views into Spreadsheet, you can use the subbar property. It allows adding views below the toolbar, but above the datatable.

Inside of the subbar property you can define a view, e.g. toolbar, apply some css to it and specify the elements that will be shown in the view.

webix.ui({
    view:"spreadsheet",
    data: base_data,
    subbar:{
        view:"toolbar", css:"webix_ssheet_toolbar",
        elements:[
            { view:'label', template:"Custom cell editor: ", width:190},
            { view:'text', id:'text', width:250 },
            {}
        ]
    },
});

Related sample: Subbar

Making SpreadSheet readonly

To activate the readonly mode, you need to set the readonly property to true in the SpreadSheet configuration:

webix.ready(function(){
    webix.ui({
        view:"spreadsheet",
        data: base_data,
        readonly:true
    });
});

From now on, users won't be able to manipulate the cells. The Instruments panel and the subbar will be hidden.

Related sample: Readonly Spreadsheet


Math Operations in SpreadSheet

SpreadSheet allows working with simple mathematical operations as well as with formulas. The component calculates them and displays the result in the related cells.

To start working with data as mathematical expressions, you should set the math parameter to true. By default, it's disabled. SpreadSheet supports native Excel math.

var math_data = {
  "styles": [
    [ "wss1", ";;right;;;;;;;;;;;;;" ],
    ...
  ],
  "sizes": [
    [ 3, 2, 37 ]
    ...
  ],
  "data": [
    [ 3, 2, "=SUM(B3:E3)", "wss1" ]
    ...
  ],
  "spans": [
    [ 3, 2, 4, 1 ]
    ...
  ]
};

webix.ready(function(){
    webix.ui({
        view:"spreadsheet",
        math: true,
        data:math_data
    });
});

Related sample: Math in the Spreadsheet

Syntax

The syntax of mathematical expressions is the same as that of Excel.

  1. Formula must start from the '=' sign.
  2. The names of formulas and cell references must be written in capital letters.
  3. The following elements can be used within formulas:
  • basic mathematical operators, which are: +, -, /, *
  • numbers
  • cell references
  • Excel-like functions
"data": [
    [ 3, 2, "=A1+B2",""],
    [ 4, 2, "=7+8",""],
    [ 5, 2, "=7+B2",""],
    [ 6, 2, "=SUM(A3+D7)",""]
    ...
 ]

There are two variants of recording a function, depending on which you can get different results:

  • if you want to apply a formula only to two certain cells, you need to specify comma-separated references to these cells, e.g.:
"data": [
 [ 7, 2, "=SUM(A3,D7)",""]
]
  • if you want to calculate the values of cells in a range, you should define colon-separated references to the first and the last cells of the range, e.g,:
"data": [
 [ 7, 2, "=SUM(A3:D7)",""]
]

Formulas

SpreadSheet can work with the Excel formulas. Below you'll find the full list of formulas with detailed descriptions.

  • SUM - adds values;
    • empty cells, logical values like TRUE, or text are ignored.
  • AVERAGE - returns the average (arithmetic mean) of the arguments;
    • if a range or a cell reference argument contains text, logical values, or empty cells, those values are ignored; however, cells with the value zero are included.
  • COUNT - counts the number of cells that contain numbers, and counts numbers within the list of arguments;
    • empty cells, logical values, text, or error values in the array or reference are not counted.
  • COUNTA - counts the number of cells that are not empty in a range, zero is excluded.
  • COUNTBLANK - сounts empty cells in a specified range of cells;
    • cells with zero values are not counted.
  • MAX - returns the largest value in a set of values;
    • empty cells, logical values, or text in the array or reference are ignored. If the arguments contain no numbers, MAX returns 0 (zero).
  • MIN - returns the smallest number in a set of values.
    • empty cells, logical values, or text in the array or reference are ignored. If the arguments contain no numbers, MIN returns 0 (zero).
  • PRODUCT - multiplies all the numbers given as arguments and returns the product;
    • only numbers in the array or reference are multiplied. Empty cells, logical values, and text in the array or reference are ignored.
  • SUMPRODUCT - multiplies corresponding components in the given arrays, and returns the sum of those products.
    • for valid products only numbers are multiplied. Empty cells, logical values, and text are ignored. Treats array entries that are not numeric as if they were zeros.
  • SUMSQ - returns the sum of the squares of the arguments;
    • empty cells, logical values, text, or error values in the array or reference are ignored.
  • VARP - сalculates variance based on the entire population;
    • empty cells, logical values, text, or error values in the array or reference are ignored.
  • STDEVP - calculates standard deviation based on the entire population given as arguments. The standard deviation is a measure of how widely values are dispersed from the average value (the mean).
    • empty cells, logical values, text, or error values in the array or reference are ignored.
  • POWER - returns the result of a number raised to a power;
    • works with real numbers.
  • QUOTIENT -returns the integer portion of a division. Use this function when you want to discard the remainder of a division;
    • works with real numbers.
  • SQRT - returns a positive square root.
  • ABS - returns the absolute value of a number. The absolute value of a number is the number without its sign.
  • RAND - returns an evenly distributed random real number greater than or equal to 0 and less than 1. A new random real number is returned every time the worksheet is calculated.
  • PI - returns the number 3.14159265358979, the mathematical constant pi, accurate to 15 digits.
  • INT - rounds a number down to the nearest integer.
  • ROUND - rounds a number to a specified number of digits.
  • ROUNDDOWN - rounds a number down to a specified number of digits.
  • ROUNDUP - rounds a number up to a specified number of digits.
  • TRUNC - truncates a number to an integer by removing the fractional part of the number.
  • EVEN - returns number rounded up to the nearest even integer.
  • ODD - returns number rounded up to the nearest odd integer.

Related sample: Math in the Spreadsheet

Formula Editor

Spreadsheet possesses an advanced formula editor. Its main features are:

  • providing the list of possible formulas on entering the first letter of the formula name in the input;
  • entering formula operands either by selecting a range of cells or by clicking the related cells.

It's easy to enable the formula editor, just set the liveEditor property to true in the spreadsheet configuration:

webix.ui({
    view: "spreadsheet",
    data: base_data,
    liveEditor: true
});

Related sample: Edit formulas


Data Export

SpreadSheet provides the possibility to export data to Excel, PDF ans PNG formats.

For any of these formats, you need to initialize a SpreadSheet first:

webix.ui({
    id:"ss1",
    view:"spreadsheet",
    data: sheet1_data
});

Then call the corresponding method: toPDF, toPNG or toExcel to export data from SpreadSheet into the file of the necessary format:

for Excel:

webix.toExcel("ss1");

for PDF:

webix.toPDF("ss1");

for PNG:

webix.toPNG("ss1");

Related sample: Export to .xlsx, .pdf and .png


Excel File Import

Loading data from Excel into SpreadSheet

You can easily import data from an Excel file into SpreadSheet. For this purpose, you can choose one of the ways below:

1) specifying the necessary file in the SpreadSheet constructor with the help of the url parameter:

webix.ui({
    view:"spreadsheet",
    url: "binary->../common/test.xlsx",
    datatype:"excel"
});

The notation "binary->../common/test.xlsx" allows loading compiled files from the computer and get their content.

The "excel" datatype allows parsing the content of a binary file and getting it in the form necessary for SpreadSheet.

2) calling the load method:

$$("ssheet").load("binary->../common/test.xlsx", "excel");

The parameters are:

  • file - (string) the name of the file to load
  • datatype - (string) data type (should be "excel" here)

3) using the parse method to load data to the component:

{ view:"uploader", value:"Load from Excel file", on:{
    onBeforeFileAdd: function(upload){
        $$("ssheet").reset();
        $$("ssheet").parse(upload.file, "excel");
        return false;
    }
}}

Parameters of the parse method are the following:

  • file - (object) uploaded file object
  • datatype - (string) data type (should be "excel" here)

Customizing the imported data

You can customize the presentation of the loaded data: set the name of the sheet and control the number of the loaded rows.

webix.ui({
    view:"spreadsheet",
    url: "binary->../common/test.xlsx@Data[0-10]",
    datatype:"excel"
});

The string value of the url property binary->files/data.xlsx@Data[1-10]" includes the following parts:

  • binary - the name of the proxy object
  • ../common/test.xlsx - path to the Excel file
  • @ - optional, the delimiter that detaches the link from its parameters (can be omitted together with parameters)
  • Data - optional, the name of the Excel sheet to render
  • [1-10] - optional, the rows that should be rendered in the viewer

To render rows starting from a certain row, you can set the rows array as [8-].

Related sample: Import from Excel


Handling Events with SpreadSheet

Attaching Event Handler

The user can add any user-defined handler to any of the available events. To do this, the user can use the attachEvent method with the following parameters:

  • evName - name of the event;
  • evHandler - user-defined event handler.
webix.attachEvent(evName, evHandler);

Several handlers can be attached to one and the same event, and all of them will be executed. The names of the events are case-insensitive.

Detaching Event Handler

There is a simple way of removing an event-handler:

webix.detachEvent(id); // unique id of the event handler

List of supported events

You can find the full list of the supported events in the API Reference.

Related sample: Events


SpreadSheet General How-Tos

How to create multiview with SpreadSheets?

It's possible to create several SpreadSheets on a page with the help of the multiview property of toolbar and switch between them with the help of a segmented button.

To implement such a configuration, you should initialize multiview with several spreadsheets first. Then create a toolbar with a segmented button on it and specify the spreadsheets' ids in the options of the segemented button:

webix.ui({
    rows:[
        { cells:[
            {
                view:"spreadsheet",
                id:'ss1',
                columnCount:15,
                data: sheet1_data
            }, {
                view:"spreadsheet",
                id:'ss2',
                columnCount:15,
                data: sheet2_data
            }, {
                view:"spreadsheet",
                id:'ss3',
                columnCount:15,
                data: sheet3_data
            },
        ]}
    ]
    {
        view:"toolbar", css:"webix_ssheet_toolbar", elements:[
            {
                view:"segmented",
                multiview:true,
                options: [
                    { value: "List 1", id: 'ss1' },
                    { value: "List 2", id: 'ss2' },
                    { value: "List 3", id: 'ss3' }
                ], width:390
            },
            {}
        ]
    }
]

Related sample: Several lists Spreadsheet


Start

Guides

You are in the heart of the documentation that covers tricks, tips and techniques for working with the library. The chapter is divided into subject areas, each of which contains a set of task-oriented articles. Articles are of various difficulties and both a beginner and a master can find there a helpful information to build a powerful application.

Designing User Interface

  • Building App Architecture
  • Structuring a Big Application
  • Initialization from Markup
  • Using Webix Jet Micro-Framework
 Describes different ways you can follow to design and build the user interface for your application.

Loading and Storing Data

  • Data Loading
  • Defining Data Scheme
  • Server-side Integration
  • Data Binding and Syncing
  • Data Updating
  • Ajax operations
 Teaches you how to load data into a component using different data sources, formats and techniques.

Configuring Components

  • Changing Visibility
  • Disabling/Enabling
  • Adding/Removing Views
  • Adding/Removing Multiview Cells
  • Adding Headers
  • Changing Properties
  • Initial Sizing
  • Resizing Components
  • Managing Scrolling
  • Localization
 Says about various means you've got to configure a component initially and to dynamically change this configuration later: sizing/ resizing techniques, localization, changing configuration properties etc.

Managing Data in a Component

  • Data Object Operations
  • Selecting Items and Navigation
  • Adding/Deleting Items
  • Data Templates
  • Working with Dates
  • Filtering and Sorting
  • Grouping Data Items
  • Validation
  • Editing Data Items
  • Controls for Editing
  • Paging
  • Drag-n-Drop within Webix Views
  • Working with the clipboard
  • Undo for Data Components
 Covers techniques for performing general and advanced operations under data, such as adding, deleting, sorting, filtering etc.

Exporting Content and Data

  • Components Export to PNG
  • Data Components Export to Excel
  • Data Components Export to PDF
 Discusses the possibilities of exporting the content and data of components to PNG and Excel formats.

Styling and Animation

  • Skins
  • Component Styling
  • Animation
  • Icons with UI Components
  • Setting Borders to the Components
 Says how to style Webix application: styling techniques, css classes used in components, animation and visual effects.

Interacting with Users

  • Creating Message Boxes
  • Setting Progress Bar and Overlay Messages
  • HTMLForm and Form Treatment
  • Managing Controls in a Form
  • Uploading Files
  • Uploading Files with Form Component
  • Event Handling
  • Keyboard Events and App Navigation
  • Adding Active Elements to Components
 Describes various ways you can communicate with users: events, message boxes, forms and their controls

Web and Internet

  • Webix Storage Interface
  • Offline Support
  • Saving Application State
 Focuses on how to provide offline support for an app and save its state.

Extending components

  • Component Copying and Extending
  • Creating a Custom Component
 If the wealth of provided functionality is not enough for you, the library provides flexible means for extending existing components.

Third Party Integration

  • Text Editor Integration
  • Scheduler and Gantt Integration
  • Chart Integration
  • Maps Integration
  • Integration with DHTMLX Components
  • JQuery Integration
  • Backbone Integration
  • Angular JS Integration
  • How Integrate any Thirdparty Tool Using a Custom Component
 Says which third-party libraries and how can be integrated with Webix components

Auxiliary Resources

  • Top 10 Helpers You Should Know About
  • Webix in Touch Environment
  • Advanced Drag-and-Drop
  • Data Drivers
  • Number formatting methods
  • Date formatting methods
 Extra goodies in the Webix library


Designing User Interface

  • Building App Architecture
  • Structuring a Big Application
  • Initialization from Markup
  • Using Webix Jet Micro-Framework


Beginner

Building App Architecture

Basic principles

Before using library components you need to draw the scheme of their arrangement and define the way they would be positioned towards each other. It can be done with the help of four interface-building components, namely:

  • Layout
  • Multiview
  • Accordion
  • Scrollview
  • Carousel

All the interface-building components inherit from view, a base class or, simply put, a container where you ought to place the component before working with it.

Layout allows dividing a page into rows and columns to organize sections to put other components. All of them will be visible within the same page at the same time.

Similar functionality you can find with a form and toolbar components that house controls (input fields, checkboxes, buttons, etc.) organized under the same pattern as layout (rows and cols). See Controls Guide to learn the variety of controls offered by this lib.

Mutliview, carousel, accordion and scrollview allow presenting different views in one and the same area when you are short of space. They differ in the ways of switching between these views:

  • for multiview cells you need a dedicated button to switch between them;
  • accordion items are expanded and collapsed on clicking their headers;
  • scrollview allows scrolling through the whole content it houses;
  • carousel panes change in turn by clicking on them or swiping (on touch devices).

All layout types are initialized within the webix.ui constructor and can be nested into each other:

webix.ui({
    view:"layout", rows:[
     {...}, //any component
     {...}
    ]
});

Layout

If you just divide the page into rows or columns (cols) - you'll get standard layout to display the components side by side.

webix.ui({
    rows:[
     {...}, //any component
     {cols:[
        {...},
        {...}
    ]
});

More about Layout.

Form

Form helps divide the page into rows and cols to create a layout for controls. Unlike layout, this component should be initialized directly, using the view name.

webix.ui({
    view:"form",
    elements:[
     {...}, //any control
     {cols:[
        {...},
        {...}
    ]
});

If form controls are placed into the elements array - they will be arranged in rows.

More about Form

Accordion

Accordion consists of items each of which takes a separate row or column with a header and can be collapsed and expanded.

webix.ui({
    view:"accordion", rows:[
        {view:"accordionitem", header:"Item1", body:{ ...}},
        {header:"Item2", body:{...}}
    ]  //two ways of accordion item initialization are equal
});

If you place an array of objects with body and header into layout row/column - you'll automatically get accordion with accordion items without direct initialization.

webix.ui({
    rows:[
        {header:"Item1", body:{ ...}},
        {header:"Item2", body:{...}}
    ]
});

More about Accordion.

Scrollview

Scrollview is standard layout with a scrollbar. It can house any HTML content, any layout or component in its body:

Scrollview

webix.ui({
    view:"scrollview",
    body:{
        rows:[{...}, {...}]
    },
    scroll:"y" //scrolling direction
});

More about Scrollview.

Carousel

Carousel rows and cols are shown in turn, one by one, on clicking dedicated buttons or swiping on touch devices:

Carousel

webix.ui({
    view:"carousel",
    cols:[
        {...},
        {...}
    ]
});

More about Carousel

Multiview

Multiview is a layout with multiple hidden views that are shown in turn with one view being always visible.

webix.ui({
    view:"multiview", //optional line
    cells:[
        {...},
        {...}
    ]
});

Note that for mutliview you should provide the logic for switching between views. It can be a tabbar or a segmented button.

If you just define cells you'll automatically get multiview, if you add tabs to cells within one and the same constructor - it will turn into tabview. In this case, a switching button is not needed as tabs perform this function.

webix.ui({
    view:"tabview", //optional line
    tabs:[
        {id:"1", ...},
        {id:"2", ...}
    ],
    cells:[
        {id:"1", ...},
        {id:"2", ...}
    ]
});

More about Multiview and Tabview.

Isolating IDs inside Layouts

Basic rules of ID assignement can are described here.

The features is true to all the layout types described above. It allows for using the same IDs for components lying in different layout sections while preserving the ability to access the needed component without ambiguity.

Layout section should be equipped with an isolate property:

webix.ui({
   cols:[
     { id:"col1", isolate:true, rows:[
        { view:"list", id:"mylist" },
     ]},
     { id:"col2", isolate:true, rows:[
        {view:"list", id:"mylist" },
     ]}
   ]
});

The list view is used twice in the "app" but in different layout columns with isolate functionality switched on.

To address such lists separately, use yhe ID of its parent layout section:

var list1 = $$("col1").$$("mylist");
var list2 = $$("col2").$$("mylist");

//Otherwise, you'll get the last view
var list2 = $$("mylist");

What's Next

  • To learn how to set various border types or create a borderless design, consult the dedicated article.
  • To learn how to set headers for components in layout rows, cols, multiview cells, etc, study the corresponding article.
  • Layouts can be sized according to common rules described in the Sizing Components article.
  • Layouts can respond to changes of window size. Learn how to tune responsive behaviour.


View

View is a base class for all the ui-related components. It's a place where you put them before working. A pure view doesn't contain any information yet it may come with borders.

View performs a function of a placeholder to the layout components and layout itself. All of them are initialized according to the following scheme:

webix.ui({
    view:"dataview",
    ...
});

View ID

Views themselves can be put into other views thus creating a complex app structure with parent and child components. Any view features its unique ID that differentiates it from other views in the application:

Default ID

var layout = webix.ui({
    rows:[
        {view:"list", ...}, //gets "$list1" ID
        {view:"list", ...} //gets "$list2" ID
    ]
});

Then, you can get the objects of these views as:

//getting list 1 object
var list1 = layout.getChildViews()[0];
..or
var list1 = $$("$list1");

//getting list 2 object
var list2 = layout.getChildViews()[1];
..or
var list2 = $$("$list2");

Still, it's much more convenient to define custom "speaking" IDs to the views.

Custom ID

webix.ui({
    id:"lists",
    rows:[
        {view:"list", id:"order-list"},
        {view:"list", id:"data-list"}
    ]
});

Then, you can get the objects of these views as:

//getting list 1 object
var list1 = $$("lists").getChildViews()[0];
..or
var list1 = $$("$order-list");

//getting list 2 object
var list 2 = $$("lists").getChildViews()[1];
..or
var list2 = $$("$data-list");

Working within several views you can refer to the components with respect to their hierarchy or by using the view's unique ID.

Note that:

  • Using auto-generated IDs is unsafe as they may change dynamically;
  • The ID of any component can be found in its object as view.config.id;
  • View IDs are reflected in HTML as a view_id attribute of a topmost div of a component;

Empty View

Views can as well be empty. An empty view is two braces {} you put between meaningful components to leave space between them.

Spacer between buttons on toolbar

webix.ui({
    view:"toolbar", cols:[
        {view:"button", value:"but1" },
        {},
        {view:"button", value:"but2"}
    ]
})

Views in HTML

Views can be placed into HTML containers and take the dimensions of these containers (if any)

//body section
<div id="mylayout" style="width:600px;height:400px;"></div>

//script section
webix.ui({
    view:"layout",
    container:"mylayout",
    rows:[...]
    ...
});

Basic View Methods

1 . getParentView() & getTopParentView()

The method is called from any view and is used to get the parent object of this view.

webix.ui({
    view:"layout", id:"my_layout", rows:[
        {view:"toolbar", id:"my_Bar", cols:[
            {view:"button", id:"my_button", ..}
        ]},
        {view:"template", ...}
     ]
});

var t = $$("my_button").getParentView(); //  returns toolbar object
var l = $$("my_button").getTopParentView(); //  returns layout object

2 . getFormView()

The method returns an object of a parent form for the control it is called for. It's especially useful in case of complex forms:

webix.ui({
    view:"form", id:"my_form", elements:[
        {view:"text"},
        {cols:[
            {view:"combo", id:"my_combo", ..}
        ]},
        {view:"checkbox", ...}
     ]
});

$$("my_combo").getFormView(); //returns "my_form" object

3 . getChildViews()

This method, on the contrary, returns, an array of all the children of the calling component. Array members are numbered starting from 0.

For instance, if you have a toolbar within the layout and the toolbar itself comes with three buttons, the function will return the following:

var bar_id = $$("my_layout").getChildViews()[0].config.id; //toolbar ID

var but_id = $$("my_toolbar").getChildViews()[1].config.id //ID of the 2nd button

4 . index()

Like the above mentioned one, this method works with views containing other views that are stored in an array ( the property may be called cols, rows, elements, options depending on the component).

Getting the view's index means getting its position in the array (zero-based numbering.) Method is called from the parent view and takes the ID of the necessary child view as parameter.

webix.ui({
    rows:[
        {id:"cell1", view:"list", ...},
        {id:"cell2", view:"form", ...},
        {id:"cell3", view:"dataview", ...}
    ]
});

$$("mylayout").index($$("cell1")); //-> returns 0 for the 1st array element

5 . getNode()

The method helps us get an HTML container of the component.

<div id="my_box"></div>
...
webix.ui({
    view:"toolbar", id:"my_bar", ...
});

var box = $$("my_bar").getNode;

6 . getInputNode()

The method works with form controls defined by input tag in HTML, the simplest being text. It returns DOM element related to the input with all its properties.

{view:"form", elements: [
    { view:"button", id:"b1", value:"Login", type:"form" },
    {...}
]}

$$("b1").getInputNode();//-> <input type="button" style="height:27px; width:149px" value="Login">

Dimensions here are library defaults for the button.

See the corresponding chapter of API Reference to learn about view's methods, parameters and events.


Responsive Layouts

Webix layout and accordion structures can respond to the changes of window size by hiding & showing or moving their rows (cols) depending on currently available space.

It occurs when:

  • Layout or accordion are initialized without an HTML container, and hence, feature no fixed sizing;
  • The size of any component in such layout/accordion is bigger than the space available for its rendering. Fixed sizing is the right way to achieve it. Read more on initial component sizing.

Responsive behavior features 2 modes:

  • Views are hidden and can be shown back;
  • Views are moved to another place in layout.

Initial Layout

Responsive Hiding

To enable view hiding and showing on window resizing, set responsive property of a layout/accordion to true.

webix.ui({
   view:"layout", //optional line
   responsive:true,
   cols:[
        {view:"list", ...},
        {view:"template", ...}
        {view:"datatable", ...}
    ]
});

Related sample: Responsive Layout - Hidden cells

When space is not enough the last view from the left is hidden first.

After Window Resizing

Responsive Moving

To enable component moving during window resizing, provide an ID of the target layout as a value of responsive attribute of a parent layout of the needed component:

webix.ui({
    id:"a1", rows:[
        { responsive:"a1", cols:[ //parent layout for template
             { view:"list", ...},
             { view:"template", ... }, //template will be moved to "a1" layout
             { view:"datatable", ... }
        ]}
    ]
});

When space is not enough middle and right views are more likely to be moved.

Related sample: Responsive Layout

After Window Resizing

If accordion items are placed into layout during resizing, they will behave like layout rows and cols.

For layouts and accordions that lie inside an HTML container the functionality can be switched on by calling resize() method after the container has been resized:

webix.event("divId", "resize", function(e){
    $$("layout").resize();
});


Intermediate

Structuring a Big Application

While building a big app interface, there are two options you can choose from:

  • using Webix Jet
  • creating custom code by following basic recommendations

Easy Apps Building with Webix Jet

There is a convenient and simple for understanding and developing micro-framework Webix Jet. It allows building very flexible and reliable complex web applications with little effort. To get the details on the use of the micro-framework, read the full guide on Webix Jet.

Basic recommendations on custom app construction

The rest of the article tells about logic-based app structuring and shows how to divide the application code into semantic blocks, which enhances its readability and simplifies editing of code, including the addition of some new functionality.

For better understanding, please study the following articles:

  • Start Coding with the Webix Library
  • Quick Start Guide, or How to Initialize a Component
  • Building App Architecture - Layout and its Types

Here everything is about logic, structure and optimized coding. The basic principles are:

  • store big code snippets in variables;
  • put apart application design and inner functionality.

For samples, please look through the demo applications provided with this library.

Construction Methods

The two main functions to construct the application are as follows:

  • webix.ui() - the object constructor that creates a new instance of the specified view. Must be used anyway.
  • webix.ready() - optional - a handler that is called just after the page has been completely parsed. The alternative to the onload() method and onDocumentReady event.

In short, it look like this:

webix.ready(function(){
    webix.ui({
        view:"list", ... //any component including "layout"
    });
});

Inside the webix.ui constructor you define the layout of your app, divide it into rows and columns and place UI component into it. Details here

Putting Apart Logic and Design

Design here means layout type (layout, multiview, accordion) as well as the UI components you've chosen for your application and the controls you insert into them.

Logic here means any functions you attach to the components and controls as well as those establishing links between components.

For a clear code it's recommended to store logic and design separately in variables (call them logic and ui_scheme), or in case of really big apps - in separate files.

Three-file application includes:

  • index.html file that contains:
    • standard HTML markup with head and body sections;
    • library scripts included into the document head;
    • webix.ready function with webix.ui constructor in the script part of the document body;
    • links to ui and logic javascript files (look below);
    • links to CSS files and those storing inline JSON and XML data;
  • app.js file that contains all the components included into the ui_scheme variable(any name can be used);
  • logic.js file with all the functions you need to build a fully interactive app. All of them are stored in the logic variable (again, the variable name is to your choice).

You can store the whole application in one and the same index file, but the division of the script into logic and design sections is a must. Just put components in the ui_scheme variable and functions into the logic variable.

webix.ready Function - "index.html" File Contents

HTML for such file looks like this:

<!DOCTYPE html>
  <head>
    <!--library files-->
    <link rel="stylesheet" href="../webix.css" type="text/css" media="screen" charset="utf-8">
    <script src="../webix.js" type="text/javascript" charset="utf-8"></script>

    <!--application files-->
    <script type="text/javascript" src='./logic.js'></script>
    <script type="text/javascript" src='./app.js'></script>

    <link rel="stylesheet" type="text/css" href="./styles.css">
  </head>

  <body>
    <script>
     ... place for your app
    </script>
  </body>
</html>

The app is placed into document body embraced by script tags. Everything lies within the webix.ready function:

webix.ready(function(){
    webix.ui(ui_scheme);
    logic.init(); //reference to logic section
 });
  • If there any dates in your app - define common formatting methods for them right now.
  • If you have components that are beyond the application layout (e.g. a popup window called on a button clicking) - put it into another webix.ui constructor right now.
webix.ready(function(){
    webix.ui(ui_scheme);
    webix.ui(ui_window);
    logic.init(); //reference to logic section
    webix.i18n.parseFormatDate = webix.Date.strToDate("%m/%d/%Y");
 });

Inside the webix.ui constructor layout as well as components are placed. Here, we've put a variable there, to be exact - the ui_scheme and ui_window variables that store these components.

Design Section - "app.js" File Contents

The variables from above are declared separately, outside the webix.ui constructor, either in the same file within the webix.ready function, or (better) in a separate app.js file.

They should also be as short as possible:

var ui_scheme = {
    rows:[grid, footer],
    maxWidth:800
};

Grid and footer and variables declared separately and placed into the two-row layout. This is rather a simple application.

It's recommended that components with options (tabbar, toolbar), forms, non-visible dataCollections should be included into the main app in the form of variables declared beforehand.

Any component or several connected components can be stored in the variable that is later on included into the main layout variable(here:ui_scheme) that is placed into the webix.ui constructor.

Logic Section - "logic.js" File Contents

Logic block is stored in a logic variable declared either in a separate logic.js file (better), or somewhere outside the webix.ui constructor but within the webix.ready function.

Logic block is divided into the functions called during component initialization and the definition of all the function used for the application.

The init() function includes:

  • all the events attached to the components (except for those attached to them within their bodies). See Event Handling for better understanding.
  • links between components - binding and syncing.
var logic = {
    init: function(){
        //ties between views
        $$("form1").bind($$("datatable1"));
        $$("datatable1").sync($$("list1"));

        //biult-in functions
        $$("list1").attachEvent("onAfterSelect", function(id){
            $$("datatable1").select(id);
        });

        //custom functions
        $$("datatable1").attachEvent("onItemClick", logic.delete_row);
    }
}

For custom functions attached either within component/control body or within init block (see above) use the following reference:

logic:function_name //since they are placed into the "logic" var

Outside the init block you should describe all the custom functions attached to application components either in the init block or within their bodies:

delete_row: function(){
    $$("datatable1").remove(id);
}

Other Possibilities

Sometimes the variable that stores main layout structure (ui_scheme ) is included into the init function of the logic block and the whole script in the index file contains just a line:

ui.html

logic.init();.

logic.js

var logic = {
    init:function(){
        webix.ui(ui_scheme);
        //some additional logic defined outside the init block (if needed)
        logic.init_filtering();
    }
}

It goes without saying that a long list of custom styles is taken out into a separate file that is included into an index file with a help of a link in its head section (together with library styles).

Images for the application as well as custom icons (except for built-in ones) are stored in a separate folder, as a rule, in the same directory as the index file or somewhere nearby.


Advanced

Initialization from Markup

Library components are JSON objects in essence. Each of them is constructed with a set of key:value pairs that describe its properties.

webix.ui({
    view:"toolbar",
    width: 300,
    elements:[
        {view:"button", value:"OK", inputWidth:100},
        {view:"button", value:"No", inputWidth:100}
        ]
});

The toolbar from above is made of three members (view, width, elements), the last one containing an array of two members (two buttons).

At the same time, components can be initialized not only by literal notation, but also within HTML and XML markup.

Bonuses of markup initialization

  • you needn't define template to enable data rendering).Still, you should use property names in hash signs;
  • datasource can be defined in frames of unordered lists or HTML tables.

License restrictions

  • XML initialization is available in Webix Pro edition only;
  • HTML initialization can be used with any Webix edition.

Initializing from Markup

XML and HTML markup initialization can totally replace JSON configuration for people who are more used to working with markup languages. It has simpler syntax so you are less likely to get lost among brackets and commas. Such functionality can be useful when you code the page with the help of server scripts since it's easier to get XML (HTML) data from them than JSON.

In general, the markup can be taken from:

  • any node of this document including body;
  • separate file with HTML or XML markup;
  • response of server script;

HTML and XML markup get peculiar tags to serve the needs of Webix object initializing (described later).

Webix HTMLform component is more likely to initialized from HTML and XML, yet any component is subject to this technique.

Working with Webix Markup Class

To init Webix components from HTML or XML, you should work with webix.markup class that offers a pattern for markup processing.

The main methods here are init(node, target) and parse(node) where arguments mean:

  • node - which data to use for initialization. By default data is taken from document.body.
  • target - where should the newly created component be placed. By default it's placed into the HTML node defines by node (document.body, if it's not defined as well).

Initializing and parsing serve different purposes:

  • The init() method inits Webix object in HTML layout.
  • The parse() method inits the component in Webix layout.

The simplest initialization script looks as follows:

// data is taken from document body and component is initialized there
webix.ready(function(){
    webix.markup.init();
});

External-file or serverside data is loaded to the page by Ajax. Here you should specify path to the file(script) and set initialization pattern in a callback.

In the code below, data comes from external XML file, the node is incoming data while the target is body of the current document.

webix.ajax("data/config.xml?!", function(text, data){
    var config = webix.markup.parse(text, "xml");
    webix.ui(config);
});

Related sample: Load UI by ajax

You can use markup initialization by parsing markup to the neccessary part of the Webix script thus creating a Webix object.

webix.ui({
    rows:[ {}, {id:"placeholder", template:"html->dummy" }
    ]
});

function load_grid() {
    webix.ajax("data/gridconfig.xml", function(text, data){
        webix.ui(
            webix.markup.parse(text, "xml"), //source
            $$("placeholder")) //target
    })
};

Target is not defined within the parse() function yet it is specified in the webix.ui() constructor as $$('placeholder').

Markup Peculiarities

The rules of HTML and XML initialization differ, so you should consult dedicated articles to learn them.

  • Initialization from HTML;
  • Initialization from XML - available Webix Pro edition only.

Related Articles
  • HTMLform


Initialization from HTML Markup

See also general rules of markup initialization that are described in separate article.

Initialization from HTML is a nice feature for those who work in HTML mainly. By the way, a similar technology is used within JQuery Mobile framework.

Basic principles

1. DIV blocks as components

The page is divided into div blocks that house Webix components defined by their data-view attribute:

  • data-view="component_name" to initialize most of Webix components;
  • data-view="cols" or data-view="rows" to initialize Webix layout;
<div data-view="rows"> <!--layout-->
    <div data-view="template" data-height="35"> My header</div> <!--template-->
</div>

2. "Data" attributes as component properties

DIV "data" attributes set other properties of the component:

<div data-view="text" data-name="email" data-label="Email"></div>

In other words, you use the same properties as in JSON configuration, but prefix them with "data-".

Pay attention that while parsing from HTML, camelCase attributes must be replaced with dashed ones: "minWidth" => "data-min-width":

<div data-view="list" data-width="320" data-max-width="500" data-min-width="100">
    #id#: #value#
    <ul data-view="data">
        <li id="9998">Item 1</li>
        <li id="9999" class='myitem'>Item 2</li>
    </ul>
</div>

3. Inner HTML matters

Inner HTML of a DIV block defines visible text:

  • text of a button, template, text, textarea, etc.:
<div data-view="button" data-width="150">Button</div>
<div data-view="text" data-label="Phone">123456789</div>
<div data-view="template" data-height="35"> My header</div>
  • text of a window head:
<div data-view="window" data-id="win1">
    <div data-view="head">Test header</div>
    ...
</div>

Related sample: HTML initialization : Window

  • data template for data management components:
<div data-view="list" data-url="data/data.json" data-select="true">
    Package: #Package# (#Version#)
</div>

Related sample: HTML initialization

4. Specific tags and attributes

  • data-stack - defines array or sub items such as rows or cols for layout and the like, and headerlayout (accordion) components:
<div data-view="layout" data-stack="cols">
    <div data-view="template">Cell 1.1</div>
    <div data-view="template">Cell 1.2</div>
</div>

Related sample: HTML initialization : Nested layouts

<div data-view="headerlayout" data-stack="cols">
    <div data-view="body" data-header="Section A">
        <div data-view="list" data-url="data/data.json"> #id#: #Package# </div>
    </div>
    <div data-view="body" data-header="Section B">
        <div data-view="list" data-url="data/data.json"> #id#: #Package# </div>
    </div>
</div>

Related sample: HTML initialization : Accordion

By default, the sub items will be treated as rows for layouts and form and cols for toolbar.

<div data-view="toolbar"> <!--data-stack="cols"-->
    <div data-view="button" data-width="150">Button</div>
    <div data-view="label" data-label="Press the button to run App"></div>
</div>

Related sample: HTML initialization

  • config - defines configuration for a complex property that contains several settings in itself:
<div data-view="list">
  <config name="type" height="50" width="200"></config>
    #id#: #value#
  <ul data-view="data">
    <li id="9998">Item 1</li>
    <li id="9999" class='myitem'>Item 2</li>
  </ul>
</div>

5. Standard HTML

Standard HTML is used for:

  • form and its elements:
<form>
    <input type="text" name="title" value="" placeholder="Book title" /><br/>
    <textarea name="annotation" id="annotation" rows="4">some book annotation is here</textarea><br/>
</form>

Such code can be easily turned into Webix Htmlform component:

<form data-view="htmlform" data-id="formView">..

Related sample: HTML initialization : HTML form

  • inline data within data presenting components:
<div data-view="list" data-width="320">
    #id#: #value#
    <ul data-view="data">
        <li id="9998">Item 1</li>
        <li id="9999" class='myitem'>Item 2</li>
    </ul>
</div>

Note that inline datasource is marked by data-view attribute with data value.

Related sample: HTML initialization

Datatable

Datatable and treetable columns are built from child DIVs of the main component container:

<div data-view="datatable" data-autoheight="true" data-width="400">
    <div data-view="column" data-width="150" data-id="firstname">
        First Name
    </div>
    <div data-view="column" data-width="150" data-id="lastname">
        Last Name
    </div>
    ...
</div>
  • "data" attributes are used to set column properties;
  • inner HTML of column DIVs is turned into their headers.

Related sample: HTML initialization : DataTable

Pager

When initialized from markup Webix pager should be placed into a separate DIV block while the master component should refer to it by its ID:

<div data-view="datatable" data-pager="mypager">
...
</div>
<div data-view="pager" data-id="mypager" group="10" size="3"></div>

Note that pager properties are not prefixed with "data-".

Related sample: HTML initialization : DataTable with Pager

Tabview and Accordion

Webix tabview and accordion are made of separate blocks, each of which featuring header with title and body with content inside.

In markup you need to place each block into a separate DIV with the attributes:

  • data-view with "body" value;
  • data-header with header text.

Tabview

<div data-view="tabview">
    <div data-view="body" data-header="List 1">
        <div data-view="list" data-url="data/data.json"> #id#: #Package# </div>
    </div>
    <div data-view="body" data-header="Text 2">
        <div data-view="template">Just some text here</div>
    </div>
</div>

Related sample: HTML initialization : Tabbar

Accordion

<div data-view="accordion">
    <div data-view="body" data-header="Section A">
        <div data-view="list" data-width="320" data-url="data/data.json"> #id#: #Package# </div>
    </div>
    <div data-view="body" data-header="Section B">
        <div data-view="list" data-width="320" data-url="data/data.json"> #id#: #Package# </div>
    </div>
</div>

Related sample: HTML initialization : Accordion

Chart

Chart axes are defined by config tags in HTML markup:

<div data-view="chart" data-type="stackedArea" data-color="#58dccd" data-value="#sales#"
  data-alpha="0.7" data-url="data/chart.json">
    <config name="xAxis" template="#year#"></config>
    <config name="yAxis"></config>
</div>

Axis names are defined by name attributes while other attributes are not prefixed by "data-" and are the same as in JSON configuration.

chart Series

If series are needed for the chart they are initialized via a separate config object:

<div data-view="chart" data-type="stackedArea" alpha="0.7" eventRadius="5" data-url="data/chart.json">
    <config name="xAxis" template="#year#"></config>
    <config name="yAxis"></config>
    <config stack='series'>
        <config  value="#sales#" color="#58dccd">
            <config name="tooltip" template="#bottom#"></config>
        </config>
        <config  value="#sales2#" color="#dc58cd">
            <config name="tooltip" template="#bottom#"></config>
        </config>
        ...
    </config>
</div>

The attributes of series are not prefixed by "data-" and are the same as in JSON configuration.

Related sample: HTML initialization

Windows and Menus

Window peculiarities

When initializing Webix window from markup, you need to remember the following things:

  • window should be set on the same level as other layout components;
  • window is comprised of two parts - head and body that should be defined via separate DIV blocks.
<div data-view="rows">
    <!--layout config>-->
</div>
...
<div data-view="window" data-id="win1">
    <div data-view="head">Test header</div>
    <div data-view="body">
        <div data-view="template">Cell 1.2</div>
    </div>
</div>
  • in addition, window show method should be called as it won't appear by itself:
webix.markup.init();
$$("win1").show();

Related sample: HTML initialization : Window

Menu and submenu peculiarities

If menu is initialized from markup it's vital to remember that its submenus should be as well initialized the same way as windows:

<div data-view="submenu" data-id="submenu1">
    <ul data-view="data">
       <li data-id="1.1" data-submenu="submenu3">Item 1.1</li>
       <li data-id="1.2">Item 1.2</li>
    </ul>
</div>

And then they should be included into the main menu (or other submenus) with the help of their submenu property (submenu ID should be specified):

<div data-view="menu" data-height="50">
    <ul data-view="data">
        <div data-view="menu">
            <ul data-view="data">
                <li data-id="1" data-submenu="submenu1">Item 1</li>
                <li data-id="2" data-submenu="submenu2">Item 2</li>
            </ul>
        </div>
        <li data-id="3">Item 3</li>
    </ul>
</div>

Any level of nesting is possible.

Related sample: HTML initialization::Menu


Available only in PRO Edition

Initialization from XML Markup

See also general rules of markup initialization that are described in a separate article.

Initialization from XML is simpler in terms of syntax while at the same time tags feature greater semantic value than HTML, yet XML is not that popular due to its "strict" nature.

To intergrate this functionality with IE8, set the initial page tag as < html xmlns:x > instead of < html >.

Below the peculiarities of initialization for different Webix components are listed.

Layout with different components

XML Toolbar, List and Form

<x:ui>
        <x:rows>
            <x:template>My header</x:template>
            <x:toolbar>
                <x:button width="150">Button</x:button>
                <x:label>Press the button to run App</x:label>
            </x:toolbar>
            <x:cols>
                <x:list url="data/data.json" select="true">
                    <x:template>Package: #Package# (#Version#)</x:template>
                </x:list>
                <x:htmlform>
                    <input type="submit" />
                </x:htmlform>
                <x:list width="320">
                    <x:template>#id#: #value#</x:template>
                   <x:data>
                        <li id="9998">Item 1</li>
                        <li>Item 2</li>
                   </x:data>
                </x:list>
            </x:cols>
            <x:template>My footer</x:template>
        </x:rows>
    </x:ui>

Related sample: XML initialization

Comments:

  • semantially rich tags coincide with component names. The pattern such for tags is as follows: < x:name >;
  • x: namespace for tags that form Webix component including Webix ui constructor(< x:ui >);
  • component properties come as tag attributes;
  • standard HTML tags perform their function in the way they do it in HTML (< li >);
  • Form in layout comes in standard HTML tags while form not placed in layout requires specific tags as well (see later).

Accordion

Accordion features an array of accordionitems, each of which has a header and body where any Webix component can be placed.

JS initialization

{
    view:"accordion", rows:[
        {header:"Section A", body:{view:"list", url:"data/data.json", template:"#id#: #Package#"} },
        {...}
    ]

}

XML initialization

Remember that anything you init from XML, should be among < x:ui > tags!

<x:accordion>
    <x:body header="Section A">
        <x:list width="320" url="data/data.json"> #id#: #Package# </x:list>
    </x:body>
</x:accordion>

Or:

<x:headerlayout stack="cols">
    <x:body header="Section A">
        <x:list url="data/data.json"> #id#: #Package# </x:list>
    </x:body>
</x:headerlayout>

Related sample: XML initialization : Accordion Related sample: HTML initialization : Accordion

Datatable

Datatable features an array of columns each of which has a set of congiguration options:

JS Initialization

{
    view:"datatable",
    autowidth:true, autoheight:true,
    columns:[
        {id:"rank", header:"", width:250, sort:"int"},
        {id:"title", header:"Film title", width:200, sort:"string"}
    ]
}

XML Initialization

<x:datatable autowidth="true" autoheight="true">
        <x:column id="rank"  header=""           width="50"  sort="int"></x:column>
        <x:column id="title" header="Film title" width="200" sort="string"></x:column>
</x:datatable>

Related sample: XML initialization : DataTable

Form

If placed in layout rows or cols, form can be initialized with standard HTML tags. Standalone form not placed in layout requires tags with x: prefix.

<x:form id="log_form" width="300">
    <x:text label="Email"></x:text>
    <x:button value="Login" type="form"></x:button>
</x:form>

Related sample: XML initialization : Fieldset

HTMLform has its own initializing patterns including via webix markup class.

Tabview

Tabview is a hybrid layout that features several view cells and dedicated tabs to switch between these cells.

JS initialization

Tabs and cells are connected by their IDs that must coincide.

{
 view:"tabview",
 tabs:[
    { value: 'List 1', id: '1'},
    { value: 'Text 2', id: '2'}],
 cells:[
    { view: 'list', id: '1', url:"ata/data.json", template:"#id#: #Package#"}
    { view: 'template', id: '2', template:"Just some text here"}]
}

XML Initialization

During XML init you needn't define IDs - just place necessary conponents within body tags that substitute cells. At the same time, header attrbute of this tag defined text value for a tab.

<x:tabview>
    <x:body header="List 1">
        <x:list url="data/data.json"> #id#: #Package# </x:list>
    </x:body>
    <x:body header="Text 2">
        <x:template>Just some text here</x:template>
    </x:body>
</x:tabview>

Related sample: XML initialization : Tabbar

Altering Namespace

You can change the default x: namespace as well as completely get rid of it. You need to define the new namespace before initialization from markup:

webix.markup.namespace = ""; //empty namespace
webix.markup.namespace = "wx"; //new namespace

webix.markup.init();

From now on, you can use initialize Webix components using standard tags, or tag with your custom namespace:

Empty Namespace

<ui>
    <form id="log_form" width="300">
        <text label="Email"></text>
    </form>
</ui>

Related sample: XML init : empty namespace

Custom Namespace

<wx:ui>
    <wx:form id="log_form" width="300">
        <wx:text label="Email"></wx:text>
    </wx:form>
</wx:ui>

Related sample: XML init : custom namespace


Using Webix Jet Micro-Framework

Webix Jet is a client-side JavaScript micro-framework that considerably simplifies the process of creating applications with complex structure based on the Webix library.

The framework allows avoiding big repetitive parts of code, as an application is divided into independent modules which are developed separately. Webix Jet helps you to implement a wide variety of features within your app. It's possible to add navigation, multiple locales, diverse customizable skins, organize work with big datasets, etc.

The division of code into modules enhances the security and reliability of an application. Thus, you use compact code to build a safe and feature-rich web application.

You can find the detailed tutorial on the usage of Webix Jet on GitBook. In the tutorial the process of creating an application is described together with all the possibilities of the framework:

  • The Basics chapter introduces you to the general principles of building apps with the framework. Here you will also find the basics of creating views and subviews;
  • The Data Loading chapter goes into details of loading data into views: tells you about creation of models, describes work with the server-side and shows the peculiarities of asynchronous data loading;
  • The Advanced Views Handling chapter helps you to extend your knowledge of views and gain experience of a more advanced manipulation with views. You will learn about the usage of handlers and the scope. Besides, you'll find there the description of possible variants to connect separate views;
  • The Navigation chapter dwells on the ways of implementing navigation in the application. You will learn how to organize inner navigation in the app, use the menu plugin and restore the application's state to make navigation smart;
  • The Helper Modules chapter tells you about the helpers that can be used to implement such useful features as access control, CRUD functionality, data status and multi-language support in your app;
  • The Development Notes chapter gives you helpful tips on building an application, discusses how the structure of URL is formed and describes the ways of creating unique IDs for components and elements.


Webix in Touch Environment

Webix works equally well on desktop and touch devices out of box.

Touch support is enabled in all the Webix components with the touch events being translated into native Webix ones to ensure their flawless work. For instance, when you tap a list item, the onItemClick event fires for it. If selection is enabled for this list, list item is selected.

In addition there are global touch events that are not component-specific and fire for Webix application as a whole. All of them are described in detail in API Reference section.

Working with Webix Touch Module

Touch events are controlled by Webix Touch module where configuration for different aspects of touch behavior such as touch speed, touch and scroll delay can be changed.

Also the module allows for disabling Webix touch events in favour of native ones in either of the two ways:

  • total disabling of Webix touch support - neither global events nor component-specific events fire;
  • limiting Webix touch support - only in-component events work, global ones are disabled.

Related Articles
  • Adjusting Mobile Apps to Screen Size


Loading and Storing Data

  • Data Loading
  • Defining Data Scheme
  • Server-side Integration
  • Data Binding and Syncing
  • Data Updating


Beginner

Data Loading

After a data component has been initialized, you need to populate it with data in any of supported formats: JSON, XML, CSV, JSArray, HTMLtable.

There we have two major possibilities that are true for all the data components.

  • Loading from External Resource - File or Database
  • Parsing from String

After data has been pushed to component (loaded or parsed) it should be rendered within the component with the help of Webix templates.

Loading from External Resource

To load data from an external file or database, you should specify the path to this file/or serverside script that fetches data:

1 . As value of the component url property. Data will be loaded right after component initialization. Type of incoming data should be specified (if it's not JSON) as well.

{
    view:"list"
    url:"data.xml"
    datatype:"xml"
}

2 . As a parameter to the load() function you apply to the component on the necessary event.

$$("mylist").load("data.xml");

Load function has three parameters:

  • path to the necessary file or script;
  • datatype - in case of JSON data this param can be omitted;
  • callback function if needed.
$$('component_id').load(".../data.xml", "xml", function(){
  //callback function
});

Related sample: Form: Loading

It can be called on the necessary page event (button clicking, etc.) as well as on component inner event.

As soon as the component is parsed:

webix.ui({
view:"list",
ready:function(){
    this.load("data/books2.xml","xml");
    this.select(this.getFirstId());
    }
});

Loading via Proxy Objects

At the same time, you can set rather a complicated loading pattern in a proxy object you pass into the url property or load() function.

Webix features predefined proxy objects for offline support, connector usage, etc. To learn more about proxy functionality, consult the dedicated article.

view:"list"
url:{
    $proxy:true,
    load: function(self){
        self.load(a.json);
    },
     save:function(){
     ...
    }
}

Furthermore, if a serverside dataset is too big, dynamic loading allows to load limited quantity of data items first and then load new data only as you scroll or page through the component.

Note that there's a separate article dedicated to Serverside Integration. There you'll also find customization patterns for loading from server.

Setting an Alternative Datasource for a Bound Component

With bound components you can enable data loading not from master component (as expected by default), but directly from server.

{
    view:"list"
    url:"data/list.php" //the default datasource
},
{
    view:"form",
    id:"form11",
    ...
    dataFeed: "data/form.php" //datasource for the form only
}

// form takes data from selected record in list
$$('form1').bind($$('list1'));

More on Data Binding

Loading Messages

Webix provides info boxes that are laid over the component for a while to display desired data, e.g.:

  • to inform users that data is being loaded (in case of big datasets);
  • to inform users that there's no data for this component.

Webix (datatable) features info message support out of the box in the form of overlay boxes with any text or html content:

dtable.showOverLay("Loading");
dtable.hideOverlay();

Related sample: Loading screen

More info on datatable loading screen support.

For other components there exists a possibility to define Overlay Boxes and Progress Bar (Progress Icon) with the help of the dedicated modules.

webix.extend($$("list1"), webix.OverlayBox); // on "this" pointer if the method is called within the component

webix.ui({
    view:"list",
    id:"list1",
    url:"...",
    ready:function(){
        if (!this.count()){ //if no data is available
            webix.extend(this, webix.OverlayBox);
            this.showOverlay("<div style='...'>There is no data</div>");
        }
    }
});

Related sample: Empty list

More info on overlay boxes and progress bar

Data Loading Events

Webix offers the following events to control the beginning and the end of the loading process:

  • onBeforeLoad - fires just the moment XML data loading begins;
  • onAfterLoad - fires when XML data loading is complete;
  • onStoreLoad - fires when raw external data is fully loaded (regardless of data type).
mygrid.attachEvent("onAfterLoad", function(){
    webix.message("Data loaded");
})

Related sample: Loading screen

In case something goes wrong with loading (and sometimes it does!) learn how to handle errors on the client side in the Processing loading errors article.

Parsing

Here the data in supported formats comes as it is (string or array).

Firstly, it may be the value of data parameter.

JSON array within the Dataview object

webix.ui({
    view:"dataview",
    template:"#title# Year: #year#, rank: #rank#",
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, rank:1},
        { id:2, title:"The Godfather", year:1972,  rank:2},
        { id:3, title:"The Godfather: Part II", year:1974, rank:3}
    ]
});

JSON object is stored in a variable declared beforehand

var tabledata=[
    { id:1, title:"The Shawshank Redemption", year:1994, rank:1},
    { id:2, title:"The Godfather", year:1972,  rank:2},
    { id:3, title:"The Godfather: Part II", year:1974, rank:3},
    { id:3, title:"The Godfather: Part II", year:1974, rank:3}
];

webix.ui({
    view:"dataview",
    template:"#title# Year: #year#, rank: #rank#",
    data: tabledata
});

The variable may be declared either in the same file or in an external js-file you refer to in the document's head.

Secondly, data can be parsed with the help of parse(); method that takes data and datatype as parameters.

Data Parsing from XML string

webix.ui({
    view:"dataview",
    id:"dataview",
    datatype:"xml"
});

 //function is executed on pre-defined event, e.g. on button click

function parse(){
   var str = "<data>
      <item id='10'><title>The Lord of the Rings</title>
      <year>2003</year><rank>10</rank></item>
      </data>";
   $$("dataview").clearAll();
   $$("dataview").parse(str,"xml");
}

Related sample: Dataview: XML Dataset

If you want to parse data in addition to the existing dataset, specify position of parsing, namely the index from which you insert new data:

$$("datatable").parse({
      pos: $$("datatable").count(), //number of records will be right the last index +1
      data:dataset
  });

Data Parsing Events
  • onParse - fires when a component has received inline data and is ready for usage:
dtable.attachEvent("data->onParse", function(driver, data){
    //for json data
    webix.message("Count of records "+data.length);
});

Since the event is triggered for the component DataStore, the handler should be prefixed by "data->".

Promise API in Data Loading

Webix is integrated with Promiz.js library to treat the result of asynchronous operations (like data loading) without callbacks.

It means that any Ajax request returns a promise object than can be treated with Promiz.js API.

"Promise" objects is returned by either of these methods

var promise = grid.load("my.php");
var promise = webix.ajax("my.php");
var promise = webix.ajax().get("my.php");
var promise = webix.ajax().post("my.php");

Bonuses

1 .You may forget about callbacks and process the result of a request in Promiz.js way:

promise.then(function(realdata){
    //success
}).fail(function(err){
    //error
});

2 .You can "parse" promise objects directly into the component:

list.parse( webix.ajax("my.php"));

The data will be parsed the moment it comes from server.

3 . You can make use of waitData property each data component is supplied with and apply Promiz.js methods to it:

//"promise" approach
grid.waitData.then(function(){
    //when we have data - do some actions
});

Alternatively, Webix onAfterLoad event can be used:

//standard approach
grid.attachEvent("onAfterLoad", function(){
    //when we have data - do some actions
});

More about Webix and Promiz.js integration.


Beginner

Supported Data Types

The majority of data-presenting components take data in XML, JSON, JSArray and CSV formats. Still, three of them, namely grouplist, treetable and Tree support only XML and JSON datatypes since only they can show hierachy which is a key feature of these components.

  • Data sources and loading methods are described in Data Loading section.
  • Data Drivers that with processing lofic for each format are descriped in Data Drivers;
  • Customization of Data Types by changing default Driver behavior - Customizing Data Types.

All in all, Webix supports the following data types:

  • json - default
  • xml
  • jsarray - plain JS array
  • html - parsing data from HTML markup
  • csv - comma separated values
  • excel - custom data type for parsing Excel files
webix.ui({
    rows:[
        { view:"list", data:json_data },
        { view:"datatable", columns:[...], datatype:"xml", data:xml_data }
    ]
});

Data Type Samples

Here we'll see how one and the same dataset looks in different formats while paying attention to non-hierarchical and hierarchical data.

Non-hierarchical data

Person | Place | Age
Nanny | Alabama | 45
Derek | New York | 23
Samuel | Oregon | 32

XML

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <item id="1" person="Nanny" place="Alabama" age="45"/>
    <item id="2" person="Derek" place="New York" age="23"/>
    <item id="3" person="Samuel" place="Oregon" age="32"/>
</data>

JSON Object

[
    { "id":"1", "person": "Nanny", "place": "Alabama", "age": "45" },
    { "id":"2", "person": "Derek", "place": "New York","age": "23" },
    { "id":"3", "person": "Samuel", "place": "Oregon", "age": "32"}
]

JSArray

[
    [ "Nanny", "Alabama", "45" ],
    [ "Derek", "New-York", "23"],
    [ "Samuel", "Oregon", "32"]
]

CSV

CSV, or Comma Separated Values, is a sequence of characters with rows and fields being separated by some breaks (comma, tab, new line).

Nanny, Alabama, 45
Derek, New-York, 23
Samuel, Oregon, 32

By default line anf field delimiters are "\n"(new line) and ","(comma) respectively.

To change the logic of CSV parsing for the application components, look up the related article.

Excel

Excel datatype presents a set of parsing rules for Excel files loaded as binary data:

{ view:"list", url:"binary->files/data.xlsx", datatype:"excel"}

Excel data will be parsed into a simple JS array (as with "jsarray" datatype).

[
    [ "Nanny", "Alabama", "45" ],
    [ "Derek", "New-York", "23"],
    [ "Samuel", "Oregon", "32"]
]

Check Excelviewer documentation for details.

Hierarchical Data

XML

By default records of any hierarchy level and their children are introduced with item tags:

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <item value="animals" open="1">
        <item value="Fish">
            <item value="Marine">
                <item>Halibut</item>
            </item>
            <item value="Fresh Water">
                <item>Rainbow Trout</item>
            <item/>
        </item>
        <item value='Mammals'>
            <item value="Domestic">
                <item>Cow</item>
            </item>
            <item value="Wild">
                <item>Wolf</item>
            </item>
        </item>
    </item>
</data>

Related sample: Tree: XML Dataset

JSON

By default child records are stored in the data object property of the parent record.

[{"id":"1", "title":"Animals", data:[
    {"id":"1.1", "title":"Fish", data:[
        {"id":"1.1.1", "title":"Fresh Water", "name":"Halibut"},
        {"id":"1.1.2", "title":"Marine", "name":"Rainbow Trout"}
        ]
    },
    {"id":"1.2", "title":"Mammals", data:[
        {"id":"1.2.1", "title":"Domestic", "name":"Cow"},
        {"id":"1.2.2", "title":"Wild", "name":"Wolf"}
        ]
    }
    ]
}]

Related sample: Tree: JSON Dataset

Custom Tags for XML and JSON Data


Advanced

Customizing Data Types

By default JSON children are stored in the data property object while XML records (both parents and children) are introduced by an item tag. However, any custom tags will do provided that you create a custom data format based on a prebuilt one.

Parsing logic for each of the supported data types is stored in the webix.DataDriver object (webix.DataDriver.json, webix.DataDriver, xml, etc.). There you can change default tags in two ways:

  • change the logic of the existing data driver - desrcibed here. All incoming data of the state type will be processed according to the new logic.
  • copy the existing driver object and create a custom one on the base of it. The new processing logic will be applied only to data with the new data format you specify as datatype. Described below.

Custom Tags for JSON

Default JSON data with 2 nesting levels

[
    { id:"1", open:true, value:"The Shawshank Redemption", data:[
        { id:"1.1", value:"Part 1" data:[
            {id:"1.1.1", value:"Page 1"},
            {id:"1.1.2", value:"Page 2"}
        ]},
        { id:"1.2", value:"Part 2" }
    ]},
    { id:"2", value:"The Godfather", data:[
        { id:"2.1", value:"Part 1" }
    ]}
]

Declaring the new format:

var myjson = webix.DataDriver.myjson = webix.copy(webix.DataDriver.json);

Changing tags:

Elements of the first nesting level will be stored in parts, while the second-level ones will be stored in pages.

myjson.child=function(obj){
                if (obj.$level == 1)
                    return obj.parts;
                if (obj.$level == 2)
                    return obj.pages;
            };
//or, if you need the same property for all children
myjson.child="parts";

New Dataset:

[
    { id:"1", open:true, value:"The Shawshank Redemption", parts:[
        { id:"1.1", value:"Part 1" pages:[
            {id:"1.1.1", value:"Page 1"},
            {id:"1.1.2", value:"Page 2"}
        ]},
        { id:"1.2", value:"Part 2" }
    ]},
    { id:"2", value:"The Godfather", parts:[
        { id:"2.1", value:"Part 1" }
    ]}
]

Don't forget to specify the name of the new format as the datatype for your component!

webix.ui({
    view:"treetable",
    //..config
    datatype:"myjson"
});

Related sample: Tree: JSON Dataset

Custom Tags for XML

Default XML Data

<data>
    <item value='The Shawshank Redemption' open='1'>
        <item value='part1'></item>
            <item>Page 15</item>
            <item>Page 16</item>
        <item value='part2'></item>
    </item>
</data>

Declaring the new format:

var myxml = webix.DataDriver.myxml = webix.copy(webix.DataDriver.xml);

Changing tags:

myxml.records = "/*/book";

myxml.child = function(obj){
    if (obj.$level == 1)
        return obj.part;
    if (obj.$level == 2)
        return obj.page;
}
//or, if you need the same property for all children
myxml.child="part";

New Dataset:

<data>
    <book value='The Shawshank Redemption' open='1'>
        <part value='part1'>
            <page>Page 15</page>
            <page>Page 16</page>
        </part>
        <part value='part2'></part>
    </book>
</data>

Don't forget to specify the name of the new format as the datatype for your component!

webix.ui({
    view:"treetable",
    //..config
    datatype:"myxml"
});

Related sample: Tree: XML Dataset

Customizing CSV parsing logic

Global changes

The default parsing logic of CSV data can be changed globally:

webix.DataDriver.csv.cell = "\t";
webix.DataDriver.csv.row = "|";

Now, all the components that use "csv" datatype, will be parsed according to new rules.

Creating custom datatype

A custom datatype should be created in case you wish to apply it to one or several components while leaving the global CSV parsing unchanged.

webix.DataDriver.mycsv = webix.extend({
    row:"|",
    cell:"-"
}, webix.DataDriver.csv);

Now, you can use it in component instances:

var grid = webix.ui({
    view:"datatype",
    datatype:"mycsv",
    data:'1-The Shawshank Redemption|2-The Godfather'
});

//or for loading data in that format
$$('mylist').load("data.csv","mycsv");


Intermediate

Dynamic Loading

Dynamic loading means loading data on request, from the server. For example, a PHP script could supply data dynamically to a Webix component.

Dynamic loading is useful for long datasets since data populates the component in smaller portions. Initially data fills the view to some extent and later on it is dynamically loaded each time you scroll up and down the view or switch among pages.

For linear structures (used in the majority of Webix data components) you can control the process by specifying:

  • the item position to start loading with;
  • how many data items should be loaded each time the user scrolls/pages the element.

Read more at Dynamic Loading for Plain Structures.

For hierarchical structures like Tree and TreeTable you can specify:

  • the node ID for which you need to load child data.

Read more at Dynamic Loading for Hierarchical Data Structures.

Note that dynamic loading works only if the functionality is supported by the server.

Here's an example of dynamic loading using ServerSide Connectors.

Server Script "data_dyn.php"-file

<?php
  require_once("../../common/config.php");
  $data = new JSONDataConnector($conn, $dbtype);
  $data->dynamic_loading(30);  // the number of records loaded initially
  $data->render_table("packages_plain", "id", "package, size, architecture, section");
?>

Related Articles

  • Dynamic Loading for Plain Structures
  • Dynamic Loading for Hierarchical Data Structures


Dynamic Loading for Plain Structures

Data can be loaded to non-hierarchical components in portions:

  • Firstly, a limited number of records is loaded;
  • Then, data is loaded at the moment when:
    • user scrolls the component;
    • user switches to the new page within the component (in case pager is defined);
    • loadNext method is applied;

Currently dynamic loading for linear data is implemented for the following components: DataTable, Treetable and Dataview.

Configuring Dynamic Loading Behavior

To enable dynamic data loading you need to:

1 . Set the component datasource that will load initial data. It can be done either with the help of url property or load method;

var dview = webix.ui({
    view:"dataview",
    url:"data/data_dyn.php"
});
//or
dview.load("data/data_dyn.php");

2 . Optionally, define various aspects of dynamic loading such as:

  • datafetch - the number of records that should be loaded from server side during each dynamic loading request. 50 by default;
  • datathrottle - time in milliseconds between subsequent dynamic loading calls, which helps to minimize the quantity of requests during quick paging or scrolling;
  • loadahead - the number of records that should be loaded ahead of the "datafetch" parameter.
webix.ui({
    view:"dataview",
    datafetch:50,
    datathrottle: 500,
    loadahead:100
});

Related Samples

  • Related sample: Setting the Number of Items to Load
  • Related sample: Setting Polling Interval for Loading
  • Related sample: Dynamic loading. Load Ahead

Serverside Request

When scolling or pagination occurs, the component will automatically issue a request based on the datasourse, e.g. "data/data_dyn.php?continue=true&count=100&start=130" where:

  • continue - flag that indicates that this request was formed automatically;
  • count - value of datafetch parameter;
  • start - ID of the last data item in the data component before issuing a request.

Note that your server script should be able to handle these parameters.

Serverside Response

Serverside response should include the following information:

  • data - the array of data records;
  • pos - position in the data component to add the loaded data to (required during each dynamic loading call);
  • total_count - the total number of records available on the server (required only for initial loading call);

Sample of JSON response

{
    "data":[
        {"id":1,"package":"acx100-source"},
        {"id":1,"package":"acx200-source"}
    ],
    "pos":0,
    "total_count":999
}

Dynamic Loading by Api

The loadNext method can be used to send a request that loads the specified number of records and parses them into the component. The arguments are:

  • count - the number of records that will be loaded on function execution;
  • start - the start position to insert the loaded data to;
  • callback - function to be executed after the response comes ( or null if you don't need the one);
  • url - the loading url (if it wasn't specified in the component constructor);
  • now - boolean to ignore datathrottle and start loading data immediately on loadNext() execution.

Using url set in the component constructor

grida = webix.ui({
    view:"datatable",
    url:"data/data_dyn.php"
});
grida.loadNext(10, 0);

Related sample: Dynamic loading with removing the existing content

Using given url

gridb.loadNext(50,900,function(){
    this.showItem(903);
}, "data/data_dyn.php");

Related sample: Setting loading position

Use Cases

The method allows the following scenarios:

  • new data may be added to the end of current component data:
grida.loadNext(30, pos, function(){
    this.showItemByIndex(pos);
    pos += 30;
});

//pos - index of the last data item

Related sample: Dynamic loading with appending content

  • new data may substitute current component data (it should be cleared beforehand);
webix.ui({
    view:"datatable",
    "data->onParse":function(){
        this.clearAll();
        this.data.url = "data/data.php";
    }
});
grida.loadNext(10, base);

//base - index of the last data item

Related sample: Dynamic loading with removing the existing content

Dynamic Loading Events

You can capture the moment just before a dynamic loading request is sent to server with the help of an onDataRequest event.

It can be used to cancel the default behavior and issue a custom data request:

dtable.attachEvent("onDataRequest", function (start, count) {
  var data = custom_load_data(start, count);
  dtable.parse(data, "json");
  return false;
));

Related articles

  • Dynamic Loading for Tree and Treetable


Dynamic Loading for Hierarchical Data Structures

This article discusses dynamic loading for tree, treetable and TreeCollection. Refer to the main Dynamic Loading article if needed.

Data can be loaded dynamically into hierarchical components as follows:

  • First, the top parent nodes are loaded. Initially, they are collapsed (unless their open property is true).
  • Then, data is loaded under each node when it is expanded.
var tree = webix.ui({
  view: "tree",
  url: "data/data_dyn.php"
});
// or
var tree = webix.ui({});
tree.load("data/data_dyn.php");

By default, Webix expects JSON data. The server can also return XML - see Loading Tree Data.

Dynamic loading can be implemented in three different ways:

  • by setting the webix_kids property to true on nodes that are expected to have children
  • by calling the loadBranch() method
  • by setting a custom handler for the onDataRequest event

Using the webix_kids flag

On parent data items that can have children, you can set the webix_kids flag to true. When the user expands these nodes, Webix will automatically send XHR requests to the server for more data.

webix.ui({
  view: "tree",
  url: "data/data_dyn.php",
  data: [
    // parent node below
    { id: "1", value: "Branch", webix_kids: true }
  ]
});

Webix will automatically generate the request URL to dynamically load data, based on the url property specified when initializing the component - "data/data_dyn.php?continue=true&parent=1", where:

  • parent - ID of the node that has just been opened;
  • continue - flag indicating that it is an auto-generated request.

If url is specified, Webix will also make an initial request for that URL, without parameters. Make sure the server-side script can handle both situations: the initial loading of data (top-level parent nodes), and loading children under a given parent node.

While you can write custom scripts for this, you can check the ready-made ServerSide connectors.

Using the loadBranch() function

You can catch the node expansion events (onBeforeOpen or onAfterOpen) to load branch data using the loadBranch method. Let's assume that we have initial data loaded:

webix.ui({
  view: "tree",
  data: [
    { id:1, value: "Layout Branch", webix_kids: true },
    { id:2, value: "Data Branch", webix_kids: true },
  ],
  on: {
    onBeforeOpen: function (id) {
      // if children have not been loaded yet
      if (this.getItem(id).$count === -1)
        this.loadBranch(id, null, "data/data_dyn.php");  // null means no callback
    }
  }
});

Related sample: Loading Branch Data

The URL of the new request will be based on the url property of the tree, which can be overridden by the loadBranch method - "data/data__dyn.php?continue=true&parent=1". The parameters are the same as above:

  • parent - ID of the node that has just been opened;
  • continue - flag indicating that it is an auto-generated request.

If you want to use the same data source, omit the last parameter to loadBranch():

var tree = webix.ui({
  view: "tree",
  url: "data/data_dyn.php",
  ...
});

this.loadBranch(id, null);  // "data/data_dyn.php" will be used

Be sure the branch data sent by the server is an object with parent and data properties. A JSON response should look like this:

{ parent: 1, data: [ ...array of child items... ] }

Redefining onDataRequest Event

Set the onDataRequest event handler to redefine the default dynamic loading behaviour and use any desired method to get the data from the server:

The event fires when the user expands a node that has the webix_kids property set:

{ id: "1", value: "Layout Branch", webix_kids: true }

As it is stated above, this event triggers dynamic loading. In other words, if a component features a datasource (defined either by url property or load method) a request is issued using this url.

Still, the onDataRequest event makes it possible to redefine the logic in favour of custom one.

Let's assume that we have initial data loaded in some of the ways:

webix.ui({
  view: "tree",
  data: [
    { id: 1, value: "Layout Branch", webix_kids: true },
    { id: 2, value: "Data Branch", webix_kids: true },
     ],
  on: {
    onDataRequest: function (id) {
    webix.message("Getting children of " + id);
    this.parse(
      webix.ajax().get("data/data_dyn_json.php?parent=" + id).then(function (data) {
        return data = data.json();
      })
    );
    // cancelling default behaviour
    return false;
    }
  }
});

Related sample: Modifying onDataRequest event

Here you completely redefine the default event handling and cancel default dynamic loading behaviour.

Be sure the branch data you get is returned with parent and data properties. For JSON the returned data looks like this:

{ parent:1, data:[ ..array of child items..]}

Dynamic Loading with ServerSide Connectors

In case you use Data Connector to load data from a database into a Tree or TreeTable dynamically, you should call dynamic_loading() on the server side:

Dynamic loading from a server database. Server-side code.

require_once("../connector-php/codebase/data_connector.php");  // includes the connector file
$conn = mysql_connect('localhost', "root","");  // creates a connection
mysql_select_db("sampleDB");// selects a database

$data = new TreeDataConnector($conn, "MySQL");  // initializes the connector object
$data->dynamic_loading(30);  // enables dynamic loading
// loads data from the specified database table
$data->render_table("packages_tree", "id", "value, state", "", "parent_id");

Note, inside dynamic_loading() you should specify a number of records that will be loaded at once.

Everything else is the same as in case of usual loading from a database.

Dynamic loading from the server. Client-side code.

webix.ui({
  url: "data/data_dyn.php"
});

Note that each data item is supplied with the webix_kids flag to ensure dynamic loading.

Related sample: Dynamic Loading

Related Articles

  • Dynamic Loading for Plain Structures


Advanced

Management of loading errors

Since data loading depends on multiple factors, server side frequently returns loading error messages instead of requested data. The webix UI library allows trapping such errors and treating them in some way on the client side.

Default Error Management

By default if an error occurs, there appears a webix.message with details being shown in console. This functionality works only in _debug code version while release version doesn't show any error messages.

To switch off the default error handler, use the following code:

webix.detachEvent(webix.debug_load_event);

Global Error Events

You can create your own global loading error hander that will catch serverside error responces regardless of the component:

onAjaxError(request_obj) - fires when any Ajax request results in an error; onLoadError(text, xml, xhttp, obj) - fires when an error has happened during loading the data into any component on the page.

Global events are attached to Webix object:

webix.attachEvent("onLoadError", function(text, xml, ajax, owner){
      //text - response text
      //xml - response xml object
      //ajax - xmlHttpRequest object
      //owner - component which triggered error

      ... custom code ...
});

Component Error Events

At the same time, each data component features its own onLoadError event with the same parameters:

$$('list').attachEvent("onLoadError", function(text, xml, ajax, owner){ .. }

Furthermore, you can connect a custom error handler to a specific data requests.

$$('list').load("data.php",{
    success:function(text, xml, ajax){ ... },
    error:function(text, xml, ajax){ ... }
});

The same syntax is used for webix.ajax requests:

webix.ajax("data.php", {
    success:function(text, xml, ajax){ ... },
    error:function(text, xml, ajax){ ... }
});


Intermediate

Defining Data Scheme

Data scheme defines schemes for data processing, the default actions for loaded, updated, serialized as well as grouped and sorted.

Object scheme is defined as in the scheme property. Generally, it allows you to set a default scheme for data records of DataStore. So, in cases when you add an empty record to DataStore, the record will be populated with the values set by the scheme.

Any changes you apply through data scheme are directly applied to datastore items.

var list1 = webix.ui({
    view:"list",
    ...
    scheme:{
        name:"Unknown",
        age:16
    }
});

list1.add({}); //adds { name:"Unknown", age:16} record

Add() is the method of the DataStore component.So, we use the data property to access it.

In addition, there are 6 special keys you can use within the property:

  • $init - runs when data is initially being loaded to the component + while reloading data for new DataStore items + when the add method is called;
  • $update - runs for existing items while reloading data (for new items $init runs) + when the update method is called;
  • $save - runs when saving to server is triggered in any of the ways;
  • $change - runs each time data in the table is changed (i.e. loaded,added,updated,deleted). Note, the key runs when either the $init or the $update key runs;
  • $serialize - runs when the serialize method is called;
  • $group - the object with grouping parameters. Passed to the group function that automatically runs when data is initially being loaded to the component;
  • $sort - the object with sorting parameters. Passed to the sort method that automatically runs when data is initially being loaded to the component.

Below you can find examples of using each of the keys.

$init key

Input parameters

The $init function accepts 1 parameter - the data item object.

And called:

  • for each data item, while initial data loading;
  • for newly-added items, while data reloading;
  • for the specified item, when the add method is called.

Usage example

Let's assume, you want to populate a combo with data from some database field, e.g. from the field with name 'categories'. To make the combo recognize the field values as options, the combo should get data as 'text'/'value' pairs.

And here the $init key will come in useful:

webix.ui({
    view:"list",
    layout:"x",
    scheme:{
        $init:function(obj){
            if (obj.year>=2000) obj.$css = "newtime";
            if (obj.year<=1970) obj.$css = "oldtime";
        }
    },
    ...
});

Related sample: Horizontal List

$update key

Input parameters

The $update function accepts 1 parameter - the data item object.

And called:

  • for each data item, while initial data loading;
  • for updated items, while data reloading;
  • for the specified item, when the update method is called.

Usage example

Let's assume, in your database table you have a field with the name 'update_date' where store the date of the last item update. To have the field values up to date, you can use the $update key and specify it as in:

webix.ui({
    view:"list",
    ...
    scheme:{
        $update:function(obj){
            var today = new Date();
            obj.update_date = today.getDate();// 'update_date' is the name of data property
        }
    }
});

$save key

The $save function accepts 1 parameter - the data item object.

input parameters

And called:

  • each time new or changed data is send to server.

Usage example

In combination with $init key, $save gives you an ability to set loading and saving pattern for serverside data.

For instance, you can work with dates as DateTime objects on client side while storing them as strings on server. To avoid formatting after each operation, do it only on data loading and saving.

webix.ui({
    view:"datatable",
    url:"data.php", //loading data
    save:"connector->data.php", //saving data
    scheme:{
        //turning strings into objects on loading
        $init:function(obj){
            if(obj.birthday)
                obj.birthday = webix.i18n.parseFormatDate(obj.birthday);
        },
        //turing objects back to strings on saving
        $save:function(obj){
            if(obj.birthday)
                obj.birthday = webix.i18n.parseFormatStr(obj.birthday)
        }
    },
    columns:[...]
});

$change key

Input parameters

The $change function accepts 1 parameter - the data item object.

And called:

  • each time data is changed in the table.

Usage example

Let's assume, you have a datatable with a list of films and want to color rows with films that less than 1980 year in green. Here you can use the $change that will run each time data is changed and check whether the changed item(s) should be colored in green.

webix.ui({
    view:"datatable",
    ...
    scheme:{
        $change:function(item){
            if (item.year > 1980)
                item.$css = { "color":"green" };
        }
    }
})

Related sample: Rows styling

$serialize key

Input parameters

The $serialize function accepts 1 parameter - the data item object.

And called:

  • for each data item, when the serialize method is called.

The $serialize key is the only key that must return some value while the $serialize function must return data item object that will go to the result serialized JSON object.

Usage example

Let's assume, in the database you store date values as Date() objects. But on the client you want to operate with such data as with strings. In this case, you can specify the $serialize key and call the serialize method to get data in the required format:

var mylist = webix.ui({
    view:"list",
    ...
    scheme:{
        $serialize: function(obj){
            return {name: obj.name, date: dhx.i18n.dateFormatStr(obj.date)};
        }
    }
)};

var items = mylist.data.serialize();
//serialize() is the method of the DataStore component.
//That's we use the [data](data) property to access it.

Note, the method accepts a DataStore item and generally, changes made through the function change DataStore dataset.The example above shows how to get formatted data without changing the DataStore object.

$group key

Input parameters

The $group function accepts 1 parameter - so-called group object that has 2 properties:

  • by – a data property according to which items will be united in groups;
  • map – an object that defines properties of the items in the group;

Properties are specified by an array. The first element of this array is a template with a property from original data, the second one – the functor that will be applied to all values of the property (set by the first element) in the group.Grouping provides the following functors: - sum – gets the sum of the values; - max – gets the maximum value in the group; - min - gets the minimum value in the group.

It’s possible to define custom functor. Read on the topic in the related article - Custom Functor for Data Grouping in Charts.

The $group function is called:

  • for each data item, while initial data loading

The function doesn't run when you programatically call the group method.

Usage example

Let's take the following example: you've got the sales information over the last years in several companies and want to show total sales per companies in a chart. So, you need to get objects of the same companies and sum up their sales. Grouping helps to resolve this problem.

webix.ui({
    view:"chart",
    ...
    scheme:{
        $group:{
            by:"#company#", // 'company' is the name of data property
            map:{
                sales:["#sales#","sum"]
            }
        }
    }
});

Related sample: Grouping

$sort key

Input parameters

The $sort function accepts 1 parameter - so-called sorting object that has 3 properties:

  • by - a name of data property according to which items will be sorted by,
  • dir - the sorting direction: “asc” or “dsc”,
  • as - the sorting method
    • 'int'
    • 'string'
    • 'string_strict' (case-sensitive “string”)
    • or custom.

A custom sorting method is defined by a function. This function is called for each pair of adjacent values and returns 1,-1 or 0: - 1 - the object with the first value in pair must go before the second one - -1 - the second object goes before the first - 0 - the objects are equal

The $sort function is called:

  • for each data item, while initial data loading.

The function doesn't run when you programatically call the sort method.

Usage example

Let's assume, you need to sort data by time property that consists of minutes and seconds divided by ”:”. Through such an example, we can show both use of the $sort key and how to define a custom sorting method:

webix.ui({
    view:"chart",
    ...
    scheme:{
        $sort:{
            by:"time",
            dir:"asc",
            as: sortTime
        }
    }
});

function sortTime(a,b){
    a = a.split(":");
    b = b.split(":");
    if(a[0] > b[0]) return 1;
    else if(a[0] < b[0]) return -1;
    else{
        if(a[1] > b[1]) return 1;
        else if(a[1] < b[1]) return -1;
        return 0;
    }
}


Intermediate

Server-side Integration

Serverside integration is possible with Webix data components, client-side datastores (called Data Collections) and forms. It is enabled in several ways:

  • you can write your own custom scripts in you favourite language to load data and save changes back;
  • you can use server side rest api
  • you can make use of a Server Side Connector (ready to use solution for data loading and saving). Connectors are available in PHP, Java, .Net, ColdFusion versions;
  • You can use MVC.Net, Ruby on Rails, PHP Yii MVC frameworks coupled with your scripts or connectors.

Data Loading

Basic client-side code that enables loading data to a component during its initialization is as follows:

webix.ui({
    id:"dtable",
    view:"datatable",
    url:"data.php"
});

Or, to load data after component init, apply load() method to it:

$$("dtable").load("myscript.php", "xml");

Note that

  • Server script you state as url parameter or pass into load() function executes GET request and returns data from server in either of the possible data formats;
  • You should specify datatype parameter if incoming data is other than JSON (the default datatype);
  • In case of long datasets dynamic loading functionality will be helpful;
  • Default loading pattern can be customized - specific loading modes, ajax helper for passing params into load script.

More info about custom scripts is in the dedicated article.

If you are unsure what to do in case you need to get data from a different domain with relations to your app's one, consult the our solution to cross-domain data loading.

Data Saving

Basic client-side code that enables data saving from a component to database is as follows:

webix.ui({
    id:"dtable",
    view:"datatable",
    save:"save_script.php"
});

Note that

  • Save script gets data in POST request and saves them to database.
  • Save script typically returns operation status and ID of the changed item. To tune server-side response, look into the dedicated article.
  • Saving can be implemented via Webix Ajax helper, which adds more flexibility.

In addition, save property automatically initializes DataProcessor for this component so that data changes are transmitted to your save script. DataProcessor listens to component events, defines editing operation (as insert, update and delete one) and sends changed data to server script in POST request.

Defining Operation Type

By default, operation status comes as webix_operation in POST request. Usually, save script is single and contains patterns for different operations.

At the same time you can define a specific script for each operation. Dataprocessor will define the type of operation and the necessary script will be executed:

save:{
    "insert":"data/insert.php",
    "update":"data/update.php",
    "delete":"data/delete.php"
}

Related sample: Server-side Integration: Custom URL

If you need to change the default pattern of data processing - look up Dataprocessor docs;

Saving Uploaded files

If you use Webix Uploader, you may wonder about how saving of the files is performed.

{
    view:"uploader",
    id:""uploader1,
    name:"uploader"
    upload:"upload.php"
    autosend:false
}

$$("uploader1").send();

Note that

  • Autosend should be set to false in order that saving starts only when you call the send method. When you call it, the script specified in upload property will be executed;
  • Server part of file upload is described in detail in the dedicated part of uploader documentation;
  • The information about how to save form and uploader data separately - is nearby.

Saving Form and Input Data

Form data is either

  • pushed to the component it is bound with;
  • or (more typically) is sent to server by Webix Ajax request

Further Reading

  • Customizing Loading Pattern. Ajax Loading and Parsing
  • Saving Data with Webix Ajax Helper
  • Loading and Saving with Custom Scripts
  • Loading and Saving with Server Side Connectors
  • Customizing DataProcessor
  • Offline Support
  • Working in REST Mode
  • Working with Proxy Objects


Advanced

Custom Server Scripts

In case of custom server scripts you write all the logic of database connection, execute queries that get data from the necessary tables as well as queries for data inserting, updating and deleting.

Basic client-side loading and saving pattern remains unchanged:

webix.ui({
    view:"list",
    url:"load.php",
    save:"save.php"
})

Url loads data returned by dedicated script while save points to script that saves data to database each time you make changes on client side.

The following basic instructions will help you tune your scripts to return data and provide responses for editing operations. Here we work on PHP with SQLite3 database.

  • Data Loading
  • Data Saving
  • Tuning serverside response

If you are unsure what to do in case you need to get data from a different domain with relations to your app's one, consult the our solution to cross-domain data loading.

Data Loading

Webix components support incoming data in JSON, JSArray, XML, HTMLtable and CSV formats, so ensure that your script returns data properly formatted.

For JSON, encode the resulting data array with the dedicated function(json_encode() in PHP)

//connect to database
$db = new SQLite3('../../../common/testdata.sqlite');

//select data
$res = $db->query("SELECT * FROM films");

//convert data to json
$data = array();
while ($rec = $res->fetchArray(SQLITE3_ASSOC)) //each row
    $data[] = $rec;
//output json
echo json_encode($data);

Datatree loading

Datatree can be populated with inline data grouped on client side or with hierarchical data grouped by server-side script.

For hierarchical data you need to have:

  • relation_id field in database table that for each record will store the ID of a record that will be parent for this one. For root record this parameter will be 0;
  • (optionally) - open field for each record indicating whether this record will be initially opened (1) or not (0) - if it has children, of course.

Dataset is compiled with a function that contains SQL query with WHERE clause, which gets data from root record (parent = 0) down to all its children. JSON data for datatree should store chilren for an item in its data property:

function get($id = 0) {
    $db = new SQLite3('../../../common/testdata.sqlite');
    //connect to database

    //select data
    $res = $db->query("SELECT * FROM films_tree WHERE parent={$id}");

    //convert data to json
    $data = array();
    while ($rec = $res->fetchArray(SQLITE3_ASSOC)) {
        $rec["data"] = get($rec["id"]); //putting chilrden into item "data" property
        $data[] = $rec;
    }
    //output json
    return $data;
}

//formatting output
echo json_encode(get());

Form Loading

On client side, load() method is applied to an already initialized form. The method contains loading script that sometimes requires record ID as part of GET request.

$$("form1").load("server/form.php?id=3");

Then on server you'll have the ID to use in WHERE clause of SELECT query.

$id = $_GET["id"];

$res = $db->query("SELECT * FROM films WHERE id={$id}");

Data Saving

In essence defining save initializes DataProcessor that gets data ready for sending to server and triggers script executing each time changes are made. Defaut DataProcessor logic can be customized.

Scripts gets changed data in body of POST request. For each inserted, updated and deleted record, all properties of its object are sent together with webix_operation

id  8
rank    99
rating
title   New
votes   100
webix_operation delete
year    2012

Additional item properies can be set as well by updating this item on client side:

var item = this.getItem(id);
item.old_rank = some; //setting new property and value for it
this.updateItem(id);

The new property old_rank will be passed in POST like native item properties.

Related sample: Datatable: Reordering

You can easily get to these parameters to use them for making corresponding database quieries.

$operation = $POST['webix_operation'];

if($operation=="insert")
    $db->query("INSERT SQL query");

Don't forget to escape user data to avoid SQL injections:

$title = $db->escapeString($_POST["title"]);

And convert data to JSON according to common pattern above.

Datatree Saving

With datatree use the same pattern as above and don't forget to update parent field with parent item value in INSERT and UPDATE queries.

It goes without saying that you should render this field during loading (SELECT * guarantees this for sure) and update it on client side while working with tree data.

$parent = $_POST["parent"];

//queries

Related sample: Tree: Saving

Form Saving

Form is typically saved on some page event (e.g. button clicking) so there's no need in initializing DataProcessor for it. As a result, POST request will contain only form data and no webix_operation type.

You decide what should be done:

  • UPDATE data on server side for a record that was previously loaded to this form;
  • INSERT data into necessary database table (i.e. create a new record);
  • update data on client-side - in this case form should be bound with a component or Data Collection so that form gets data from them and send changed to them while their save scripts handle these changes.

Typical Ajax request to save form data to server look like this:

webix.ajax().post("server/form_save.php", $$(""myform).getValues(), function(response) {
        webix.message(response.status);
});

Form getValues() returns data from all fields as JSON object - just what is required for params sent via Ajax.

For tuning responses scroll down a little bit. For learning Webix API for Ajax operations - go there.

Tuning ServerSide Response

For each query you should tune response, which can be either plain text or JSON object with necesary params:

//plain text on failure
echo "Data saving was not performed";

//JSON with item ID and status for failure
echo '{ "id":"'.$id.'", "status":"error" }';

//JSON with item ID and status for success
echo '{ "id":"'.$id.'", "status":"success" }';

//JSON for successful inserting operation
echo '{ "id":"'.$id.'", "status":"success", "newid":"'.$db->lastInsertRowID().'" }';

$res = $db->query(SQL query);

if($res)
    //response for success
else
    //response for failure

For INSERT operations, new ID is important as on client side any newly added item gets temporary ID randomly generated by webix.uid() method (something like 1369905287157).

After adding this item to database table it gets normal ID generated by auto increment, and this ID will be loaded to client side on page refresh. So, you might require this new ID at once to work with recently added item.

If you use Ajax request, these responses are easily derived in callback. If response is a JSON object, any of its properties can be treated separately.

webix.ajax().post("server/save.php", {}, function(response) {
        webix.message(response.status);
});

More about Ajax operations in Webix.


Intermediate

REST Mode Support

Webix features full support for REST load and save protocol.

To enter REST mode, use prefix rest before load and save scripts. This will enable the necessary proxy object.

{
    view:"datatable",
    ..config..
    save: "rest->server/datatable_rest.php",
    url: "rest->server/datatable.php"
}

Related sample: Datatable: REST

You can as well init REST proxy object and set is as value of url and save properties. For these needs webix.proxy() function receives rest prefix and path to your serverside save script.

var rest = webix.proxy("rest", "server/datatable_rest.php");

REST Load and Save Pattern

  • On loading GET request is executed and data in any of supported data formats is returned;
  • When editing happens or update() method is called - PUT request is generated, item ID and other params are sent to the script. Item ID is shown in the address line;
  • When item is added inside the component - POST request is generated, item ID and other params are sent to the script. Item ID is shown in the address line;
  • When item is removed from th component - DELETE request is generated, item ID is sent to the script.

Save script treats adding, editing and deleting operations separately and should contain different code on the base of request method.

Serverside Response

Serverside response is set like with any custom script.

Note that Webix DataProcessor can be tuned to update client-side data from response automatically:

view:"datatable",
save: {
    url:"rest->server/datatable_rest.php",
    autoupdate:true
}


Intermediate

Saving Data with Webix Ajax Helper

Webix ajax helpers helps save component data on demand as well as form and input data.

Note that DataProcessor isn't initialized this time and you need to catch the necessary events (add, edit, delete) yourself. For forms saving request is usually send on button click.

Data is sent to server script in the body of Ajax POST request:

webix.ajax().post("myscript", params, callback);

Note that

  • "myscript.php" can be your own script on any language you choose. It can be as well a connector-based script);
  • params are sent in form of JSON object (which is exactly what the form's getValues method returns:
webix.ajax().post("my_script", {id: some, name: some, address:some }, callback);
webix.ajax().post("my_script", form.getValues(), callback);

If combined with connector-based script, simplified data transfer protocol can be used.

Additionally, you can pass extra parameters as GET request:

webix.ajax().post("data/load.php?id=1&action=update", {prop1:value1, prop2:value2} function(text, data){
    ...//callback
});

There you'll have in serverside script:

$id = $_GET['id'];
$action = $_GET['action'];
$prop1 = $_POST['prop1];
$prop2 = $_POST['prop2];

Learn more about the possibilities of Webix Ajax interface.


Intermediate

Customizing Loading Pattern. Ajax Loading and Parsing

By default Webix loads data to its component by an asynchronous Ajax GET request. However, various modifications are possible.

Loading Data via POST Request

By default data is loaded via GET request. To change it to POST, use post prefix.

{
    view:"datatable",
    ..config..
    url: "post->load.php"
}

Loading Data via Synchronous Ajax Request

You can change the request to a synchronous one (sometimes it may be useful).

{
    view:"datatable",
    ..config..
    url: "sync->load.php"
}

Modifying Background Ajax Requests

There exists no possibility to modify background Ajax requests sent by the above pattern.

However, you can catch Webix onBeforeAjax event to modify ANY Ajax request on the page (so be attentive):

Sending Headers

webix.attachEvent("onBeforeAjax", function(mode, url, data, request, headers){
  headers["Content-type"]= "application/json";
});

Note that Webix Ajax module (described below) features a built-in functionality for sending headers with serverside requests.

Loading with Webix Ajax Helper

To load data on demand without breaking application flow, you can resort to Webix Ajax interface.

//get request (default)
webix.ajax("data/load.php",function (text,data){
    $$("list").parse(text);
});

Serverside script should return inline data in any of supported data types so that it can be parsed into the necessary component.

Above snippet will set the new data for list. To add new data to the existing list data, define start position for parsing:

webix.ajax("data/load.php",function (text,data){
    $$("list").parse({
        pos: $$("list").count(), //start position
        data:text
    });
});

For setting the necessary serverside response manually, see the dedicated article. As to Server Side Connector, they return data in JSON or XML format depending on connector type.

Ajax loading allows passing params to serverside script as GET request:

webix.ajax("server/load.php?id="+id, function(text, data){
    ...//callback
});

Learn more about Webix Ajax Operations.

Adding Extra Functionality to Loading Functions

Here you should consult:

  • Ready-to use proxy objects for offline support;
  • Proxy object for working in REST mode;
  • Guidlines about proxy objects and custom proxy objects in particular.


Intermediate

Offline Support

Offline support allows storing serverside data locally in your browser cache which helps you go on working with data components after refresh when connection to server fails.

Saving the whole page via Cache Manifest

Files subject to caching, should be listed in a cache manifest, a typically HTML5 feature, which allows for differentiating between files available in an offline mode from those available when you are connected.

Firstly, the manifest is included into each webpage you'd like to be cached.

<!DOCTYPE html>
<html manifest="app.appcache">

Secondly, manifest details are specified in the app.appcache file. As a rule, the following files should be cached:

offline_app.html //each application file itself,

../../../codebase/webix.js //library files
../../../codebase/webix.css

data/data.json //data-loading file

Offline Support for Webix Component Data

Offline support is implemented via three load and save modes:

  • offline and cache - both working with serverside data that is additionally stored locally;
  • local - works with local storage data only.

Offline Mode

Offline mode ensures that serverside data will be stored locally in browser and later on, the component will always try to reach server to get or save data BUT in case of failure, the data will be loaded from cache and stored in cache, accordingly. When you are connected again, all changed data should be derived from cache and sent to server (otherwise on next page refresh it will be replaced by outdated serverside data).

Webix works with cache through its webix.storage.local interface. See the description of caching logic.

To enable this, use offline prefix before load and save scripts:

{
    view:"datatable",
    id:"datatable1",
    ..config..
    save: "offline->server/datatable.php",
    url: "offline->server/datatable.php"
}

Related sample: Datatable: Offline mode

Or, if you load data after component init, pass this prefix (offline or cache) to load fucntion together with load script itself:

//two methods are equal
$$("datatable1").load(offline->server/datatable_load.php);
$$("datatable1").load(webix.proxy("offline", "server/datatable_load.php"));

//or, if you want to load data in POST request:
$$("datatable1").load( webix.proxy("offline", "post->url.php"));

In essense, the prefix signifies integration with a dedicated proxy object that contains all the logic of offline storage. Proxy objects are described separately.

Cache Mode

When you enter cache mode, data is first loaded to component and put to browser local storage and then you work ONLY with this cached data: it's loaded from cache and stored to it without trying to connect to server.

Webix works with cache through its webix.storage.local interface. See the description of caching logic.

To enable this, use cache prefix before load and save scripts:

{
    view:"datatable",
    id:"datatable1",
    ..config..
    save: "cache->server/datatable.php",
    url: "cache->server/datatable.php"
}

Related sample: Datatable: Cache mode

Or, if you load data after component init, pass this prefix (offline or cache) to load fucntion together with load script itself:

//two methods are equal
$$("datatable1").load(cache->server/datatable_load.php);
$$("datatable1").load(webix.proxy("cache", "server/datatable_load.php"));

//or, if you want to load data in POST request:
$$("datatable1").load( webix.proxy("cache", "post->url.php"));

In essense, the prefix signifies integration with a dedicated proxy object that contains all the logic of offline storage. Proxy objects are described separately.

Local Mode

When you work in local mode, your component deals with local storage objects only. You can load data from local storage and save it there without any serverside part.

Webix works with cache through its webix.storage.local interface. See the description of caching logic.

In local mode, you should provide names of localStorage objects instead of urls:

{
    view:"datatable",
    id:"datatable1",
    ..config..
    save: "cache->mydata",
    url: "cache->mydata"
}

Neither offline nor cache modes allow accessing localStorage objects, but local mode makes it possible.

Working with Cached Data

Both of these proxy objects, offline and cache, offer API for working with currently cached data. Methods are applied to the component's url property object:

$$("datatable1").config.url.someMethod();
  • clearCache() - to remove cached data of this component;
  • setCache(data) - pushes any data to cache. Data should be passed as JSON object or JSON string;
  • saveAll() - serializes current component data and pushes it to cache;
  • getCache - gets the latest copy of cached data for this component in the form of JSON object. It can be used to populate the component with the help of parse method.

Setting Static Cache

In addition, you can manually set data for component cache. Here you manipulate Webix proxy objects.

Firstly, you should create cache proxy object. It includes server script for data loading:

var static_proxy = webix.proxy("cache", "server/datatable.php");

This object should be used for data loading(url) and saving(save):

var grid = {
    view:"datatable",
    ..config..
    save: static_proxy,
    url: static_proxy
};

Then, you set necessary data to this object via the setCache() method:

if (!static_proxy.getCache())
    static_proxy.setCache([
        {"id":1,"title":"The Shaushenk Redemption ",
            "year":"1998","votes":194865,"rating":"7.5","rank":1},
        {"id":2,"title":"The Godfather",
            "year":"1974","votes":511495,"rating":"9.2","rank":2}
    ]);

Related sample: Datatable: Cache static mode

Proxy objects are described in detail in the corresponding article.


Advanced

Webix Proxy Objects

Either the component's url property or its load function can be used not only for passing loading script, but can include additional loading logic in proxy objects.

Built-in Proxy Objects

There's a list of ready-to-use Webix proxy objects that can be used by adding prefixes to a loading script.

  • offline and cache - for application offline support of applications that use serverside data;
  • local - for saving component data into browser local storage and working with it. Described as part of offline support article;
  • connector - for saving data via Server Side Connector;
  • rest - for working with server in REST mode;
  • post - for loading data in POST request (GET by default);
  • sync - for loading data via a synchronous Ajax request (by default, loading is performed by an asynchronous request);
  • indexdb - for working with indexedDB in-browser database storage;
  • faye - for enabling live data update on all clients currently using the application. Look here for details;
  • binary - for loading and reading files as arraybuffer;
  • json - for sending JSON data to server via RESTful "save" requests with "application/json" content type.

Prefixes are used before the path to you serverside script:

var list = {
    view:"list"
    url:"offline->load.php",
    save:"offline->load.php"
};

grid.load("rest->load.php")

You can browse the samples of Proxy usage by a link.

Using methods of Built-in Proxy Objects

Methods of a proxy object are called from the url of the component it's used for:

//returns cached data for this list
list.config.url.getCache();

You can also save an instance of the necessary proxy object in a variable and call all methods from it:

var static_proxy = webix.proxy("cache", "server/datatable.php");

var grid = {
    view:"datatable",
    ..config..
    save: static_proxy,
    url: static_proxy
};

if (!static_proxy.getCache())
    static_proxy.setCache([
        {"id":1,"title":"The Shaushenk Redemption ",
            "year":"1998","votes":194865,"rating":"7.5","rank":1},
        {"id":2,"title":"The Godfather",
            "year":"1974","votes":511495,"rating":"9.2","rank":2}
    ]);

Related sample: Datatable: Cache static mode

Customizing Built-in Proxy Objects

You can add extra functionality to built-in proxy objects or redefine existing properties or methods by extending their functionality.

For instance, you can change the default place for storing cached data of an offline proxy object, which is webix.storage.local by default:

webix.proxy.myCustomName = {
    init:function(){
        webix.extend(this, webix.proxy.offline);
    },
    cache: some_place_you_choose
};

And then use it as prefix to load and save scripts:

{
    view:"datatable",
    url:"myCustomName->load.php",
    save:"myCustomName->load.php"
}
//or, after component init
$$("datatable1").load("myCustomName->load.php");

Creating Custom Proxy Objects

Proxy object is a plain JSON object you create to add extra functionality to your loading and saving pattern.

It features

  • compulsory $proxy property set to true;
  • other properties;
  • functions to fire on loading and saving;
  • other methods.

Proxy objects

webix.proxy.myCustomName = {
    $proxy:true
    load:function(view, callback){
        //your loading pattern
        ...
        webix.ajax(this.source, callback, view);
    },
    save:function(view, update, dp, callback){
        //your saving pattern for single records
        ...
        webix.ajax().post(url, data, callback);
    },
    saveAll:function(view, update, dp, callback){
        //your saving pattern
        ...
        for (var i = 0; i < updates.length; i++) { ... }
    },
    result:function(state, view, dp, text, data, loader){
        //your logic of serverside response processing
        ...
        dp.processResult(state, data, details);
    },
    //other custom properties and methods
    prop1:value1,
    method1:function(){ ... }
};

Predefined methods that can be customized include:

  • load(view, callback) - is used for data loading and takes two parameters:
    • view - object - the component you work with;
    • callback - function, object - loading callback;
  • save(view, update, dp, callback) - is used for saving of single records and triggers when changes occur on client side. Takes four parameters:
    • view - object - the component you work with;
    • update - array - array of changed records, each of which contains data object, record id and operation name;
    • dp - object - DataProcessor object;
    • callback - function, object - saving callback;
  • saveAll(view, update, dp, callback) - is called after saving of a single record is complete to catch up for other changes occured in the component. Takes the same parameters as save();
  • result(state, view, dp, text, data, loader) - is called after data is saved and serverside response is received. Takes five parameters:
    • state - object - operation state;
    • view - object - the component you work with;
    • dp - object - DataProcessor object;
    • text - string - serverside response text;
    • data - object - raw data of serverside response;
    • loader - object - XHR loader object.

To use a custom proxy, append its name as prefix to a loading or saving script (or both, is needed):

{
    view:"datatable",
    url:"myCustomName->load.php",
    save:"myCustomName->load.php"
}
//or, after component init
$$("datatable1").load("myCustomName->load.php");


Intermediate

Working with IndexedDB

Webix offers a simple way for efficient work with IndexedDB in-browser storage.

Complying with Webix concept of serverside proxy objects IndexedDB support is implemented via indexdb proxy object that contains necessary logic for creating databases as well as working with existing ones.

Webix indexdb proxy object is used for:

  • creating IndexedDB database in current browser and populating it with data;
  • getting IndexedDB data and loading it into Webix data components (datatable, dataview, list, chart);
  • saving changes you perform over component data into the corresponding database. Each time you refresh the page up-to-data data is loaded.

Indexdb proxy object features three built-in methods:

  • load - loads database data from the chosen database into the component;
  • save - saves component changes into the chosen database;
  • create - creates an IndexedDB database with objectstore(s) and loads data to it(them).

Loading data from IndexedDB Store to Webix Component

To load data from an existing IndexedDB database, provide its name together with an objectstore name according to the following pattern: indexdb->db_name/store_name.

Both database and objectstore names are must-have paramaters:

{
    view:"datatable",
    id:"datatable",
    url:"indexdb->mydb/mycollection"
}

//or, for loading data after component init
$$("datatable").load("indexdb->mydb/mycollection");

Related sample: Connector DataTable loading

Component's url property as well as load method define datasource. In case of IndexedDB, they call load method of an indexdb proxy object and pass database and objectstore names into it.

Saving Component Data to IndexedDB Database

To save changes performed over component data, you need to pass database and objectstore names into the component's save property according to the following pattern: indexdb->db_name/store_name:

{
    view:"datatable",
    url:"indexdb->mydb/mycollection",
    save:"indexdb->mydb/mycollection"
}

Related sample: Connector DataTable saving

Component's save property calls save method of an indexdb proxy object.

Creating IndexedDB Datatase and Populating it with Data

The indexdb proxy allows using its methods directly. For instance, you can call create method with the following code:

webix.proxy.indexdb.create(dbname, collection_data, dbversion, callback);

Where:

  • dbname - name of a databases being created;
  • collection_data - JSON object that contains collection names as keys and collection data as values;
  • dbversion - version of the database being created. It you prefer not to bother about versons, pass null;
  • callback - callback function.

Here's an example of a function call, where mydb database with mycollection objectstore is created and data is loaded to the objectstore.

webix.proxy.indexdb.create("mydb", {
    mycollection:[
        {"id":1,"title":"The Shaushenk Redemption ","year":"1998","votes":194865,
            "rating":"7.5","rank":1},
        {"id":2,"title":"The Godfather","year":"1975","votes":511495,"rating":"9.2",
            "rank":2},
        {"id":3,"title":"The Godfather: Part II","year":"1974","votes":319352,
            "rating":"9.0","rank":3},
        {"id":4,"title":"The Good, the Bad and the Ugly","year":"1966","votes":213030,
            "rating":"8.9","rank":4},
        {"id":5,"title":"My Fair Lady","year":"1994","votes":533848,"rating":"9.1",
            "rank":5},
        {"id":6,"title":"12 Angry Men","year":"1957","votes":164558,"rating":"8.9",
            "rank":6}
    ],
    //mycollection2:[data], //as many stores as you like
    //mycollection2:[data]
}, null, init_demo);

Related sample: Connector DataTable loading

Webix data loading pattern in described separately.


Websockets (Faye)

Faye proxy object is used to ensure live data update on all the clients currently using the application with this feature. It is based on Faye publish-subscribe messaging system which is in turn based on the Bayeux protocol.

Faye proxy object is useful for creating corporate chats clients. It can be used with any Webix data component while list is the most suitable one a chat.

Proxy object is defined within the component constructor with the help of url and save properties:

{
    view: "list",
    id:"chat",
    url: "faye->/data",
    save: "faye->/data"
}
//or, to load data after component init
$$("chat").load("faye->/data");
  • Url property, as well as load method is used to define datasource for the component. Here it includes proxy name (faye) and storage name on your faye server (any);
  • Save property enables data saving to the chosen storage. On page refresh up-to-date data is loaded into the component.

Storage name must contain slash at the beginning.

Starting Faye server

Besides, you need to provide standard logic to staring Faye server:

var http = require('http'),
faye = require('faye');

var server = http.createServer(),
bayeux = new faye.NodeAdapter({mount: '/'});

bayeux.attach(server);
server.listen(8000);

Initializing Faye client

And define Faye client and its ID that are required for faye proxy:

webix.proxy.faye.client = new Faye.Client('//localhost:8000/');
webix.proxy.faye.clientId = webix.uid(); //or any custom pattern

Related Sample

To play with the feature, load and unzip the demo. Don't forget about NodeJS server running.


Intermediate

DataProcessor

Webix DataProcessor is a functional library that lets you to ‘communicate’ with server-side backend. It

  • resides on the client side as a mixin of Webix library;
  • listens to component events - data adding, updating, moving (should be enabled separately) and removing - and passes changed data as well as operation performed (insert, update, delete) to the server script in POST request.
  • handles data validation before passing to server script;
  • can be used for any UI component and DataCollection.

Without DataProcessor, you need to attach corresponding functions to component events (onAfterInsert/Update/Delete) to get data ready for processing.

You can find the full list of DataProcessor methods, properties and events in the API Reference.

DataProcessor Initialization

DataProcessor object can be initialized in both long and short forms. Compulsory parameters include:

  • url, a path to your own server script or connector-based one (described in Server Side Connector). In any case, it should be the script that enables data loading from the database into the component;
  • master, a component or DataCollection you will use the dataProcessor with.

Other parameters (mode, validation rules, on, etc.) and optional and can be found here.

Implicit Initialization via Save Property

When you define url (path to the necessary script) as value of save property for the needed component (master) - DataProcessor is automatically initialized:

webix.ui({
    view:"datatable",
    //..config..
    url: "data.php", //script that links to DataConnector and loads data
    save: "connector -> data.php" //the same script used for data processing

    //or
    url:"data_load.php", //your custom script for loading
    save:"data_save.php" //you custom script for saving
});

Short Form

A short form connects the previously created dataProcessor to the component, but if there isn't any, it creates the new dataProcessor.

Short Form (master, url)

webix.dp("mylist", "some_script.php");

Long Form

With a long form you make use of the new constructor where you create an object through object literals.

Full Form

dp = new webix.DataProcessor({
    url: "data.php",
    master: $$('mylist'),
    //optional properties
});

Related sample: Server-side Integration: List

A long initialization form allows for setting an ID for the dataprocessor. Otherwise, it is given an auto-generated one.

Getting DataProcessor Object

Dataprocessor features a set of methods and properties that can be used to change default processing pattern. To make use of them, you need to get to a dataprocessor object, which can be achieved with the help of Webix dp method:

  • getting a dataprocessor initialized for a component with the specified ID:
var dp = webix.dp("mylist"); //returns dataprocessor object for "list" view
  • getting a dataprocessor with the specified ID
var dp = webix.dp.$$("mydp");

Data Processing Operations

DataProcessor interpretes client-side operations performed on each data item and defines the type of data action for it:

The default processing looks as follows:

  • If remove() function is called within the component, action type is delete;
  • If editing is done, or update() function is called, data action is of an update type;
  • If you add() data to the component, the data action is insert.

This data action together with data of edited/added/deleted record is sent to server script the moment any editing operation is performed. Data action is passed as:

  • !nativeeditor_status parameter in case of implicit DataProcessor initializing (with save property) and simultaneous usage of connector;
view:"list",
save:"connector->myscript.php" //link to Server Side Connector
  • webix_operation parameter in all other cases.

It looks like this:

id  7
title   The Shawshank Redemption
webix_operation delete

And other protocol with implicit Dataprocessor initializing for connector-based scripts:

1_!nativeeditor_status  update
1_birthday  1965-08-19
1_id    1

The moment Dataprocessor returns data, script execution begins (if other is not stated):

  • If serverside integration is enabled with a Server Side Connector, the connector automatically generates database request corresponding to action type to treat changed data;
  • For custom scripts, you get webix_operation and other data via POST request and write corresponding queries for each type of operation.

DataProcessor for Drag-n-Drop and Data Moving

DnD operations and data item moving can be tracked by DataProcessor like any other CRUD operation provided that you switch on DataProcessor trackMove functionality.

new webix.DataProcessor({
    master: tree,
    url: "...",
    trackMove:true
});

Related sample: Server-side Integration: Tree

DataProcessor EventSystem and Error Tracking

DataProcessor events (listed in API reference) can be used for different purposes. For instance, the events can help you:

1) Modify data before it's gone to server with the onBeforeDataSend event that takes the whole dataobject as parameter:

dp.attachEvent('onBeforeDataSend', function(obj){
    obj.data.StartDate = webix.i18n.dateFormatStr(obj.data.StartDate);
});

2) Track successfull and unsuccessful serverside responses separately with the help of onAfterSync and onAfterSaveError events respectively:

Successful server response

dp.attachEvent('onAfterSync', function(id, text, data){
    var response = data.xml(),
    hash = response.data;
    //hash {type:'', tid: '', sid:''}
});
  • type - type of action performed (insert, update, delete);
  • sid - item ID that was sent to server for update;
  • tid - item ID that returned from server after update.

tid and sid will only be different in case on insert operation. In this case, DataProcessor automatically changes client-side ID to the ID that was generated for the item on server.

Unsuccessful server response

dp.attachEvent('onAfterSaveError', function(id, status, obj){
     var operation = this.getItemState(id).operation; //operation that was performed
});

In case of an error during saving, response status will always be 'error' while type of operation is derived by getItemState method.

Getting to a master component from DataProcessor

Inside DataProcessor event handlers you can reach the master component througn DataProcessor configuration objetc:

dp.attachEvent('onSomeEvent', function(id, status, obj){
   var grid = this.config.master; //this == DataProcessor
});

Data Updating from Server Response

As it was stated earlier, the new ID from response of insert request will automatically replace the temporary client-side ID. This is part of default DataProcessor behavior, and no specific actions are required.

Additionally, yuo can enable automatic data update for all fields taking part in insert and update operations. It requires the following additions to the code:

  • tune serverside response to return the whole data object (not only status or IDs);
  • enable DataProcessor autoupdate functionality:

Either during explicit DataProcessor definition

new webix.DataProcessor({
    updateFromResponse:true,
    master:"datatable1",
    url:"..."
});

Or when defining DataProcessor implicitely

view:"datatable",
save:{
    url:"...",
    updateFromResponse:true
}

Related sample: Datatable: Updating

It can be uselful for REST-full applications or when you need to fill in client-side fields which values can be calculated only on server side, etc.

Changing Default Processing Logic

The event system for dataProcessor helps change the default processing logic right on client-side.

To alter processing, you should manually attach processing function to the necessary DataProcessor event (onBeforeDelete, onBeforeInsert, onBeforeUpdate). For instance, set update action type on onBeforeDelete thus making connector issue UPDATE request instead of DELETE.

This is how we change deletion from database by updating this record:

webix.ui({
    view:"datatable",
    id:"grid",
    ..// config options
    url:"data/employee.php",
    save:"connector->data/employee.php"
 });

..//function redefining removal into updating

webix.dp($$("grid")).attachEvent("onbeforedelete", function(id, action){
        action.operation = "update";
        action.data.deleted = webix.i18n.parseFormatStr(new Date());
});

where..

  • id - the ID of the item being processed;
  • action - DataAction object;
  • operation - the database operation being performed (action type);
  • data - refers to component inner DataStore. Here we can get to the desired data item property (action.data.property_name).

Now, when a record is removed from the component, a field deleted of this record is updated in the database table. The current date is set into it to track the moment when the record was removed on the client side.

Learn more about the possibilities of data manipulation on clent side in related articles:

  • Data Adding and Deletion;
  • Data Updating
  • Data Editing

Cancelling and Enabling Dataprocessor for Some Operation

Cancelling DataProcessor

Not any client-side update is to be saved to server. To temporarily cancel DataProcessor you can:

  • either apply ignore fucntion to the Dataprocessor object.
webix.dp("grid").ignore(function(){
    $$("grid").add(data);
});
  • switch Dataprocessor off during the update operation:
dp.on();
$$("grid").add(data);
dp.off();
  • cancel automatic data sending via DataProcessor autoupdate property.
//initially during dp configuration
new webix.DataProcessor({
    updateFromResponse:true,
    master:"datatable1",
    url:"...",
    autoupdate:false
});

//dynamically
webix.dp($$("datatable1")).define("autoupdate", false);

Enabling Dataprocessor

The following concerns only disabled DataProcessor or the one with the changed behavior or if you need to emulate DataProcessor logic. In other cases DataProcessor performs the below described actions automatically.

To enable DataProcessor, and hence, trigger, sending its data to server, save method should be used with item ID and operation name as parameters:

webix.dp($$("datatable1")).save(1, 'update');

To get all changes in the component and send them to server, send method should be used:

webix.dp($$("datatable1")).send();

Data Validation with DataProcessor

Data validation is enabled by including specific rules for input field. You can read about them here. With rules specified, the validation process starts each time you try to save data to the database.

dp = new webix.DataProcessor({
    rules:{
        $all:webix.rules.isNotEmpty
    },
    url: "save.php",
    master: $$('mylist')
});

Sending Headers with DataProcessor-based Requests

There exists no possibility to send headers with DataProcessor requests as they are executed in background. However, you can catch Webix onBeforeAjax request to modify ANY Ajax request issued from the page:

webix.callEvent("onBeforeAjax", function(mode, url, data, request, headers){
    headers["Content-type"]= "application/json";
});

Note that Webix Ajax module features a built-in functionality for sending headers with serverside requests. The above solution is only for DataProcessor Ajax requests.

Related Article

  • Dataprocessor API - Methods, Properties and Events
  • Server Side Connectors


Advanced

Data Connector

The Server Side Connectors together with DataProcessor use their inner logic to interpret CRUD operations and generate the code to update database tables according to the changes made.

  • Connectors come in ready-made PHP, Java, .Net, ColdFusion versions;
  • they simplify data loading from database and data saving. You needn't write database queries yourself;
  • allow basic CRUD operations on server-side;
  • enable server-side sorting and filtration;
  • feature built-in protection against CSRF and XSS attacks.

As a rule, one and the same connector is used for loading data and saving.

Connector Documentation
  • PHP connectors;
  • Java Connectors;
  • .Net Connectors;
  • ColdFusion Connectors.

There you should search for standard DataConnector and JSONDataConnector that are intended for use with our touch-oriented libraries including Webix.

Data Loading

Connectors perform database queries and return data in XML format (standard DataConnector) or in JSON (JSONDataConnector). Data formats are described separately.

To load data with the help of the necessary connector, you should:

  • write a connector-based script that connects to the necessary database AND contains path to the necessary connector. In addition, it may contain extra data rendering logic (described below).
  • specify this script as url for the Webix component you work with.
webix.ui({
    view: "datatable",
    ..config..
    url: "server/data.php"
    datatype:"xml"
});

//or, in case you load data after component init:

$$("grid").load("server/data.php");
  • Datatype can be omitted in case of JSONDataConnector usage since it returns data in default JSON format;
  • In case of long datasets, make use of dynamic loading functionality;
  • If you are unsure what to do in case you need to get data from a different domain with relations to your app's one, consult the our solution to cross-domain data loading.

Connector Based Script (PHP Solution)

Below is the guide how to write the script that will link component and dataConnector (call it data.php, e.g):

1 . Connect to the database and select to the necessary connector.

Specify path to desired Data Connector, and connect to your database:

require_once("../../data_connector.php"); //!connector
$dbtype = "MySQL";
$conn = mysql_connect(localhost, "login","password");

2 . Initialize dataConnector:

$data = new JSONDataConnector($conn, $dbtype);

Here you can enable protection against CSRF and XSS attacks:

CSRF Protection

ConnectorSecurity::$security_key = true;

XSS Protection

//safehtml
ConnectorSecurity::$xss = DHX_SECURITY_SAFEHTML;

//trusted
ConnectorSecurity::$xss = DHX_SECURITY_TRUSTED;

By default, SECURITY_SAFETEXT protection is used, so you needn't specify it directly.

3 . Render data from the needed table/ tables:

In case of a single table you specify its name, the primary key field and field names you'd like to render:

$data->render_table("users","id","user, email, status");

In case of hierarchical data, you also specify relation id, which is the name of the field that stores ID of the parent branch for this record:

$data->render_table("users", "id", "user, email, status", "", "relation_id" );

In case of several tables you need to write a SQL-query, specify the primary key field and fields to render.

$data->render_sql("SELECT user, email, status, project FROM users, projects", "id", "user, email, status, project");

Here you can enable dynamic loading, which is useful in case of long datasets. The argument states the number of records loaded initially while the others will be loaded as you scroll or page through the data in the component:

$data->dynamic_loading(30);

Comments:

Render_table and render_sql have common parameters:

  • table name / SQL-query;
  • name of primary key (ID) field;
  • names of fields to take data from;

4 . Customize rendered data

Apart from these two basic functions, you can add extra functionality by using the following methods:

  • configure - configuring a temporary table for further usage the same way you do it with render_table.
  • limit - customizing the amount of rendered data. Takes for parameters: start line, the number of lines to be rendered, column name to take data from, and sorting direction in this column;
$last_value -> configure("wages", "id", "values, start_date");

$last_value -> limit(0, 1, "date_start", "desc");

Here values from the "wages" table are sorted by date while the descending direction means that the highest line will be the latest value. The result of the query will be the first line of the sorted table.

  • mix - defining data for a field/column in the UI component. The data comes from the table different from that you use to render data for this component.
$data -> mix("wage", $last_value, array("empl_id" => "id"));

Here the method works with a column/field name of the component, the value, you'd like to render there and ID correspondence between the tables.

  • filter - filtering data on serverside. Takes column name and desired value as arguments
$data -> filter("field_name = ''");

Here the data is filtered by a "field_name" field and shows all records where it is empty.

Connectos have big possibilities of customization, so consult their documentation.

Saving Data with Connectors

To enable saving data with the chosen connector, you should specify it as value of the component save property (in addition to mentioning as url for loading).

webix.ui({
    view: "datatable",
    ..config..
    url: "server/data.php"
    save:"connector->server/data.php"
    datatype:"xml"
});

Note that

  • The must-have detail here is a connector prefix before the path.
  • As soon as you define you connector-based script as save script, DataProcessor is initialized to send changed data to this script.

DataProcessor passes changed data from the component alongside with the operation (update, insert, delete) performed on it. This operation corresponds to query type the connector will execute over the database table. If you neeed to customize this behavior - go to DataProcessor docs.

There are two protocols for data transfer with Server Side Connectors

  • Standard - used for automatic data sending from a component to server (each time you add, edit, remove item);
  • Simplified - used for manual triggering of server script execution, e.g. issuing Ajax request.

Standard Protocol

  • get request automatically receives mark ?editing=true
  • post request receives data for the record being edited. It includes data from all fields of this record AND !nativeeditor_status (update, insert, delete) that is defined automatically on the base of user actions;
  • response comes as in XML that includes type of performed action, original item ID and item ID after processing.

ServerSide Response

<?xml version='1.0' ?><data><action type='update' sid='1' tid='1' ></action></data>

Original ID (sid) and ID after processing (tid) may differ when item adding is performed on client side, during which item gets temporary ID that is changed to database record ID after inserting this item into the database.

Response can be changed. See connector documentation for the needed pattern.

Simplified protocol

  • you should specify desired operation (action type) manually in get request as "myscript.php?action=insert";
  • post - properties you pass within Ajax request in form of JSON object;
  • response - true/false for update operation plus item ID for insert and delete.

More about simplified data transfer here.

Simplified protocol can be used for Ajax requests:

webix.ajax().post("myscript.php?action=update",
    {id: new_id, name: new_name}, //params
     function(response){ //callback
        if(response) //for update it's either true or false
            webix.message("Done");
        else
            webix.message("Update Failed");
});


Cross-Domain Data Loading

It's quite uncommun that your app may require data from domain different to the one it's hosted on. Take for instance that you app is hosted at http://app.mydomain.com, data is located at http://data.mydomain.com and the data-loading script is called "data.php".

Standard loading will fail in this case as all browsers block all cross-domain operations for the sake of safety even if you try using a different port.

Nevertheless, there are techniques to overcome these problems. With Webix lib, you can use two of them:

  • Cross-Origin Resource Sharing to perform types of requests;
  • JSONP Loading for GETting data only.

In both cases you cannot load data with load method that data components normally use for external data. On the contrary, you issue data requests and parse the returned data in callback.

Cross-Origin Resource Sharing or CORS

CORS requires additional server configuration, namely you need to configure data server so that it allows any program from the app's domain (and hence, the app itself) to get data from it.

When you issue such Ajax request with Webix ajax function like this:

webix.ajax("http://data.mydomain.com/data.php", function(text, data){
    table.parse(data.json());
});

The browser sends the following header with the HTTP request:

Origin: http://app.mydomain.com

You need to make data server (http://data.mydomain.com:) to respond with a specific "allowing" header as well. Like here, app's server is allowed to get data from data server:

Access-Control-Allow-Origin: http://app.mydomain.com

This can be done in three ways:

  • You configure the server’s settings;
  • You adjust the code of your app to output the header as a part of server response;
  • You use some thirdparty API with server already already set for CORS protocol.

More detailed information about CORS in the Wiki article.

Advantages

CORS technique is standard based, safe and can be used with any kind of data (structured or not) while supporting all types of requests – GET, POST, PUT, DELETE, etc.

Drawbacks

CORS protocol can't be used in IE8 and IE9.

JSON with Padding or JSONP

In frames of Webix JSONP technique requires changes in client-side code, namely you get data with a special webix.jsonp() method that hides all technical details of JSONP handling but at the same time you need to do some coding:

//client-side pattern
webix.jsonp("http://data.mydomain.com/data.php", {}, function(data){
     table.parse(data);
});

Note that in comparison to Ajax, JSONP always provides structured data, not a raw response text.Thta's why the server script must return encoded data:

//server-side pattern
$data = get_data_in_some_way();
$json_data = json_encode($data);

$jsonpname = $_GET["jsonp"];

header('content-type: application/json; charset=utf-8');
echo $jsonpname."(".$json_data.")";

As you can see, the response data is wrapped, encoded as JSON and is sent back combined with “jsonp” parameter.

Wikipedia article about JSONP.

Advantages:

JSONP works in all browsers and doesn’t require server reconfiguration.

Drawbacks:

JSONP requires extra coding but is limited to work only with structured data as well as suitable only for GET requests. At the same time, it is prone to XSS attacks. It's recommended to resort to JSONP only if you need to support IE8 and IE9 browsers.


Intermediate

Data Binding and Syncing

When you have multiple related views (components) on the page you can bind them together or sync their data in order that any changes in one of the views would trigger changes in the bound/synced ones. The main component is called a master one while the bound one is a slave. Master view appears to be the datasource for the slave one.

There are 2 main ways to link data:

  • when data in master component changed - slave control gets new data; // syncing
  • when selection in master component changed - slave control gets new data. // binding

In both cases, based on configuration

  • slave can take new data from master component;
  • slave can take new data from server side.

Binding and Syncing - Difference

When you bind data to any component it means that when you select an item from one component, this item will be the datasource for another component. Most typically, binding is used with some data-presenting component and a form / htmlform.

When you sync data, it means that the whole visible data from one component is at once copied to the other.

Data Binding

Data binding is implemented with the help of the bind function that is called from the slave component and has a master component as parameter.

$$('htmlform1').bind($$('list1'));

In this case, selection of any list item will result in the form filling with data from the list. Be careful to specify name property for input fields in the form/htmlform. Its values must coincide with template items of the master component (in case of datatable look at column ID-s):

  • component template item = field name in a form;
  • datatable column ID = field name in a form.

Changes in the slave component will affect master one, which means that if you edit the info in the form, then save it (click sumbit button), the list item will have this new data.

$$("htmlform1").save();

Related sample: Binding to a native HTML form

Slave can as well be unbound from the master by the opposite method:

$$('htmlform1').unbind();

From now on, list changes cannot affect form data and vice versa.

Adding data to master collection When no item is selected in a master component (here:list), data in the slave one can still be pushed to it.

In other words, if you call save() method for the bound form when no item is selected in the master, a new item will be added to master collection.

The only thing you should do is to remove selection in the master:

$$("list1").unselectAll();
//or
$$("list1").setCursor(null);

Related sample: Binding to List

Advanced Binding

Data binding features a lot more advanced options to explore:

  • it is subject to customization with the help of additional parameters;
  • it is suitable for binding hierarchical structures;
  • it features event system;
  • it has a native API to set default data for cases when no record is selected in the master control;
  • it utilizes cursor concept to bind to an invisible DataCollection;
  • a lot more..

Study the corresponding article for details.

Syncing Data of Two Components

Data syncing allows making a full or partial copy of data from one data-presenting component and pass it to the other one. Any change in the master component results in the same change in the slave one.

There can be more than one slave component. In this case, all slaves change simultaneously on master component change.

Note that this functionality works with components datastores, that's why data property is used everywhere.

Full Syncing:

The datasets of the two components are absolutely identical.

$$('slave_component').data.sync('master_component');

Partial (Filter-Based) Syncing

Slave view shows only the data items that comply to a certain criterion defined by the function. Here only the films shot after 1994 will be shown.

$$('dview2').data.sync($$('listA'), function(){
        this.filter(function(data){
        return data.year > 1994;
    });
});

Unsyncing

If the syncing functionality is no longer needed, you can call the unsync command for the component that was previously synced with another one:

$$('dview2').data.unsync();

Related into on data filtering.

Simultaneous Operations within Synced Componens

In case of two and more component synced to one datasource (either a visible component or non-visible dataCollection), it seems nice to synchronize user operations as well.

For instance, if an item is selected in one of components, the same item should be selected in the synced one. This is easily done programmatically.

Take for instance we have a dataview and datatable, both synched with the same dataCollection.

var data = new webix.DataCollection({
    url:"../my_data.json" //load data from an external file
});

$$("dataview_1").sync(data);
$$("datatable_1").sync(data);

The event system for selection offer the onAfterSelect event. The function that is fired on this event takes the ID of selected item as parameter:

$$("dataview_1").attachEvent("onAfterSelect", function(id){
    $$("datatable_1").select(id);
}); //item ID of dataview coincides with that of datatable  row

$$("datatable_1").attachEvent("onAfterSelect", function(id){
    $$("dataview_1").select(id.row);
}); //item ID of datatable row coincides with that of dataview item

Related sample: Data Binding

Data Binding and Syncing with Non-UI objects

One-Time Syncing

One-time syncing allows for synchronizing the data of two components (one of them can be DataCollection) at a chosen time of the application flow without tracking data changes afterwards.

Such syncing presupposes populating one component with the data of another one and is done with importData method:

$$("listB").data.importData($$("listA"));

Note that it's a DataStore method, so it should be called for component data.


Data Binding and Syncing with Non-UI Objects

The webix library contains view-less yet meaningful elements. They have no graphic representation and are used to store data in them.

  • DataValue - stores a single value like any input control (text, button, label, etc.);
  • DataRecord - stores a single record like form and htmlform;
  • DataCollection - stores a non-hierarchical collection of records (like list, dataview, datatable, etc.);
  • TreeCollection - stores a hierarchical collection of records (like tree and treetable).

These collections can store data and have the same API as their "visible" siblings. Such methods as bind() and sync() can be used with them as well.

How can you benefit from them?

DataCollection and TreeCollection Usage

Non-ui components store some info you'd like to use later in visible components. For instance, in the DataCollection you can specify the needed dataset and later on, sync all the data-presenting components with it so that they all are fed with the same data.

var data = new webix.DataCollection({
    template:"#rank#. #title# - #year#",
    data:big_film_set //the datasource
});

Now let's init the list and sync it with out invisible DataCollection

webix.ui({
    view:"list",
    id:"list",
    template:"#rank#. #title# - #year#",
    data:"" // we needn't specify anything here
});

$$('list').data.sync(data);

Now, if we bind a form to the DataCollection, it will be a slave view in relation to the synced list as well! And any data from the form will be added to dataCollection, and then to list.

However, data will not fill the form unless we refer to cursor concept.

Cursor Concept

Cursor position is the ID of an item that the cursor is set on. Cursor should be set in case several components are bound to/synced with one and the same source, e.g. one and the same DataCollection, in order to avoid conflicts between different component referring to one and the same datasource and making changes upon it.

The invisible dataCollection is a master component for both the form and data-containing components synced with it. But since it's invisible, data cannot be operated on. The issue is solved by using any component to set cursor to an item from dataCollection each time this item is selected in the chosen component.

For instance, you'd like a list to be "volonteer" to get to dataCollection during form filling.

$$('list').attachEvent("onAfterSelect", function(id){  data.setCursor(id); });

As a result, data is saved to dataCollection after editing as well as to all the synced components without any additional manipulations.

Related sample: DataCollection Syncing

Server-Side Integration with non-UI Components

Server-side work is enabled with dataConnector to load data and dataProcessor to save changes back to the database. It can be used for both "visible" and "invisible" (non-ui) components.

To use dataProcessor with dataCollection synced with some component on the page, you should go through a three-stage process.

1 . Define a dataCollection and populate it with data from the database:

store = new webix.DataCollection({
    url:"../common/connector.php",
    datatype: "xml"
});

2 . Declare a dataProcessor for the dataCollection:

var dp = new webix.DataProcessor({
    master: store,
    url: "../common/connector.php"
});

3 . Sync a data-presenting component with the dataCollection:

list.sync(store);

Related sample: Data Syncing with DataCollection

DataCollection and Datatable Syncing

DataProcessor and server-side integration work the same way with all components yet in case of datatable extra functionality appears.

DataConnector allows rendering data from one table into a component (render_table method) or displaying data from several tables using custom SQL-query (render_sql method). More info about this in the Serverside Integration article.

Working with Database Tables: ID-to-Text Transformation

Tables in the database are often connected by ID while on client-side, within the component, we require that text values should be shown. The solution hides in loading data from the needed tables into different dataCollections and refer to datatable colummn configuration to render the database data.

First, create several dataCollections and load data from connected database tables.

Table Rendering

var employee = new webix.DataCollection({
    url:"data/employees.php",
    save:"connector->data/employees.php" //dataprocessor, short init form
});

var customers = new webix.DataCollection({
    url:"data/customers.php"
});

var orders = new webix.DataCollection({
    url:"data/orders.php",
    save:"connector->data/orders.php"
});

What is there in these collections?

While database connect parameters are the same for two collection, they differ in tables they render:

--library connectors for working with server side
require_once("./config.php");
$data = NEW JSONDataConnector($db,"SQLite3");

--for employee collection
$data->render_table("employees","id","email, fullname, login");

--for customers collection
$data->render_table("customers","id","lastname, firstname, job, address, city, zip, country");

--for orders collection
$data->render_table("orders","id","date, employee, customer, status [,other fields]);

Then create a datatable and sync it with either fo these collections.

$$("dash-ord-active").sync(orders);

This will be the main datasource for the component. As far as in the "orders" table contains just IDs of dedicated customers and orders, they should be transformed into text while rendering to datatable .

For these needs there's a collection property in datatable column API to point to a datasource different from that of the whole component.

{ view:"datatable", id:"dash-ord-active",
 columns:[
        { id:"date", header:"Order Date" },
        { id:"employee", header:"Employee", collection:employee},
                { id:"customer", header:"Customer", collection:customers},
                { id:"status", header:"Status" },
                { id:"fee", ...},
                { id:"taxes", ...},
                { id:"total", ...} //other columns
        ]
}

Two columns for the datatble are fed directly from employee and customers collection where they get text values instead of ID-s.

Datatable column configuration is described in related datatable documentation.


Working with Bound Components

Binding makes selected record of one component a datasource for another. The basic binding tie is established between two components using their IDs of variables they are stored in (if any).

$$("myform").bind(list);

It has already been described.

Here different aspects of bata binding are examined.

Binding Rules

The bind() method can take two optional parameters to customize the binding pattern - rule format.

The customization is only possible in case slave component is based on DataStore (all data management components except for tree-like) or TreeStore (tree and treetable).

Binding rule defines a scheme according to which records in the slave component are filtered. It can be either a string or a function.

Binding rule as a function

As function, binding rule takes 2 parameters:

  • slave - slave data object;
  • master - master data object.

Slave list displays records with category equal to master value

$$("list").bind($$("richselect"), function(slave, master){
    return slave.category == master;
});

Here list data is filtered according to the option you choose within a richselect control.

Related sample: List Data Bound to Richselect

Additionally, binding rule can cancel bind applying in runtime.

Slave datatable displays only records with movie property equal to master record ID

gridb.bind(grida, function(slave, master){
        if (!master) return false; //cancelling bind applying
    return master.id == slave.movie;
});

Here binding is cancelled in case no data is sent from master (i.e. no record is selected in master).

Related sample: Linking tables

Binding rule as a string

If master component is loaded with hierarchical data you can define a binding rule with the help of the following flags:

  • $level - only immediate children of a selected item are pushed to slave component. By default children are introduced by data key in all the supported data formats:

Grid will show only children of a selected tree node

$$("grid").bind( $$("tree"), "$level");

Input JSON of such a tree is as follows:

{ id:"..", value:"..", data:[
    //will be shown in slave component
    { id:"..", value:".." },
    { id:"..", value:".." }
]}

Related sample: Tree Data Binding

  • $data - the object of a selected item (without children) is pushed to a slave component. Here you should pass the format of subdata presentation to specify data items necessary for the slave.

Format of bound data presentation

Format can be a string that defines the key by which desired data is set in the item object. As a rule, it differs from the key by which children are set (if they are set via "data" (default), it's more reasonable to use $level rule):

$$("grid1").bind( $$("tree"), "$data", "records");

Input JSON data of such a tree is as follows:

{ id:"..", value:"..", records:[
    //will be shown in slave component
    { id:"..", value:".." },
    { id:"..", value:".." }
]}

Related sample: Data binding - subdata

Format can be set via a function where you describe binding behavior manually:

$$("grid2").bind( $$("tree"), "$data", function(obj, source){
    if (!obj) return this.clearAll();
    var fulldata = [].concat(source.data.getBranch(obj.id)).concat(obj.records);
    this.data.importData(fulldata, true);
});

Here we get item chilren with the help of a getBranch() method, combine them with data set by records key and import the resulting array into slave datatable.

Related sample: Data binding - subdata

Binding Events
  • onBindApply – fires the moment binding is applied;
  • onBindRequest - fires when the component is ready to receive data from the master component;
  • onBindUpdate – fires when the value in the slave view changes and save() is called to update master.
$$("files").bind($$("folders"));

$$("files").attachEvent("onbindapply", function(){
    // makes the preview template empty
    $$("preview").setHTML("");
});

Preventing from Undefined Values

What happens when no selection is made in the master component? If no measures are taken, the slave component would show undefined values.

This concerns only data components that have template property in their constructor and doesn't concern form and htmlform where binding is set according to the names of their inputs.

The defaultData property of the master one helps solve the problem.

webix.ui({
    rows:[
        {view:"list",
        template:"#rank#.#title#",
        data:...
        defaultData:{
            rank:"0",
            title:"default Item"
            }
        },
        {view:"template",
        template:"#rank#.#title#"}
    ]
})

$$("template1").bind($$("list1"));

Related sample: Default Data

Now, when no item is selected in the list, template will show default values (as set by the defaultData) instead of undefined ones.

Look to CollectionBind API for more details.

Cursor Concept for Bound Collections

Cursor concept is used to control focus within the application with bound and synced data-management components. Its position is the ID of the active data item.

Simply put, cursor stores the ID of a data item from the master control for which binding is performed at the moment.

You can get and set cursor position with the help of the following methods:

  • setCursor(cursor); - string, number - sets the position of the cursor, the ID of the necessary data item.
  • getCursor(); - gets the current cursor position.
var cursor = master.getCursor();

Cursor can be deleted to remove the current bind link:

master.setCursor(null);

If a form (slave) is bound to a list (master) and cursor is removed from the list - form will be emptied.

Cursor is as well useful when working with non-visible DataCollections.

Using Binding for Server Side

As a rule, slave component doesn't communicate directly from server-side. It receives data from the master view it is bound with and the changed data is sent first to the master that handles communication with the server.

However, there exists a possibility to get serverside data for the slave based on master selection - dataFeed functionality.

webix.ui({
    view:"form",
    id:"myform",
    ...//config
    dataFeed: "slave_data.php"
});

$$("myform").bind($$("mydatatable"));

Datafeed defines URL that will be used by slave control to sent serverside request the moment selection in the master component changes.

The functionality works the same for form and collections (data components) yet the URL parameters differ:

  • for forms the request URL looks like: "slave_data.php?action=get&id="+obj.id
  • for data components the request URL is as follows: "slave_data.php?filter[id]="+obj.id

where obj is selected data item in the master component.

Saving Data of Multiple Bound Forms

When a form is bound to a component, data from the selected item is transmitted to the form as well as any changes you make within the form are saved automatically to the selected item.

It happens on calling the save(); method

$$("myform").save();

But if you have two forms bound to one and the one component and you save each of the forms separately, the data from the previously saved one is lost. The solution is the saveBatch() method that makes simultaneous saving of several forms.

It is called from the master component rather than from either of the slave forms.

$$("mydatatable").saveBatch(function(){
     $$("myform1").save();
     $$("myform2").save();
});


Intermediate

Data Updating

Component items can be edited within the component itself, within its rows and cells, provided that the component is switched to editable mode.

Data updating allows for editing info in dedicated input fields like UI text. It works regardless of the component's editability state.

Updating data for selected items can be implemented in two ways:

  • one by one - with the help of updateItem() function;
  • in groups - by pushing data from bound form / htmlform. Data Binding

UpdateItem() Function

Updating process happens in two stages:

1 . Placing selected data to some editor (ui-related text or dedicated HTML input field) with the help of an attached event.

<input type="text" id="value" style='width:300px' value="new value" />
...
$$('mylist').attachEvent("onAfterSelect", function(id) {
    var value = this.getItem(id).title;
    document.getElementById("value").value = value;
}); // as a result, the item title from the dataset appears in the text field

2 . Saving the edited data back to the component. It is implemented with an update function that takes ID of selected item as argument. Called from component object, it is included into the complex update function.

function update_item() {
    var data = $$('data'); // ID of the data-presenting component
    var sel = data.getSelectedId(true);
    if (!sel) return;  //if nothing is selected, there's nothing to update!
    var value = document.getElementById("value").value; //deriving new value from the input
    for (var i = 0; i < sel.length; i++) {
        var item = data.getItem(sel[i]);
        item.title = value; //setting the new value for the item
        data.updateItem(sel[i], item); //the dataset is updated!
    }
}

Related sample: Server-side Integration: Dataview

Form / HTMLform binding

Data binding helps greately simplify the process and makes editing of several item values convenient. It ensures that a data component (dataview, list, etc.) transmits data to a form / htmlform each time an item there is selected.

More info on Data Binding

$$('htmlform1').bind($$('listA'));

The function above makes list a datasource for form, so when an item in the list is selected, the form is filled. Input names in the form must coincide with item properties from teh initial dataset (those you include into #hash signs# within data template) for the list.

Having finished editing data in form fields, call the save function to push new data into the list.

<input type="button" value="Submit" onclick='$$("htmlform1").save()'/>

Related sample: Data Binding

The same functionality is used when updating data items loaded from the database. Read about Server-side Integration in the corresponding chapter of the documentation.


Configuring Components

  • Managing Visibility of Components
  • Disabling/Enabling Components
  • Adding Headers to Components
  • Dynamic UI Modifications
  • Adding and Deleting Multiview Cells Dynamically
  • Changing Properties of Components
  • Sizing components
  • Resizing Components
  • Scroll Control
  • Date and Number Localization


Beginner

Managing Visibility of Components

By default, all ui-related components except for window and popup are visible on the page after their initialization.

Show() and Hide() methods

To show and hide any component in layout you should call show() and hide() methods respectively:

$$("my_window").show();
$$("my_button").hide();

The alternative to the hide() is a hidden:true parameter that is included into the component constructor. The component can be shown later with the show() method.

When manipulating visibility of components it seems useful to know whether the component is visible on the page at the moment. This can be checked with the help of isVisible() method that return true or false depending on the component's state.

$$("my_window").isVisible();

Manipulating Visibility of Control Groups

At the same time the library allows grouping controls and changing their visibility in groups. It's useful when you want to define different button sets for different states of the application.

To show and hide groups of elements you make use of the batch property and associated with it showBatch() method.

Batch groups elements by one and the same value that is as well assigned to each of the needed controls.There can be as many batches as you wish depending on the quantity of the manipulated controls.

One of the batches(groups) is shown initially. It is defined by visibleBatch property.

Take following steps to use this functionality

1 . Include batch property into desired controls.

webix.ui({
        view:"toolbar", visibleBatch:"1", // batch "1" is visible initially
        cols:[
            {view:"button", value:"first", batch:"batch 1", align: "left"}, //various controls
            {view:"button", batch:"batch 2", ... },
            {view:"button", batch:"batch 3", ... },
            { ....}
            ]
     });

2 . Assign the function to change visibility of controls to a suitable control.

Here radio options coincide with batch values from the code above:

    { view:"radio", id:"rad", label: "select", click:"change_batch", options:[
        "batch 1","batch 2", "batch 3"
        ] } //chanding radio buttons triggers the function execution

3 . Write the function to show the controls with the chosen batch value.

function change_batch(){
    var mode = $$("rad").getValue(); // returns "batch 1", etc..
    $$("mybar").showBatch(mode); //the value is passed into the function
}

Related sample: Hiding and Showing Groups of Controls


Beginner

Disabling/Enabling Components

webix UI library allows tempoparily disabling functionality of some component. It remains visible yet becomes dim, and neither of it's elements works.

The functions to disable and enable components are as follows:

$$("cell").enable();
...
$$("cell").disable();

Related sample: Disabling Components

When can it be useful?

  • For instance, you have a dataview and a form and want to disable a form until an item from the dataview nearby is selected.

  • Or you want to temporarily disable a component until server operation is performed (e.g. data saving) in order that users can't click buttons and make selection.

To check whether the component is enabled or disabled now, use the appropropriate method:

$$('cell').isEnabled(); //returns boolean values


Intermediate

Adding Headers to Components

Header is a blue section above the main contents of a component or layout row/column.

Depending on the context, header is defined in two ways:

  • as template type;
  • as component property.

Related sample: Window with a Component Inside

Header as Template Type

This way of header initialization is used within layout rows and columns. Here header is just one of template types.

If you want to make a header for, say, dataview, make two rows and place header in the first row while the dataview should be in the second one.

Type:"header"

webix.ui({
    rows:[
        { view:"template", template:"some text", type:"header" }, //1st row
        { ....} //2nd row
        ]

});

BTW, another template type, namely section, allows for setting a specific header that looks like a thin line that encircles the component and has a heading above.

Type:"section"

{ view:"template", template:"some text", type:"section" }

During header initialization the view:template line is optional.

Related sample: Template Types

Header as Component Property

Still, some components have built-in means of header building.

  • Accordion Items
  • Tabview Tabs
  • Property Sheet

Accordion item is divided into body and header

{ view:"accordionitem", header:"Pane ", body:"text' }

Headers of tabview tabs are defined as header properties of tabview cells:

{ view:"tabview",
  cells:[
    {
      header:"List",
      body:{
        view:"list", ...
      }
    }
  ]
}

Related sample: Tabview: Basic Initialization

Property sheet looks like a grid with sections separated by blue headers. In essence, any line without data becomes header, the heading text being defined by label property.

 { label:"Layout" }, //header
 { label:"Width", type:"text", id:"width"}, //line with data

Related sample: Property Sheet: Basic Initialization

UI-related window features header defined by its head property.

Adding buttons into the header

Since a header is a template, only HTML-buttons can be added into it. If you want to add some buttons into the header of a component, the best solution is to use the Toolbar component:

webix.ui({
  view:"toolbar",
  cols:[
    { view:"label", label:"Projects", width:400,},
    { view:"button", value:"Load" },
    { view:"button", value:"Save" },
    { view:"button", value:"Info" }
  ]
});

Related sample: Toolbar with Buttons in the Header


Dynamic UI Modifications

Webix lib offers several ways to alter the already initialized layout:

  • you can add any view to the existing layout, including complex views that have a number of child components;
  • you can remove any view from existing layout;
  • you can reconfigurate layout-like comopnent by passing an array of new children views to it;
  • you can replace any view in layout by another view.

Let's consider these possibilities in detail:

Adding/Removing Views Dynamically

You can add and remove components dynamically after you've already initialized layout and set some components. It works for:

  • layout rows and cols;
  • multiview cells;
  • accordion and carousel panels;
  • toolbar controls;
  • form controls.

Adding and removing views is implemented with the help of the addView() and removeView() methods.

Adding View

To add the new view (layout row and column, multiview cell, accordion panel, as well as any toolbar or form control) - specify the view object and position to insert.

Adding a button to the toolbar

var id = $$("toolbar").addView({
    view:"button", value:"new button",
}, index);

Index defines position where the new component or control should be inserted among the children of the parent component. It can be

  • first (index 0);
  • last (index -1);
  • any. Index of any view can be derived with the help of index method that can be called for layout-like Webix components (layout, multiview, accordion, carousel, form, toolbar).

Adding View

webix.ui({
    id:"layout1",
    rows:[
        {view:"text", id:"text1"},
        {view:"button", value:"Add View", click:addView}
    ]
});

var pos = $$("layout1").index($$("text1"));
$$("layout1").addView({view:"text", id:"text2"}, pos);

Related sample: Adding Views

The newly added view can be sized during adding according to common rules as well as later on via property (re)defining.

Removing View

removeView() method removes components from layouts and is called from the parent component to remove any of its children. The method takes a child view object or its id as an argument.

Removing a button from the toolbar

$$("toolbar").removeView(id);

Related sample: Adding Views

Rebuilding Application Layout

Here we look at advanced possibilities of webix.ui() method.

Besides its main purpose - instantiation of Webix component, it method can also be used for changing layout provided that additional params are passed to it.

All in all, its parameters include:

  • configuration object - (object, array) - a JSON object with the application config of any level of complexity;
  • parent element - (id or object) - Webix component that acts as a parent to an object you are going to init (first param);
  • replacement object -(id, index or object)- Webix component in a parent object that will be replaced by an object you are going to init (first param).

Thus webix.ui() constructor can be used to:

  • redraw layouts (layout, multiview, form, accordion) that feature arrays in their structure:
webix.ui({
    view:"form", id:'myform', elements:[...]
});

//redraw form with new elements
webix.ui([..new elements..], $$('myform'));

Related sample: Dynamic Layout Rebuilding

  • replace any existing object:
webix.ui({
    id:'mylayout',
    rows:[
        {view:'toolbar', ...},
        {view:'datatable', id:'mydatatable' ...},
    ]
});

//replace datatable
webix.ui({..new config..}, $$('mylayout'), $$('mydatatable'));

Related sample: Dynamic Layout Rebuilding

Reloading layout from the server

To load a new configuration from the server - you can use the following technique:

webix.ajax("config.json", function(text){
    webix.ui(webix.DataDriver.json.toObject(text), $$('mylayout'), $$('mydatatable'));
});

where the config.json contains the new configuration.


Adding and Deleting Multiview Cells Dynamically

Here two approaches are possible:

1 . If you are using multiview with a switching control (tabbar or segmented) - you should treat multiview and a switching control separately. In other words you should add and remove options for tabbar (segmented button) and at the same time add and remove views for the multiview.

2 . If you are using tabview (integral component that consists of a built-in multiview and tabbar) - note that it features dedicated methods to add and remove views together with the corresponding tabs.

Using Tabbar and Multiview

Both Tabbar and Segmented Button feature separate parts - tabs or segments - that are defined by options property.
Each of its options can be connected with a separate view or a separate click handler.

Table 1 Switch controls
view:"segmented"
view:"tabbar"

Tabs/segments can be added and deleted on the go with the help of the following methods:

  • addOption() - adds a new tab/segment according to the provided configuration;
  • removeOption() - removes the tab/segment according ot the provided ID.

Multiview cells can be added and deleted denamically by using:

  • addView() - adds view to layout (multiview is layout) according to the provided configuration;
  • removeView() - removed layout cell by the given ID.

Adding

rows:[
    {view:"tabbar", id:"tabs", multiview:true, options:[], ..}, //empty tabbar
    {view:"multiview", id:"views", cells:[
        {template:"..."} //multiview should have at least one cell
    ]}
]
...

function open_new_tab(id){
    var item = $$('list1').getItem(id);

    //adding a new cell to multiview
    $$("views").addView({ view:"template", id:item.id, template:item.title});
    //adding option to the tabbar
    $$('tabs').addOption(item.id, item.title, true);
};

Deletion

function del_tab(){
    //getting the ID of the active tab
    var id = $$("tabs").getValue();

    //removing tabbar option
    $$("tabs").removeOption(id);

    //removing corresponding view
    $$("views").removeView(id);
}

Related sample: Dynamic Adding/Deleting of Tabs in Tabbar

The logic of view adding and removal can be studied in detail in the
Dynamic UI Modifications.

Using Tabview

Tabview is a hybrid of a multiview and tabbar.
It features two methods that allow adding and removing cells together with corresponding tabs.

Each combination of a tab and a cell is configured as:

{ header:"header_title", body:{ ..view config ..}

The same configuration is passed into the addView() method:

$$("tabview1").addView({
    header:"New Tab",
    body:{ //webix.uid() generates a random number
        template:"New content "+webix.uid()
    }
});

The tabview cell can be removed by removeView() method that required an ID if this cell:

var id = $$("tabview1").getValue(); //id of active cell
$$("tabview1").removeView(id);

Related sample: Tabview: Adding and Removing tabs

Built-in Tab 'Close' Button

Webix tabbar can be equipped with a 'Close' button:

//all tabs
{view:"tabbar", close:true, options:[]}

//some tabs
{view:"tabbar", options:[
    {id:1, value:"Tab 1", close:true},
    {id:2, value:"Tab 2"}
]}

If a closable tab is used in a separate tabbar, you should provide logic to remove the corresponding view.

tabbar.attachEvent("onOptionRemove", function(id, value){
    $$("multiview").removeView(id);
});

ID of the tab concides with ID of the view, normally.

If a closable tab is used within a tabview, the corresponding tab will be removed from the app automatically.


Intermediate

Changing Properties of Components

Defining New properties

The properties of Webix components can be changed after initialization each time the define() method is applied to them. It takes the following arguments:

  • a component's property you want to change;
  • the new value for this property as arguments.

The method can be applied to any object pointed to by its ID:

//loads new data to the list
$$("mylist").define("url", "new_data.xml");

//sets new height for the list
$$("mylist").define("height", 300);

//changes the label of the button
$$("button1").define("label", "New value");

The method as well takes hash of property-value pairs to change multiple properties at once:

//set new data and height for the list
$$("mylist").define({
    url: "new_data.xml",
    height: 300
});

Webix has rich API that allows performing various operations and can be used instead of the define() method. So we advise you to look up a suitable method in the API reference before use the define() method.

Applying Property Changes

In order that new properties came into force, you should apply either of these methods to the redefined component:

  • refresh() - used to repaint a single component and doesn't affect page structure. It's used for data-containing components (list, datatable, chart etc. and all controls).
  • reconstruct() - used to rebuild the component that affect page structure. It concerns components that build application layout and house other components and control: layout, multiview, accordion, carousel, form and toolbar.
$$("layout").define("rows", [ {view:"button", ...}, {view:"label", ...} ]);
$$("layout").reconstruct();

The reconstruct() method is out-of-date. We recommend you to use more modern techniques of rebuilding components that are described in the section Rebuilding Application Layout.

  • resize() - adjusts a component to the new size.

Changing the Component's Config

The desired configuration parameter can be accessed and changed through the config property as well.

//reading height
var height = $$("myList").config.height;
//setting new height
$$("myList").config.height = 400;
$$("muList").resize();

Changing component properties via config comes handy when getting and setting values for component items that are stored in an array that is a property itself.

Defining width of a datatable column

webix.ui({
    view:"datatable",
    id:"mytable",
    columns:[
        { id:"col_1", header:"Film title",width:200},
        { id:"col_2", header:"Released" , width:80}]
        })
//reading 1st column width
var colWidth = $$("mytable").config.columns[0].width; // 200

//resizing the 1st column

dtable.resize();

Redefining Item Properties

Type with data-containing components denotes the way each data item looks like rather than look-and-feel of the whole component.

webix.ui({
    view:"list",
    type:{
        width:200, //item width
        height: 50
        },
    width: 250 //list width
    ..
});

To redefine width of the item, you should use customize() method instead of define() - the arguments are the same:

$$("list1").customize({ width:210}); //item width changes
$$("list1").refresh();

More about Type Implementation.


Beginner

Sizing components

You can set dimensions for the components and their items in 5 ways:

  • Fixed Sizing
  • Auto Sizing
  • Adjusting mobile apps to screen size
  • Relative Sizing
  • Dynamic sizing

Later on, you can dynamically resize the components.

Fixed Sizing

Fixed dimensions are set by width and height parameters that can be applied to components and their items as well as to the whole layout.

Layout Sizing

webix.ui({
    id:"layout",
    height:600,
    width:700,
    rows:[
        {template:"row 1",height:20},
        {template:"row 2"},
        {cols:[
            {id:"a1", template:"column 1", width:150}
        ]}
    ]
}).show();

Related sample: Layout and Resizer

When giving fixed dimensions to the components in layout, don't forget that layout rows and columns will adjust to the sizes of the nested components automatically.

Control Sizing

Controls feature inputWidth and inputHeight properties that define dimensions of input areas and button text values.

Button Sizing

{ view:"button", value:"Prev", type:"prev", width:100, inputWidth: 70, height:20 }

Read more about the possibilities of control sizing in the Controls Guide

Component Item Sizing

If you want to specify the dimensions of an item rather than the component, include height and width parameters into the component's type property .

Dataview Component and Items with Fixed Dimensions

webix.ui({
    view:"dataview",
    width: 520,         //  component's dimensions
    height: 270,
    type:{
        height: 90,     //  dimensions of each dataview item
        width: 250
    }
    ...
});

Related sample: Dataview Italic

Sizing Limits

During dynamic resizing or when the component is initialized in layout with at least one resizer line, minimum and maximum dimensions are very helpful. They are set with the help of the following properties:

  • minWidth and minHeight (number) - on resizing the component cannot takes less space than specified. If more space is available, the component will take it.

  • maxWidth and maxHeight (number) -on resizing the component cannot take more space than specified. At the same time, the component may take smaller width nd height values and take smaller space.

Auto Sizing

1.Autosizing to the dimensions of the parent container.

By default components are autosized to the dimensions of the parent HTML-container.

Inline CSS

<div id="areaA" style="width: 320px, height: 400px"></div>
<script type="text/javascript" charset="utf-8">
    webix.ui({
         container: "areaA", //corresponds to the value of <div> id parameter
         view:"list",
         ...
    });
</script>

Auto sizing adjusts the component or its item to available space (parent container, if these's the one; otherwise, to the document body). If there're several components or several layout columns on the page, each of which, they will equally distribute available space among them.

2.Content Autosizing.

If you define autoheight as true the height of layout rows will be adjusted to their contents.

How does this property work? By setting autoheight to the template we let it 'go' to its contents (text, as a rule) and calculate itself the height of the text on the screen. This height will be the template's height and the corresponding layout row will adjust to this parameter.

Autoheight for view Template

rows:[
    { template:"html->my_box1", autoheight:true},
    { template:"Area 1"},
    { template:"html->my_box2", autoheight:true}
]

Related sample: Autosizing to Content

Some components also feature the autowidth property.

3.Item Content Autosizing

To adjust item's width to its contents you should use adjusting or auto height depending on the component.

Datatable column width is adjusted to its contents:

Datatable Column Sizing

columns:[
    { id:"rank", header:"", css:"rank", adjust:true },
    ...
]

Related sample: Adjusting columns to the content

Auto height is set within component type that defines properties of an item (not the whole component). Each item is adjusted to its content, which may result in variable dimensions of items:

//list with variable item height
webix.ui({
    view:"list",
    width:250,
    type:{
        height:"auto"
    }
});

//dataview with variable item width and height
webix.ui({
    view:"dataview",
    width:250,
    type:{
        height:"auto",
        width:"auto"
    }
});

In addition, component width and height can be adjusted to the predefined dimensions of HTML elements of its items. For these needs, set sizeToContent property for a component:

Dataview Item Sizing

webix.ui({
    view:"dataview",
    template:"#title#<br/> Year: #year#, rank: #rank#",
    sizeToContent:true
});

Note that even in case these HTML elements are different for different items, the dimensions are measured only once (for the first input, as a rule) and then sizing is performed. At the same time, some of them may be smaller or bigger.

Related sample: Autosizing Items to Content

Adjusting Mobile Apps to Screen Size

Webix offers “full screen” mode to make the application take all available screen space. In this mode, the app will take up the entire screen of the mobile device.

Fullscreen mode is enabled with webix.ui.fullScreen() command before UI initialization:

webix.ui.fullScreen();
webix.ui({
    rows:[...]
});

Relative Sizing

Relative dimensions can be defined with the help of the {gravity:x} parameter which makes one component x times bigger then the other.

One of the 'Save' buttons is twice bigger then the other one.

webix.ui({
    view:"toolbar",
    { view:"button", value:"Load", width:200 },
    {  margin:4, borderless:true, rows:[
        { view:"button", value:"Save",  gravity:2 },
        { view:"button", value:"Save"}
         ...
    ]}
});

Related sample: Toolbar: Multiple Rows

Dynamic Sizing

Dynamic sizing ensures adequate visibility of components regardless of screen size and makes them dynamically respond to changing window dimensions.

By default, dynamic sizing is true for components that feature no sizing of their own and are not placed into any sized HTML container. Such components take space of the entire screen and are resized as the browser window resizes.

To enable dynamic sizing in other situations, take the following steps:

  • create div container and give relative dimensions to it;
  • put a Webix component into it (define the container property within the component);
  • ensure that the component is adjusted to its container each time you resize browser window.
<div id="testA" style='width:50%; height:50%;'></div>
...
grid = new webix.ui({
    container:"testA",
    view:"datatable",
    ...
});

webix.event(window, "resize", function(){ grid.adjust(); })

Note that events to HTML nodes are attached via event() method rather than attachEvent().

Related Articles:

  • Event Handling
  • Component Resizing


Intermediate

Resizing Components

The component can be resized in two ways:

  • Setting new dimensions to the component itself and applying resize().
  • Setting new dimensions to the component container and applying adjust() to the component.

On-page resizing with resizer lines and responsive behavior on window resizing is discussed separately.

Resizing the Component

The component is resized by changing values of its width and height properties.

The properties can be changed in two ways:

  • with the help of define() method:

Resize the dataview from 500px to 700px in width

dtable = new webix.ui({
    view:"datatable",
    width: 500,
    ...
})

dtable.define("width", 700);
dtable.resize();

//or both width and height
dtable.define({
    width:700,
    height:500
});
dtable.resize();

Related sample: Dynamical adjusting to the parent container

  • by getting directly to the component config:

Changing dataview width and height

$$("dview").config.width = 261;
$$("dview").config.height = 700;
$$('dview').resize();

Related sample: Resizing

Resizing the Component's Container

Container is an HTML node you place your component into.

When you resize the container size and (optionally) call adjust() method for the component in it - component will change its dimensions to match with the container new size.

Placing datatable in testA container

<div id="testA" style="width:500px;"></div>
...
grid = new webix.ui({
    view:"datatable",
    container:"testA",
    ....
});

Container can be resized in two ways:

  • via DOM reference
document.getElementById('testA').style.height="455px";
grid.adjust();

Related sample: Resizing

  • using webix toNode() method:
webix.toNode("testA").style.width = "700px";
grid.adjust();

Related sample: Dynamical adjusting to the parent container

Component can be as well adjusted to the dynamically-sized container.

Resizing Several Components at a Time

If you need to resize several components lying inside one and the same parent component (like dataviews, lists, datatables inside one and the same layout with its own ID, you can redefine their dimensions, call the resize() function from the parent and pass the true parameter to it.

webix.ui({
    view:"layout", //optional
    rows:[
        {view:"dataview"},
        {view:"list"},
        {view:"datatable"}
    ]
});

$$("dataview1").define("width", 300);
$$("list1").define("width", 350);
$$("datatable1").define("width", 420);

$$(layout1).resize(true);

For altering dimensions of the component children use the corresponding method:

$$('accordion').resizeChildren();

Study the Sizing Components article to learn about initial component sizing.


Intermediate

Scroll Control

Webix provides extensive scrolling management tools.

  • Firstly, Webix components are supplied with vertical and horizontal scrollbars that can be shown and hidden programmatically;
  • Secondly, scrolling in the application can be controlled with the help of common methods and properties;
  • Thirdly, Webix library features a separate component called scrollview, a container view with scrollbars for placing any content there (plain text, HTML, Webix views);

By default, Webix uses native browser scrollbars. In Webix Pro edition custom Webix-made scrollbars are available.

Tuning Scrolling

By default, component features vertical scrolling. It can be modified via the dedicated scroll property that may take the following values:

  • "x" - sets a horizontal scrollbar;
  • "y" - sets vertical scrollbar (default);
  • "xy" - sets both horizontal and vertical scrollbars;
  • false - defines non-scrollbale component.
webix.ui({
    view:"list",
    id:"mylist",
    scroll:"x", //"y", "xy", false
    ..//config
});

Some components feature such properties as scrollX and scrollY that take boolean values to enable/disable the specified scrolling direction, so check a component's API Reference.

Scrolling and Dynamic Loading

With dynamic loading, only part of the stored records are loaded into the component during init. Each time you scroll down/up the component, a data request is sent to server to load the next portion of data.

Read more about dynamic loading.

Scrolling to a definite position in the view

If the dataset if too long (e.g. a collection of verses) it seems nice to have an ability to scroll to a definite poem automatically with a click of a button.

Here you have several possibilities:

1 . Make use of the component's scrollTo(x,y) method:

The function is called from a scrollview object and takes horizontal and vertical position of the necessary line into it. If you state this position as button's ID, the function will look like this:

function scroll(id){
    id=this.config.id * 1; //gets ID of the clicked button
    $$("verses").scrollTo(0, id); //scrolls through the view with the specified ID
}

Scroll position can be calculated during development state with the getScrollState() method that returns an object with X and Y parameters.

You can as well as set time for the scrollTo() function to perform.

webix.ui({
    view:"mylist",
    scrollSpeed:"100ms",
    ...
})

2 .Scrolling via focusing on the necessary view withtin the scrollview.

Here the button's ID should be connected to the ID of the row in the scrollview:

{ view:"button", value: '..', id: '1', click:"scroll"},
{ view:"button", value: '..', id: '2', click:"scroll"},

Then the showView() set focus to the scrollview item with the corresponding ID.

webix.ui({
    view:"scrollview",
    id:"verses",
    body:{
       rows:[
           { id:"verse_1", template:".."},
           { id:"verse_2", template:".."},
           { id:"verse_3", template:".."}
       ]
});

 function scroll(id){
            $$("verses").showView("verse_"+id);
        }

Related sample: Scrollview

3 . Make the view show the definite item specified by its ID:

$$("mylist").showItem(5); // the list should be scrollable

Related sample: Horizontal List

Within datatable scrolling via showing includes the following methods:

  • showItem(rowId) - scrolls to a definite row indicated by its ID;
  • showItemByIndex(rowIndex) - scrolls to a definite row dfined by data item index in the datasource;
  • showCell(rowID, cellID) - scrolls to a definite cell (both vertical and horizontal scrolling modes work).

Defining scroll position

Scroll state is defined as the combination of a top and left scroll position (how much is the component scrolled from its top and left border). In case you have either a horizontal or vertical scrollbar, the scroll state includes only one value - X or Y respectively.

Scroll position can be derived with the getScrollState() method to learn the current values:

var scPos = $$("mylist").getScrollState(); // returns data as ({x:30,y:200})
var posx = scPos.x; // 30
var posy = scPos.y; // 200

Webix Custom Scroll

The feature is available in Webix Pro edition only.

Webix offers custom scrollbars to replace native browser ones. The advantages are as follows:

  • semi-transparent thin grey bars feature neat design;
  • the bars are initially and hidden appear only when scrolling movement is detected on the page (provided scrolling is enabled).

Related sample: Custom Scroll

The feature is provided by a separate CustomScroll module that you need to enable before use.

Make sure you wrap everything into a webix.ready() function that is executed after page loading:

webix.ready(function(){
    //enabling CustomScroll
    if (!webix.env.touch && webix.ui.scrollSize)
        webix.CustomScroll.init();

    //your webix app
    webix.ui({
        ...
    });
});


Intermediate

Date and Number Localization

Different countries and regions have their own rules for writing dates, numbers and monetary units. All these issues should be taken in account in case a target group for your app is wider than one country or region.

The set of rules for this or that country is called locale and includes methods for date, time, number and price formatting. Localization methods belong to the i18n class and treat data according to he set format.

By default Date() constructor outputs raw data. Unformatted, it looks barely readable.

new Date(2012,10,30); //-->Tue Nov 30 2010 00:00:00

Date and time should be formatted either with Date or i18n class.

Numbers differ by delimiter before the fractional part and between thousands while prices should be rendered with an appropriate currency mark. Formatting is done either in the Number or i18n class.

Built-in Locales

The standard package of the Webix library includes 9 locales, namely:

  • 'en-US' - North American (used by default);
  • 'ru-RU' - Russian;
  • 'fr-FR' - French;
  • 'ja-JP' - Japanese;
  • 'be-BY' - Belarusian;
  • 'de-DE' - German;
  • 'es-ES' - Spanish;
  • 'it-IT' - Italian;
  • 'zh-CN' - Chinese.

Webix Pro edition includes over 300 locales to match a great variety of cultures.

Locale Structure

The way formatted date is presented depends on locale you use. Locale is a set of rules for dates, numbers and price units for this or that region or country. By default en-US locale is used.

en-US Locale

webix.i18n.locales["en-US"]={
  groupDelimiter:",",
  groupSize:3,
  decimalDelimiter:".",
  decimalSize:2,

  dateFormat:"%m/%d/%Y",
  timeFormat:"%h:%i %A",
  longDateFormat:"%d %F %Y",
  fullDateFormat:"%m/%d/%Y %h:%i %A",

  price:"${obj}",
  priceSettings:{
     groupDelimiter:",",
     groupSize:3,
     decimalDelimiter:".",
     decimalSize:2
  },
  fileSize: ["b","Kb","Mb","Gb","Tb","Pb","Eb"],

  calendar: {
    monthFull:["January", "February", "March", "April", "May", "June",
        "July", "August", "September", "October", "November", "December"
    ],
    monthShort:["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug",
        "Sep", "Oct", "Nov", "Dec"
    ],
    dayFull:["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",
        "Friday", "Saturday"
    ],
    dayShort:["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
    hours: "Hours",
    minutes: "Minutes",
    done:"Done",
    clear: "Clear",
    today: "Today"
  },

  controls:{
    select:"Select"
  }

  dataExport:{
    page:"Page",
    of:"of"
  }
};

Numbers:

  • groupDelimiter (string) - a stop mark to divide number groups;
  • groupSize (number) - the number of digits in each group. Typically it's 3 since thousands are the most frequent group;
  • decimalDelimiter - a stop mark to divide even number from fractional part;
  • decimalSize (number) - the number of digits in the fractional part;

Date and Time:

  • dateFormat, longDateFormat, fullDateFormat - define the way day, month and year look in stated modes;
  • timeFormat - defines the way hours, minutes and seconds look.

Start Date:

By default, a week in the calendar starts on Sunday. However, you can set any day as a start day using the webix.Date.startOnMonday property

webix.Date.startOnMonday = true;

Price states monetary unit applied to the data from data object ({obj}).

Calendar:

  • monthFull, dayFull (string) - an array of full and short month names for this location;
  • monthShort, dayShort (string) - an array of full and short day names for this location.

When formatted to a short/long date, the date from the first snippet looks like this:

Formatted with en-US locale

format:webix.i18n.dateFormatStr
    //--> 11/30/2010

format:webix.i18n.longDateFormatSt
    // --> 30 November 2010
  • hours, minutes - localization options for 'Hours', 'Minutes', 'Done' labels in the calendar.
  • today, clear - configuration for "Today" and "Clear" buttons, used for selection of current date and removing selection

Controls

Text labels for some parts of webix components that are more likely to be changed in a scope:

  • select - text label of the 'Select' button of the multisuggest (used in multiselect input, editor and filter). The default value for North American locale is "Select".

Data Export

Text labels used in the page numbering line in the footer of the exported PDF document.

  • page - text label of the "Page" part in the page numbering line
  • of - text label of the "of" part in the page numbering line

Applying a Locale

Locales other than en-US should be set manually.

First, you need to include the corresponding js file of the locale in the head of your page.

For example, to apply the French locale, include the fr.js file like this:

<script src="//cdn.webix.com/site/i18n/fr.js"></script>

Then you should apply the chosen locale with the help of the setLocale() function that takes locale name as a parameter.

webix.i18n.setLocale("fr-FR");

After this any method applied to the webix.i18n object will redraw date and numbers according to the rules described in the applied locale.

Formatted with fr-FR locale

format:webix.i18n.dateFormatStr
    // -->30/11/2010

format:webix.i18n.longDateFormatStr
    // --> 30 Novembre 2010

Altering a Locale

To change one or several parameters for the current locale, you need to redefine them and then apply the same locale so that your changes come into force:

webix.i18n.fullDateFormat = "%Y-%m-%d %H:%i";
webix.i18n.setLocale(); //locale name is not specified here

Setting Localized i18n Format

Localization is done via the i18n class and allows setting customized formats gathered under one and the same locale.

In case of datatable, format is stated by the dedicated format parameter while data is specified by column ID:

{ header:"Date",  id:"start", format:webix.i18n.dateFormatStr},
{ header:"Price", id:"price", format:webix.i18n.priceFormat}

Related sample: Internationalization

Other components like list, dataview and Tree have quite the other way of data presenting. To ensure proper formatting, you should make use of a template function:

template:function(obj){
    return webix.i18n.longDateFormatStr(obj.start)+"<br/>"+
       webix.i18n.priceFormat(obj.price);
}

The format in use is defined by current locale. EN-US (default) locale sets dateFormatStr as "%m/%d/%Y" while price format is set as "{obj}currency" where obj is price value.

Related sample: Dataview Formatting


Managing Data in a Component

Here you learn how to present and process data with the help of dedicated components differing in look and feel yet similar in functionality. They are as follows:

Chart, Datatable, Dataview, Grouplist, List, Property Sheet, Tree, Treetable, Unitlist

  • Data Object Operations
  • Selection
  • Adding/Deleting Data Items
  • Data Templates
  • Working with Dates
  • Data Filtering and Sorting
  • Data Validation
  • Editing Data Items
  • Data Editors
  • Paging
  • Drag-n-Drop within Webix Views
  • Working with the clipboard
  • Grouping Data Items
  • Undo for Data Components


Beginner

Data Object Operations

Every UI component features inner storage for loaded data:

  • DataStore - non-hierarchical (inline) store for list, dataview, datatable, chart;
  • Treestore - hierarchical store for tree, treetable and grouplist provided that they are loaded with hierarchical XML or JSON.

Both of the stores feature common methods, properties and events to work with data items on client side while TreeStore offers extended API for treating data items observing hierarchy.

While manupulating data items, you can:

  • apply methods directly to the Data/TreeStore of the component- $$("list").data. Only some functions require this.
  • apply methods to the component by its ID - $$("list"), which implies addressing datastore. Most methods have this pattern.
$$("list").data.each(function(obj){...}); //iterates through items array

$$("list").count(); //counts items in the list datastore

Each data item object posesses the unique ID, index in the data array and set of properties.

Getting the item object

To get the data item object, you should use the getItem method:

var mylist = webix.ui({
    view:"list",
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}
    ]
});

//'item2' variable will contain an object of the related list record
var item2 = mylist.getItem("book2");

//you can access data members directly
var title = item2.title;//-> "The Godfather"

Getting the item id

Each data item has its ID defined in the dataset. Knowing item ID you can get to all its properties through an item object (described above).

Table 1 Method(s) for getting the item id
Method | Description
id (object) | gets the ID of a data item
getFirstId() | gets the ID of the first data item (with the "zero" index)
getLastId() | gets the ID of the last data item
getNextId (id ) | gets the ID of a data item that succeeds the one with the specified ID
getPrevId (id ) | gets the ID of a data item that precedes the one with the specified ID
getIdByIndex (index ) | gets the item ID by its index
getRange (fromId, toId ) | gets an array of IDs in a predefined scope
getIndexRange (fromInd, toInd ) | gets an array of IDs in a predefined scope
getFirstChildId (id ) | gets ID of the first child of the specified item in the hierarchical treestore
getParentId (id ) | gets ID of the parent of the specified item in the hierarchical treestore
getNextSibling (id ) | gets ID of the next sibling of the specified item in the hierarchical treestore
getPrevSibling (id ) | gets ID of the previous sibling of the specified item in the hierarchical treestore

Getting the item index

Each data item defined in a dataset has an index - the position in the dataset starting from 0.

Table 2 Method(s) for getting the item index
Method | Description
getIndexById (id ) | gets the item index by its ID
getBranchIndex (id ) | gets item index in a specific branch

Checking the existence of an item

To check whether a specific item exists in the data set, you should use the exists method:

var mylist = webix.ui({
    view:"list",
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}
    ]
});

mylist.exists("book2");// -> true
mylist.exists("book222");// -> false

Changing the item id

To change the current id of an item, you should use the changeId method:

var mylist = webix.ui({
    view:"list",
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}
    ]
});

mylist.data.changeId("book1", "book01");

Changing data properties of an item

To change the current value of some item property, you should use the following technique:

item2 = mylist.getItem("book2");
item2.title = "Star Wars";

mylist.refresh();
//or
mylist.updateItem("book2", item2);

Methods refresh and updateItem lead to one and the same result and don't have any specificity.

Manipulations with items in the data set

Table 2 Method(s) and properties for manipulating items in the data set
Method | Description
count() | returns the count of items in the data set
getVisibleCount() | (just for the List component) returns the number of items that can be seen with the current view height
data.each() | iterates through the collection of data items
data.order | returns an array of IDs of the currently displayable items
data.pull | returns the hash of all data items
data.eachChild(id) | returns the hash of all children (first-level sub items) of the specified item in the hierarchical dataset
data.eachSubItem(id) | returns the hash of all subitems (regardless of level) of the specified item in the hierarchical dataset
data.eachOpen() | returns the hash of all open data items in the hierarchical dataset

Unlike order, the pull property returns all the items whether they are displayed in the component or not.

var mylist = webix.ui({
    view:"list",
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}
    ]
});
mylist.data.pull["book2"];//-> {id:"book2", title:"The Godfather", year:"1972"}

mylist.data.pull["book2"].title;//-> "The Godfather"

mylist.data.pull;
//- >[{id:"book1", title:"The Shawshank Redemption", year:"1994"},
//    {id:"book2", title:"The Godfather",            year:"1972"}]

Iterating data items

To iterate through the collection of data items, you should use the each method of the DataStore class.

var mylist = webix.ui({
    view:"list",
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}
    ]
});

var titles =[];
mylist.data.each(function(obj){ titles.push(obj.title); });
//-> titles=["The Shawshank Redemption", "The Godfather"]

The code is equal to a standard for-loop:

for(i = 0; i<data.length; i++ ){
    titles.push(obj.title);
}

Moving items within the data set(s)

Basically, here we speak about changing item position in the data set. Item position is its index (zero-based numbering).

Table 2 Method for moving items within the data set
Method | Description
move(sid, tindex, tobj, tid ) | moves the specified item to a new position
moveBottom (id ) | moves the specified item to the last position
moveTop (id ) | moves the specified item to the first position
moveDown (id, step ) | increases the item index and moves the item to the new position
moveUp (id, step ) | decreases the item index and moves the item to the new position

Moreover, the move method makes it possible to programmatically drag an item from one component instance to another (from one list to another list):

//moves item with id="book1" to the 2nd pos in the same list (remember about 0-based numbering)
mylist.move("book1", 1);

//moves the item with id="book1" to the first position in the "mylist2"
var id = mylist.move("book1", 0, mylist2);


Beginner

Selection

Built-in Selection

Single-Item Selection

To enable selection you should include select property into the component constructor and set its value to true (or 1).

     webix.ui({
            view:"dataview",
            select:1, //enables select mode
            ...//config
        });

Related sample: Selection

The items will be selected on mouse click.

Selection of Multiple Items

  • To enable selection of several items clicked in succession with 'Ctrl' key pressed, you should switch the component to the multiselect mode.
  • To enable multiselection by clicking items (or tapping them on touch devices) you should additionally switch to "touch" variation of multiselection.

Dataview, List and Tree Multiselection

"Ctrl"+click mutliselection

webix.ui({
    view:"list",
    select:"multiselect",
    ..// config
})

"Touch" mutliselection

webix.ui({
    view:"list",
    select:"multiselect",
    multiselect:"touch"
    ..// config
})

Datatable and Treetable Multiselection

"Ctrl"+click mutliselection

webix.ui({
    view:"datatable",
    multiselect:true,
    select:'cell', //multiple seelction of cells
    ...// config
})

"Touch" mutliselection

webix.ui({
    view:"datatable",
    multiselect:"touch",
    select:'cell',
    ...// config
})

Moreover, components that present hierarchical data (Tree and treetable) feature the level multiselection pattern. If set, it allows multiple selection of items within one and the same tree branch, the items belonging to one and the same hierarchy level.

webix.ui({
    view:"tree",
    select:true,
    multiselect:"level", // in addition to the enabled selection
    ....//tree config

})

Related sample: Multiline Selection

Datatable and treetable feature more selection modes that are described in the datatable documentation.

Selection methods

You can select items with the help of selection methods triggered by various events;

  • select( IDs, [non_modal, continue] ) function selects the specified items. Check selection API for details.

If you don't pass any parameter into the function, all items will be selected.

You can select the first and the last item from the dataset without specifying their IDs. In this case, you should additionally apply first() and last() methods to the component.

$$('datalist').select($$('datalist').getFirstId();) //selects the first data item in the list

$$('dataview').select(4); //the cell containing item with ID = 4 will be selected
$$('dataview').select([2,3,4]); the items with IDs equalling to 2, 3 and 4
  • selectAll() function equalls to select(); with no parameters and highlights all the items at once;
  • unselect() and unselectAll() - the functions work similar to the above mentioned and deselect items according to the same principles;
  • isSelected(int) - the function checks whether the item with this ID is selected. Returns true or false;
  • getSelectedId() - the function doesn't take any parameters. It returns the ID of a selected item or an array of IDs in case of multiselect mode.

Keyboard navigation

Keyboard navigation can be used for the component with enabled selection.

webix.ui({
    view:"list",
    select:true,
    navigation:true
});

Related sample: Navigation in DataTable

Note than not all data components support navigation by default. Then KeysNavigation module should be added manually.

webix.ui({
    view:'dataview', id:"dataview1", select:true, navigation:true
});

webix.extend($$('dataview1'), webix.KeysNavigation);

The code above adds navigation only to this instance of a Dataview, still it's possible to provide the functionality for all dataviews in the app.
For more details, refer to Component Extending article.


Intermediate

Adding/Deleting Data Items

Here you should make use of add() and remove() methods included into your custom functions.

These methods are true for chart, datatable, list and dataview components. For Tree and treetable look up their documentation.

Adding and deletion is implemented in the form of event taking place on user action. Normally, it is done on clicking the button with a corresponding label.

Basic Adding and Deleting

Basic syntax here looks as follows:

$$("myview").add({
         id:"item_id",  //adding  an item with two properties
         property:"some_value"
})
$$("myview").remove("item_id"); //to delete a single item

$$("myview").remove(["idA","idB","idC","idD"]); //to delete multiple items

Adding User Data from Form

To add an item which is a string entered by user in a form, you need to derive this string from the input area and then add data to the desired component. Again, specify everything by their ID. It's a common rule for all methods and event handlers.

Form and HtmlForm components have different code for input fields - look for the library's text control and standard html input respectively. It means that different methods are used to get data from them:

Adding Data from JS Form

function addData(){
    $$("data_1").add({
        user:$$('form1').getValues().user,
        email:$$('form1').getValues().email,
    }, 0);
} //'user' and 'mail' are ID-s of dedicated text fields

Adding data from [HtmlForm]

function addData() {
    $$("data_2").add({
        title: document.getElementById("title").value, //data users enter into an input field
        year: document.getElementById("year").value
    },0)
}

Deletion of Selected Items

Since only selected items can be deleted, set the select parameter to true (select: true) during the initialization of the component. Before removal let's check whether an item is selected with the help of the simpliest if-else statement.

Deletion of one item

function removeData(){
    if(!$$("data").getSelectedId()){
    webix.message("No item is selected!");
    return; //'data' is an ID of the needed component
}
$$("data").remove($$("data").getSelectedId());
}}

Related sample: Adding/Removing Items

Deletion of several items

In multiselect mode several items from the dataset can be selected. To remove all selected items, make use of a for-loop:

function remove_item(){
    var list = $$('mylist');
    var sel = list.getSelectedId(true);
    if (!sel) return;
    for (var i = 0; i < sel.length; i++)
    list.remove(sel[i]);
};

All the items can be removed from the component with the help of the following code:

$$("mylist").clearAll();

The above described methods are as well true for database-connected components. Learn more about server-side integration here .


Intermediate

Data Templates

Here we speak about the ways of presenting data inside the component after data loading.

After the data is loaded to the component it is stored in the data object and the component searches for the right value to display. So what is the object value for each data item?

Data Item Value

All supported data types may contain more than one value per item e.g. each item of a filmset may contain not only a film's title but also its rank, production year, and number of votes.

Still, different components have different possibilities and requirements:

  • Components with single-value items: list and its variants (grouplist, unitlist and x-list), dataview and tree. Each of their items takes one value by default.
  • Components with multiple-value items: datatable and treetable. They take as many items as many columns are defined.
  • Chart requires a pair of values - one for each axis.

Item Value can be defined by:

  • JSON property/XML tag value
//JSON
[ {id:1, value:"3", title:"" }, {id:2, value:"2", title:""} ]

//XML
<data><item value='3' other:""/><item value='2' other:""/></data>

Related sample: Tree: JSON Dataset

Such definition would suit single-value components. If a data item has other properties, their values won't be shown unless you define a template.

  • data template that performs two tasks
    • main - defines which item property (-ies) should be treated as value to display;
    • adds formatting to this value.

Templates can be defined for any component you wish.

Templates can set one or several properties as the value to display:

webix.ui({
    view: "list",
    template: "#title#"
}); // this list will show 'titles'

webix.ui({
    view: "list",
    template: "#value#.#title#"
}); // this list will show 'values' and 'titles'

Related sample: List

  • datatable and treetable column ID that act as templates for cells.
view: "datatable",
columns: [
    { id: "id", header: "...", width: 50}, // 1st col displays item 'IDs'
    { id: "title" }, // 2nd col displays item 'titles'
    { id: "value" }  // 3rd col displays item 'values'
]

Column IDs perform the main template function - they set the value to display. To add extra words or formatting to the displayed values, you can define a template for the column.

{ id: "title", template: "The title is <b>#title#</b>!" }

Template for CSV and JSArray

CSV and JSArray data types have no tags or properties.

//CSV
'3,4 \n 2,6 \n 5, 9'

//JSarray
[
    [3, 4],[2, 6],[5, 9]
]

The elements are defined by their position in the CSV string or JSArray - data0, data1, data3

//list template
template:"#data0#.#data1#"

//datatable columns

columns: [
    { id: "data0" },
    { id: "data1" }
];

Related sample: Loading from inline datasource

As far as you've noticed, only JSON and XML data can be displayed without refering to template, since only they can directly set value. Moreover, this can be applied only to components with single-value items.

Chart exception

Chart requires two values per item - one for each axis.

  • Y-axle value is defined by the value property that can be additionally amended within the yAxis object property.
  • X-axis value is defined by the template within the xAxis object property.
webix.ui({
   view:"chart",
   value:"#data0#", //in case of CSV or JSArray
   xAxis:{
       template:"#data1#"
   },
   yAxis:{
       template:function(obj){
             return (obj%20?"":obj
    }
});

In case of template function (described below) value is referred to as obj instead of standard obj.value (obj.title, obj.data0).

Related sample: Chart: CSV Dataset

Template Contents

The whole template comes in quotation marks and includes:

  • JSON keys / XML tags from the initial dataset, surrounded by hash signs;
  • HTML tags and CSS selectors (optional, adds styling);
  • plain text.

Template Sample

template: "<span style='classname'>#title#</span>. Shot in #year#. Ranked #rank#."

Title, year and rank signify repeated values from the dataset. All the titles will be styled with the help of the .classname CSS class. 'Shot in' and 'Ranked' are plain text to be shown to the user.

Optionally, you can define the template for data copied to clipboard. If not specified, data will be taken according to the above-mentioned template.

templateCopy: "#rank#.#title#"

In this case, only the rank and title values are copied.

Grouplist has its own templating pattern. Look into the related article for details.

The item in the intial dataset looks like this:

//JSON
{ title: "My film", year: 1994, rank: 7 }

//XML
<item>
    <title>My film</title>
    <year>1994</year>
    <rank>7</rank>
</item>

Inside the component it looks like this: My film. Shot in 1998. Ranked 7.

Don't confuse template property with the template component.

Template Types

Templates can be defined in five very flexible ways:

  • as HTML strings within JavaScript objects
  • by creating named templates
  • by extracting them from an HTML container
  • by retrieving them from an external file
  • as a function returning a string

Templates are included into Webix components as well as into some of their properties that take objects as values.

  • Tooltip implementation
  • Type implementation

HTML inside JavaScript

JSON data in the dataview

var big_film_set = [
    { id: 1, title: "The Shawshank Redemption",
      year: 1994, votes: "67,879",
      rating: "9.2", rank: 1
    },
    { ...}
];

webix.ui({
  view: "dataview",
  template: "<div class='rank'>#rank#.</div><div class='title'>#title#</div>"
});

Related sample: Template as a String

Named Template

Templates may be included inside the type parameter. Type applies to each item rather then the whole component.

1 . First you should create a type with the webix.type constructor. It is created for the specified UI component:

webix.type(webix.ui.dataview, {
    name: "typeA",
    template: "<div class=''>#rank#.</div>"+
            "<div class='title'>#title#</div>"+
            "<div class='year'>#year# year</div>"
});

2 . Then you specify the name of that type as value of type property for this component:

webix.ui({
    view: "dataview",
    type: "typeA",  // name of the webix.type object created in the first step
    ...
});

Related sample: Named Templates

See the corresponding article to learn more about type implementation.

HTML Container with Data Template

The template may be defined inside an html-container and referred by its id:

<textarea id="template_container" rows="5" cols="60" style="margin-left:20px">
   <div class='overall'>
        <div class='rank'>#rank#.</div>
        <div class='title'>#title#</div>
        <div class='year'>#year#</div>
   </div>
</textarea>

<script>
webix.ui({
    view: "dataview",
    // lookup the textarea by id and fetch its contents
    template: "html->template_container",
    ...
});
<script>

Related sample: Pure HTML Template

External HTML template

Templates can be defined in external files. The template parameter will be a link to this file, prefixed by http->:

webix.ui({
    view:"dataview",
    template:"http->template.html",
    data:big_film_set
});

The file contents (an HTML template from the example above):

<div class="overall">
    <div class="rank">#rank#.</div>
    <div class="title">#title#</div>
    <div class="year">#year# year</div>
</div>

Note that these HTTP requestes are not cached. If you use the same template repeatedly, it's better to retrieve it via AJAX and store it in a variable:

var objectDetailTemplate = webix.ajax().sync().get('template.html').responseText;

Related sample: Pure HTML Template: Referring to External HTML

Template Function

template may as well be function that returns the string to render. No #-interpolation will take place in this case; you have to interpolate variables on your own.

...
template: function (obj) {
    return "<div class='overall'><div class='rank'>" + obj.rank + ".</div>" +
      "<div class='title'>" + obj.title + "</div>" +
      "<div class='year'>" + obj.year + " year</div> </div>";
}

Related sample: Template as a Function

  • If value is defined by JSON/XML tag value - you refer to it as obj.value.
  • If value is defined by template - you refer to it as obj.title, obj.rank, obj.data0 (CSV, JSArray) etc.

XSS Safe templates

By default, #...# template placeholders are replaced with the data value without any processing. If you have HTML data in the data object, it is also placed in the template. In most cases this is an advantage, but sometimes it may be necessary to output such data as text, not a HTML:

  • when you have text data with special HTML characters (<, >, and &);
  • when you are not sure whether the data is safe (e.g. was entered by the user).

In such cases you can add an exclamation mark ! after the opening #:

{
  template: "My #data#" // will output data as HTML content
},
{
  template: "My #!data#" // will output data as Text content
},


Intermediate

Tooltip Implementation

Tooltip stands out of the fixed pattern. It lies above other ui-related components, which makes it similar to window and popup.

Tooltip is connected with some component or its item and becomes visible when you place a mouse pointer over it and disappears when it leaves the area. Doesn't it resemble onMouseOver/onMouseOut events? Still, event handling is quite another story.

Here, you don't need any specific code to make it work. You should just include a tooltip into the necessary component and specify the info to be shown inside a tooltip area.

Tooltip may include text as well as items from the dataset.

webix.ui({
    view:"dataview",
    ...
    tooltip:{
        template:"<span class='webix_strong'>Rating: </span> #rating#<br/>
        <span class='webix_strong'>Votes: </span> #votes#"
    }
});

Related sample: Template of Tooltips

By default, tooltip is placed on the same level with the mouse pointer, 20 px to the right from it.

To change this pattern, specify the coordinates relative to the mouse pointer as values of dx and dy properties.

tooltip:{
    template:"<span class='webix_strong'>Rating: </span> #rating#<br/>
    <span class='webix_strong'>Votes: </span> #votes#",
    dx: 10, //20 by default
    dy:5    // 0 by default
}

Datatable Tooltip

Datatable tooltip is defined is quite another way. Several steps are possible:

  • Setting tooltip:true for the whole component. It enables tooltip functionality for the grid and shows tooltip for each column showing the row value that stands as ID for this column.

General datatable tooltip

webix.ui({
    view:"datatable",
    tooltip:true,
    columns:[
        {id:"name", header:"Name"},
        {id:"age", header:"Age"}
    ],
    data:[
        {id:1, name:"Ann", age:25},
        {id:2, name:"Tom", age:27}
    ]
});
//the tooltip for the first column of the first row is "Ann"
  • Customizing tooltip data for each column. Tooltip should be switched on for the whole grid:
webix.ui({
    view:"datatable",
    tooltip:true,
    columns:[
        {id:"name", header:"Name", tooltip:"My name is #name#. I'm #age#."},
        {id:"age", header:"Age"}
    ],
    data:[
        {id:1, name:"Ann", age:25},
        {id:2, name:"Tom", age:27}
    ]
});
//tooltip for the first column of the first row is "My name is Ann. I'm 25."
  • Setting tooltip for datatable header. Tooltip should be switched on for the whole grid:
webix.ui({
    view:"datatable",
    tooltip:true,
    columns:[
        {id:"name", header:"<span title='My tooltip text'>Name</span>"},
        {id:"age", header:"Age"}
    ]
});
//tooltip for the Name column is "My tooltip text"

Advanced tooltip configuration

Instead of defining tooltip for each column separately, you can define tooltip once for all columns

webix.ui({
    view:"datatable",
    tooltip:function(obj, common){
        //obj - row object
        //common.column - configuraton of related column

        return "<i>"+obj[common.column.id]+"</i>";
    },
    columns:[
        {id:"name", header:"<span title='My tooltip text'>Name</span>"},
        {id:"age", header:"Age"}
    ]
});


Intermediate

Type Implementation

Type property allows treating each of the component's items separately - specify its dimensions, set CSS class, define data template and include elements that will be common for all the items.

Type is applicable to the following data components:

  • dataview;
  • list;
  • grouplist;
  • unitlist;
  • menu;
  • tree;
  • datatable and treetable to define common properties for cells;

Webix item type is an object that is constructed of parameters you'd like to apply to each item of the component. These parameters can be native properties of Webix components or user-defined ones.

Native properties are described in the component API and may differ from component to component. They may include:

  • template - the template of data visualization of each item;
  • templateStart and templateEnd - wrappers for each data item, are not redefined, as a rule. More Info.
  • width and height - width and height of each data item;
  • css - item styling;
  • headerHeight (unitlist specific) - the height of unit headers.

In the sample below it is shown how you size the dataview itself and how the dimensions of dataview cells are sized.

webix.ui({
    view: dataview,
    width: 550,
    data: ... ,
    type:{
        template: "<div class='rank'>#rank#.</div><div class='title'>#title#</div>",
        width: 261,
        height: 90,
        css: "movie"
    }
});

Related sample: Template as a String

Note that the template set for the whole component will override the template defined within the component type.

// the "#rank#. #value#" template will be used
webix.ui({
    view: dataview,
    template: "#rank#. #value#",
    data: ... ,
    type:{
        template: "<div class='rank'>#rank#.</div><div class='title'>#title#</div>",
    }
});

At the same time you can define the type separately by using webix.type constructor and then apply it to the necessary component:

webix.type(webix.ui.dataview,{
    name:"typeA",
    template: "<div class=''>#rank#.</div><div class='title'>#title#</div>",
    width: 261,
    height: 90,
    css: "movie"
});

webix.ui({
    view: "dataview",
    type: "typeA", //name of the new object created in the first step
    ...
});

Related sample: Named Templates

Defining Common Elements

Common elements can be included in either of the two ways:

  • {common.property} - allows including a constant value for all the items into the template:
webix.ui({
    view:"list",
    template:"{common.itemIcon} #rank#. #title#",
    type:{
        itemIcon:"<span class='webix-icon fa-film'></span>"
    }
});
  • {common.method()} - allows including result of a function call into the template:
webix.ui({
    view:"list",
    template:"#rank#. #title# {common.itemYear()}",
    type:{
        itemYear:function(obj, common){
            if(obj.year>=2000){
                return "<span class='newtime'>"+obj.year+"</span>";
            } else if(obj.year<1970){
                return "<span class='oldtime'>"+obj.year+"</span>";
            } else
                return obj.year;
        }
    }
});

Related sample: List::Advanced Template

The type function takes item object as parameter, so all its properties are accessible in it.

Datatable and treetable already feature some common elements out of the box.

  • Datatable built-in type templates;
  • Treetable biult-in type templates.

Redefining default template elements

You can completely change the component's look and feel inside the type by altering HTML for the items. Type properties subject to altering are as follows:

  • template - standard item template, can be used outside the type configuration with the same result. Includes data properties in #hash# signs and optionally, HTML content;
  • templateStart - container element for data item, wraps the elements defined by template. Opening element;
  • templateEnd - closing element for templateStart.

In other words, each data item HTML content includes templateStart - template - templateEnd. TemplateStart and templateEnd are not normally changed, but still the possibility exists.

This is how standard list can be redefined:

webix.ui({
   view:"list",
   type:{
      templateStart:"<div item_id='id' class='custom_item'>",
      template:"#rank#. #title#<br><div style='text-align:right;'>#year#</div>",
      templateEnd:"</div>"
   }
});

Related sample: List::Advanced Template


Intermediate

Working with Dates

Dates with UI Components
  • Loading and Formatting
  • Editing
  • Sorting
  • Dates with Forms
  • Date and Number Localization

Loading and Formatting

Dates are loaded to components according to common data loading rules.

Either in the database or in data files dates can be stored in two ways: as DateTime objects or as strings.

  • DateTime objects should be formatted for adequate presentation. Otherwise, the output will be like "Tue Nov 30 2010 00:00:00 GMT+0200";
  • Strings can be either shown in the way thay are stored or converted to objects and then formatted.

Only DateTime objects defined with the new Date(); method are subject to formatting since it presupposes "to-string" conversion. Strings should be converted beforehand.

Pre-Formatting: String-to-Object Conversion

There exist two methods of date-to-string conversion:

1 . Built-in (map property). Datatable Only.

Conversion is provided by map property used for the column instead of column ID. Like ID, map refers to the necessary data item and allows for format specification:

webix.ui({
    view:"datatable",
    columns: [
        { map:"(date)#enddate#",editor:"date",header:"End date", width:120}
    ],
    data: [
        {id:"1", startdate:"2013-09-26", enddate:"2011-05-15"},
        {..}
    ]

})

2 . Custom (using webix.Date object functions).

Applicable to all data management conponents including datatable.

Here we create the necessary conversion pattern and then define it as scheme for the loaded data.

var my_format = webix.Date.strToDate("%Y-%m-%d");
//hyphen-separated values are interpreted as year-month-date object

webix.ui({
    view:"datatable",
    ..//config
    scheme:{
            $init:function(obj){
                obj.startdate = my_format(obj.start);
            }
    }

})

Related sample: Converting strings to dates

Now we've got DateTime objects ready to formatting.

Defining Formatting Methods

There're two objects in the library that handle dates - webix.Date and webix.i18n. Both of them contain date formatting and processing logic while the later is responsible for date (as well as number and price) localization.

webix.i18n

Localization means locales implementation where locale is a collection of formatting methods and patterns for a certain area. They are defined separately and later applied to the necessady data. By default, if you format dates with the i18n object, all the dates and numbers will be formatted according to North American region rules.

Date and Number localization are described in the related article.

webix.Date

The Date object allows for formatting dates regardless of locales with the help of the dateToStr() method. It requires format specification in its argument.

{ header:"m/d/Y", sort:"date", id:"start", format:webix.Date.dateToStr("%m/%d/%y")}

The datatable column here shows the stored date in a "month number/day number/two-digit yeat" format.

Possible format specifiers are listed in the related article.

Applying Formatting Methods

Only datatable has a format property for its columns while other components require a specific function template.

Formatting Datatable Data

webix.ui({
    view:"datatable", columns:{
        [{ header:"WeekDay", id:"start", format:webix.i18n.longdateFormatStr},
         {...}
        ]
})

Formatting Other Component's Data

//format is specified by locale
webix.ui({
    view:"list",
    template:function(obj){
            return webix.i18n.longDateFormatStr(obj.start);
                }
})

//format is specified separately
var myformat = webix.Date.dateToStr("%m/%d/%y");

webix.ui({
    view:"list",
    template:function(obj){
            return myformat(obj.start);
                }

Editing

Dates within components are edited with the help of the dedicated editor (see Data Editors for details).

Requirements for Date editing:

  • component should be editable.
  • editor type should be defined. Here we need "date";
  • editValue (data item subject to editing) should be specified (excluding datatable). The thing is that components may have more than one data item in a cell.
  • optionally editaction is defined. (click by default).

This editor is used as datepicker to call UI calendar on defined edit action to pick the necessary date.

webix.ui({
    view:"dataview",
    ..//config..
    editable:true,
    editor:"date",
    editValue:"start", //refers to data item
    data:[
            { text:"Joint 2", start:new Date(2011,1,14)},{...}]
})

Related sample: Dataview Formatting

When working with server-side, initialize a dataProcessor for the component and the changes will be automatically saved back to server.

Sorting

Though dates are presented as strings, they are sorted as date objects. So before sorting don't forget to convert strings to DateTime objects in case they are stores as strings (see above).

Sorting can be applied in two directions: "asc" (ascending) and "desc" (descending).

1 . Built-in Sorting. Datatable Only.

Datatable features dedicated sort property for its cloumns.

2 . Custom Sorting. Applicable to all components.

Here we make use of the sort() function that needs:

  • template of the data item subject to sorting;
  • sorting direction;
  • sorting mode ("string", "string_strict", "int", "date").

HTML Button Triggers Sorting

<input type='button' value='Sort "Asc"' onclick='grid.sort("#start#", "asc", "date");'>

Related sample: Using date templates

Data Sorting Api.

Dates Inputting in Forms

Form fields that require date inputting from users should be supplied with a calendar for user convenience.

There exists a special datepicker control that looks like a normal text field with a calendar icon.

When you click it a popup calendar appears. On selecting the necessary date, click somewhere outside the popup and the date will be shown in the text field. By default, date is shown formatted as "%Y-%m-%d" and stored as DateTime object.

Related sample: Date picker in Calendar

Customization

The calendar can be customized within the webix.editors object as well as localized according to common rules.

The default date for the control to show as well as the default date of the popup calendar is the current one. The pattern can be changed by setting the necessary value in the datepicker constructor:

{
    view:"datepicker",
    value:new Date(2011,1,12)
}

Default formatting can be changed as well. Formatting rules are described above and applied to the control as value of its format property.

{
    view:"datepicker",
    format: webix.Date.dateToStr("%d/%m/%y")
}

Related sample: Date picker in Calendar

If a form is bound to the component, it will load dates in the format specified by the component formatting pattern, or, if custom format is defined for datepicker, it will get the one from the latter.


Intermediate

Data Filtering and Sorting

Sometimes you need to view definite items rather then the whole dataset. Here you play around with the filter() method.

The task is as follows: you have a film set and want to filter it by title and year, with the possibility to enter the text criterion into the input area. At the same time filtration should start with the first letter while newly added letters would trigger data re-filtering.

Two major possibilities of data filtering are content filtering and sorting using built-in means and custom filtering where you should write your own function with the filter() method.

Content Filtering and Sorting

Available for datatable and treetable only. Filtering and sorting parameters are set for each column separately.

The content parameter set to 'textFilter', 'selectFilter', 'numberFilter' or 'dateFilter' value enables filtering. The former filters data as you type values into the input while the latter allows selecting from the predefined list

Data is sorted thanks to the sort parameter that may take 'int', 'date', 'string' and 'string_strict' (for case-sensitive filtering) values. You click headers of the dedicated columns to enable both ascending and descending sorting patterns.

webix.ui({
    view:"datatable",
    id:"films",
    columns:[
        { id:"title",   header:["Title", {content:"textFilter"}], sort:"string"},
        { id:"year",    header:["Year",  {content:"selectFilter" ], sort:"int"},
        { id:"votes",   header:"Votes",     sort:"int"}
    ],
    ...
});

Related sample: Filtering by several criteria (AND logic)

If you want to include an additional criterion to the built-in filter, use the compare property to define the additional filtering

Datatable is a peculiar component and has a number API peculiarities. That's why, refer to the corresponding articles:

  • Datatable Filtering
  • Datatable Sorting

Treetable shares features of both datatable and Tree, that's it has similar fimilar sorting and filtering patterns. In addition, it borrows filterMode property from the tree API (described further).

Custom Filtering

Other components should be filtered with the dedicated filter() function that takes filtering value from the input area and shows only those data items that comply with it.

Filtering can be implemented in two ways:

Using data template

webix.ui({
    rows:[ //firstly define input area and data object
        {
            view:"toolbar",
            elements:[{view:"text",
            id:"list_input"]
        },
        {
            view:"list",
            id:"list",
            template:"#rank#. #title#",
            select:true,
            data:big_film_set
        }
    ]
});

$$("list_input").attachEvent("onTimedKeyPress",function(){
    var value = this.getValue().toLowerCase(); //input data is derived
    $$("list").filter(#title#, value);
}); //the titles are filtered

The same pattern is observed with components featuring similar data templates (dataview and Tree).
In the list above the template includes rank and title values for each film. More about data templates.

Using a function

Filter() method can have a function as argument. It returns data values that comply with input text:

$$("list_input").attachEvent("onTimedKeyPress",function(){
    var value = this.getValue().toLowerCase(); //here it gets user input value
    $$("list").filter(function(obj){   //here it filters all titles from the dataset
    return obj.title.toLowerCase().indexOf(value)==0;
})

Related sample: List: Filtering

Peculiarities of Tree Filtering

Tree Filtering

//html input field
<input
    type='text'
    placeholder="type filter criteria here"
    style='width:250px; margin-left:20px'
    onkeypress="filter_tree()"
>

//filtering function
function filter_tree(){
    tree.filter("#value#", this.value);
}

// tree object
webix.ui({
    view:"tree",
    select:true,
    data: smalltreedata
});

The function performs filtering according to #value# values. It takes into account all the tree levels and displays results with the children of the filtered branches even if the children's values don't comply with the filtering criterion.

At the same time, you can change the filtering pattern with the help of the tree filterMode property with an object value.

{
    view:"tree",
    filterMode:{
        showSubItems:false,
        openParents:false,
        level:3},
    ...
}
  • showSubItems (boolean) - defines whether the component should display children of the filtered items.
  • openParents (boolean) - defines whether the component should expand branches to show the found items.
  • level (number) - sets the hierarchy to filter tree nodes (one-based numbering). The '0' value says to filter all nodes.

Related sample: Filtering

Related sample: Filtering in TreeTable

Filtering by Multiple Properties

It's common knowledge that data management components can features more than one data template item per record. For instance, datatable record consists of several cells in different columns, dataview and list records contain several items, which is reflected in their data template.

You can filter data in the component referring to either of its template values using one and the same input field.

webix.ui({
    rows:[
        {view:"list", id:"dlist",
        template: "#rank#. #title#. #year#<br/>#category#",
        ..//list config
        },
        {view:"text", id:"filter-list" //input for filtering
        }
    ]
})

$$("filter-list").attachEvent("onTimedKeypress", function(){
    var text = this.getValue().toString().toLowerCase();
    //after text entering - filter related grid
    $$("dlist").filter(function(obj){
        //filter by multiple properties
        var filter = [obj.title, obj.category, obj.year].join("|");
        filter = filter.toString().toLowerCase();
        return (filter.indexOf(text) != -1);
    });
});

Related sample: Multiple Filter

Sorting

Sorting is enabled by sort() function that takes data item, sorting direction and sorting mode as parameters:

  • Sorting as component property. Data will be during component initialization:
webix.ui({
    view: "list",
    template:"#title# - #year#"
    sort:{
        by:"#title#",
        dir:"asc",
        as:"string"
    }
});
  • Sorting as a separate function. Data sorting will be triggered by any event you associate it with:
$$('chart').sort('#year#','desc');
$$('tree').sort('#value#', 'asc');

Read about more detailed description of the sort method in the dedicated chapter of API Reference


Intermediate

Data Validation

All the data from input fields must be validated before being sent to server. Data validation is implemented with dataprocessor, htmlform and form as well as with all the data management componens (datatable, dataview, tree, treetable, list).

Data validation is activated:

  • Generally, validation is started on calling the validate() method. You can call it:
    • on form submitting;
    • on any inner event (onChange for form, onAfterEditStop for data component);
  • With the DataProcessor object data is validated each time you save it to server. If validation fails, data isn't sent to server;
  • With data components data is validated each time changes are made - editing, adding and updating (the moment add() and update() methods are called);
  • By means of on-the-go HTML5 validation that works for form and htmlform.

While the first three are features of this library and work in conjunction with validation rules, the latter is a built-in HTML5 feature.

Validation by API

Data validation can be triggered on any event of any form element and validate any number of controls as well as the whole form:

Normally, form and htmlform, data validation is bound to a submit button with the help of click event handler:

{ view:"button", value: "Submit", click:function(){
    form.validate();
}}

At the same time, you can trigger validation whenever you like, e.g. on onChange event of a control:

{ view:"text", name: "fname", on:{
    "onChange":function(){
        //either validate the whole form
        this.getParentView().validate();
        //or validate this element only
        this.validate();
    }}
}

Live Validation in Forms

Validation event can not only be attached to the control in a common way (as above) but by specific validateEvent property that allows for automatic attaching of two events:

  • "blur" - to start validation on onBlur event, when focus is moved from the control;
  • "key" - to start validation on onKeyPress event when a users enters a character into the field.

Note, that this method allows for defining validation event only for this control.

In case of data components, validation can be set on data loading to ensure that data came with right values:

 webix.ui({
    view:"datatable",
    ..// config
    ready:function(){
        this.validate();}
});

Related sample: Datatable Validation

Partial Validation

With the validate() method you can validate:

  • the whole form/component:
form.validate(); //all fields are validated
list.validate(); // data of the whole list is validated
  • specific component item;
list.validate(2); //data item with id=2 will be validated
text.validate(); //validate only this text field

Note that if a separate form field is validated, only its own validation rules will be considered.

webix.ui({
    view:"form", elements:[
        { view:"text",  required:true, name:"text1" },
        { view:"text",  validate:webix.rules.isNumber, name:"text2" }
    ]
});

$$("text1").validate();

Related sample: Per Item Validation with Predefined Rules

Validation Message

If any record or field fails validation, it is marked with embedded red highlighting (true for both in-library and HTML5 validation).

It is also very easy to apply built-in validation messages for form fields.

All you need to do is to specify the invalidMessage property and set the necessary text of the message:

{ view:"text", label:'Username', name:"login", invalidMessage: "Login can not be empty" },

Validation messages require some space under form fields. You should specify the bottomPadding property and set the appropriate value to define the bottom offset of the input:

var formElements = [
    { view:"text", label:'Username', name:"login",
        invalidMessage: "Login can not be empty" },
    ...
];

webix.ui({
    view:"form",
    elementsConfig:{
        labelPosition: "top",
        labelWidth: 140,
        bottomPadding: 18
    },
    elements: formElements
});

Related sample: Validation Message

The property is 18 px by default. If the value isn't set, space for validation messages will be automatically specified as 18px.

Adding input description

There's also a possibility to put some hints on correct filling of form fields for users.

The bottomLabel property will be helpful for this purpose. Don't forget to set the bottomPadding property to specify the size of labels.

{ view:"text", type:"password", label:"Password", bottomPadding: 35,
    bottomLabel: "* The password must have at least 6 characters"},

Related sample: Input Description at the Bottom

Validation Handling

Additionally, a custom message can be set to handle validation process. It's done in two ways:

1 . Webix message can be used together with the validate() method within the sumbit_form custom function;

webix.ui({
    view:"form",
    id:"myform",
    elements:[
        {},  //input fields
        { view:"button", inputWidth:300, label:"Submit", click:"submit_form"}]
});

submit_form = function(){
    if (this.getParentView().validate()) //on success
        webix.message("All is correct");
    else
        webix.message({ type:"error", text:"Form data is invalid" });
};

2 . Webix message can be attached to validation events with the help of its on property. Possible events here are:

  • onAfterValidation - triggers on validation process complete;
  • onValidationSuccess - triggers if data passes validation successfully;
  • onValidationError - triggers in case an error during validation happens.

Here you can see how message can be formed in case of a validation error:

on:{
webix.ui({
    view:"form",
    on:{
        onValidationError:function(key, obj){
            text = "Login can't be empty";
            webix.message({ type:"error", text:text });
    }
});

Related sample: 'onValidationError' Event

Message boxes of all types are described here.

Validation Rules

The validate() function checks if data complies to certain rules defined in the rules object that contains a collection of property-rule pairs. Predefined rules are accessed through webix.rules class.

Form validation

Here you attach rules to inputs by their names. Name is read-only property that can be assigned to any input of the form/ htmlform.

You can do this either within rules object property of the form component:

view:"form", elements:[
    {view:"text", name:"field1"},
    {view:"text", name:"field2"}
],
rules:{
    field1:rule1,
    field2:rule2
}

Related sample: Basic Validation

Or, you can attach a rule right in the input constructor as value of its validate property:

view:"form", elements:[
    { view:"text", label:'Is a Number', validate:webix.rules.isNumber, name:"text2" },
    { view:"text", label:'Is an Email', validate:webix.rules.isEmail, name:"text3" }
],
elementsConfig:{
    labelAlign:"right",
    on:{
        'onChange':function(newv, oldv){
            this.validate();
        }
    }
}

Related sample: Per Item Validation with Predefined Rules

Component Data Validation

Here you need to define which data item you'd like to validate, namely specify its template #value# or, in case of datatable, column ID.

rules:{
    "template/ID": rule
}

Validation rules can be of three types:

  • Predefined Rules
  • Custom Rules
  • Rules using Special Validation Keys

Predefined Rules

There are four of them:

  • isNotEmpty - checks whether a value is empty;
  • isNumber - checks whether a value is number;
  • isEmail - checks whether a value is e-mail (looks for an @-sign, fullstop, text after it);
  • isChecked - checks whether a checkbox is checked.
webix.ui({
    view:"form1",
    elements:[
        { view:"text", label:'Username', name:"login" },
        { view:"text", label:'E-mail address', name:"email"},
        { view:"text", label:'Password', name:"password"},
        { view:"checkbox", labelRight:'I accept terms of use', name:"accept"}

    ],
    rules:{
        login: webix.rules.isNotEmpty,
        email: webix.rules.isNumber,
        phone: webix.rules.isEmail,
        accept: webix.rules.isChecked
    }
});

Related sample: Validation with Predefined Rules

In case you are parsing JSON data, you should set the predefined rules as follows:

"rules":{
   "login":"isNotEmpty",
   ...
}

It is needed for JSON data to be parsed properly.

Note that in case you define rules within input constructor, the isNotEmpty rule can be substituted by required property.

//it's better to use
{ view:"text", label:'Not empty', required:true }
//instead of
{ view:"text", label:'Not Empty', validate:webix.rules.isNotEmpty }

Related sample: Required inputs in a form

Conditional usage of built-in rules

Predefined validation rules can be wrapped by another function to apply them selectively:

Ignoring empty values during validation

rules:{
   city:function(value){
        return !value || webix.rules.isNumber(value)
  }
}

Remember that a validation function must return true for success and false for failure.

Custom Rules

Basically, any custom function can define a rule. Such function takes the validated value as parameter.

Validation rules may define the minimal and maximum value for the form field or check whether the input data complies to a certain criterion.

Validation Criteria for Numbers

webix.ui({
    view:"form",
    rules:{
        text1:function(value){ return value > 100; },  // over 1400
        text2:function(value){ return value < 100; }, // below 100
        text3:function((value){ return value > 0;} //positive
    }
});

Related sample: Validation with Custom Rules

Special Validation Keys

The keys are used with both predefined and custom rules for special cases, for instance:

  • if you need apply the same rule to each property of data object, use $all key;
  • if you need data from several form fields for validation, use $obj key.

$all key

All the fields must be filled

rules:{
    $all:webix.rules.isNotEmpty
}

Related sample: Validation with a Common Rule for All Fields

$obj key

The whole data object is passed into the rule while field data is accessed as obj.field_name or obj.template/ID.

Both votes and rank values must be positive

rules: {
    $obj:function(obj){
        return obj.votes > 0 && obj.rank > 0;}
}

Related sample: Datatable Validation. Complex Rule.

It is as well used in defining complex rules, e.g. when password confirmation is required.

Passwords must be equal

rules:{
    $obj:function(data){ //data = obj
        if (data.pass1 != data.pass2){
            webix.message("Passwords are not the same");
            return false;
        }
    return true;
    }
}

Related sample: Password Confirmation

Note, that even if you don't pass data object into the function, you still can work with all its values deried with form getValues() method.

Complex Rule

webix.ui({
    view:"form",
    rules:{
        $obj:function(){
            var data = this.getValues(); //!getting data object
            if (!webix.rules.isEmail( data.email ))  //ckecking email
                return false;
        if (data.name == "") //checking name
            return false;
        return true; //success!
        }
    }
});

Related sample: Validation with a Complex Rule

What should be taken into account:

  • If there are fields without name property, the function returns false;
  • In case all rules are observed, the function returns true and the form is treated as valid.

Validation of Hidden and Disabled Fields in Form

By default hidden and disabled fields are not validated. If you want to include them into a validation process, you need to provide validation mode:

//hidden fileds will be validated
$$("$form1").validate({hidden:true});

//both hidden and disabled fields will be validated
$$("$form1").validate({hidden:true , disabled:true});

Related sample: Form with Tabs

Note that if the form is hidden itself, hidden and visible fields are not separated.

Data Validation for Components

As with form, rules are set within the component constructor. With validation enabled, you'll be warned about invalid data in your component on client side while avoiding loading wrong data to server.

The validated data item is defined by its template, rules being the same as with form elements:

List Data Validation

webix.ui({
    view:"list",
    template:"#rank#. #title#",
    rules:{
        title: webix.rules.isNotEmpty
    },
    ..//list config
})

As a result, you cannot add an empty record to list data.

Related sample: List: Validation

Read more about data templates here.

With datatable component we need a column ID, since it correlates with data items.

Datatable Data Validation

webix.ui({
    view:"datatable",
    columns:[
        { id:"rank", header:"", ..},
        { id:"title", header:"", ..}
    ],
    rules:{
        "rank": positiveNumber, //custom rule
        "votes": positiveNumber
    }
})

Related sample: Datatable Validation

Invalid data is highlighted within the component and cannot be sent to server (in case you work with dataprocessor).

Validation during in_Component editing

By default, with rules defined, validation is started each time we finish editing and close the editor for this or that data item.

However, editing events allow validation with an editor opened. The obvious bonus of such method is that until new data is valid, it can't be changed within the component.

Here the onBeforeEditStop event comes to our help. It's attached to the component you work with:

webix.ui({
    view:"datatable",
    ..//config
    on:{
        onBeforeEditStop:function(state, editor, ignore){
            var check = ( editor.type.getValue() != "" );
            if (!ignore && !check){
                webix.message(editor.column+" must not be empty");
                return false;
            }
        }
    }
});

Related sample: Datatable. Editing Validation.

The function takes three arguments here:

  • state - the object that stores old and new value of the text editor;
  • editor - the editor being used;
  • ignore - the flag to indicate user action after editing, whether they save the new data or escape the saving thus restoring the old data.

More information about text editors you can find in the dedicated article.

HTML5 Data Validation

Here we speak about clientside, in-browser data validation powered by HTML5 means.

In HTML5 layout input tags come in a plenty of types and feature a number of attributes that define validation pattern.

Input types conside with a type property of the view text while other input attributes are listed within the attributes object property:

HTML Javascript
<input type="text" id="text1"
    title="First name is required!"
    maxlength="25"
    placeholder="Your name" required>
<label for="text1">First name</label>

{ view:"text", type:"text", attributes:{
    maxlength:25,
    required:"true",
    title:"First name is required!"
}, value:'', label:"First Name"}

Here validation is defined by required attribute.

The validation process starts as soon as you type the first character into the field. When the necessary pattern is observed, a red highlighting disappears. Furthermore, if you try submitting the form, a validation error message appears for each field that has been incorrectly filled:

  • in case of the wrong filling: "Please enter an email address/ a URL !" - depending on the type property value;
  • in case of an empty field: "Please fill out this field!"

HTML5 input types for the library's form component are as follows::

  • text (default type for this lib);
  • password - hides typed characters;
  • email - requires @ symbol for validation;
  • url - requires http:// prefix for validation.

Related sample: HTML5 Data Validation

Related Articles

  • Creating Message Boxes


Intermediate

Editing Data Items

Library components have similar editing patterns yet some peculiarities should be taken into account. Hence, there exist two groups:

  • Editing Datatable and Treetable
  • Editing Other UI-Related Components

Generally, a set of properties in the component's constructor enable on-the-go editing with its items. At the same time, programmatic editing is as well possible.

For these needs take the following steps during component initialization:

  • set the editable property to the true state;
  • define editor type.
  • define editAction (single or double mouseclick, or keyboard action).

With datatable you should include the editor property into a column object.

Data editors and edit actions are described here;

Datatable and Treetable Editing

By default, only datatable and treetable feature built-in editing ability.

Editable and editAction are included into the component object while editor is set for each column separately.

webix.ready(function(){
    webix.ui({
    view:"datatable",
    columns:[
        { id:"rank", editor:"text", header:""},
        { ...},
        { ...}
    ],
    editable:true,
    editaction:"click",
    data: small_wide_film_set //data from external js-file
});

Related sample: Opening multiple editors

Editing Other UI-Related Components

To enable edit mode with other ui-related components, you should create a prototype object on their base and extend them with editability. Then they will get the above mentioned functionality.

For instance, to edit ui-related list, create an editable prototype for it first and give it name to your taste:

webix.protoUI({
    name:"editlist" // or "edittree", "dataview-edit" in case you work with them
}, webix.EditAbility, webix.ui.list);

And proceed with the list object initialization. Note that view is called "editlist" value instead of "list," since it's the name of the newly create object from the code above:

webix.ui({
    container:"listA",
    view:"editlist",
    template:"#rank#. #title#",
    editable:true,
    editor:"text",
    editValue:"title",
    data:big_film_set
});

Related sample: List: Editing

Take notice of the editValue property here. It defines the dataset item from the template since each record in list and similar components has a template with several values from the initial data source. Study the nature of template-making here.

Note that editing allows for on-page changes only and doesn't presuppose automatic data saving into the dataset. To actually save data you should initialize webix.DataProcessor for the edited component.

Editing Methods

There's a collection of methods to enable and control editing.

Generally, you can switch any data item to the editable state with the edit() method that requires item ID as parameter:

editlist.edit(7);

To open editor in the datatable cell, you need to specify row and column ID-s. However, it's recommended to use editRow, editColumn and editCell functions. See the datatable API for details.

datatable.edit({
    row:2,
    column:"title"
});

In addition, the following methods are applicable:

  • editNext() - closes the currently opened editor and opens editor in the next editable item.
  • editStop() - closes all opened editors. Data is automatically saved;
  • editCancel() - cancel editing and closes all opened editors. Data isn't saved.
  • editFocus() - enables editing in the editor in focus (the method is helpful for several active editors on the page).

Check editing methods in the API reference.

Editing via a Form

Form and Component Binding

Webix components can be bound to each other to ensure select-based synchronous changing of their data. For instance, a simple function can be used to bind a form to a grid, which allows to edit datatable data:

  • clicking the component item will trigger form filling;
  • then you edit data in the form;
  • form [saving] will send changed data back to the component.
$$('form1').bind('datatable1');

Related sample: Editors. Bind Form

Note that name attributes of form fields coincide with properties (fields) of the data used for the edited component while the component can be non-editable itself. You can study data binding separately.

Related Form for an Editable Component

Webix editing API allows to attach a form without data binding as well. Unlike binding, it works only for editable components.

First of all, you need to define the related form inside a master component with the help of form property:

    view:"datatable",
    editable:true,
    form:'myform' //ID or object of related form/popup

A form should be defined separately, either in layout or in popup.

view:"form",
id:"myform",
elements:[...]

//or
view:"popup",
id:"myform",
body:{
    view:"form", elements:[...]
   }

Note that:

  • ID or object attached to a component by the form property should point to either a form, or a popup in which the form lies;
  • In case of a popup, it can be initialized hidden so that it will be shown only when editing starts (when you click data item in master component).

Related Articles

  • Data Update - the alternative method of item editing
  • Data Editors


Intermediate

Data Editors

In this article build-in component editors and edit actions for them are discussed. To learn about Webix editing pattern, go to the main article.

Opening and Closing Editors
  • an editor for the component is enabed, or opened, by the editAction that is defined for the whole component;
  • an editor is closed by moving focus outside the editor (e.g. clicking another component part) or by hotkeys 'Enter' for saving the new value and 'Esc' for exiting without saving.

Editor Types
Table Editor Types
editor:"text"
Learn more
editor:"password"
Learn more
editor:"inline-text"
Learn more
editor:"select"
Learn more
editor:"combo"
Learn more
editor:"richselect"
Learn more
editor:"multiselect"
Available in Webix Pro edition only
Learn more
editor:"checkbox"
Learn more
editor:"inline-checkbox"
Learn more
editor:"color"
Learn more
editor:"date"
Learn more
editor:"popup"
Learn more

Related sample: Editor Collection

Text

A base editor for text values of datatable and dataview cells, list rows. By default is enabled on clicking the needed item;

{ id:"title", header:"Film title", editor:"text",

Related sample: Basic use of editors

Password

A base editor for passwords that masks symbols in the input.

//in the property sheet editor is defined by "type"
{ id:"pass", label:"Passoword", type:"password"}

Related sample: Property Sheet: Basic Initialization

Inline-text

A customizable text editor. Here you should set a template for the editing area, type and dimensions of an input area;

{ id:"year",template:"<input type='text' value='#value#' style='width:130px;'>",
    editor:"inline-text"}

Related sample: Using 'inline' editors

  • If you specify the editor:"inline-text" attribute the component will provide a special processing treat for the editor while editing: invoking edit-related events.
  • If you don't specify the editor attribute you should provide the processing logic for the editor on your own.

Select

A customizable editor that allow for choosing one of the offered values. It looks like a standard HTML select control.

{ id:"type", header:"Category",  editor:"select", options:[...]}

Related sample: Using the 'select' editor

The options can be defined by either a simple or an associatibe array as well as by url. Look here for details.

Combo

Webix combo control with the possibility to filter a popup list by entering symbols into the dedicated input;

{ id:"title", header:"Film title",  editor:"combo",  options:[...]}

Related sample: Datatable: Combo Editor

  • The options can be defined by either a simple or an associatibe array as well as by url. Look here for details;
  • The editor is subject to extensive customization.

Pro Extensions for Combo Editor

In the Webix Pro edition the editor can be extended to show either a dataview or datatable in the popup:

  • Dataview Suggest
  • Grid Suggest

Richselect

Webix richselect control that is a non-editable variation of a combo editor.

{ id:"title", header:"Film title",  editor:"richselect",  options:[...]}

Related sample: Datatable: RichSelect Editor

  • The options can be defined by either a simple or an associative array as well as by url. Look here for details;
  • The editor is subject to extensive customization.

Pro Extensions for Combo Editor

In the Webix Pro edition the editor can be extended to show either a dataview or datatable in the popup:

  • Dataview Suggest
  • Grid Suggest

Multiselect

The editor is available is Webix Pro edition only

The editor is based on Webix multiselect control and allows selecting multiple options at a time.

{ id:"assigned", editor:"multiselect", optionslist:true, options:[...]}

Related sample: Multi-select editor in the DataTable

  • The optionlist property is defined for the editable element (here:column) so that it can parse multiple values from the editor into a single cell value.
  • The options can be defined by either a simple or an associative array as well as by url. Look here for details.
  • The editor is subject to extensive customization.

Checkbox

A checkbox editor presupposes the choice between two values (true or false). In general, yon can assign any value to "true" and "false" checkbox states.

{ id:"ch3", header:"CheckBox",template:"{common.checkbox()}", editor:"checkbox"}

The notation above does nothing with checkbox value. If you want to derive its value as data item property, you should either:

1) Define checkbox options with values for each state:

{ id:"ch3", template:"{common.checkbox()}", editor:"checkbox", options:{
    "true":"On","false":"Off","undefined":"Off"}

Related sample: Using 'inline' editors

2) Set checkValue and unCheckValue pair:

{ id:"ch1", checkValue:'on', uncheckValue:'off', template:"{common.checkbox()}",
    editor:"checkbox"}

Related sample: Checkbox and radio in DataTable

Inline-checkbox

A customizable checkbox. You can do without a checkbox icon and define any template for boolean values, even a styled text.

function custom_checkbox(obj, common, value){
    if (value)
        return "<div class='webix_table_checkbox checked'> YES </div>";
    else
        return "<div class='webix_table_checkbox notchecked'> NO </div>";
}
    ...
{ id:"ch1", header:"", template:custom_checkbox, width:40, editor:"inline-checkbox"},

Related sample: Custom radio and checkbox in DataTable

Color

It is used for editing color value in the dataset with the help of a colorboard. Colors are stored as hex codes; hence, you should set an appropriate template for a component item to display the chosen result as color, for instance, make a colored background.

var tpl="<span style='background:#value#; border-radius:4px;'>&nbsp</span> #value#";

{ id:"start", editor:"color", template:tpl, header:"Color A",width:120}

Related sample: Color Editor

Date

In its essence it is a datepicker that initializes a calendar to pick the necessary date.

{ map:"(date)#enddate#",    editor:"date",  header:"End date",  width:120},

Related sample: Date Editor

Popup

A popup window with body contents depending on data you edit.

  • textarea - a multi-row input for editing long texts. The popup features width: 250 and height:50 by default.
{ id:"title",   header:"Film title", editor:"popup"}

Related sample: Pop-up editors

  • colorboard and caledar - come in popup windows by default and are set as date and color editor types.

$Popup

configuration for popup editors.

Popup Configuration

Configuring popups in a scope

You can configure editing controls inside popup windows, e.g. define other dimensions, alter properties of textarea, colorboard and calendar (check the corresponding articles.)

Popup editors can be configured in a scope with the following code. All the same-name editors in the application will be redefined:

//config may as well include only text, color and date hash
webix.editors.$popup = {
    text:{
        view:"popup", width:250, height:200,
        body:{view:"textarea"}
    },
    color:{
        view:"popup",
        body:{ view:"colorboard", width:500, height:500, rows:50, cols:50 }
    },
    date:{
        view:"popup",
        body:{ view:"calendar", weekNumber:true }
    }
};

Configuring popups separately

Any instance of a popup editor can be configured separately, with the help of a suggest property of an item in question:

Adding a weekHeader to the Date editor

{ id:"start", editor:"date", suggest:{
    type:"calendar",
    body:{
        weekNumber:true
    }
}}
  • type (string) - type of a suggest list that defines which Webix component will be used in a suggest body. The possible values are:
    • "list" - default suggest type that is used for select editors (combo, richselect and multiselect), can be omitted;
    • "calendar" - suggest type for date editor;
    • "colorboard" - suggest type for color editor;
  • body (object) - configuration of a component (list, calendar or colorboard)

Select editors offer a wide range of customization possibilities that are described in detail separately.

Defining options for select editors

Options for select editors (select, combo and richselect) are defined under the common pattern width the help of 'options' attribute of the dedicated column. There exist several possibilities:

1) Options are set directly in the "options" attribute either in an index or associative array as well as in a JS object:

Options defined by a simple array in the column config

columns:[
    { id:"cat_id", editor:"select", options:["Crime", "Thriller", "Western"]}
]

Related sample: Using the 'select' editor

Options defined by an associative array in the column config

columns:[
    { id:"cat_id", editor:"select", options:[
        {id:1, value: "Crime"},
        {id:2, value:"Thriller"},
        {id:3, value:"Western"}
    ]}
]

Options defined by a JS object

columns:[
    { id:"cat_id", editor:"select", options:[
        "1" : "Thriller",
        "2" : "Crime",
        "3" : "Western"
    ]}
]

Related sample: Using the 'select' editor. Specifying select options in a variable

2) Options are defined by a separate variable containing option collection. In this case the "options" attribute must be set to the name of this variable.

Setting select options in a variable

var film_options = [
    {id:1, value: "Thriller"},
    {id:2, value: "Crime"},
    {id:3, value: "Western"}
];
//or
var film_options =["Crime", "Thriller", "Western"];
...
columns:[
    { id:"cat_id", editor:"select", options:film_options, header:"Category"}
]

Related sample: Datatable: Combo Editor

3) Options are taken from file or loaded by url defined by "string" value of options attribute.

Options loaded from an external file

columns:[
    { id:"cat_id",  editor:"select", options:"data/options.json"}
]

Related sample: Loading data in the 'select' editor

"Options" have an alias attribute "collection" that features the same functionality.

Using "collection" to define options

columns:[
    { id:"cat_id", editor:"combo",  collection:film_options, header:"Category"}
]

Advanced configuration of select editors

Webix select controls, combo, richselect and multiselect, are highly customizable, which means that the same-name editors
can be customized too. The following things can be changed:

  • template of list items;
  • template of the input field (combo editor only);
  • filtering pattern (combo only);
  • text of "Select" button (multiselect only);
  • the number of list items in the popup;
  • functions can be attached to a list.

Two column attributes are mandatory - options or collection to interprete options into text and suggest to define the confuguration of related popup list:

{ id:"year", editor:"combo", options:years, suggest:{
     template:'#value#', //template of the input when editor is opened, default
     filter:function(item,value){ //redefines default webix combo filter
        if (item.value.toString().toLowerCase().indexOf(value.toLowerCase())===0)
            return true;
        return false;
     },
     body:{
        template:'Year #value#', //template of list items
        yCount:7, //10 by default
        on:{
           'onItemClick':function(id){
                webix.message(this.getItem(id).value);
            }
        }
     }}
}

Related sample: Datatable: Advanced Combo Editor

Multiselect specificity

To configure a suggest list for a multiselect editor, one should specify its suggest type - multisuggest:

{ id:"year", editor:"multiselect", options:years, optionlist:true, suggest:{
    view:"multisuggest",
    buttonText:"Select items"
}}

Datatable and treetable specificity - live editors

Webix datatable, treetable and property sheet can use any of the above mentioned editors in live mode and update the same data property is case it's used in another column other than the edited one.

//"rating" is used in both columns while it can be editable ony in the first one
columns:[
    { id:"rating",  header:"Count", editor:"inline-text", liveEdit:true},
    { template:"#rating#", width:150 }
]

Related sample: Using 'live' editors

The moment the second column (the one that is automatically edited) changes its value, onLiveEdit event takes place.

Edit Actions
  • 'click' - opens the editor on a single click (used by default);
  • 'dblclick' - opens the editor on a double click;
  • 'custom' - allow setting the necessary way of editing, e.g a keyboard event.

When setting an editaction to "custom", you need to refer to UIManager and write a function to enable the needed editing pattern:

webix.UIManager.addHotKey("enter", function(view){
    var pos = view.getSelectedId();
    view.edit(pos);
}, gridc);

Here editing is enabled on pressing the "Enter" key on the selected item.

Custom Editors

The library allows creating fully custom editors.

webix.editors = {
    "mytext":{
        focus:function(){...}
        getValue:function(){...},
        setValue:function(value){...},
        render:function(){...}
     }
  };

To define a new editor, you should specify at least 5 methods for it:

  • focus() - sets the focus to the input with the editor;
  • getValue() - gets the value of the editor;
  • setValue() - sets the value of the editor;
  • render() - renders the editor;
  • getInputNode() - gets the input area object.

For instance, this is how a biult-in text editor is made:

webix.editors.myeditor = {
    focus:function(){
        this.getInputNode(this.node).focus();
        this.getInputNode(this.node).select();
    },
    getValue:function(){
        return this.getInputNode(this.node).value;
    },
    setValue:function(value){
        this.getInputNode(this.node).value = value;
    },
    getInputNode:function(){
        return this.node.firstChild;
    },
    render:function(){
        return webix.html.create("div", {
            "class":"webix_dt_editor"
        }, "<input type='text'>");
    }
}

Inner properies

  • this.node - HTML tag of the editor. Appears after render() execution;
  • this.value - the initial value of an input. Appears after setValue(); execution;
  • this.config - editor configuration;
  • this.popup - popup ID (is used for editors with popup windows)

Extending Functionality of an Editor

In addition to creating an editor "from scratch", you can extend any of the existing ones. It becomes helpful when slight changes are needed.

For instance you have a datatable column with e-mails. Input type email from HTML5 package will warn you in case some of e-mail address features is missing. The cell will be highlighted red.

In this case you extend the existing text editor and change render pattern in it:

    webix.editors.myeditor = webix.extend({
            render:function(){
            return webix.html.create("div", {
                "class":"webix_dt_editor"
            }, "<input type='email'>");
        }}, webix.editors.text);

Related sample: Custom Text Editor


Intermediate

Paging

Paging helps present numerous items from the dataset dividing them into groups to display on separate pages. It is used in conjunction with data-presenting components like dataview, datatable and list.

Pager can be initialized as

  • separate ui-related component (should be linked to a component to enable paging);
  • as property of the component it is used for.

In both cases pager can be placed into its own HTML container different from that of the associated component.

Main properties of a pager object:

  • size - the number of records per page;
  • group - the number of pages (numbered squares for paging);
  • page - sets the page that will be shown intially (zero-based numbering).

If a component container is too small to display the number of items specified by size, a scrollbar appears.

Related sample: Paging animation

Paging and Dynamic Loading

With dynamic loading, only part of the stored records are loaded into the component during init. Each time you page through the component, a data request is sent to server to load the next portion of data.

Read more about dynamic loading.

Pager as separate view

In this case pager is initialized as separate component in layout and is linked to the datatable by ID.

webix.ui({
    rows:[
        {
            view:"datatable",
            columns:[ ...],
            pager:"pagerA", //linking to a pager
        },
        {
            view:"pager", id:"pagerA",
            size:50,
            group:5
        }]
})

Related sample: Visible Pager in Layout

In this case when pager is a standalone view size property can be combined with either limit or count property to set the total values for the pager, namely:

  • limit - the total number of pages in pager. The number of records will be calculated automatically.
  • count - the total number of records the pager will process. The number of pages will be calculated automatically.

You can as well use Webix pager as a separate entity without master component and provide fully custom login for it - go to the end of the article for details.

Pager as component property

Here pager object appears to be the property of a datatable and includes two parameters of its own.

webix.ui({
    view:"datatable",
    columns:[...],
    pager:{
        size:50,
        group:5
    }
});

Related sample: Visible pager

Several Pagers per Component

If you want more than one pager for the component, for instance the ones above and below the view, there should be two containers in HTML layout, or two views with pager instances. The two pagers must be linked to each other with the help of the clone method.

You can clone both standalone pagers and those included into the component constructor.

Cloning a standalone pager

//an identical pager
$$("pagerA").clone($$("pagerB"));

//a pager with some properties of its own
$$('pagerA').clone({
    container:"pagingB_here",
    size:50,
    group:5
});

Related sample: Two-area pager

With a component pager you need to get the pager object with the getPager() method:

Cloning a component pager

grida.getPager().clone({
    container:"paging_here_too",
    size:10,
    group:5
});

Related sample: Defining several pagers on a page

Cloned pagers will change their values sumultaneously!

Invisible pager

Paging can be implemented through an invisible pager, which gives you an ability to control the process by custom functions and create your own "Next/Previous Page", "Jump to Start/End" buttons, etc. instead of a standard pager.

For these needs you should include apiOnly parameter with true value into the pager constructor, whether it is initialized as a separate view or as a component's property.

Datatable with Invisible Pager

view:"datatable",
...
pager:{
    id:"pagerA",
    apiOnly:true, //makes pager invisible
    size:50,
    group:5
}

In this case, dedicated buttons will help us page:

Next Page Button

<input type='button' value='next page' onclick='next_page()'>
...
function next_page(){
    $$("pagerA").select("next");
}

Related sample: Not-visible pager

Select() function can take the index of the desired pager (zero-based numbering,) or its **order* ("next", "prev", "first", "last").

Custom Templates for Paging

By default, pager looks as numbered squares accompanying the component . But at the same time you can change the pattern with the help of a custom template:

Template elements may include the following elements:

  • {common.prev()} - 'less-than' sign, directs to previous page;
  • {common.first()} - double 'less-than' sign, directs to the first page;
  • {common.next()} - 'greater-than' sign, directs to the next page;
  • {common.last()} - double 'greater-than' sign, directs to the last page;
  • {common.page()} - displays the number of the current page (starting from 1);
  • {common.pages()} - displays a set of numbered squares;
  • pager data elements (e.g. '#limit#' to display the total number of pages);
  • standard text.
pager: {
    template: "{common.prev()}{common.next()}Page {common.page()} from #limit#"
}

Related sample: Custom Pager Template

HTML Custom Pager

You can use HTML elements as a base for a custom pager that includes both HTML tags and pager properties in its template.

Properties of the component pager are stored in the data object, pager templates reside in the common object:

  • data.page - the index of the current page(zero-based numbering);
  • data.size - the number of data records per page (either set manually, or calculated on the base of component size)
  • data.limit - the number of record processed. Equals to the number of records in the connected component.
  • common.next(), common.prev(), common.first(), common.last() - page order signs.

Custom 'select' pager

pager:{
    template:function(data, common){
        var current = data.page + 1;
        var html = "<select onchange='grida.setPage(this.value)' style='text-align:center; width:150px'>";
        for (var i=1; i<=data.limit; i++)
            html+="<option "+(i == current?"selected='true'":"")+">"+i+"</option>";
        html+="</select> from "+data.limit;
        return html;
    },
    container:"paging_here",
    size:10,
    group:5
}

Related sample: Custom pagers

Pager Localization

By default, pager uses recognizable signes to display order buttons (first, last, prev, next).

Default Locale

webix.locale.pager = {
    first: " &lt;&lt; ",
    last: " &gt;&gt; ",
    next: " &gt; ",
    prev: " &lt; "
};

Pager localization allows using words of any language for these buttons:

Custom Locale

webix.locale.pager = {
    first: "First",
    last: "Last",
    next: "Next",
    prev: "Prev"
};

Related sample: Pager localization

Animation during Paging

Animation it switched on by animate property. Set to true, it allows scrolling through the view in X or Y mode, depending on the scroll value of the main component.

Animation can take various effects when they are stated in the animate constructor through type, subtype and direction parameters.

pager: {
    animate:{
        direction:"top",
        type:"flip"
    }
}

Related sample: Paging animation types

Learn more about animation types and subtypes in the corresponding chapter of the manual.

Page and Component Size

Here we treat two tasks:

1 . How to ensure that the number of records per page equals to the number of records the component can display?

The number of records per page is stated by the size:(number) parameter of a pager.

At the same time, the number of records can be limited in the component itself by the following parameters:

  • yCount (number) - the number of items in a vertical mode;
  • xCount(number) - the number of items in the horizontal mode (typical of dataview and x-list).

All you need is to make these two parameters the same:

rows:[
    {
        view:"pager",
        id:"pagerA",
        size:10
    },
    {
        view:"datatable",
        columns:[...],
        pager:"pagerA",
        yCount:10
    }
]

Related sample: Adjusting Component Size to Page

2 . How to adjust component size to page size?

To adjust the number of records shown per page to the size of parent HTML container and, hence, to the component's height, you should let pager autosize.

<div id="testA" style='height:600px; width:300px;'></div>
...
webix.ui({
    rows:[
        {
            view:"pager",
            id:"pagerB",
            autosize:true,
            group:5
        },
        {
            view:"list",
            pager:"pagerB",
            container:"testA"
        }
    ]
});

Related sample: Adjusting Page Size to Component Size

Paging Methods

Getting Pager Object

$$("datatable1").getPager();

Getting Current Page

Note that you'll get page index (zero-based numbering), so add 1 to get the actual page number.

$$("datatable1").getPage();

//or, using the pager object
$$("pagerA").config.page;

Setting (Opening) Page

To programmatically switch to the necessary page, specify the page's index within the dedicated method:

$$("datatable1").setPage(2); // makes the third page visible

..or select the needed page:

$$("datatable1").getPager().select(2); // -> selects the third page

Standalone Pager

Pager can be used without master component for creating custom logic. To render such pager, the following code should be used:

webix.ui({
  view: 'pager',
  template: '{common.prev()} {common.pages()} {common.next()}',
  master:false,
  size: 50,
  group: 5,
  count: 1000,
  on: {
      onItemClick: function(id, e, node) {
          //..some custom logic..
      }
  }
});

Template parameter can be omitted in favour of default template.

Related sample: Standalone pager

Note that count and size parameters should be used anyway, count divided by size equals to the total number of pages.


Intermediate

Drag-n-Drop within Webix Views

Basics of DnD

Here we speak about simple drag and drop of items within one and the same component as well as between different views and their instances. The information about how to make any app element draggable is to be found in the dedicated article of the documentation.

Drag-and-Drop Modes

All the components you'd like to work with must have drag property, both source and target components. In case of several instances of one and the same component, it would be enough to enable DnD. For adequate DnD between different components study external data functionality.

The property has several values to define DnD mode:

  • drag:true - enables drag-n-drop within the component, allows taking items into its other instances and different components on the page;
  • drag:"order" - enables DnD in the reorder mode, allows dragging component item within one component thus changing their order;
  • drag:"source" - enables dragging items from the component without an ability to drop data from other components;
  • drag:"target" - enables dropping data to the component. It can take data from outside, but you cannot drag anything from it.

Mutlidrag mode (dragging of several items at a time is possible) is enabled by setting multi selection ability within the component.

Multi Selection:

  • multiselect: true - selection of several items regardless of their heirarchy;
  • multiselect:"level" - selection of several items belonging to one and the same hierarchical level within the same tree branch.

Treetable Multidragging

webix.ui({
    view:"treetable",
    ..//treetable config
    multiselect:true,
    drag:true
})

Related sample: Multi Drag-and-Drop between Trees

Reorder mode works only with non-hierarchical components like datatable, list and x-list.

Related sample: DnD with List Items

Drag-and-Drop Context and Events

In essence, DnD is a a set of sequential events: first you hook on the necessary component item, then drag it to the desired position and drop the item releasing the mouse button.

Therefore, the component with draggable items as well as the one with a dropping ability, gets the following events:

  • onBeforeDrag - fires before DnD is started;
  • onBeforeDragIn -fires before a dragged item is moved over the dropping area;
  • onBeforeDrop - fires when the dragged item is moved over the dropping area;
  • onAfterDrop -fires after the dropping has happened;
  • onDragOut - fires when a dragged item moves out of the dropping area.

They are used to control the DnD process and customize it on different stages since any event can trigger any custom function you'd like to associate this event with.

Functions attached to these events have context and native event as arguments.

Native event is a DOM event that happens during drag-and-drop while context is an object with the following properties:

  • from - the source object;
  • to - the target object;
  • source - the ID of the dragged item(s);
  • target - the ID of the drop target, null for drop on empty space;
  • start - the ID from which DnD was started.

For instance, the onBeforeDrop can be used to make a copy a dragged item the moment it's dropped while not changing its place at all:

view:"datatable",
drag:true,
on:{
    onBeforeDrop:function(context, e){
        this.getItem(context.target).title = context.source.innerHTML; //copying
        this.refresh(context.target);
        return false; //block the default behavior of event (cancels dropping)
    }
}

Related sample: Drag-and-Drop from HTML

More about the possibilities of DnD event system

Drag-and-Drop - Advanced Level
  • Defining Drag Handle - learn how to set a dragging handle to a component item;
  • Defining Drag Marker - how to set a DnD message and mark by color the dropping area;
  • DnD with Tree and TreeTable Components - how to observe hierarchy during DnD;
  • DnD Between Different Components - how to use the externalData property while dragging an item from one component to another;

  • Drag-and-Drop Events - how to use DnD event system for custom DnD, e.g. copying items with drag-and-drop;

  • On-Page Drag-n-Drop (Advanced Level) - how to make any Webix view or HTML node on the page draggable and control every aspect of DnD;

  • HTML5 Drag-n-Drop with Webix Views - how to use HTML5 DnD within Webix lib.


Advanced

Defining Drag Area

Predefined drag area is usedful when using drag-n-drop on touch devices as slide movements over drag area will be interpreted as dragging rather than scrolling.

Related sample: Drag and Drop with Drag Handle

By default any draggable item or component can be dragged by clicking and holding left mouse on any of its areas, but sometimes it looks more convenient to define a separate area that will be the only place you can click to drag the item.

Such area may be defined by icon on the item included into the item data template.

Create an icon

<style type="text/css">
    .webix_drag_handle{
    background-image:url(./handle.png); // path to the image icon
    background-repeat: no-repeat;
    cursor:n-resize; //type of the cursor to signify DnD ability
            }
</style>

Define drag area

webix.ui({
    view:"list",
    template: "#data#<div class='webix_drag_handle'></div>"
    on:{
        onBeforeDrag:function(data, e)
        return (e.target||e.srcElement).className == "webix_drag_handle";
        }
 });

OnBeforeDrag event triggers a function that sets 'webix_drag_handle' class for both target and source elements.

Drag Area with Datatable

To define a drag area for Webix Datatable you should either add template to some column or add a separate column with drag area CSS:

view:"datatable",
drag:true,
columns:[
    { id:"title",   fillspace:true, header:"Film title" },
    { id:"drag", header:"", template:"<div class='webix_drag_handle'></div>", width:35}
]

Related sample: Limiting the draggable area for items (dragging rows)

In case of column drag-n-drop, drag area can be defined as well:

view:"datatable",
dragColumn:true,
columns:[
    { id:"votes", header:"<div class='webix_drag_handle'></div>Votes", width:120},

Related sample: Limiting the draggable area for items (dragging columns)

Related Articles

  • Defining Drag Marker
  • DnD with Tree and TreeTable Components
  • DnD Between Different Component


Advanced

Defining Drag Marker

Drag Marker is a graphical element that appears in the dropping area and helps clearly see the position where the dragged element needs to be dropped.

Related sample: Custom Target Drag Marker

The look-and-feel of the drag marker is set via a div element with a CSS class where you set all its properties (positioning, borders, background color, marker text (if any), etc.. ).

.my_line_mark{
    border-top:1px dashed orange;
    width:100%; height:1px;
    position:absolute;
    left:0px;
    display:none;
}

The div element is placed into the document body:

var marker = webix.html.create("div", {
        "class":"my_line_mark"
},"&nbsp");
document.body.appendChild(marker);

The library features a set of functions for working with HTML. One of them, create(), makes an HTML div container with Javascript means, assigns a CSS to it while the content of the new HTML block is empty, which is signified by &nbsp.

After that, you should extend the already initialized component with the drag marker functionality. Here the $dragMark property comes to your help. Its value is a function that makes the marker visible as soon as the dragged element reaches the target area. Marker dimensions depend on the dimensions of an element being dragged:

webix.extend(treea, {
    $dragMark:function(context, ev){
        marker.style.display = 'none';
        if (context.target){
            var pos = webix.html.offset(ev.target); // position of the target view
            var box = webix.html.offset(this.$view); // current position of the dragged element

            marker.style.display = 'block'; // shows the marker
            marker.style.top = pos.y+"px"; // sets top offset of the marker
            marker.style.left = box.x+"px"; //sets left offset of the marker
            marker.style.width = this.$view.offsetWidth+"px"; //set the marker width
        }
    }
}, true);

Comments:

  • the function takes DnD context (described above) and native DOM event as parameters;
  • initially the drag mark is not displayed and becomes visible only in the target area;
  • firstly, properties of a dragged element are found out; then they define properties of the drag marker;
  • webix.html.offset method gets the absolute top and left postioning of an HTML element specified as an argument;
  • offsetWidth DOM method returns width of an element, including borders and padding.

Adding and Removing Marks

addCss() and removeCss() methods can help you apply any style for your drag marker defined as a CSS class. They are also used within a $dragMark function, but here you heedn't create a separate HTML container for the marker.

webix.extend(treeb, {
    $dragMark:function(context, ev){
        if (this.my_marked && this.my_marked != context.target){
            this.removeCss(this.my_marked, "my_custom_mark", true);
            this.my_marked = null;
        }
        if (context.target){
            this.my_marked = context.target;
            this.addCss(context.target, "my_custom_mark", true);
        }
    }
}, true);
  • my_custom_mark is a CSS class for drag marker;
  • a marker is added only to a target component (the mark becomes visible as you drag an item to the target);
  • a marker is hidden the moment a dragged item leaves the target area as well as the moment you drop an item there.

Related Articles

  • Defining Drag Area
  • DnD with Tree and TreeTable Components
  • DnD Between Different Component


Advanced

Drag-and-Drop with Tree and TreeTable

In case of tree and treetable where data is presented in a hierarchical way, it's vital to specify how tree nodes would be dragged between different levels.

By default, if a tree node is dragged into the branch of the same level as its parent, it becomes the first child of this branch. At the same time, if you drop lower-level nodes to the higher-level branches (the mouse is released over this higher-level node) the dragged node takes its level and become the previous child of this node. )

In addition, if you drag-and-drop the tree branch it is moved together with its leaves.

Related sample: Basic Drag-and-Drop between Trees

Event handling within DnD can help you change dragging as well as dropping pattern.

For instance, if you want to prevent DnD on a top level items as well in leaf items, you should block it before the dragged element reaches the dropping area:

on:{
    onBeforeDragIn:function(config, id){
        if (!id) return false;                      //block dnd on top level
        if (!this.getItem(id).$count) return false; //block dnd in leaf items
}}

Dropping process can be as well customized. To enable dropping of the nodes into a tree branch as its children you should state that the dropping target is a parent branch.

on:{
    onBeforeDrop:function(context){
        context.parent = context.target;    //drop as child
        context.index = -1;                 //as last child
}}

Related sample: Drag-and-Drop between Tree Nodes - Drop as Child

The posiition of a dropped item is set in the following way: the item becomes the first child if it is dropped over an opened tree branch; in other cases, e.g. the item is dropped over the leaves of a tree branch is takes the next position relative to the child it is dropped over:

on:{
    onBeforeDrop:function(context){
        if (this.getItem(context.target).$count && this.getItem(context.target).open){
            //drop as first child if the item is dropped into an opened tree branch
            context.parent = context.target;
            context.index = 0;
        } else {
            //in other cases, the dropped item takes the next next position
            context.index++;
        }
    }
}

Related sample: Drag-and-Drop between Trees - Drop Next

Related Articles

  • Defining Drag Area
  • Defining Drag Marker
  • DnD Between Different Component


Advanced

Drag-and-Drop between Different Components

External Data Functionality

During drad-n-drop operations between different components as well as different instances of a component it's vital to ensure that data items from the source component receive adequate representation in the target one.

externalData property features a function responsible for dragging as value (in case you work with different components).

{   view:"tree",
    drag:true,
    select:true,
    data:[],
    externalData:grid2tree
};

The property function takes two parameters - data and id:

  • data (object) - the data item to move;
  • id (string) - the item id in the source element.

When moved to the target component the item retains the ID it had in the source component unless the target already has an item with this ID. In this case, the ID will be set randomly while the initial ID will be stored in the function.

Take for instance, an app containing two trees, a dataview and datatable. The tree dataset includes items with data.value items while dataview and datatable have data.title and data.rank. To enable drag-n-drop within the whole group, you need two functions:

1 . The function that will populate dataview and datatable.

function tree2grid(data, id){
    data.rank = data.rank || -1;
    data.title = data.title || data.value;
    return data;
}

Notice the "or" logic here:

  • If you drag data from datatable to dataview and vice versa, native data and external data have the same parameters, so data.title value from the datatable becomes data.title of the dataview. The same is true about data.rank.
  • If you drag data from any of the trees to datatable and dataview, you need to redefine data.title parameter and take its value to the data.value of the tree. Then, since in the sample data for both trees has no data.rank parameter, its value will be displayed as "-1".

2 .The function that will populate tree with dragged data.

function grid2tree(data, id){
    data.value = data.value || data.title;
    return data;
}

Here only data.value matters. The tree will take the dragged-and-dropped data.value value from the other tree, or the data.title value from either fo the datatables.

Related sample: Basic Drag-and-Drop

Related Articles
  • Defining Drag Area
  • Defining Drag Marker
  • DnD with Tree and TreeTable Components


Advanced

Drag-and-Drop Events

DnD event system allows you to customize the process of drag-and-drop and adjust it to your needs.

Copying with DnD

Basically, drag-and-drop of component items means that you remove an item from one component and place it to the other one. Still if needed, you can copy items with DnD by actually leaving a dragged item in the source component and making its copy in the target one.

For these needs, we refer to the onBeforeDrop event and associate a copying function with it. Also, we make use of source and from properties of the DnD context object.

gridb.attachEvent("onBeforeDrop", function(context, ev){
    for (var i=0; i< context.source.length; i++){
        context.from.copy(context.source[i],context.start,this,webix.uid());
    }
    return false;
});

Here we copy each item (that is dragged) from the source object with the help of the dedicated function. It takes the following arguments:

  • context.source[i] - the ID of the copied object;
  • context.start - the index of the copy;
  • this - the object that an item is copied to (since the fucntion is attached to gridb, this refers to it)
  • webix.uid() -the ID of the copy-item, here it's generated automatically with the tool for getting an unique (in frames of a session) ID.

Displaying Titles of Dragged Items

In case of datatable, the whole rows can be dragged to other components as well as moved between datatable instances.

By default, the whole row is displayed while being dragged, which is not always convenient and pleasant to see. Sometimes, it would be enough to display the value of the main column during DnD. The same happends with dataview and list, the components that feature several template values in each item.

Here, the onBeforeDrag event is needed as the functionality should be enabled as soon as we hook on the necessary item. Also, as above, we take source and from properties from the DnD context object.

grida.attachEvent("onBeforeDrag", function(context, ev){
    context.html = "<div style='padding:8px;'>";
    for (var i=0; i< context.source.length; i++){
        context.html += context.from.getItem(context.source[i]).title + "<br>" ;
    }
    context.html += "</div>";
});

Here we create a div container for the DnD context item and define 8-px padding for it. Then, with each of the dragged items from the source we take a title value from the dataset and close a div container.

Related sample: Using events for customizing dnd

Related Articles

  • Defining Drag Area - learn how to set a dragging handle to a component item;
  • Defining Drag Marker - how to set a DnD message and mark by color the dropping area;
  • DnD with Tree and TreeTable Components - how to observe hierarchy during DnD;
  • DnD Between Different Component - how to use the externalData property while dragging an item from one component to another;


HTML5 DnD with Webix Views

HTML5 brought native drag-n-drop techniques that can be used as well for Webix views. Here we study how to drag html nodes to a Webix datatable using HTML5 dnd.

Related sample: HTML5 Drag-and-Drop handling

Firstly, we make the needed HTML nodes (here - colored divs below grid) draggable and assign a function to fire when you start dragging them:

<div id="divA" draggable="true" ondragstart="drag(event)" > A </div>

And enable drag-n-drop in both directions (drag from here and drop here) within a Webix grid:

view:"datatable",
..config..,
drag:true

Secondly, we need to set which data matters during DnD. In HTML5 data is transferred with the help of (surprisingly) dataTransfer object. We need the following of its methods:

  • setData() - to set transferred data as {key1:value1, key2:value2};
  • getData(key) - to get the needed data item by its key;

From HTML nodes we take their text values (innerHTML);

function drag(ev){
    ev.dataTransfer.setData("title",ev.target.innerHTML);
}

When the dragged node is dropped on the target grid item, we get the data from DataTransfer and parse it into the item.

HTML5 events are handled with event method that takes node or its ID, event type, event handler and "this" object as parameters. Event names are passed without on prefix:

webix.event(mygrid.$view, "drop", function(e){
    var grid = $$(e); //e - id of drop target
    var id = grid.locate(e); // return ID of target grid item
    grid.getItem(id).title = e.dataTransfer.getData("title"); //setting new title
    grid.refresh(id); //make the changes visible
});

At the same time, we need to prevent default drag-n-drop behavior, if we want HTML nodes to keep their position (in fact, copying of their innerHTML takes place);

webix.event(mygrid.$view, "dragover", function(e){ e.preventDefault(); });

HTML5 Drag-n-Drop can be studied here (Mozilla Developer Network).


Intermediate

Working with the clipboard

Webix provides support for the clipboard operations in all data-containing components. For this purpose, the library supplies the CopyPaste mixin.

By default, the support is disabled. To enable it, set the clipboard property to true :

Enabling the clipboard support

webix.ui({
    view:"list",
    ...
    clipboard: true,
});

Related sample: List: Work with Clipboard

In 3 components this mixin is already included. These components are:

  • DataTable (has extended support. See details);
  • Tree (has extended support. See details);
  • List.

If you want to work with the clipboard in any other data-containing component, you should extend it with CopyPaste class. For example, to add the support to DataView use the technique shown below:

var webix.ui({
    view:"dataview",
    id:"myview",
    ...
    clipboard: true,
});

webix.extend($$("myview"),webix.CopyPaste);

Custom 'copy' function

To customize the way that the data will be stored in the clipboard (when the user presses CTRL+C) you should use the templateCopy property. In that case, before transfering to the clipboard the copied data will be modified according to the specified template.

To use the the templateCopy property you need to set the clipboard property to a value 'custom'.

Let's take a simple example: you have a list that displays the names of your favourite films. Assume, in the clipboard besides the film title you want to store its year and rating.

Then:

  • Set the clipboard property to the 'custom' value;
  • Specify the templateCopy property like this (as a parameter, the template function takes the data item object):
var films_set = [
    { id:1, title:"The Shawshank Redemption", year:1994, votes:678790, rating:9.2},
    { id:2, title:"The Godfather",            year:1972, votes:511495, rating:9.2},
    { id:3, title:"The Godfather: Part II",   year:1974, votes:319352, rating:9.0},
    { id:5, title:"My Fair Lady",             year:1964, votes:533848, rating:8.9}
];

webix.ui({
    container:"box",
    view:"list",
    data:films_set,
    template:"#title#",
    clipboard: "custom",
    templateCopy: function(item) {
        return item.title+" (year: "+ item.year+", rating: "+item.rating+")";
    }
});

Related sample: List: Work with Clipboard

Custom 'paste' function

To customize the way that the data will be retrieved from the clipboard to a Webix component you should use the onPaste event.

The event fires when the user presses Ctrl+V keys combination and as a parameter, the handler function takes the text stored in the clipboard.

To use the the onPaste event you need to set the clipboard property to a value 'custom'.

var films_set = [
    { id:1, title:"The Shawshank Redemption", year:1994, votes:678790, rating:9.2},
    { id:2, title:"The Godfather",            year:1972, votes:511495, rating:9.2},
    { id:3, title:"The Godfather: Part II",   year:1974, votes:319352, rating:9.0},
    { id:5, title:"My Fair Lady",             year:1964, votes:533848, rating:8.9}
];

webix.ui({
    view:"list",
    id:"mylist",
    ...
    clipboard: "custom"
});
$$("mylist").attachEvent("onPaste", function(text) {
    text = text.split(" , ");

    var sel = this.getSelectedId(true);
    for (var i = 0; i < sel.length; i++) {
        var item = this.getItem(sel[i]);
        item.title = text[0];
        item.year = text[1];
        item.votes = text[2];
        item.rating = text[3];
        this.refresh(sel[i]);
    }

});

Related sample: List: Work with Clipboard

Clipboard Events
  • onPaste - fires when Ctrl+V shortcut is pressed:
tree.attachEvent("onPaste", function(text) {
        webix.message("Node is pasted: " + text);
});

Related sample: Custom Clipboard Operations


Grouping Data Items

Grouping Types

Grouping data in Webix components can be obligatory and optional, static and dynamic.

Obligatory grouping

Grouping is a must-have feature for components that present data hierarchically yet are populated with non-hierarchical (inline) dataset.

Such components are subject to initial static grouping. Each group features a group header(parent branch) that can be opened to show the group members.

  • grouplist;
  • tree;
  • treetable.

When they are fed with hierarchical data grouping is not necessary. Read more about data types.

Optinal grouping

Data can be groupped if you need to present data united by some criterion.

  • chart;
  • datatable.

With these componnents you can see only the result of grouping.

In case of inline dataset:

  • the initial grouping for list makes it grouplist;
  • the initial grouping for datatable makes it treetable. Still, datatable can be dynamically grouped.

However, they are separate components - groulist and treetable - and should be created with their own names.

Static/Initial grouping

Grouping criteria are set during component init by the $group key of the scheme object. Necessary for the components with obligatory grouping.

webix.ui({
    view:"tree",
    scheme:{
        $group:"year"
    }
});

Related sample: Tree: Plain JSON Data with Client-side Grouping

Dynamic grouping

Grouping is defined by a function applied to the component.

$$("mytree").group("year");

To cancel grouping, make use of the opposide method.

$$("mychart").ungroup();

Setting Grouping Pattern

Syntax for group() method and $group object property is the same - you need to specify here the grouping critetion as:

  • data item;
  • function;
  • object.

Data Item

String that points to the property from the initial dataset;

//static mode
tree = webix.ui({
    view:"tree",
    scheme:{
        $group:"year"
    }
});

//dynamic mode
tree.group("title");

Function

The function is applied to data object and returns grouping criterion(-a);

scheme:{
    $group:function(obj){
        return obj.year + ..;
    }
}

Related sample: List: Grouping

Object

An object with properties defining grouping criterion and grouping pattern:

  • by (must-have) - set the grouping criterion either as string or as function.
  • map - an object that redefines values to display in the current template. Here math functors are applied to the specified properties of group members.
  • footer (for treetable) - defines template for extra table line that displays common property of group members.
  • row (for datatable and treetable) - defines template for the whole row regardless of initial columns.
//static mode
webix.ui({
    view:"chart",
    scheme:{
        $group:{
            by:"year",
            map:{...}
        }
    }
});

//dynamic mode
grida.group({
    by:"year",
    map:{...}
});

If you use only by property in the group object, it is the same as if you define criterion with a data item or function. Hence, the following definitions are equal:

$group:"year"

$group: function(obj){ return obj.year;}

$group:{ by:"year" }

$group:{
    by: function(obj){ return obj.year }
}

The function can be of any complexity:

by: function(obj){ return Math.floor(obj.year/10); }

Related sample: Static grouping

Grouping Functors

Grouping functors are used within map and footer that redefine templates.

$group:{
    by:"year",
    map:{
        property(template):['property', functor]
    }   //or property:[function (obj){...}]
}

Grouping functors:

  • any to show all values for this property; the same effect will be set if you omit functor at all.
  • sum to calculate and show total sum of the values;
  • max to pick the maximum value of the property;
  • min to pick the minimum value of the property;
  • count to calculate the number of items in each group;
  • string to show property name as a string rather than its value. For {year:1994}, the word "year" witll be displayed in the component.
  • custom functor for other math operations.

Learn more about grouping functors.

Templates for Groups and Items

By default, component items display object value which is:

  • value property of the datasource;
  • value from the dataset defined by template;
  • value of an array element (if data comes in JSArray);

For items that display a group headers (parent branches), value is the one defined by by criterion:

webix.ui({
    view:"tree",
    scheme:{
        $group:{
            by:"year" // group header value
        }
    },
    data: [  //default value
    { id:1, value:"The Shawshank Redemption", year:1994, votes:678790, rating:9.2, rank:1}, {...}]
});

Related sample: Tree: Plain JSON Data with Client-side Grouping

If a component has a template that sets other property as value for its items, you need to define map to redefine this value during grouping:

webix.ui({
    view:"tree",
    template:'{common.icon()} {common.folder()}#title#',
    scheme:{
        $group:{
            by:"year",
            map:{
                title:['year', 'any']
            }
        }
    }
});

Initially, template allows showing only titles. Map tells that group title is year and makes year the value to show.

Each component has its own peculiarities concerning templates in a grouped mode. Study them below.

In addition, you can chanage data to display by defining a function for the "onGroupCreated" event.

Datatable and Treetable Specificity

For datatable and treetable data templates are set by column IDs or column template or both.

Yet, in grouped mode, the grids won't show data for those columns which templates are not set either by template function or by map.

Map can redefine more than one property.

map:{
    votes:["votes", "sum"], //"votes" values will be summed
    title:["year"] //title will take year values
}

Related sample: Aggregating data while grouping

Function templates allow for setting different presentation ways for group items and group headers.

  • obj.$group - stores item state (whether it is a group item or group header )
  • obj.$level - stores hierarchy level with upper being 1.

The two snippets are equal:

template: function(){
    if(obj.$group) return ...; //for group headers
    return ... //for group items
}

template: function(){
    if(obj.$level==1) return ...; //for group headers
    return ... //for group items
}

Treetable with map defined:

columns:[
    { id:"title", template:function(obj, common){
            if (obj.$group) return common.treetable(obj, common) + obj.title;
            return obj.title;
            }
    }
],
scheme: {
    $group:{
        by: "year",
        map:{
            title:["year"] //year is 'obj.title' for group header
        }
    }
}

Related sample: Aggregating data while grouping

Treetable with unset map:

columns:[
    { id:"title", template:function(obj, common){
        if (obj.$level == 1) return common.treetable(obj, common) + obj.value;
        return obj.title;
        }
    }
],
scheme:{
    $group:"year" //year is obj.value for group header
}

Related sample: Static grouping

Row Templates and Additional Rows

Row template

Row property within grouping object sets group header template for the whole row regardless of grid columns.

grida.group({
    by:"year",
    map:{
        "year":["year",  "any"],
        "votes":["votes", "sum"]
    },
    row:function(obj){
        return "Year "+obj.year+", total votes: "+webix.i18n.numberFormat(obj.votes);
    }
});

Related sample: Data aggregation in Custom Format

Group Footer

Group footer display common value for all the members of this group, e.g. total sum, max or min value, etc.

Footers are defined in the same way as map and includes the chosen property treated with a functor and a template for the footer row.

grida.group({
    by:...,
    map:{...},
    footer:{
        votes:["votes", "sum"],
        row:function(obj ){ return "<span style='float:right;'>Total: "+webix.i18n.numberFormat(obj.votes)+"</span>"; }
    }
});

Related sample: Dynamic grouping: Extra lines

Chart Specificity

For grouped chart grouped items and group headers correspond to each of its axes

  • X-axis values display grouping criterion (introduced by by);
  • Y-axis values display the chosen values of group items treated with a functor.

For instance, if you need to display sells of each company, you should group all sales values by company while calculating the sum for each company.

webix.ui({
    view:"chart",
    value:"#sales#", //default template for Y axis
    scheme:{
        $group({
            by:"company", //template for X axis
            map:{
                sales:["sales","sum"]
            } //Y axis template now shows sum of all sales for each year
        })
    }
})

Related sample: Grouping

The first element in the map is a data item property while the second one is a functor applied to all the values of this property.

Grouplist Specificity:

Grouplist features ites own properties:

  • templateItem - to set template for items in a group;
  • templateGroup/templateBack - to set template for group header.

See grouplist article for details.

Grouping Events
  • onGroupCreated - fires when grouping is applied to the component and takes the following parameters:
    • id - ID of the group header (parent branch);
    • value - value of the grouping criterion;
    • data - component data object;
  • onGroupFooter - fires when grouping is applied to the component and a footer for each group is provided.
webix.ui({
    view:"treetable",
    on:{
        "data->onGroupCreated":function(id, value, data){
            this.item(id).value = "Year "+value;
        }
    }
});

grida.group({
    by:"year" //obj.value = year
});

Related sample: Handling events while data grouping


Custom Functor for Data Grouping

Functor is a method that is applied to an item property in order to define the way it is presented in a group header.

[
    { id:1, title:"The Shawshank Redemption", year:1994, votes:678790},
    { id:2, title:"The Godfather", year:1972, votes:511495},
    { id:3, title:"The Godfather: Part II", year:1994, votes:319352},
    { id:4, title:"The Good, the Bad and the Ugly", year:1972, votes:213030}
]

When data is grouped by year, we may want to learn total number of votes per year, or their maximim/minimal value, etc. It is grouping functors that are designed for this purpose. They are used within map object of the grouping function.

$group:{
    by:"year",
    map:{
        votes:['votes', 'sum']
    }   //'sum' is a functor to calculate votes total for each year
}

Related sample: Data aggregation

Simplest operations are supplied by prebuilt grouping functors stored in the GroupMethods class.

However, you can a create custom functor to meet your needs.

Adding a New Functor

Any function can become a grouping functor provided that you've given it the unique name, described the logic and added to the GroupMethods class.

Such function takes two arguments:

  • prop - the property to process;
  • data - data object with items of this group.

There's no functor to find out the average value for item ptoperties, so let's call it median and add it.

webix.GroupMethods.median = function(prop, data){
                if (!data.length) return 0;
                var summ = 0;
                for (var i = data.length - 1; i >= 0; i--) {
                    summ += prop(data[i])*1;
                };
                return summ/data.length;
            };

And apply the newly created functor referring to it by its name:

$group:{
    by:"year",
    map:{
        votes:['votes', 'median']
    }
}

Related sample: Custom aggregation while grouping

The functor can be as well defined bypassing GroupMethods class by setting a custom fucntion.

function getAverage(prop, data){
               //..the same as for 'median' above
}

$$("mychart").group({
        by:"year",
        map:{
            sales:["sales", getAverage]
        }
});

Related sample: Grouping

By the way, you can omit the functor yet set the way grouping criterion will be presented:

webix.ui({
    view:"treetable",
    columns:[ //default template for ungrouped items
        { id:"title", template:"{common.icon()} #title#" },
    ],
    scheme:{
        $group:{
            by:function(obj){ return Math.floor(obj.year/10); },
            map:{
                title:[function(obj){
                    var min = obj.year - obj.year%10;
                    return min + " - "+ (min+10)
                }]
            }
        }
});

Related sample: Static grouping


Undo for Data Components

While working with Webix data components, you can enable the undo functionality that allows reverting changes in case server returns an error message.

The undo operation can be applied to any DataStore-based component.

To enable undo, you need to set the undo parameter to true in the configuration of the component:

webix.ui({
    view:"list",
    id:"mylist",
    template:"#title#",
    data:dataset
    undo:true
});

The undo API includes three methods:

  • undo - reverts the previously made change in the component.
$$("mylist").undo();

For example, if you add an item into the component, then change it and finally decide to delete it, a call of the undo() method will revert just the result of the delete operation.

If you want to delete all the changes made to an item and set it to the initial state, you should pass the id of this item to the undo() method.

  • removeUndo - removes history about all the operations made to an item.
$$("mylist").removeUndo(id);

As a parameter the method takes the id of an item.

  • ignoreUndo - calls a function that will be ignored in the undo history track. The method is useful if you want the applied changes not to be reverted by the undo() method in future.
$$("mylist").ignoreUndo(function(){
    $$("mylist").addItem({...});
});

The ignoreUndo() method takes as a parameter the function for which undo history track should be disabled.


Exporting Content and Data

  • Components Export to PNG
  • Data Components Export to Excel
  • Data Components Export to PDF


Components Export to PNG

You can export Webix components to the PNG format. The components don't require any special configuration to be exported.

The described functionality is available both in Standard and Pro versions, but pay attention that the IE browser is supported starting from version 10.

To export a component into a PNG file, you need to call the toPNG method. The method takes the next parameters:

  • id - (string, object) id or object of the exported view
  • name - (string) optional, name of an exported png file

For example, if you want to export a chart to a PNG file, you need to call the toPNG() method with the chart id as parameter:

webix.ui({
    view:"chart",
    id: "myChart",
    // chart configuration
    ...
});

webix.toPNG($$("myChart"));

Related sample: Export to PNG


Data Components Export to Excel

You can export Webix data components to the Excel format.

The components don't require any special configuration to be exported.

The described functionality is available both in Standard and Pro versions, but pay attention that the IE browser is supported starting from version 10.

To export data from a data component into an Excel document you need to call the toExcel method. The method takes 2 parameters:

  • id - (string, object) id or object of the exported view
  • options - (object) optional, a set of configuration options that define what data will be displayed in the Excel file

For example, to export a list to an Excel document, you need to call of the toExcel() method that takes the view object or its id as a parameter:

webix.ui({
    view:"list",
    id: "mylist",
    // list configuration
    ...
});

webix.toExcel($$("mylist"));

Related sample: Export to Excel

Customizing Export to Excel

The toExcel() method returns all data specified in the dataset of a component without any data formatting. However, you may need to get data from some particular fields.

Export API allows

  • setting columns you'd like to see in the export file.
webix.toExcel($$("mylist"), {
    columns:{
        "rank":true,
        "title":true
    }
});
  • defining custom parameters, such as header, width or template for data in the specified column:
webix.toExcel($$("mylist"), {
    columns:{
        "title":{header: "Title", width: 200, template: webix.template("#id#.#name#")},
        "year":{header: "Year", width: 100}
    }
});

The column will be rendered with the stated additional properties, which may differ from the component's parameters.

  • including extra fields into export by forming them right within the export function:
webix.toExcel(list, {
    columns:{
        Custom1:{
            template:function(obj){
                return "Year " + obj.year;
            },
            width:50,
            header:"Year"
        },
        //other columns
        title:true
    }
});

"Custom1" (any name can be used) receives data from the year field even if it is not seen in this component but is presented in its dataset. The field is rendered with width and template as well as header that will be the header of the corresponding column in the resulting table.

Related sample: Export to Excel


Data Components Export to PDF

You can export Webix data components to the PDF format. The components don't require any special configuration to be exported.

The described functionality is available both in Standard and Pro versions, but pay attention that the IE browser is supported starting from version 10.

To export a component into a PDF file, you need to call the toPDF method. The method takes the next parameters:

  • id - (string, object) id or object of the exported view
  • name - (string) optional, name of an exported png file

For example, if you want to export a list to a PDF file, you need to call the toPDF() method with the list id as a parameter:

webix.ui({
    view:"list",
    id: "mylist",
    // list configuration
    ...
});

webix.toPDF($$("mylist"));

Related sample: DataTable Export to PDF

Customizing Export to PDF

The toPDF() method returns all data specified in the dataset of a component without any data formatting. However, you may need to get data from some particular fields.

Export API allows

  • setting columns you'd like to see in the export file
webix.toPDF($$("mylist"), {
    columns:{
        "rank":true,
        "title":true
    }
});
  • defining custom parameters, such as header, width or template for data in the specified column:
webix.toPDF($$("mylist"), {
  columns:{
    title:{ header: "My title", width: 200, template: webix.template("#id#.#title#")},
    year:{ header:"Year", width:150}
  }
});

The column will be rendered with the stated additional properties, which may differ from the component's parameters.

  • including extra fields into export by forming them right within the export function:
webix.toPDF(list, {
    columns:{
        Custom1:{
            template:function(obj){
                return "Year " + obj.year;
            },
            width:50,
            header:"Year"
        },
        //other columns
        title:true
    }
});

"Custom1" (any name can be used) receives data from the year field even if it is not seen in this component but is presented in its dataset. The field is rendered with width and template as well as header that will be the header of the corresponding column in the resulting table.

  • specifying the autowidth parameter to define the columns' width automatically. By default, the paper size of a PDF document is A4. If you set the autowidth property to true, columns will be able to have any possible width that will define the width of a PDF page
webix.toPDF($$("mylist"), {
    autowidth:true
});
  • setting the orientation parameter which defines the PDF page orientation: portrait (default) or landscape
webix.toPDF($$("mylist"), {
    orientation:"landscape"
});
  • specifying the docHeader and docHeaderImage parameters to display some text or image in the header of the export file
// setting a custom text in the header of the PDF file
webix.toPDF($$("mylist"), {
    docHeader:"This document was made with Webix library. http://webix.com"
});

// setting a custom image in the header of the PDF file
webix.toPDF($$("mylist"), {
    docHeaderImage:"../common/logo.jpg",
});

Related sample: DataTable Export to PDF: Custom configuration

Styling the exported data

Since data export to PDF is implemented with the help of the third-party library, you can tune the appearance of elements in the exported PDF document using properties described in its documentation.

Configuring the document's header

To configure the header of the exported PDF document, you can set a configuration object as a value of the docHeader property. Inside this object besides the text string specify all the needed properties, e.g. define the text alignment and color.

An example config may look as:

webix.toPDF($$("mylist"), {
    docHeader:{
        text: "List with custom styling",
        textAlign:"center",
        color:0x663399
    }
});

Pay attention that the color should be set in hex format starting from the 0x prefix.

There are many other possible properties of the config object. You can look all them up in the corresponding documentation (follow the "document/headeropts" section).

Configuring the header image

The export API allows you not only to set the link to the image, but also to specify an object with the necessary configuration properties of the image:

webix.toPDF($$("mylist"), {
    docHeaderImage:{
        url:"link",
        align:"left", // "right"/"center"
        width:300,
        height:20
    }
});

Thus, you can configure the image's alignment, as well as its width and the height. More options are enumerated in the specific documentation (see the "document/imageimg-opts" section).

Related sample: DataTable Export to PDF: extended configuration

Configuring the document's table

It's also quite easy to configure the look of the resulting table with data. You can manage the table's elements to get the desired result:

  • the table's header, e.g. set text alignment, the font size, the background color and the color of the text:
webix.toPDF($$("mylist"), {
    header:{
        textAlign:"center",
        fontSize:13,
        backgroundColor:0x3498DB,
        color:0xFFFFFF
    }
});
  • the table itself, e.g. align the text in it:
webix.toPDF($$("mylist"), {
    table:{
        textAlign:"center"
    }
});
  • the table's footer, e.g. by specifying the font size, its height and text alignment:
webix.toPDF($$("mylist"), {
    footer:{
        fontSize:9,
        height:20,
        textAlign:"right"
    }
});

Related sample: DataTable Export to PDF: extended configuration

More possible configuration properties are described in the corresponding documentation (follow the "document/tableopts" section).


Styling and Animation

  • Skins
  • Component Styling
  • Animation
  • Icons with UI Components
  • Setting Borders to the Components


Skins

Webix provides 11 skins that you can use to change the overall look of your application:

  1. Flat (default skin)
  2. Compact
  3. Material Design
  4. Touch

  5. Air
  6. Air Compact
  7. Clouds
  8. Glamour
  9. Light
  10. Metro
  11. Terrace
  12. Web

Each skin requires including its specific CSS file.

All CSS files for skins reside in the codebase/skins folder of the package.

Flat

To apply the Flat skin, include the default CSS file:

Applying the 'Flat' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/webix.css" rel="stylesheet" type="text/css">

Compact

To apply the Compact skin, include the compact.css file:

Applying the 'Compact' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/compact.css" rel="stylesheet" type="text/css">

Material Design

To apply the Material Design skin:

  • download it from a separate repository at github.com
  • copy files into codebase folder of Webix UI package
  • include the material.css file:

Applying the 'Material Design' skin to the app

<script src="../codebase/webix.js"></script>
<link href=".../codebase/skins/material.css" rel="stylesheet" type="text/css">

You can read a more detailed article about the usage of Material Design skin.

Touch

To apply the Touch skin, include the touch.css file:

Applying the 'Touch' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/touch.css" rel="stylesheet" type="text/css">

Air

To apply the Air skin, include the air.css file:

Applying the 'Air' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/air.css" rel="stylesheet" type="text/css">

Air Compact

To apply the AirCompact skin, include the aircompact.css file:

Applying the 'AirCompact' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/aircompact.css" rel="stylesheet" type="text/css">

Clouds

To apply the Clouds skin, include the clouds.css file:

Applying the 'Clouds' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/clouds.css" rel="stylesheet" type="text/css">

Glamour

To apply the Glamour skin, include the glamour.css file:

Applying the 'Glamour' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/glamour.css" rel="stylesheet" type="text/css">

Light

To apply the Light skin, include the light.css file:

Applying the 'Light' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/light.css" rel="stylesheet" type="text/css">

Metro

To apply the Metro skin, include the metro.css file:

Applying the 'Metro' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/metro.css" rel="stylesheet" type="text/css">

Terrace

To apply the Terrace skin, include the terrace.css file:

Applying the 'Terrace' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/terrace.css" rel="stylesheet" type="text/css">

Web

To apply the Web skin, include the web.css file:

Applying the 'Web' skin to the app

<script src="../codebase/webix.js"></script>
<link href="../codebase/skins/web.css" rel="stylesheet" type="text/css">


Material Design Skin

Skin works with Webix 2.3+. It is not inluded in the package and should be downloaded from GitHub.

You can see live demo by this link.

How to use
  • copy files into the codebase folder of Webix UI package
  • use skin file on a page as any other skin
<html>
<head>
    <script type="codebase/webix.js"></script>
    <link rel="stylesheet" type="text/css" href="codebase/skins/material.css">
</head>
<body>
webix.ready(function(){
    //some webix related UI here
});
</body>
</html>

Shared CSS classes

An example of CSS classes usage is given by this link.

Text and Background

The following css classes are available for text:

  • text_primary
  • text_info
  • text_success
  • text_warning
  • text_danger
  • text_muted

The background css classes have similar names. Just replace text_ with bg_:

webix.ui({
    rows:[{
        template:"Some text",
        css:"text_info"
    },{
        template:"Some background",
        css:"bg_danger"
    }]
});

Buttons

You can apply several classes for a button:

  • button_primary
  • button_info
  • button_success
  • button_warning
  • button_danger
  • button_transparent
  • button_raised

The flat buttons look like this by default:

You can also combine flat and "raised" buttons by means of using several css rules:

webix.ui({
    view:"button",
    css:"button_success button_raised"
});

Icons

There are 3 css icon classes:

  • solid_icon
  • action_icon
  • danger_icon

webix.ui({
    view:"icon",
    icon:"users",
    css:"solid_icon"
});

Panels

The following types of panels can be used:

  • bg_clean
  • bg_panel
  • bg_panel_raised

webix.ui({
    rows:[
        { template:"A" },
        { template:"B", css:"bg_panel"},
        { template:"C" }
    ]
});

Material layout

The skin adds one more type of layout:

webix.ui({
    type:"material",
    rows:[
        { template:"A" },
        { template:"B" },
        { template:"C" }
    ]
});

This type of layout shows all content elements as material panels.

License

Code is released under the MIT License:

Copyright (c) 2015

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Intermediate

Component Styling

Basic Principles of Styling

All the library components are styled with the help of an external style sheet "webix.css" you specify in the document head area alongside with the "webix.js" lib file. It's a mandatory step.

After that, the styling can be customized in two modes:

1 . With embedded styles you define in the document head between < style > tags.

<style>
    .my_style  {
        font-style: italic;
    }
</style>
<script>
    webix.ui({
         view:"dataview",
         css:"my_style",
         template: "#title#<br/> Year: #year#, rank: #rank#",
    });
</script>

Related sample: Dataview Italic

2 . By means of inline styling where you insert CSS into HTML tags during defining an appropriate template for data rendering.

Setting CSS class:

webix.ui({
    view:"dataview",
    template:"<div class='my_style'>#title#<br/> Year: #year#, rank: #rank#</div>",
    data:"..."
});

The result will be the same as above.

Adding Style

view:"window",
body:{
    template:"<span style='font-size:14px;font-style:italic'>Styled Window</span>"
}

Related sample: Styled Window

Dynamic Styles

A CSS class can be added to the component on the go, by either using the standard pattern of property redefinition:

.mycss{
   color:red;
}
//"datatable" - component ID
$$("datatable").define("css", "mycss");

or by using webix.html helper:

//getNode() returns the component's topmost node
webix.html.addCss( $$("datatable").getNode(), "mycss");

The advantage of the addCss method is that it is supplied with the opposite one, the removeCss that can be used to undefine the CSS class from the component:

webix.html.removeCss( $$("datatable").getNode(), "mycss");

Styling inside Type Parameter

When you set dimensions of component items, you use the type property that contains an object with an item's width and height. There you can as well put other parameters including template and css.

webix.ui ({
    view:"dataview",
    type:{
        height: 45,
        width: 300,
        template:"<span style='color:#67B802; font-style:italic'>#name#</span>"
    }
    ...
})

Type can also be created separately through the webix.type class.

webix.type(webix.ui.dataview,{
    name:"custom",
    template:"<span style='color:#67B802; font-style:italic'>#name#</span>",
    height: 45,
    width: 300
});

webix.ui ({
    view:"dataview",
    type: "custom",
    ...
})

Related sample: Dataview Type Styling

Adding Predefined Webix CSS Classes

You can either apply predefined CSS as it is:

webix.ui({
    view:"dataview",
    template:"<div class='webix_strong'>#title#</div> Year: #year#, rank: #rank#",
    ...
});

Related sample: Controlling a Number of Displayed Items

Or redefine default CSS for this document:

.mywin .webix_win_head .webix_template{
    background: #444; color:#AFA;
}

Related sample: Styled Window

As far as you've noticed, Webix default CSS classes are marked by a "webix_" prefix. Moreover, each component part has its peculiar CSS class, you can redefine. Read below to learn more about it.

Styling separate items in the component

Instead of defining css class for the whole component you can define css class for single items. To do so you need to place $css property in the data object. This property can contain a name of css class or a hash of css rules.

Setting item's style directly in the dataset

<style>
    .my_style{
        background-color:#FFAAAA;
    }
</style>

<script>
webix.ui({
    view:"list",
    data:[
        { id:1,
          value:"The Shawshank Redemption",
          $css:"highlight"
        },
        { id:2,
          value:"The Godfather",
          $css:{ "text-align":"right" }
        }
    ]
})
</script>

If you want to change styles dynamically, after page loading you can use the addCss and removeCss api.

Styling of a Specific Part of a Component (CSS maps)

CSS maps help stylize a specific part of a component. You should refer to its CSS map, pick the css class to the needed part and define the style in the document head.

Style applies to the header of the unitlist:

<style>
.webix_unit_header{
    color:#cb4c26;
    font-style:italic;
}
</style>

CSS classes for each component are described in CSS Image Maps Section

Styling Instances of One and the Same Object

Controls are most frequently used components so one and the same control type, e.g. button, occurs more than once on the page, as a rule.

Take, for instance, buttons. If you want to style each button differently, you should define a separate CSS class for each button, like this:

.bt_1 input{
    border-radius:12px; -moz-border-radius:12px; -webkit-border-radius:12px;
    background: #396D9E;
    ...
}
.bt_2 input{
    border-radius: 4px; -webkit-border-radius: 4px;-moz-border-radius: 4px;
    border: 1px solid #3D7113;
    ...
}

Here .bt1 and bt2 are class names for two different buttons while input specifies that the button's input area should be styled as well.

Related sample: Buttons: Styling

Changing Default Icons

Default FontAwesome icons that are used for various controls can be changed to custom ones, which is described in detail in a separate documentation article.


CSS Image Maps

Components: Controls:
  • Accordion CSS
  • Calendar CSS
  • Carousel CSS
  • Chart CSS
  • Colorboard CSS
  • Datatable CSS
  • Dataview CSS
  • Grouplist CSS
  • Layout CSS
  • List CSS
  • Menu CSS
  • Message Box CSS
  • Popup CSS
  • Property Sheet CSS
  • Toolbar CSS
  • Tree CSS
  • TreeTable CSS
  • Unitlist CSS
  • Uploader CSS
  • Window CSS
  • XList CSS
  • Button CSS
  • Checkbox CSS
  • Colorpicker CSS
  • Combo CSS
  • Counter CSS
  • Datepicker CSS
  • Label CSS
  • Radio CSS
  • Richselect CSS
  • Segmented CSS
  • Select CSS
  • Tabbar CSS
  • Text CSS
  • Textarea CSS
  • Toggle CSS


Accordion CSS

css class | Element
.webix_accordionitem | a single pane of the accordion
.webix_accordionitem_body | the body of the pane
.webix_accordionitem_header | the expanded header
.webix_accordionitem_header.collapsed | the collapsed header
.webix_accordionitem_label | the label of the header
.webix_accordionitem_button | 'expanded' or 'collapsed' arrow depending on the pane type

Read more about Accordion


Calendar CSS

{ view:"calendar" }

{ view:"calendar", type:"time" }

Calendar CSS
css class | element
.webix_cal_month | the 'month' section of the calendar
.webix_cal_next_button | the 'next' button
.webix_cal_prev_button | the 'previous' button
.webix_cal_header | the header of the calendar
.webix_cal_week_header | the week header of the calendar
.webix_cal_body | the body of the calendar or time view
.webix_cal_row | the row of the calendar (week)
.webix_cal_week_num | the week number of the calendar
.webix_cal_day.webix_cal_outside.webix_cal_event | the day of the neighbouring month in the calendar (weekend)
.webix_cal_day.webix_cal_outside | the day of the neighbouring month in the calendar (weekday)
.webix_cal_day | any weekday of the month
.webix_cal_day.webix_cal_event | weekend on the calendar
.webix_cal_day.webix_cal_select.undefined | selected day
.webix_cal_day.webix_cal_day_disabled | disabled day
.webix_cal_footer | footer of the calendar (area below calendar body)
.webix_cal_time | timepicker area in the calendar footer
.webix_icon.fa-clock-o | "clock" icon in the timepicker
.webix_cal_done | "Done" button in month selection part or time view
Time view CSS
css class | element
.webix_time_header | header of the time view
.webix_cal_minutes | "minutes" part in the time view header
.webix_cal_hours | "hours" part in the time view header
.webix_hours | "hours" part in the time view body
.webix_minutes | "minutes" part in the time view body
.webix_cal_block | any hour slot
.webix_cal_block.webix_selected | selected hour slot
.webix_cal_block.webix_cal_day_disabled | disabled hour slot
.webix_cal_block_empty | "am/pm" identifier in the calendar body
.webix_cal_block.webix_cal_block_min | any minute slot
.webix_cal_block.webix_cal_block_min.webix_selected | selected minute slot
.webix_time_footer | footer of the time view
.webix_cal_block.webix_cal_block_min.webix_cal_day_disabled | disabled minute slot

Read more about Calendar


Carousel CSS

Carousel is a layout-building component that can house any of the data-presenting components while navigation between them is enabled with the help of standard controls. Check their CSS maps if you want to style carousel elements.

css class | Element
.webix_carousel | carousel object
.webix_item.webix_carousel_active | casousel item that is currently shown
.webix_item.webix_carousel_inactive | carousel item that is currently hidden

Read more about Carousel


Chart CSS

css class | Element
.webix_axis_item_y | the Y-axis item label
.webix_axis_title_y | the Y-axis title
.webix_axis_item_x | the X-axis item label
.webix_axis_title_x | the X-axis title
.webix_canvas_text | all text labels using in the chart (including Y-axis, X-axis items and title

Read more about Chart


Colorboard CSS

css class | Element
.webix_color_palette | the whole colorboard
.webix_color_row | a row in the colorboard


Colorpicker CSS

css class | Element
.webix_el_colorpciker | the whole 'colorpicker' control
.webix_inp_label | text label for the control
.webix_inp_static | input area of the control
.webix_point_top | a popup arrow that points to a control that initied its appearance

To study the CSS map of the popup colorboard, please, refer to its CSS Map.

Read more about Colorpicker


Datepicker CSS

css class | Element
.webix_el_datepicker | the whole 'colorpicker' control
.webix_inp_label | text label for the control
.webix_inp_static | input area of the control
.webix_point_top | a popup arrow that points to a control that initied its appearance

To study the CSS map of the popup calendar, please, refer to its CSS Map.

Read more about Datepicker


Datatable CSS

Table 1 CSS image maps
CSS class | Description
.webix_dtable | container with DataTable
.webix_ss_header | container with the header
.webix_ss_header .webix_hcell | a cell of the header
.webix_ss_header .webix_first | the first cell of the header
.webix_ss_header .webix_last | the last cell of the header
.webix_ss_footer | container with the footer
.webix_ss_footer .webix_hcell | a cell of the footer
.webix_ss_footer .webix_first | the first cell of the footer
.webix_ss_footer .webix_last | the last cell of the footer
.webix_ss_body | container with the table body
.webix_column | a column of the table
.webix_column .webix_last | the last column of the table
.webix_column .webix_first | the first column of the table
.webix_column .webix_cell | a cell of the column

Read more about Datatable component.


Tree CSS

css class | Element
.webix_tree | the whole tree
.webix_tree_branch_1 | the first-level items of the tree
.webix_tree_branch_2 | the second-level items of the tree
.webix_tree_branch_3 | the third-level branches of the tree
.webix_tree_item | an inline item within the tree
.webix_tree_folder | a 'closed' folder icon
.webix_tree_folder_open | an 'open' folder icon
.webix_tree_file | a file icon
.webix_tree_close | a 'closed branch' sign
.webix_tree_open | an 'open branch' sign
.webix_tree_checkbox | a checkbox (if any)

Read more about Tree.


Dataview CSS

css class | Element
.webix_dataview_item | an item of the dataview
.webix_dataview_item.webix.selected | the selected item of the dataview

Read more about Dataview


Grouplist CSS

css class | Element
.webix_grouplist | the whole grouplist
.webix_list_item | an item in the grouplist
.webix_list_group_back | the group header item in the selected state
.webix_list_group | the group header item in the unselected state
.webix_arrow_icon | the arrow on the group header item

Read more about Grouplist


Layout CSS

css class | Element
.webix_layout_space | the borders of the type 'space'
.webix_layout_head | the borders of the type 'head'
.webix_layout_wide | the borders of the type 'wide'
.webix_layout_line | the borders of the type 'line'
.webix_layout_clean | the borders of the type 'clean'

Read more about Layout


List CSS

css class | Element
.webix_list | list view
.webix_list_item | an item of the list
.webix_list_item.webix_selected | the selected item of the list

Read more about List


Menu CSS

css class | Element
.webix_menu | the whole menu
.webix_menu-x | the whole menu in case of horizontal arrangement
.webix_win_body | a drop-down list
.webix_list_item | an item of the drop-down list
.webix_context_sep | a line separator between menu groups
.webix_submenu_icon | a icon for an item with a submenu


Message Box CSS

css class | Element
.webix_model_box | the whole message box
.webix_popup_text | text in the box body
.webix_popup_title | the header the box
.webix_popup_button | a button in the control area of the box

Read more about Message Boxes


Popup CSS

css class | Element
.webix_window | the whole popup window
.webix_win_body | the body of the window

Read more about Popup windows


Property Sheet CSS

css class | Element
.webix_property | the whole xlist
.webix_property_line | an item of the list
.webix_property_label_line | an item of the list
.webix_property_label | an item of the list
.webix_property_value | an item of the list

Read more about Property Sheet


Toolbar CSS

css class | Element
.webix_toolbar | the whole toolbar

Toolbar is a container for multiple controls. See the corresponding image maps to learn about custom control styling.

Read more about Toolbar


TreeTable CSS

Treetable combines features of the Tree and Datatable. Hence, its CSS classes for it are inherited from both of the components.

css class | Element
.webix_dtable | the whole datatable
.webix_ss_header | the header of a datatable
.webix_column | a column of a datatable
.webix_cell | a cell of a datatable
.webix_first | the first column of a datatatble
.webix_last | the last column of a datatable
.webix_tree_folder_open | an 'open' folder icon
.webix_tree_folder | a 'close' folder open
.webix_tree_file | a file icon
.webix_tree_open | an 'opened branch' sign
.webix_tree_close | a 'closed branch' sign
.webix_tree_checkbox | a 'checkbox' sign (if any)

Read more about Treetable


Unitlist CSS

css class | Element
.webix_list_item | an item of the list
.webix_unit_header | the header of a unit

Read more about Unitlist


Window CSS

css class | Element
.webix_win_head | the head of the window
.webix_win_body | the body of the window
.webix_window | the whole window

Read more about Window


XList CSS

css class | Element
.webix_list-x | the whole xlist
.webix_list_item | an item of the list

Read more about XList


Uploader CSS

css class | Element
.webix_remove_upload | the "remove item" area
.cancel_icon | the "remove_item" icon
.webix_upload_server | the "upload_state" area
.icon-ok webix_icon | the "upload ready" icon

Basically, uploader is comprised of other Webix components such as button and list/template. See their CSS maps for details.

Read more about Uploader


Button CSS

css class | Element
.webix_el_button | any button
.webixtype_base | default button
.webixtype_danger | a button with the "danger" type
.webixtype_form | a button with the "form" type
.webixtype_prev | a button with the "prev" type
.webixtype_next | a button with the "next" type
.webix_img_btn | a button with the "image" and "icon" type
.webix_img_btn_abs | a picture of any button with an image
.webix_img_btn_top | a button with the "imageTop" and "iconTop" type
.webix_img_btn_text | text value of the a button with an image
.webix_icon [icon-mail] | an icon for the "iconButton", "iconTop" and "iconButtonTop" button
.webix_icon_btn [icon-mail] | an icon for the "icon" button [icon-name]
.webix_el_arrow | an arrow for the 'prev', 'next' buttons

You can find the name of any icon on the Font Awesome site since icons are taken from there. Iconization in the library is described separately.

Read more about Buttons.


Checkbox CSS

css class | Element
.webix_el_checkbox | the whole checkbox
.webix_inp_label | the label
.webix_inp_checkbox_border | the input area

Read more about Checkbox


Combo CSS

css class | Element
.webix_el_combo | the whole combo
.webix_inp_label | the label
.webix_inp_combo | the input area
.webix_list | the drop-down list
.webix_point_top | the top arrow of pull-down
.webix_list_item | an item of the list

Read more about Combo


Counter CSS

css class | Element
.webix_el_counter | the whole counter
.webix_inp_label | the label of the counter
.webix_inp_counter_prev | the left button of the input area
.webix_inp_counter_value | the input area displaying the chosen value
.webix_inp_counter_next | the right button of the input area

Read more about Counter


Label CSS

css class | Element
.webix_el_label | the whole label

Read more about Label


Radio CSS

css class | Element
.webix_el_radio | the whole 'radio' control
.webix_inp_label | the label for the whole control
.webix_inp_radio_label | the label for a single radio button
.webix_all_radio | all radio buttons together
.webix_inp_radio_border | an area for a single radio button
.webix_inp_radio_border input | the input area

Read more about Radio


Select CSS

css class | Element
.webix_el_select | the whole 'select' control
.webix_el_select select | the dropdown list of the control
.webix_el_inp_label | text label for the control

Read more about Select


Segmented CSS

css class | Element
.webix_el_segmented | the whole 'segmented' control
.webix_segment_0 | the first tab in the unselected state
.webix_segment_N | the last tab in the unselected state
.webix_segment_1 | the tabs from the second to the penultimate one in the unselected state
.webix_selected webix_segment_0 | the first tab in the selected state
.webix_all_segments | all segments of the control

Read more about Segmented


Tabbar CSS

css class | Element
.webix_el_tabbar | The whole tabbar. Since most of the time a number of ".webix_item_tabs" will be rendered on top of it, the most often visible part of ".webix_el_tabbar" is the ".webix_tab_more_icon" at the end of the tab strip.
.webix_tab_more_icon | Icon at the end of the tab strip when there are more tabs to display than fit horizontally.
.webix_item_tab | A tab in the tabbar.
.webix_item_tab.webix_selected | The selected tab.
.webix_all_tabs | All tabs in the tabbar. Displayed on top of the ".webix_el_tabbar" and under ".webix_item_tab" and ".webix_tab_filler".
.webix_all_tabs.webixtype_bottom | All tabs in the tabbar of the "bottom" type
.webix_tab_filler | Space between ".webix_item_tab"s and on the right and left ends of a top tabbar.
.webix_before_all_tabs | A div before ".webix_el_tabbar". By default 100% wide and 1px tall.
.webix_after_all_tabs | A div after ".webix_el_tabbar", separating it from the content below. By default 100% wide and 6px tall.

All the classes are applicable for both top and bottom tabbar except for:

  • .webix_all_tabs.webixtype_bottom - class specific to bottom tabbar only;
  • .webix_tab_filler - appears in the bottom tabbar only if total width of all tabs is less than available space.

Read more about Tabbar control.


Richselect CSS

css class | Element
.webix_el_richselect | the whole 'richselect' control
.webix_inp_list | the input for the 'richselect' control
.webix_inp_label | the label area
.webix_point_top | the top arrow of the drop-down list
.webix_list | a drop-down list
.webix_list_item | an item of the list

Read more about Richselect


Text CSS

css class | Element
.webix_el_text | the whole 'text' control
.webix_inp_text | the input area
.webix_inp_label | the label area
.webix_el_passwordtext | the whole control, type 'password'

Read more about Text


Textarea CSS

css class | Element
.webix_el_textarea | the whole textarea control
.webix_inp_label | text label for the control
.webix_inp_textarea | the input field of the textarea

Read more about Textarea


Toggle CSS

Toggle is a two-state button, that's why it shares its types and CSS classes with the button control. Refer to its Image Map to find details while here toggle's specific classes are listed:

css class | Element
.webix_el_toggle | the toggle control
.webix_el_box.webix_pressed | text label for the control

Read more about Toggle


Intermediate

Animation

Animation Config

Animation is implemented within multiview and pager components. It sets the way the views will be changed as you switch between views or page through the component.

There exist two animation types with their own subtypes. Or, instead, you can choose on of the four animation directions:

  • slide - in, out, together;
  • flip - horizontal, vertical;
  • direction - left, right, top, bottom.

Animation in Multiview and Pager

Multiview uses slide:"together" animation type by default.

Animation can be switched off:

{view:"multiview", animate:false }

Enabling Animation

1 . The simplest means is including animate property into the multiview or pager constructor and define the necessary type and subtype:

webix.ui({
   view:"multiview",
   animate:{
      type:"flip",
      subtype:"vertical"
   },
   cells:[]
});

2 . The values for animate property can be assigned directly out of the multiview constructor. If some values have already been defined with the help of the above-mentioned method, direct assignment will rewrite them:

$$("multi").config.animate.type = "flip";
$$("multi").config.animate.subtype = "vertical";

3 . By means of the show() method.The changes will be applied once while showing the stated view. Then, the default values (initial or 'rewritten') will be used.

 $$(id).show({type:"flip", subtype:"horizontal"})

Related sample: Animated Multiview

Related sample: Paging animation types

Animating View Initialization

The moment of webix View initilization can be animated as well. It works for views created dynamically in the existing Webix layout.

To instantiate the component with animation, you should call webix.ui.animate() method instead of standard webix.ui():

webix.ui.animate(obj, parent, config);

where:

  • obj (obj) - configuration of the new component;
  • replace (string, number) - ID of the component that will be replaced by the one stated in obj;
  • config (obj, optional) - animation configuration, described above. If not defined the { type:"slide", direction:"left" } animation will be used.
 webix.ui.animate({
    id:"aboutView", template:"About page...",
}, $$("listView"));

Related sample: Manual view recreating


Intermediate

Icons with UI Components

Icons can be nested into all components and their items. You can put icon on the toolbar in form of buttons, decorate tabbar tabs, accordion panes as well as list and dataview items with them, etc.

Icons can be initialized in three ways:

  • as separate views;
  • as button types;
  • as CSS classes.

Icons are taken from the Font Awesome collection. There you can find plenty of icons to your choice and pick their names to insert them in your apps.

Related sample: Icons

View Icon

UI-related icon looks like a button with a border. Text label for this icon type is not supposed.

{ view:"icon", icon:"mail"},
{ view:"icon", icon:"users"}

The value for an icon property is the name of the needed icon.

Button with an Icon
Table 1 Icon types
type:"icon"
type:"iconTop"
type:"iconButton"
type:"iconButtonTop"
{ view:"button", type:"icon", icon:"mail", label:"Mail", width:80 }
  • type - the property that turns a standard button into an icon button:
    • icon - an icon button without a distinct border;
    • iconTop - an big borderless icon button with a text label below an icon;
    • iconButton - a small icon button with a label right of the icon;
    • iconButtonTop - a big icon button with a label below the icon;
  • icon - name of an icon (looks for it on Font Awesome);
  • label - text label for an icon button;
  • width - width of a button with label and icon;
  • badge - an orange circle that notifies about new messages.

'webix-icon' CSS Class

This method of icon initialization fits the components and items that don't normally take buttons - tabs (they are buttons themselves), panes, list and dataview items, datatable cells. In this case, icons are not buttons and perform a decorative function.

Possible CSS classes are as follows:

  • 'webix_icon fa-envelope' - a standard icon (white or black depending on current skin);
  • 'webix_input_icon fa-envelope' - a light grey icon adjusted for use in input fields.

Both of them include an icon name that can be checked on Font Awesome site.

Through CSS property:

Multiview tabs

{ view:"tabbar", options:[
    { value:"mail",  label:"Mail", css:"webix_icon fa-envelope"},
    { value:"users", label:"Users", css:"webix_icon fa-users"},
    { value:"cog",   label:"cog" , css:"webix_icon fa-cog"}
]}

By adding extra HTML:

An additional HTML element with an 'icon' class can be added to the text value of any component item:

AccordionItem pane with an icon

{ header:"<span class='webix_icon fa-envelope'></span>Mail"}

List item with an icon

{ template:"<span class='webix_icon fa-#icon#'></span> #name#"}

Here the icon's name is in hash signs since it comes from the dataset, e.g. in JSON it looks like

var data=[
    {id:1, name:"item1", icon:"envelope"},
    {id:2, name:"item2", icon:"users"}
]

Changing Default Icons

Default FontAwesome icons that are used for various controls can be changed to custom ones in several ways.

Setting Other FontAwesome Icon

If you'd like to use another icon from FontAwesome collection instead of the default one, specify its name as value of icon property:

{view:"richselect", label: 'Other', options:options, icon:"caret-down"}

As a result, the default richselect) icon, "fa-angle-down", is replaced with the one you've set.

Setting a Custom Icon

To set a custom icon that you can provide as a background-image, write the new CSS rule that redefines the default one. Nothing is changed in the control configuration:

{view:"combo", label: 'Fruit', options:[...] }

As with richselect, combo control uses "fa-angle-down" icon which CSS should be modified:

.webix_input_icon.fa-angle-down:before{
    content:""; /*removes FontAwesome icon */
    background-image: url("search.png");
    width:20px;
    height:20px;
    display:block;
}

Related sample: Styling Combo Icons

If you want to style one combo on the page while leaving another one unchanged, define a separate css class for the one in question:

{view:"combo", label: 'Fruit', options:[...], css:"custom" }

Then the necessary CSS will look like this:

.custom .webix_input_icon.fa-angle-down:before{
...
}

Component styling is described in detail in the corresponding article of the documentation.


Beginner

Setting Borders to the Components

Webix allows setting borders, margin and padding to the components and layout blocks. They should be specified within layout blocks and components to which you wish to apply the settings.

Within the form component borders are set in the same way.

Border Types

Borders can be applied to:

  • layout blocks (rows, cols, cells);
  • the whole layout and its variations (multiview, tabview);
  • any UI component;
  • part of UI component (window or accordion body, head).

Border type is set by the type parameter.

webix.ui({
    type:"space",
    rows:[
        { ... },
        { ... }
        ]
});

By default rows and columns feature thin borders, which can as well be set manually as type: 'line'. To completely rid of borders you should either set a 'clean' type or add borderless:true parameter.

Note that the chosen border, or borderless state is applied only the the layout block it's defined for it's children still feature the default border. You should set a border for them manually:

webix.ui({
    container:"divD",
    type:"space",
    rows:[
        { template:"text", borderless:true },
        { ... }
    ]
});

Here layout rows feature space border while a template that lies in one of these rows is borderless.

Margin and Padding

Margin specifies space from the view to the left inner border of its parent container (set "margin-left" property) while padding sets the offset from the component contents to its borders.

webix.ui({
    type:"space",
    margin:30,
    padding:20,
    cols:[{ }]
});

Padding can be set separately in horizontal and vertical modes:

  • padding - offset for all the borders;
  • paddingX - offset for left and right borders;
  • paddingY - offset for upper and bottom borders.


Interacting with Users

  • Creating Message Boxes
  • Setting Progress Bar and Overlay Messages
  • HTMLForm and Form Treatment
  • Uploading Files
  • Uploader and Form Integration
  • Controls Guide
  • Event Handling
  • Keyboard Events. Focusing. Navigation
  • Adding Active Elements to Components


Intermediate

Creating Message Boxes

Webix UI library helps the app communicate with users with the help of messages that can warn about error, log events, display variable values, etc.

Info Message Box

Basic message is created with the help of webix.message() function that has message text as parameter (short form).

webix.message("All is correct");

Such message is displayed in the top right corner of the window and doesn't prevent the work of the parent app while modal message boxes (described later) do.

Table 1 Message boxes
Message | Image
Default |
Error (type:'error') |

Related sample: Validation with a Complex Rule

Message Types

As seen above, message boxes can be of two types:

  • default (white background);
  • error (red background).

The latter has type argument in addition to message text and features an extended form of initialization:

webix.message({type:"error", text:"Form Data is Invalid"});

Expire Interval

By default webix message disappears either on mouse clicking somewhere outside it, or in 4000 milliseconds after appearing.

To change the expire interval or cancel it - use the expire parameter:

webix.message({
    type:"error",
    text:"Form Data is Invalid",
    expire:10000
    //expire:-1   for cancelling expire period
})

If you cancel expire period, such message will disappear only on mouse click.

Message boxes can as well be hidden programmatically:

var message = webix.message("Hi!");
webix.message.hide(message);

Modal Message Boxes

Message boxes resemble ui-related modal Window yet they are initialized in a completely another way. They prevent the workflow on the parent app until you perform actions required by them ( button clicking, as a rule). Message boxes close on a button click and callback function, if any is executed.

Message boxes contain some text and an "OK" button. There exist three types of modal message boxes:

  • webix.alert() - alert box with a button;
  • webix.confirm() - confirmation box with two button to agree or cancel;
  • webix.modalbox() - a modal message box with as many buttons as you like.

The boxes share some common properties, namely:

  • title - text of the header;
  • ok - text of the "ok" button;
  • cancel - text of the "cancel" button (only for a confirmation box);
  • text - text of the window body;
  • callback - function that is executed on button click. Callback function may include another message box the contents of which depend on your choice in the previous step;
  • type - type of the message box (warning or error);
  • width - the width of the message box;
  • height - the height of the message box.

The callback function takes result of user communication with a message box as parameter. It can be:

  • boolean true - each time you press its "OK", true is passed to the box callback. It's the only possible value for the alert box as it features the "OK" button only;
  • boolean false - each time you press "Cancel", false is passed to the callback. Works for the confirm box;
  • Button index - true for the modal box. Stores the index of the clicked button (zero-based numbering).

The result is used in the callback function that defines further actions according to its value (true or false).

At the same time, callback can be set independent of the result, as a function will be executed on button click.

Initialization

webix.alert

The text of its only button is defined as value of ok parameter. Passing result into callback is optional.

Short form

//the shortest form
webix.alert("Text");

//short form with callback
webix.alert("Test alert", function(result){....});

Long Form

webix.alert({
    title:"Custom title",
    ok:"Custom text",
    type:"alert-warning",
    text:"Warning",
    callback:function(){...}
});

Related sample: Alert message

webix.confirm

Confirm message boxes contain two buttons - "ok" and "cancel", which text is defined in the same-name properties.

webix.confirm({
    title:"Custom title",
    ok:"Yes",
    cancel:"No",
    type:"confirm-error",
    text:"Test confirm",
    callback:function(result){ //setting callback
        webix.alert({
            title:"Your Choice",
            text:"Result" +result //using callback
        });
   }
});

Related sample: Confirm message

Modal Box

Webix modalbox resembles alert and confirm in its modality, yet features several peculiarities:

  • its text can include any HTML content;
  • it may contain as many buttons as you wish defined in the buttons array that contains text values for each one;
  • the callback takes the index of the chosen button as a parameter.
webix.modalbox({
    title:"Custom title",
    buttons:["Yes", "No", "Maybe"],
    text:"Any html content here",
    width:500,
    callback: function(result){
        switch(result){
        case 0:
            //statement
            break;
        case 1:
            //statement
            break;
        ...
        }
    }
});

Related sample: Modal box

Modal Windows and Keyboard Interaction

Keyboard functionality for modal boxes is controlled by webix.message.keyboard property that is initially true.

By default modal boxes block keyboard events of the page. Users can use only the following keys that set modal box value and close it:

  • "space" and "enter" for setting true value as modal box result;
  • "escape" for setting false value as modal box result.

To disable above mentioned keys and enable standard keyboard events you should set keyboard property to false:

webix.message.keyboard = false;
webix.modalbox({...})

From now on, user gets a possibility to use full keyboard, for instance, for typing values into inputs inside modal boxes.


Setting Progress Bar and Overlay Messages

Webix allows visualizing the application workflow by adding the following elements to its components:

  • progress bar;
  • progress icon;
  • overlay box with or without message;

Setting Progress Bar/Icon

Progress bar and icon are provided by Webix Progress Bar module that can be easily mixed into any componenet including layouts.

webix.extend($$("view_id"), webix.ProgressBar);

Since now, the component with "vew_id" ID features two methods:

  • showProgress(config) - shows the progress bar/icon according to the passed configuration, or default one if the configuration is not provided;
  • hideProgress - hides progress bar/icon that was shown by the above mentioned method.

Configuration (progress_config) for a progress bar/icon includes:

  • type (string) - type of a progress element:
    • "top" - progress bar at the top of the view;
    • "bottom" - progress bar at the bottom of the view;
    • "icon" - progress icon at the center of the view;
  • icon (string) - icon name (only if type:"icon" is set). Icon names can be checked at FontAwesome);
  • delay (number) - life time in miliseconds of the progress bar, after which it is hidden (if hide parameter is enabled);
  • hide (boolean) - specifies whether a progress bar/icon shold be hidden after its life time.
  • position (number) - an optional parameter, true only for the progress bar. Specifies the position of a progress mark on a bar. Varies from 0 to 1.

Progress Bar for the Data Component

Progress Bar

//initializing the component
webix.ui({
    view:"datatable", id:"data", ..
});

//adding progress bar functionality to it
webix.extend($$("data"), webix.ProgressBar);

...
//using the functionality
$$("data").showProgress({
    type:"bottom",
    delay:3000,
    hide:true
});

Related sample: Progress Bar::Data

Progress Icon for Layout

Progress Icon

//initializing the layout
webix.ui({
    id:"app", rows:[
        ..app config..
    ]
});

//adding progress bar functionality to it
webix.extend($$("app"), webix.ProgressBar);

...
//using the functionality
$$("app").showProgress({
   type:"icon",
   delay:3000
});

Additionally, an app can be disabled for the time being.

Related sample: Progress Bars::Layout

Setting Overlay Boxes to Components

Related sample: Empty list

Overlay box is provided by Webix OverlayBox module and allows creating placeholders for data components.

The module needs to be inluded into the component:

webix.extend($$("list1"), webix.OverlayBox);

After that the following methods become accessible from the component:

  • showOverlay(text) - shows overlay box with the defined text or html;
  • hideOverlay() - hides the overlay box;

A blue bar with webix_loading_overlay CSS class will be shown. To get rid of it, or set another loading image, redefine this class.

List with 'no data' message

webix.ui({
    view:"list",
    url:"...",
    ready:function(){
        if (!this.count()){ //if no data is available
            webix.extend(this, webix.OverlayBox);
            this.showOverlay("<div style='...'>There is no data</div>");
        }
    }
});

Related sample: Empty list

Component-specific support of overlay boxes

Webix datatable features prebuilt overlay support.

Related Articles
  • Component Copying and Extending.


Intermediate

HTMLForm and Form Treatment

The most commonly used methods here include:

setValues()

Sets all the form values in one scope. Its argument is an object than contains 'property-value' pairs where new values are assigned to form elements.

Form elements (text fields, radios and checkboxes) are referred by either their names.

webix.ui({
    rows:[
        { view:"form", id:"myform", elements:[
            { view:"text", name:'field_a', label: 'from', value: "Madrid"},
            { view:"text", name:'field_b', label: 'to', value: "Milan"}
        ]},
        { view:"button", label: 'Fill form', click:"set_form" }]
});

function set_form(){
    $$('myform').setValues({
        field_a: "London",
        field_b: "New York"
    });
};

There's a second parameter for the function that is responsible for further form updates.

By defaul, it is false, which means that if you apply this function with a value just for one field, it will override the previously set values and they will be lost in nowhere. set to true, it allows for updating exisiting values with new ones.

$$('my_form').setValues({ field_b:"Paris" }); //the value for filed_a is lost!

$$('my_form').setValues({ field_b:"Paris" }, true);
// the form is updated with the specified value

Check also the API reference for this method.

load()

Loads values from a data file. Here you should pass the path to a data file as well as data format into the function.

function load_form() {
    $$('myform').load("./data/book.xml", "xml");
}

getValues()

Gets all the form values including those of hidden and disabled fields. In the snippet below form values are pasted into the console log.

webix.ui({
    view:"form",
    elements:[
        //form fields should have names for getting their values
        {view:"text", name:"login"},
        {view:"text", name:"email"},
    ]
})

function get_form() {
    var values = $$('myform').getValues();
    console.log(values);
}

You can also specify whether to include values of disabled and hidden fields into the result:

$$('myform').getValues({hidden:false, disabled:false});

Check also the API reference for this method.

clear()

Clears all the form fields.

function clear_form() {
    $$('myform').clear();
}

focus()

Sets the focus into the desired field. If used without arguments sets focus into the component it's called from. In case the item's ID is passed into the function, the corresponding item gets focus.

<input type="button" value="Focus author" onclick="focus_form('author');" /> //htmlform
<input type="button" value="Focus genre" onclick="focus_form('genre');" />

...
function focus_form(item) {
    if (!item)
        $$('htmlform1').focus();
    else
        $$('htmlform1').focus(item);
}

Related sample: Initialization in Document Body

isDirty()

Checks whether changes within form were made. The method is called before validation the form and saving form values and/or sending them to server.

function save_form(){
    var form = $$('form1');
    if(form.isDirty()){
        if(!form.validate())
            return false;
        form.save();
    }
 };

Related sample: Binding to List

Check the API reference for this method.

setDirty()

Marks the form as 'edited'.

$$('form1').setDirty();

Check the API reference for this method;

bind()

Binds the form to other component. In the snippet below list becomes a datasource for the form as well as helps save data from the form into the component.

More info on Data Binding

<div>
    <input type="number" name="rank" />
    <input type="text" name="title" />
    <input type="date" name="year" />
</div>
<script type="text/javascript">
webix.ui({
    view:"list",
    template:"#rank#. #title# Year:#year#"})

$$('htmlform1').bind($$('list1'));
//on clicking any list item the form is filled with the same values
</script>

Related sample: Binding to a native HTML form

validate()

Checks where the input data complies with the defined rules for the form.

More info on data validation.

Don't forget to specify the ID of a form / htmlform to enable this functionality since the ID is used to call these functions.


Uploading Files

Files are uploaded with the help of dedicated UI component called uploader.

Related sample: Basic List Uploader

Webix uploader inherits from view and looks like a standard Webix button you need to click to start uploading.

The button can as well be made invisible and file uploading dialog can be started on any page event (except for IE8).

Uploader Initialization

Uploader is a control that looks like a standard button yet triggers an upload window on its clicking.

Uploader is normally initialized together with the UI component to display values of pre-uploaded and uploaded files. Such component (it may be list or template, etc.) is called uploader body and is initialized separately. To link it to the uploader, specify its ID as value of uploader link property.

webix.ui({
    view:"form",
    rows:[
        {
            view:"uploader",
            id: "uploader_1",
            value:"Upload file",
            link:"mylist",
            upload:"php/upload.php",
            datatype:"json"
        },
        {
            view:"list",  id:"mylist", type:"uploader",
            autoheight:true, borderless:true
        }
    ]
});

Uploader Properties:

  • uploader ID should be specified in case you are going to work with it later;
  • value (string) - text value of the uploader button;
  • link (string) - the ID of a component to display values of chosen files;
  • upload (path) - path to a script file that will handle uploading;
  • multiple (boolean) - true by default. Set to false, it enables removing the previously added file and replacing it with a new one so that you can upload only one file at a time;
  • autosend (boolean) - true by default. Set to false, it cancels on-the-go file processing. The files are added to the uploader body only. They can be sent to server by calling the send() method later on;
  • datatype (string) - type of serverside response. Optional, json by default.

Read more about uploader configuration and server script.

Uploader Display Modes

The library offers Webix list as default component to show properties of uploaded files. You can as well init any Webix component for these needs provided that you specify an appropriate template for it.

List Uploader

Set to type:"uploader", list shows the following file info:

  • file name;
  • its extension;
  • file size;
  • Cancel icon;
  • "Upload Ready" icon (isn't shown initially for autosend:false mode. )

You can as well create a custom type for list items. It's described in an Uploader Progress Bar article.

Template Uploader

To make template displays file properties, you should define a function template to form a display string.

In the snippet below, template shows file properties in a string comprised of file names joined together with a comma.

view:"template",
template:function(data){
    var names = [];
    if (data.each)
        data.each(function(obj){  names.push(obj.name);  });
        return names.join(", ");
}

Related sample: Template Uploader

Template uploader is really good for attaching files to some message.

Manipulations with Files

The properties of the uploaded files are stored in the uploader files Data Collection that features an array of file objects.

To get to all files currently added to the uploader body, apply the following code:

//"upl1" - uploader ID
$$("upl1").files.data.pull;

The line returns an array of data items (files). Each file item contains information about its size, type, status, etc.

Each file object includes:

  • id - file ID generated automatically with the webix.uid() method per each uploading session;
  • name - file title and extension;
  • type - file extension only;
  • sizetext - size of the file (as string like 522Kb);
  • size - size of the file in bytes (as number);
  • status - upload status that changes during uploading:
    • "client" - file is added to the uploader body on client-side, the uploading hasn't been started yet or was aborted by user;
    • "transfer" - file uploading is in progress;
    • "server" - file has benn successfully uploaded;
    • "error" - an error occured during uploading.
  • item(id).context - the object uploader is connected with.

Item ID's are random numbers. They can be retrieved with getFirstId(), getLastId() and getNextId() methods.

Getting to Each File Object

File object can be retrieved by the getItem method with an ID of the necessary item as parameter:

var file_id = $$("upl1").files.getFirstId(); //getting the ID
var fileobj = $$("upl1").files.getItem(file_id).file; //getting file object
filename = $$("upl1").files.getItem(file_id).name; //getting properties
//or
filename = fileobj.name;

Webix offers rich API to manipulate with files collection and each file object. For instane, you can:

$$("upl1").files.parse(); //parse json data into files collection

$$("upl1").files.getFirstId(); //get ID of the first and last elements from the collection
$$("upl1").files.getLastId();

$$("upl1").files.getNextId(id);//get ID of the next file according to the specified one

$$(this.config.uploader).files.remove(id); //remove the specified file

Note that when you parse JSON string to the files object, no files are actually added to the uploader!

$$("uploader_1").files.parse([
    { name:"cover.jpg", sizetext:"54kb", status:"server" },
    { name:"page01.jpg", sizetext:"122kb", status:"server" },
    { name:"page02.jpg", sizetext:"142kb", status:"server" }
]);

Related sample: Adding files by API

You can get to file names simpler, with the dedicated getValues() method applied to the form that contains this uploader. The method returns name properties of each file joined into a comma-separated string.

webix.ui({
    view:"form", rows: [
        { view: "uploader", name:"records", ...},
        { view:"button", click: function() {
            var text = this.getParentView().getValues();
            text = JSON.stringify(text, "\n");
            webix.message("<pre>"+text+"</pre>");
            }
        }
});

Related sample: Template Uploader

Treating File Items in a Cycle

Cancelling uploading of several files at once:

function cancel(){
    var id= $$("upl1").files.getFirstId();
    while(id){
        $$("upl1").stopUpload(id);
        id = $$("upl1").files.getNextId(id);
    }

Defining function to execute on file uploading:

$$("uploader").files.data.each(function(obj){
    if (obj.status == "server")
         //statement
});

Array of files can be treated by file order as well:

var order = $$("uploader").files.data.order;
for (var i=0; i<order.length; i++){
    if ($$("uploader").files.getItem(order[i]).status = "server")
        //statement
}

Uploader Events

Here are main events that allow for customized uploader behavior. Full event system is to be found in the API reference.

  • onBeforeFileAdd - triggers on adding a file to uploader menu;
  • onFileUpload - trigers when upload process is started;
  • onUploadComplete - triggers when file upload is successfully completed;
  • onFileRemove - triggers when you try to remove a file from a pre-upload list (there appears a dedicated "remove" button as soon as you add a file to the uploader field);

Confirming Uploading

$$("upl1").attachEvent("onUploadComplete", function(){
    webix.message("done");
});

Related Articles

  • Configuring Uploader
  • Managing Server Part of Uploading
  • Creating a Progress Bar for Uploaded Files
  • Uploader and Form Integration
  • Binding Uploader to Any Page Element
  • Api Reference - Uploader Methods, Properties and Events
  • Uploader CSS Image Map


Configuring Uploader

Single upload

The uploader button initiates a window for browsing files on your machine and choosing the necessary one. By default, uploader supports uploading of multiple file at once and you can push this button and add as many file as you like to the uploader.

If multiple property is set to false, it enables replacing of the previously added files with new ones.

webix.ui({
    view:"uploader",
    multiple:false,
    ...
});

Related sample: Single Upload

Manual send

By default, files are added to the uploader and get processed with the dedicated script at once. To prevent this, cancel the autosend:

webix.ui({
    rows: [
        { view:"uploader",
          autosend:false,
          ...
        },
        { view:"button",
          click: "$$('uploader_1').send()";
        }
    ]
});

Related sample: Sending on custom action

Files are send later when send() function is called for this uploader. It triggers upload script execution.

The benefit of manual sending are as follows:

  • you can vizualize the response of uploading script on client side;
  • you can enable consecutive saving of uploader and form data if a form contains extra field exept for uploader.

Defining additional data to send

Uploader control allows defining extra data to send to server together with the file data.

In the autosend mode

webix.ui({
    view:"uploader",
    formData:{
        param1:value1,
        param2:value2
    },
    ...
});

During manual sending

The above metioned code can be used for manual sending as well, but alternativaly you can provide extra as the second parameter of the send method:

//either when a single file is sent to server
$$("uploader").send(id, { param1:"value1", param2:"value2"});

The id parameter is file ID in the uploader files array.

//or with callback function as first parameter
$$("uploader").send(function(res){
        /*callback function*/
    },
    { param1:"value1",
      param2:"value2"
    }
);

Uploading particular file types

Uploader can be customized to accept only particular file types during the uploading. Types of files allowed for uploading are specified in the accept property:

webix.ui({
    maxWidth:800,
    cols:[{
        view:"form", rows: [
            {
                view: "uploader", value: 'Upload Images',
                name:"files", accept:"image/png, image/gif, image/jpg",
                link:"mylist",  upload:"php/upload.php"
            }
            ...
        ]
    }]
});

In the above example Uploader accepts only files of image type (.png, .gif and .jpg formats). The full list of common media types is given here.

Related sample: Uploader - configure to accept the filetype

Related Articles
  • Managing Server Part of Uploading
  • Uploader and Form Integration


Managing Server Part of Uploading

Server Script

In eccense file uploading is done via Ajax. Each time send() function is executed, Ajax POST request is sent behind the scene. Its url is a script you specify as value of upload property.

{view:"uploader", name:"uploader", upload:"upload.php", ...}

The custom script you write yourself on your favourite language, not just PHP. Regardless of the language, the script must contain:

  • the desired destination for file uploading;
  • script response in form of a JS string - {"status":"server"} for success, {"status":"error"} for failure.

Below PHP solution is explained:

Uploader is based on an HTML input, type "file", so files passed to the script will be stored in $_FILES array under the uploader "name" The properties of an uploaded file can be gotten right here:

$file = $_FILES['uploader']; //getting a file object

$file['name']; //name of the uploaded file
$file['tmp_name']; //name of the file in the temporary storage

The simplest way to set destination and move the files there is:

$destination = realpath('./files'); //define folder
$filename = $destination."/".preg_replace("|[\\\/]|", "", $file["name"]); //set destination
move_uploaded_file($file["tmp_name"], $filename); //move files

Tuning Serverside Response

You must also tune the script response to notify you about the result of file uploading, otherwise you won't be able to get notification about upload success or failure.

The script ought to return JSON string that is later processed by Uploader to change the properties of the corresponding file object.

if ( /* conditions */ ){
    echo '{ "status": "server" }';
} else {
    echo '{ "status": "error" }';
}

Why it's done so? Each file object features status that changes during uploading:

  • client - when the file was just added to uploader and uploading hasn't started yet. Or when uploading was aborted by user;
  • transfer - during uploading until script response;
  • server - uploading finished, set when script response is "{status:'server'}";
  • error - an error has occurred during uploading, set when script response is {'status':'error'}.

The response is available directly in the send() callback that takes it as parameter:

$$("upl1").send(function(response){
    if(response)
        webix.message(response.status);
        webix.message(response.sname);
});

In addition, script may return any additional information, e.g. file storage name encoded with MD5.

$sname = md5($file["name"]);
if ( /*...*/ ){
    echo '{ "status": "server", "sname":"$sname"}';
}
...

Related sample: Sending on custom action

This additional info is added to the file object and can be later on derived just like other properties.

$$("upl1").send(function(){
    var f = $$("upl1").files;
    var file_id = f.getFirstId();
    var status = f.getItem(file_id).status; //upload status
    var status = f.getItem(file_id).name; //file name
    var sname = f.getItem(file_id).sname; //storage name
    webix.message("Upload: "+status+" for "+name+" stored as "+sname );
});

Multiple Files

In case of multiple files uploaded at a time, direct response won't suit as it contains info about one file.

Instead, start a cycle that will get to each file's value:

$$("upl1").send(function(){
    $$('upl1').files.data.each(function(obj){
        var status = obj.status;
        var name = obj.name;
        if(status=='server'){
            var sname = obj.sname; //came from upload script
            webix.message("Upload: "+status+" for "+ name+" stored as "+sname );
        }
        else{
            webix.message("Upload: "+status+" for "+ name);
        }
});

Related sample: Uploader and Form Integration

Files Data Array

The same can be done applying directly to the uploader datastore, through data array:

$$("upl1").send(function(){
    var text = f.data.pull[file_id].sname;
    webix.message("Test sname: "+ text);
});

Or, in a cycle in case of multiple files uploaded at a time:

for(var i in f.data.pull){
    var text = f.data.pull[i].sname;
    webix.message("Test sname: "+ text);
}


Progress Bar for Uploader

Progress bar is set with CSS means for each file separately and is displayed in the dedicated component(e.g. list) set to a custom type.

Related sample: Progress bar

Webix.type defines the way component items look. Here you specify the component you make the type for, name of this type and item property(ies) you set.

webix.type(webix.ui.list, {
                    name:"myUploader",
                    template: function(f, type){},
                    status:function(f){},
                    on_click:{},
                    height: 35
                    })

Template:

As a rule, displayed info contains the following data wrapped in the chosen CSS class (defined in the document head section).

  • f.name - name and extension of the file;
  • cancel icon (built-in icon set via CSS class webix_remove_upload icon-cancel-circle webix_icon). More About Iconization here;
  • f.status - "transfer" or "server" with f.percent value for the latter;
  • f.sizetext - size of the file.
template:function(f,type){
            var html = "<div class='overall'><div class='name'>"+f.name+"</div>";
            html += "<div class='remove_file'><span style='color:#AAA' class='webix_remove_upload icon-cancel-circle webix_icon'></span></div>";
            html += "<div class='status'>";
            html += "<div class='progress "+f.status+"' style='width:"+(f.status == 'transfer'||f.status=="server"?f.percent+"%": "0px")+"'></div>";
            html += "<div class='message "+ f.status+"'>"+type.status(f)+"</div>";
            html +=  "</div>";
            html += "<div class='size'>"+ f.sizetext+"</div></div>";
            return html;
}

Status:

Here you put a function that defines status message displayed in the progress bar.

status:function(f){
        var messages = {
            server: "Done",
            error: "Error",
            client: "Ready",
            transfer:  f.percent+"%"
            };
        return messages[f.status]
}

Functionality for the "cancel" icon.

on_click:{ "remove_file":function(ev, id){
                $$(this.config.uploader).files.remove(id);}
}

Minor parameters

The ones like width and height of each list item.

Beware to set the created type for the list!

{view:"list",  id:"mylist", type:"myUploader", ...}


Binding Uploader to Any Page Element

Webix uploader can exist not only in the form of a button that you press to start the upload process. It can be bound to any page element and any page event can be used to call the uploader.

All you need is to follow the following steps:

  • set an uploader invisible, or apiOnly;
  • use uploader API to handle the uploading process.

Note that you cannot use this functionality in IE8.

Initializing

Related sample: Invisible Uploader for Datatable

Such uploader can be used with data management components (datatable in particular) and allows uploading pictures on the fly.

Initialization

//app init
webix.ui({
    view:"datatable", ..
});

//uploader init
webix.ui({
    view:"uploader",
    id:"uploadAPI",
    apiOnly: true,
    upload:"php/photo.php",
    ...
});

Uploader is initialized with the separate webix.ui() call.

Tuning Upload Process

Uploading is controlled through the view and uploader events. (Event Handling is described separately):

View Events

For the 'visible part' you should define the event that starts the uploading. In the above-mentioned datatable, clicking any photo should enable file browsing dialog on your machine.

The file dialog is triggered by the same-name method that is applied to the uploader object and takes upload context hash as parameter. You will be able to use the context object later to reflect upload result on client.

webix.ui({
    view:"datatable",
    ...,
    on:{
        onItemClick:function(id){
            if (id.column == "photo")
                $$("uploadAPI").fileDialog({ rowid : id.row });
        }
    }
});

Uploader Events

  • onBeforeFileAdd - fires before file is added to the uploader and uploaded (if autosend is enabled). On this event file filtering should be done to prevent from uploading of files with undesired formats and sizes.
  • onFileUpload - fires after the file has been fully uploaded. On this event the component should be refreshed with a newly uploaded image;
  • onFileUploadError - fires in case an error happens during uploading (status error comes with the server response);
  • etc.. .
webix.ui({
    view:"uploader",
    //configuration
    on:{
        onBeforeFileAdd:function(item){
            var type = item.type.toLowerCase(); //deriving file extension
            if (type != "jpg" && type != "png"){ //checking the format
                webix.message("Only PNG or JPG images!");
                return false;
            }
        },
        onFileUpload:function(item){
            var id = item.context.rowid;
            var row = $$("people").getItem(id);

            row.photo = item.sname;
            $$("people").updateItem(id, row);
        }
    }
});

Comments:

  • item.type returns file extension;
  • item.sname returns file name under which it was saved on server;
  • item.context is uploader context previously set by fileDialog() method. item.context.rowid returns the ID of the dedicated row in datatable.

Look for more item properties in the main Uploader article.

Using ApiOly uploader for Drag-n-Drop

Uploader initialization:

webix.ui({
    view:"uploader",
    id:"uploadAPI",
    apiOnly: true,
    upload:"php/photo.php"
 });

Defining drop area

If you want to drag-and-drop files with the apiOnly uploader, you should define the desired drop area by the addDropZone method, e.g.:

  • drop to any HTML element of the page:
 $$("uploadAPI").addDropZone(document.getElementById("uploader_container"));
  • drop to HTML element of any Webix Component:
//$view contains the object of the topmost element of the component
 $$("uploadAPI").addDropZone($$("mylist").$view);

Then, all the files dropped to the area will be added to uploader files and, if autosend is not cancelled, will be sent to the server script.

Displaying the files

Additionally, you need to take care of how the files should be displayed. For Webix list there's a ready-made solution:

First, you define type uploader type for the list:

{ view:"list", id:"mylist", type:"uploader" }

Then, link to it in the uploader configuration. You should mention list ID:

{ view:"uploader", id:"uploadAPI", link:"mylist" }

Related sample: Dnd with Invisible Uploader

Check uploader display modes for details.

For other Webix components as well as for on-page HTML elements you should provide custom logic.


Uploader and Form Integration

The purpose of any form is to collect data from users. This library provides UI Form and Htmlform components with lots of controls while the uploader component helps get user files (text documents, pictures, etc.)

Related sample: Uploader and Form Integration

Uploader controls as well as the component to display pre-uploaded files is included into the form like any of its other controls:

{view:"form", elements:[
    { view:"text", label:"Title", labelPosition:"top", name:"title" },
    { view:"button", label:"Save", type:"form", click:save_form },
    {
        view:"uploader", upload:"php/upload.php",
        id:"files", name:"files",
        value:"Add documents",
        link:"doclist",
        autosend:false //!important
    },
    {
        view:"list", scroll:false, id:"doclist", type:"uploader"
    }]
}

Beware to switch off autosending to send files together with other form data.

Form Saving

While saving the form, follow the scheme:

  • send files to server;
  • (optionally ) get response of uploading script and use its data. Described here;
  • save the form data via Ajax POST request;
  • (optionally) get response from a form-saving script and use its data.

Files are processed with a script defined as upload value of the uploader (read more) while form data is processed with the help of another one. You write both scripts on your favourite language to match your needs.

The Ajax request to send the form is defined as a callback to uploader send() method, so yo first get data from uploading script responce and can use it while saving form data.

Scheme of Form Saving

function save_form(){
    $$("files").send(function(){ //sending files
        //...callback

        webix.ajax().post(
            "php/saveform.php", //saving form
            $$("myform").getValues(),
            function(text){  //responce
                webix.message(text);
            }
        );
    });
}

To learn more about how to send Ajax requests in Webix, read the Ajax Operations article.


Intermediate

Controls Guide

Controls are the most important components for event handling since they enable interaction with users. They are used separately as well as can be nested into toolbar, form, and other components. All ui-related controls inherit from input.

List of Available Controls

Button, Checkbox, Colorpicker, Combo, Counter, Datepicker, Icon, Label, Multicombo, Multiselect, Multitext, Radio, Richselect, Range slider, Search, Select, Segmented, Suggest List, Tabbar, Text, Textarea, Toggle

Form controls share a lot of features that work the same way with most of them or with very little difference.

Control Initialization

Control constructor includes its name and properties defining its look-and-feel and behavior.

Some properties duplicate HTML attributes, some are typically Webix control properties. In addition, you can set necessary HTML attributes to your control within attributes object property.

{view:"text", width:200, click:"", attributes:{ maxlength:10 }...}

Defining Text Label

The label (string) property sets a text label for a control, a string placed by the control.

  • underwrites the controls and explains its purpose;
  • label absence is defined as label:"null" or by omitting this property in the control constructor;
  • horizontal position of the label is defined by the labelAlign (string) property. Its ossible values are: - "left"(default); - "right" (except for button and toggle that takes only left alignment);
  • vertical position of the label is defined by the labelPosition (string). The only possible value is "top";
  • width of the label is defined by the labelWidth property;
  • text of the button is set by value property instead of label.

Please, don't mix it with a separate view label.

Related sample: Positioning Labels

Defining Special Modes

Any control can be set disabled and readonly with the help of dedicated properties:

elements:[
    {view:"text", readonly:true},
    {view:"datepicker", disabled:true}
]

Control Positioning

Here we make use of the align (string) property that defines horizontal position of the control and its label with respect to the parent container (e.g. form):

  • "right";
  • "left" (default);
  • "center".

Related sample: Aligning Inputs and Labels

Setting Dimensions

Each time control is initialized, space is reserved for it. It either equals to parent (form, toolbar) dimensions or is set as control width.

In case several controls are in the same row/column, the available space is distributed equally among them.

Total width of the control includes inputWidth and, therefore, labelWidth (study the picture). If you set width less than the combination of them, a part of the control won't be visible. At the same time, you can make width bigger - then, spacing will appear.

The following sizing options are possible:

  • height/width (number) - dimensions of space reserved for this control including its label;
  • maxHeight/maxWidth - maximum dimensions of the whole control. During resizing, the control can't be bigger, but can be smaller;
  • minHeight/minWidth - minimal dimensions of the whole control. During resizing, the control can't be smaller, but grow bigger;
  • inputHeight/inputWidth (number) - dimensions of the input area/ button body;
  • optionWidth (number) - sets the width of an option (segment of tab) for segmented and tabbar. Hence, for such controls inputWidth = optionWidth * N options. If this value is smaller than an width, a part of the control will disappear;
  • labelWidth - width of the text label by the control. It can't be bigger than inputWidth and, thereby, width. If it is, the control will be incorrectly displayed. By default, it features static width of 106 px.
  • gravity - relative sizing functor for controls placed in the same row/column.
//text2 is 3 times bigger than text1
rows:[
    {view:"text",   name:"text1", gravity:1},
    {view:"text", name:"text2", gravity:3}
]

Attaching Functions

Controls can trigger any function for any component in the application. Study Event Handling for details.

Inner events of controls include:

  • clicking;
  • changing their state (selection made, switching to another tab, adding new data into inputs)

Two major possibilities here include:

1 . Attaching event inside the control constructor.

With the click property. It equals to the "onItemClick" event.

{view:"button", click:"$$("my_form").save()" }

With the on property that allows attaching custom handlers to specified inner events of the control:

//clicking
{view:"button", on:{
    'onItemClick': function(){...}
    }
}

//state changing
{view:"text",  on:{'onChange': function(){... }
    }
}

2 . The same using the attachEvent() method.

//clicking
$$("my_button").attachEvent("onItemClick", function(){.... });

//state changing
$$("my_text").attachEvent("onChange", function(){.....});

The implementation of an onChange() function is described in the Form documentation.

Automatic Showing and Enabling of Related Form Fields

Each form field can have one related field defined by its relatedView property.

This field can react on changes in master field and change it's state:

  • from hidden to visible and vice versa,
  • from disabled to enabed and vice versa.

This behaviour is also defined by the master field with the relatedAction property:

Enabling a form field by changes in another

elements:[
    {view:"text", id:"master", relatedView:"slave", relatedAction:"enable"},
    {view:"text", id:"slave", disabled:true}
]

The following conditions should be observed:

  • the functionality allows for watching various value changes (empty/not empty, selected/not selected, checked/unchecked) for different controls;
  • relatedView property takes ID of the needed control as parameter (if you don't define ID manually, it will be created automatically and can be derived as view.config.id);
  • relatedAction offers two possibilities for now:
    • "enable";
    • "show";
  • Slave field may have initial values to match with master relatedAction - hidden:true for "show" and disabled:true for "enable".

Related sample: Automatic form reconfiguration

Defining Initial Values

Single-value controls

For such controls as text and textarea value property isn't normally set beforehand, as they are intended for user filling.

So these exist different variants of value treating:

  • omit this property at all;
  • make the property empty ( {view:"text", value:""} );
  • set default value that can be deleted or changed by users( {view:"text", value:"My text"} );
  • still it's better to use placeholder (the default value for the input, a hint for user. Disappears as you start typing.);
  • for two-state controls like checkbox, radio and toggle possible values are:
    • true or 1 - for a 'checked' state;
    • false or 0 - for 'unchecked' state.
  • for counter, slider and range slider initial value is normally set as a possible number or the one in the middle of the predefined range.

Multiple-value controls

Such controls fall into two groups:

  • those presupposing the choice from a pull-down or popup list of predefined values (select, combo, multicombo, richselect and multiselect);
  • those offering the choice between tabs (segments) of integral buttons, namely tabbar and segmented.

These values are set within options property either as an array or as a collections of objects.

Array of options for Combo box

{ view:"combo", id:'field_m', label: 'Combo', value:"One", yCount:"3",
    options:["One", "Two", "Three"]}

The initial value is specified by the value property and corresponds to any value from the predefined ones:

Collection of objects

 { view:"radio", label:"Branch", value:1,options:[
     { value:"Master",  id:1 },
     { value:"Branch",  id:2 }]
}

Th initial value can be set as a text value of any option:

 { view:"radio", label:"Branch", text:"Master",options:[
     { value:"Master",  id:1 },
     { value:"Branch",  id:2 }]
}

If both text and value properties are defined, the text one will be ignored.

Related sample: Radio Button ('radio')

Serverside options for multiple-value controls

Such controls as select, combo, multicombo, richselect and multiselect can get values from the serverside. The script that returns the needed data, can be defined directly in the options property:

view:"combo", options:"server/data.json"

Related sample: Advanced options for select controls ('combo' and 'richselect')

Note that the getValue() method will return the ID of the currently selected tab/segment/option.

Setting Values Dynamically

Values can be as well set after initialization with the help of the dedicated setValue() method for a single control or setValues() to set the values for controls within the form. Find the latter in the related article.

Both methods take the needed value (or object with 'ID-value' pair(s)) as parameter and are called from the necessary control or the form where the controls are nested:

$$('text1').setValue('Anna'); //for a single text field with "text1" ID

$$('form1').setValues({ //value for 2 text field in the form
    text1:"Anna",
    text2:"Brown"
});

Values of two-state controls(checkbox and radio) can be changed programmatically in different ways:

  • setValue() - with either 0 (false) to uncheck or 1 (true) to check;
  • toggle() - to change the initial value (the toggle button as well takes this method);
$$("mycheckbox").toggle(); //-> if checked - becomes unchecked and vice versa

Getting Values

Within the library we have two methods for getting values:

  • getValue() - for a component that has one value (any control);
  • getValues() - for a component that stores a number of controls (form / htmlform)

In case you want to get the value of a separate control, call the getValue method from it:

{view:"select", id:"my_sel", value:1, options:[
    { id:1, value:"Master" },
    { id:2, value:"Release" }
]}

var value = $$("my_sel").getValue(); //- > returns 1

In case controls are embedded into a form, we call the getValues() method from this form while specifying name or ID of the dedicated control.

webix.ui({
    view:"form", elements:[
        {view:"text", id:"title", value:""},
        ...//other controls
    ]
})

var title = $$("myform").getValues().title, //-> retuns value of text input

Control Value can be different:

  • text string in the text or textarea control;
  • state (boolean) of two-state controls (checkbox, radio and toggle);
  • ID of selected tab of integral buttons (tabbar and segmented);
  • ID of selected option of selection controls (select, combo and richselect);
  • string with selected option IDs of a multiselect and multicombo control.
  • text on the button;
  • selected date or color item (datepicker, colorpicker).

In case the getValue() method returns object (e.g. date object) and you'd like to see the string result at once, you can include the stringResult property into the control constructor:

webix.ui({
    view:"datepicker",
    stringResult:true, // false by default
    ..config
});

Visibility of Controls

All controls can be shown and hidden on demand:

  • one by one applying show() and hide() methods to each of the needed controls or setting hidden property.
  • in groups by implementing batches functionality. More info.

For hidden inputs within the form the library offer peculiar API that actually eliminates the need of creating hidden fields. Here you manipulate with values only.

Styling

Controls can be styled to your taste with the help of CSS Image Maps.

Common Configuration within Form and Toolbar

If you have several instances of one and the same control within a form or a toolbar (a lot of text fields in the form or several buttons on a toolbar) and want them to have the same properties, you can define these properties only once in an elementsConfig object.

Find more info in the corresponding article of our documentation.


Hidden Input Fields

Hidden input fields are often included into the form to set default values into them, the values that are not visible to users yet required for required to be sent to server They are used for saving state in multi-page forms, collecting cookies or just storing data apart from the filled in.

Within HTML developers make use of the hidden property on the INPUT tag, yet the library offers to omit the unnesessary actions and manipulate just with data.

In fact, you needn't create any hidden text fields. Because all you need is their values.

First, create a form with collection of the needed controls and input fields.

webix.ui({
    view:"form", id:"my_form",
    elements: [
                { view:"text", label:'Login', name:"field_a", width:150, labelAlign:"right" },
                { view:"text", label:'Email', name:"field_b", width:200, labelAlign:"right" }
              ]
})

These are visible input fields for users to fill in.

Then, set values for invisible inputs without initializing them. They are automtically created with your values set:

$$('my_form').setValues(
            { field_d:"Hidden Info"}
        );

When getting values for the filled in form, the function will get values from all the field, regardless of their visibility.

Let's paste them to a textarea to see that it works:

{ view:"button", click:function(){
    values = JSON.stringify($$('my_form').getValues(), null, 2);
    $$('log').setValue(values);}
}

Related sample: Hidden Inputs


Common Configuration for Form and Toolbar Controls

UI-related Toolbar and Form are specific components since they don't mean much as they are yet act as containers for controls like buttons and icons, input fields and selection controls.

All the controls are included in a toolbar and form as an array of rows/columns or elements respectively. Each control has its own configuration. However, sometimes some properties like width/height, label alignment and label position coincide, which is done to achieve the uniformity of the component's look-and-feel.

To avoid multiple repetition of one and the same property for controls belonging to one and the same toolbar you can make use of the elementsConfig property. Included into a form or toolbar it sets common configuration for all its children (controls).

Form Configuration

webix.ui({
view:"form",
    elements: [//..elenemts
        ]
    elementsConfig:{
        labelPosition:"top",
        on:{ onchange:function(newv, oldv){
                webix.message("Value changed from: "+oldv+" to: "+newv);
            })
   })

Related sample: Common Configuration

All the controls in this form with have the label on their top and respond to data alteration in input fields.

Toolbar Configuration

webix.ui({
view:"toolbar",
        elements: [
                { view:"button"},
                { view:"segmented", options:[...]},
                { view:"text"},
                { view:"select", options:[...]}
                ],
        elementsConfig:{
                width: 150,
                height: 30,
                value:"edit"}
})

Related sample: Toolbar: Common Configuration

No matter how different the controls on the toolbar are, they will all get the same height and width as well as the same "edit" value.


Advanced Configuration of Popup Selectors

Combo, richselect, multiselect and multicombo controls can be highly customized because they are comprised of the following components:

  • Webix text input that can be either editable (for combos) or non-editable (for selects);
  • Webix list from which templating and loading rules, item sizes and look-and-feel are taken;
  • Webix popup from which popup size and behaviour are taken.

The combination of list and popup is called suggest list (described in detail separately). Here we will have a look at extra configuration possibilities of suggest-based controls.

Advanced Configuration

Normally, we define select options as array or datasource:

Short notation

{ view:"combo", options:[..data..] }
//or
{ view:"combo", options:"mydata.php"}

A suggest list of a default type will be attached. It will feature default template, size and filtering(for editable inputs). If you need to customize these things, you should use the extended configuration.

Extended notation

{ view:"combo", options:{
    view:"suggest", //optional
    filter:function(item, value){ ...},
    body:{ //list configuration
        view:"list", //optional
        data:[..data..],
        template:"#value#",
        yCount:7
    }
}}

Related sample: Advanced options for select controls ('combo' and 'richselect')

As you can see, options attribute can be used as object that houses suggest configuration and list settings in its body.

Changing Option Template

Option data may contain any properies instead of (in addition to) default id-value pairs (still, id attribute is mandatory).

{ view:"combo",  value:2, options:{
    template:"#name#",
    data:[
       { id:1, name:"Banana" },
       { id:2, name:"Papaya" }
]}

Extra text or HTML can be added:

{ view:"combo",  value:2, options:{
    template:"Extra #value#",
    data:[
       { id:1, value:"Banana" },
       { id:2, value:"Papaya" }
]}

Options data may as well contain multi-line text with html tags. In this case, the height of a parent component (here:toolbar) should be increased:

{ view:"richselect",
  options:[
    { id:1, value:"Here can be some long multi line content <ul><li>item1 <li> item 2</ul>"},
    { id:2, value:"Papaya"  }
]}

Related sample: Select Boxes

Changing Filtering Pattern

When a custom template is used for a combo box filtering should be redefined as well, since by default combo popup is filtered by value property.

Options attribute houses configuration of a suggest list in use while its body attribute houses a popup list:

view:"combo", value:1, options:{
    filter:function(item, value){
        if(item.name.toString().toLowerCase().indexOf(value.toLowerCase())===0)
             return true;
        return false;
    },
    body:{
        template:"#name#",
        data:[
           { id:1, name:"Banana"},
           { id:2, name:"Papaya"}
        ]
    }
}

Filtering is applied only in case the suggest list is combined with editable inputs - combo and multicombo.

Serverside Options

The easiest way to load options from server is to set a link to the necessary script right in the options attribute:

view:"richselect", value:"2", options: "server/data.json"

For extra customization, see below how to define options dynamically.

Getting Popup and List objects

The controls feature special Api to work with their parts:

var popup = richselect.getPopup(); //popup object
var list = richselect.getPopup().getList(); // list object

Defining Options Dynamically

Defining options data through the control:

Options can be redefined like any other property:

combo.define("options", [ {id:1, value:"Apple"}, {id:2, value:"Banana"} ]);
combo.refresh();

Parsing options into a popup list

Options are parsed to popup list under Webix data loading rules:

var list = $$("combo1").getPopup().getList();
var new_options = [
      { id:1, name:"Germany"},
      { id:2, name:"Great Britain"}
];
list.clearAll();
list.parse(new_options);

Options can be loaded by Ajax as well:

webix.ajax().get("server/data.php", function(text, data){
    var options = data.json();

    var list = $$("combo1").getPopup().getList();
    list.clearAll();
    list.parse(new_options);
});

Loading options into a popup list

Options are loaded to popup list under Webix data loading rules:

var list = $$("richselect2").getPopup().getList();
list.clearAll();
list.load("server/data.json");

Syncing Options with a DataCollection

Options list can be synchronized with either other component data or Datacollection data:

$$("my_combo").getPopup().getList().sync($$("list1")); //pushes this data into combo popup

Related sample: Get Popup View

Data syncing is described in the related article.

Attaching Events within a Suggest List

You can attach functions to list under the common Events Handling pattern:

view:"combo", value:1, options:{
    body:{
        data:[
           { id:1, value:"Banana"},
           { id:2, value:"Papaya"},
           { id:3, value:"Apple"}
        ],
        on:{
           'onItemClick':function(id){
               webix.message("Clicked: "+this.getItem(id).value);
            }
        }
   }

Still, to catch changes in the combo/richselect, it's better to use the related onChange event.

Sizing and Positioning

The dimensions of a popup list as well as its position in relation to a master control can be customized via suggest/options configuration object.

view:"combo", options:{
    fitMaster:false,
    body:{
        yCount:7
    }
}

Read more about it in the corresponding documentation article.

Changing Suggest Type

Be careful while experimenting with this feature - suggest lists differ in functionality.

By default, multiple-choice controls, e.g. multiselect use a checksuggest for storing options:

{ view:"multiselect", options:[
    { id:1, value:"Alex Brown" },
    { id:2, value:"Dan Simons" }
]}

If you want to use a multisuggest for these needs, use extended configuration and specify view name:

{ view:"multiselect",  options:{
    button:true,
    buttonText:"Approve", //"Select" by default
    view:"multisuggest",
    data:[
        { id:1, value:"Alex Brown" },
        { id:2, value:"Dan Simons" }
    ]
}}

Related sample: Multi-select input

Read more about advanced suggest lists.


Intermediate

Event Handling

Events that occur on the page with a Webix-based application fall into three groups:

  • inner events of Webix components ("onAfterSelect", "onChange", "onItemClick", etc);
  • global Webix events connected with its application flow;
  • native DOM events (can be handled in Webix way as well).

The main part of the article below concerns inner events of Webix components, while the details of the other two groups can be checked by a link.

Attaching Handlers to Inner Component Events

Common inner events for all ui components are mouse events (onItemClick, onBeforeContextMenu, onMouseMoving, onMouseOut, etc) since all the components can be clicked (and right-clicked) and respond to a mouse pointer.

Other inner events depend on the component functionality and are provided in API reference for each component.

A handler can be attached to a components in different ways:

1 . The most common way is to use any event of the component (check its API ref) within:

  • attachEvent() method, or;
  • the component's on property.

2 . Depending on the component nature, you can attach a handler to some specific events defined by component properties:

  • ready property of data components;
  • click property of buttons and inputs;
  • the component's data scheme object for events connected with data loading;
  • some specific properties that point to mouse events (onClick, onContext, onDblClick, onMouseMove).

Now let's study each possibility in detail.

Using the attachEvent() method

An attachEvent() method takes the name of the component's inner event and the function it fires (handler) as parameters. The syntax is:

 $$("element_id").attachEvent("onSomeEvent", some_function(){...});

Event names are case-insensitive.

A button to collapse the all tree nodes

var myEvent = $$("button_id").attachEvent("onItemClick", function(){
    $$("dtree").closeAll();
});

Later on, you can easily detach this event from the component with the help of the opposite method:

$$("button_id").detachEvent(my Event);

Attaching a function in the component constructor

You can also define event handlers right in the component constructor within either of the following attributes:

  • on - specifies the function that fires when the stated event happens;
  • ready - specifies the function that fires when the component is ready to use (has been initialized and loaded data, if any);
  • click - specifies the function that fires when the component is clicked. Works for some form controls like simple buttons and inputs.
webix.ui({
    view:"list",
    $init: function(){...},
    ready:function(){
        this.select(this.getFirstId()); //selects the first item
        this.load("data/books2.xml","xml"); //loads data from XML dataset
    },
    on:{
        'onItemClick': function(){
            alert("you have clicked an item");
        },
        'onAfterLoad':function(){ ... }
    }
});

When attaching an event you can specify only the name of a function to attach and declare it outside the webix.ui() constructor:

function select_first(){
    $$("datalist").select($$("datalist").getFirstId();)
};

webix.ui({
    view:"button",
    on:{
        'onItemClick': select_first
    }
});

Related sample: Creating a custom table

For buttons you can make it more compact by using click attribute:

function close_tree(){...};

{ view:"button", id:"sample_button", value:"Close", width:100, click:"close_tree"}

Attaching events in the data scheme.

Data scheme allows changing the default pattern of data handling within the component.

For instance, the function specified in its $init key will run each time when data is loaded/reloaded to the component and when the add method is called.

webix.ui({
    view:"list",
    scheme:{
        $init:function(obj){...},
        $update:function(obj){...}
   }
});

Related sample: Horizontal List

More possibilities of the data scheme are described separately).

Using specific properties for mouse events

Such properties come in pairs and include:

  • onClick and on_click handlers for clicking;
  • onContext and on_context handlers for right-clicking;
  • onDblClick on_dblclick handlers for double-clicking;
  • onMouseMove and on_mouse_move handlers for setting a mouse pointer over the component (item).

For instance, you need an event that fires each time you click an item in the list and performs an action that depends on the data derived from this item.

    $$("mylist").attachEvent("onAfterSelect",function(id){
       alert(this.getItem(id).title);
    })
  • those included into the component by default (when select property is true, clicking means selection) and
  • those attached with the help of an "onItemClick" event.

Both on_click and onClick can be modified if needed.

1 . With on_click redefining can be done only after the component initialization.

The on_click

grid = new webix.ui({
    view:"datatable",
    columns:[
        { id:"", template:"<input  type='button' class='delbtn' value='Delete'>"},
        {id:"title", ...}
        ],
    on:{"onItemClick", function(){...} //default click behavior
    },
    select:true
});

grid.on_click.delbtn=function(e, id, trg){
    webix.message("Delete row: "+id);
    return false;//blocks default onclick event
};

Related sample: Datatable: Custom Handler

One of the columns features an HTML template with a button styled with 'delbtn' CSS class. All cells including the one with this button will react on default click behavior while when you click on the button itself rather than on its cell area, the default behaviour will be overridden with the function attached to the 'delbtn' CSS class.

2 . The onClick allows redefining current click behavior right in the component constructor.

webix.ui({
    view:"list",
    template:"#votes# <span class='info'>Details</span>",
    select:"multiselect",
    onClick:{
        info:function(e, id){
            webix.message(this.item(id).title);
            return false; /blocks default onclick event
        }
    },
});

When you click list item styled with info CSS class, the item won't be selected and custom message will appear.

Related sample: List: Event Handlers

The same pattern is true for other pairs of properties.

Routing Events from One Component to Another

Event Mapping helps to get rid of repetitions in code when one and the same event should be attached to different components. If you have already attached an event to the component and described the function that this event triggers, you can route this event to another component in your app.

For these needs, use the mapEvent method and pass a map into it, where the map is an event-object correspondence:

webix.ui({
    rows:[
        { view:"list", id:"list1", data:list_data, on:{
            onItemClick:getItemValue
        }},
        { view:"list", id:"list2", data:list_data}
    ]
});
//here event name should be in the lower case
$$("list2").mapEvent({onitemclick:$$("list1")});

As a result, when the second list is clicked, the function that was initially attached only to the first one, will be executed for it as well:

function getItemValue(id){
    var obj = this.$eventSource || this;
    var value = obj.getItem(id).value;
    webix.message("List: "+obj.config.id+", clicked: "+id);

}

Note that if you need to access the object for which the handler is called at the moment, you can do it via $eventSource property while this will always point to the object for which the handler is attached initially.

Event Handling with Component Items

Inner events make it possible to work with component items provided that the ID of an item you click, select, etc. is passed to the attached function.

For instance, you need an event that fires each time you click an item in the list and performs an action that manipulates its data.

$$("mylist").attachEvent("onAfterSelect",function(id){
     alert(this.item(id).title);
});

Related sample: Sizing and events

Blockable Events

Events can be divided into two groups:

  • events that don't affect the app's work by their result;
  • events that affect the app's work depending with their result. If an event title contains the word "before", the continuation of the current action depends on whether the function returns true or false.

The function returns false, selection is blocked

$$("my_list").attachEvent("onBeforeSelect", function(){ return false; })

You can also temporarily block all events assosiated with the component by using the blockEvent() method. To re-enable event triggering use the unblockEvent() method.

$$("component_id").blockEvent();

$$("component_id").unblockEvent();

Delayed Events

The default value for response to events is 500ms. With such events as onMouseMove and onMouseOut, you can delay the server response for as much time (in milliseconds) as you need:

webix.ui({
   view:"menu",
   mouseEventDelay:100,
   ...
});

Keyboard Events

Components that are in focus at the moment automatically receive the ability to respond to keyboard actions and can take keyboard events, namely

  • onKeyPress - to respond to keys specified by dedicated key codes;
  • onEditKeyPress - the same, but with an editor opened;
  • onTimedKeyPress - to trigger actions after typing has been finished.

Look how the onTimedKeyPress event works with a text field to filter data in view list:

$$("list_input").attachEvent("onTimedKeyPress",function(){
    var value = this.getValue().toLowerCase();
    $$("list").filter(function(obj){
        return obj.title.toLowerCase().indexOf(value)==0;
    });
});
//"list_input" id the ID of the dedicated "text" input control

Related sample: List: Filtering

More information about key codes and hot keys is to be found in the UI Manager article.

Global Webix Events

Webix global events are not connected with any specific component and can be used to control general application issues (clicks, touch movements, serverside requests, etc). Some of them repeat native DOM events.

Events connected with Webix components functionality

  • onDataTable(config, obj) - fires the moment before a Webix datatable is renreded on the page;
  • onEditEnd - fires when a popup data editor (date, color, richselect) is closed in any of the components on the page. See Data Editors article for details;
  • onLiveValidation(editor, result, obj, value) - fires when editing starts in the component with live validation enabled;
  • onSyncUnknown(obj, source, filter) - fires when a component tries to sync its data with a non-Webix collection;
  • onReconstruct(obj) - fires when application layout is reconstructed (view is removed, added, replaced). See Dynamic UI Modifications article for details;
  • onLayoutResize(cells) - fires when application layout is resized (not window).

General page events

  • onClick(e) - fires when a click/double click happens in any application part;
  • onFocusChange(newf, oldf) -fires when focus is changed in the application. Its parameters are Webix objects, the one in focus and the one previously focused, or null if non-Webix object is focused;
  • onReady - fires at the same time with window onload event;
  • unload - fires at the same time with window onunload event.

Page events in touch environment

  • onRotate(orientation) - fires when screen is rotated;
  • onAfterScroll(pos) - fires when some webix view has been scrolled;
  • onTouchStart(context) - fires on touch start;
  • onLongTouch(context) - fires on long touch;
  • onTouchEnd(start_context, current_context) - fires on touch end;
  • onTouchMove(start_context, current_context) - fires on touch movement;
  • onSwipeX(start_context, current_context) - fires when a horizontal swipe is detected;
  • onSwipeY(start_context, current_context) -fires when a vertical swipe is detected.

The details on Touch Events are given in the related part of API reference

Events connected with serverside requests from the page

  • onBeforeAjax(mode, url, data, request, headers) - fires when any Ajax request is issued. It can be developer request or automatic (when using Data Connectors);
  • onAjaxError(request_obj) - fires when any Ajax request results in an error;
  • onLoadError(text, xml, xhttp, obj) - fires when an error has happened during loading the data into a component. See Management of loading errors article for details.

All such events are attached to webix object:

webix.attachEvent("onRotate", function(mode){
    ..// logic
});

Handling of Native DOM Events

Native DOM events can be handled with the help of Webix event() and eventRemove() functions that are called from webix object:

var eventId = webix.event("divId", "click", function(e){
    do_something();
});

webix.eventRemove(eventId);

Comments:

  • divID - the ID of an HTML node you want to attach event to;
  • click - event name (note that they are used here without on prefix);
  • handler - function to run (its e argument points to native event object);
  • context - (optional) additional settings:
    • master - (object) an object that the this keyword refers to;
    • capture - (boolean) a flag that indicates on which stage (capture or bubble) event should be captured. false by default;
    • id - (string) event handler ID (if not set, will be generated automatically).


Advanced

Keyboard Events. Focusing. Navigation

Each time you create a component on the page, even a single one, UIManager module is initialized (though indirectly). Its main tasks are:

  • watching which component (and component item) is focused at the moment;
  • setting and removing focusing;
  • assigning keyboard events to the component in focus;
  • memorizing the component's outer scheme.

Focusing Methods

You can set and remove focus programmatically with the help of two opposite methods - focus() and blur() that are called from the component object. It can be specified in the component's ready property to set/remove focusing on page loading.

The focus() method is either used without parameters or takes an ID or name of an item as an argument. In the latter case, focus is set to this item rather to the whole component.

$$('my_toolbar').focus(); // the toolbar is focused
$$('my_toolbar').blur(); //the toolbar is no longer in focus

$$('my_toolbar').focus('my_text');
// a text input with ID/name = "mytext" on this toolbar is focused

$$("form").focus(); //the first focusable element in the form is focused

Through UI Manager you can control focus with the following methods that are called from UIManager with the ID of the needed view as an argument:

  • getFocus() - returns the view object that is currently focused;
  • setFocus(id) - sets focus into the specified location;
  • hasFocus(id) - checks whether the component is in focus and returns true or false respectively
  • canFocus(id) - checks whether the component can take focus. Invisible (hidden) views and their items as well as disabled views cannot be focused.

Focusing an item with ID 'books'

webix.ui({
    id:"books",
    view:"list"
    ...
});

webix.UIManager.setFocus("books");

Focusing Events

Every Webix component features a pair of focusing events onFocus and onBlur:

$$("datatable1").attachEvent("onFocus", function(current_view, prev_view){
    //current_view is the datatable in question
});

$$("datatable1").attachEvent("onBlur", function(prev_view){
    //prev_view is the datatable in question
});

In addition, Webix onFocusChange (global event) is triggered each time focus is shifted from one component to another. The following code retrieves the ID of the view that is in focus now and puts in into the console log.

Watching focus changes

webix.attachEvent("onFocusChange", function(current_view, prev_view) {
    webix.console.log("focused: " + (!view ? 'null' : view.config.id));
});

Keyboards Events and Hotkeys

Built-in Keyboard Events

1) 'Esc' key closes a non-modal window when it is focused.

2) 'Esc', 'space' and 'enter' keys are enabled by default for modal message boxes.

3) Editors of data component items react on the following keys:

  • 'esc' - to close without saving data changes;
  • 'enter' - to close with data changes saved.

For other situations keyboard can be connected to your application in several ways:

Attaching Hot keys

Component Navigation Keys

Hotkeys for navigation (arrow keys, Home, End, Page Up, Page Down) in data components like datatable and list can be enabled by navigation property:

{ view:"datatable",  navigation:true }

Related sample: Navigation in DataTable

Other data components need to be extended with the KeysNavigation module. Consult the dedicated article for details.

Hotkeys for Controls

For controls there exists a possibility to define a hotkey that will trigger it onClick event. The key name (e.g. 'enter' or 'space') is specified by hotkey property:

{ view:"button", click: doOnClick, hotkey: "enter" }

Related sample: Hotkeys for buttons

The doOnClick function will fire now either or pressing 'enter' or on clicking.

Key combinations joined by + or - sign are as well possible:

{ view:"button", click: doOnClick, hotkey: "enter-shift" }

Note that such functionality will work with simple controls like buttons and inputs, not with multiple-choice one.

Defining Custom Hotkeys

The addHotKey function is called from the UIManager object and has two mandatory parameters - key name and event handler. Key combinations joined by + or - sign are as well possible.

You can make hot keys global, which means that they will trigger the function regardless of the component. The one in focus will be subject to hot key actions.

webix.UIManager.addHotKey("Ctrl+V", function() {
    webix.console.log("Ctrl+V for any");
});

At the same time, you can specify any instance of a Webix component that should react on this or that hot key by passing the its into the function as a third parameter.

In case you want all the view instances react on the specified hot key, state the view name instead of ID:

//hot keys for the component with 'details' ID
webix.UIManager.addHotKey("Ctrl+Enter", function() {
    webix.console.log("Ctrl+Enter for details");
    return false;
}, $$('details')); // for "details" list only

//hot keys for all list instances on the page.
webix.UIManager.addHotKey("Ctrl+Space", function() {
    webix.console.log("Ctrl+Space is detected for list");
}, 'list'); // for all lists on the page

Related sample: Basic use of editors

Removing Hotkeys

The removeHotKey function is used to remove a hotkey. As a parameter it takes the key name:

//adding a hotkey
webix.UIManager.addHotKey("Ctrl+Space", function() { ... }, 'list');

//removing the hotkey
webix.UIManager.removeHotKey("Ctrl+Space");

Attaching Keyboard events

  • onKeyPress (code, ctrl flag, shift flag, native event) - takes key codes to perform actions on pressing the specified key/keys.
  • onEditKeyPress (code, ctrl flag, shift flag, native event) - has the same functionality as the event above, but the event can be applied to an opened editor.
  • onTimedKeyPress - fires with delay and starts function execution only when a user stops typing.

In the code below the 'Enter' key opens 'details' accordionitem. Before this, you check that it is not combined with either Ctrl, Shift or Alt key:

'Enter' key in action

$$("books").attachEvent("onKeyPress", function(code, e) {
    if (code === 13 && !e.ctrlKey && !e.shiftKey && !e.altKey) {
        $$('details').getParentView().expand('details');
    return false;
    }
});

These events require that a developer should know key codes used by UI Manager. Here they are:

Key Codes

  • 'enter': 13,
  • 'tab': 9,
  • 'esc': 27,
  • 'escape': 27,
  • 'up': 38,
  • 'down': 40,
  • 'left': 37,
  • 'right': 39,
  • 'pgdown': 34,
  • 'pagedown': 34,
  • 'pgup': 33,
  • 'pageup': 33,
  • 'end': 35,
  • 'home': 36,
  • 'delete': 46,
  • 'backspace': 8,
  • 'space': 32,
  • 'meta': 91,
  • 'win': 91,
  • 'mac': 91

Global Tab Navigation

Tab/focus Order Logic

Any app on the page is put into layout, even if it isn't declared directly, so as you open the page the whole layout is focused. All the components are children of this layout. When you put cursor into any component or its item tab navigation can be enabled:

Tab Navigation

webix.UIMananger.tabControl = true;

From now on, you can move through your app with 'tab' and 'shift+tab' keys. For instance, if you have two forms in different layout columns, focus will move through all the input fields of the first form, then move to the other, then will proceed to other components and return to the parent (layout).

Related sample: Tab Navigation

If you want to exclude a single component from tab navigation order, make use of the tabFocus property, which is true by default:

{view:'text' tabFocus: false, ... }

Tab navigation within the whole app/page is possible only if all the components are intialized as part of one and the same webix.ui constructor.

What does it mean?

The 'tab-navigated' components must be children of one and the same layout since by logic focus moves from parent view to children and vice versa.

Tab Navigation between form and toolbar

webix.ui({
    rows:[
        {view:"form",..},
        {view:"toolbar",...}
    ]
});

In case of two separate webix.ui constructors you have two separate objects without the possibility to shift focus from one to the other with the help of a 'tab' key. So move a mouse pointer instead.

Tab navigation won't work!

webix.ui({
    view:"form", ..config..
});

webix.ui({
    view:"toolbar", ..config..
});

To get the neighbouring views in focus/tab order, you should apply the following methods to the currently focused view.

Methods to Shift Focus

  • getNext(); - gets the next view;
  • getPrev(); - gets the previous view;
  • getTop(); - gets the parent view to all the components.

All these methods are called from UIManager and take the necessary view as an argument.

Let's consider the picture above and see how these methods will work for a text input field (its ID is 'year').

var prev = webix.UIManager.getPrev($$("year")); //returns 'title' input field object

var next = webix.UIManager.getNext($$("year")); //returns 'rank' input field object

var top = webix.UIManager.getTop($$("year")); //returns 'layout' object


Intermediate

Adding Active Elements to Components

According to default Webix pattern, applications are made by putting pre-built meaningful components (like grid, tree, controls) into layouts. The areas with extra interactivity can be added to Webix components in two ways:

Defining Active Zones through Component templates

Clickable (or in some other way 'active') areas inside components are defined through HTML templates and CSS classes. More on data templates.

Related sample: List: Event Handlers

In the list above the task is solved in the following way:

  • each item has a template with HTML content in addition to list item data.
  • the onClick event of a list component is redefined for info CSS class. Clicking on this area ('Details' button) invokes showing a message while clicking any list item outside the button invokes default list behaviour for clicking (here item is selected);

CSS for active element

.info{
    width:100px;
    text-align: center;
    font-weight:bold;
    float:right;
    background-color:#444;
    color:white;
    border-radius:3px;
}

List config with active span element

webix.ui({
    view:"list",
    template:"#votes# <span class='info'>Details</span>",
    select:true,
    onClick:{
        info:function(e, id){
            webix.message(this.getItem(id).title);
            return false;
        }
    }
});

Using ActiveContent Module

ActiveContent module lets developers get rid of drawing interactive elements themselves and makes it possible to use existing Webix controls for it. In other words, it allows inserting controls into views. (Normally, it goes only for layouts).

Related sample: List: Active Content

First of all, the ActiveContent module should be added to the needed component by extending its default functionality:

webix.protoUI({
    name:"activeList" //give it some name you like
},webix.ui.list, webix.ActiveContent);

Now, you can use it. Note that the name of the newly created component is used as view property value:

webix.ui({
    view: "activeList",
    id:"mylist",
    activeContent:{
        deleteButton:{
            id:"deleteButtonId",
            view:"button",
            label:"Delete",
            width:120
        },
        markCheckbox:{
            view:"checkbox", ...
        }
    },
    template: "#title#<div>{common.markCheckbox()}{common.deleteButton()}</div>"
});

"Active" template can be also defined via a function:

view:"activelist",
template: function (obj, common) {
   return obj.title+"<div>"+common.deleteButton(obj, common)+"</div>";
}
  • the activeContent property contains an array of key-value pairs where:
    • key is a used-defined name of an active area (here deleteButton, editButton);
    • value is its configuration.
  • config of the active element is stored in the common property of the housing component and can be derived by its name;
  • template for each list item includes these configurations as {common.name};

If an active content element can have a variable value (like text field, or checkbox) it can be passed to it within data item properties:

Value for 'markCheckbox' active element

view:"activeList",
data:[
    { id:5, title:"My Fair Lady", year:1964, rank:5, markCheckbox:1}
]

Click and other events are attached to the buttons according to Webix Event handling pattern:

view:"button", click:function(){...}
//or
button.attachEvent("onItemClick", function(){...});

Getting master of an active content element

  • using locate function:
    • in any mouse event handler of the active element (e.g. onItemClick event, or click property).
$$('deleteButtonId').attachEvent("onItemClick", function(id, e){
    var item_id = $$('mylist').locate(e);
    //returns id of a list item
});
  • through the active element configuration:
    • if a handler is attached to non-mouse event (all component-specific Webix events);
    • if an active element is redrawn on a mouse event (like toggle, checkbox).
on:{
    'onChange':function(newv, oldv){
        var item_id = this.config.$masterId;
    }
}

Datatable and treetable specificity

With datatable and treetable you can get a row object by $master property that includes:

  • row - row id;
  • rind - row index;
  • column - columns id;
  • cind - column index.
on:{
    'onChange':function(newv, oldv){
        var item_id = this.config.$masterId.row;
    }
}

Related articles
  • Adding a custom element to the datatable header


Web and Internet

  • Webix Storage Interface
  • Saving Application State


Advanced

Webix Storage Interface

Webix library offers its own API for working with application cache and browser local storages - permanent cache, per session cache and cookies.

Accordingly, webix.storage module contains three objects:

  • webix.storage.local - works with window localStorage object;
  • webix.storage.session - works with window sessionStorage object;
  • webix.storage.cookie - works with document cookie object.

The objects share three methods:

  • put(name, data, [domain, expires]) - the last two params concern only cookie storage. The method allows putting data to browser cache under the stated name. Data is passed as JSON object;
  • get(name) - the method derived stored data from local cache for further usage. Data comes in JSON format;
  • remove(name, [domain]) - the last param concern only cookie storage. The method removes data saved under the stated name from local cache.

Working with Local Storage

Local storage can be used for storing any application data, e.g. current state of a component derived with getState() method.

To do this, you put() state object into Webix local storage under a custom name. Data you save should be in JSON format(which is exactly what getState() returns).

function save_state(){
    webix.storage.local.put("state", grid.getState());
}

If data you'd like to save is plain Javascript object, apply Webix serialize() method to it.

To retrieve data from local storage, use get() method pointing to the name under which you've save this or that data.

function restore_state() {
    var state = webix.storage.local.get("state");
    if (state)
        grid.setState(state);
}

Related sample: DataTable state object::Session

To save and track state of a multiview-based app, follow other instructions.

Using Local Storage for Offline Support of ServerSide Applications

Local storage interface can be used for storing serverside data in case of disconnect, which ensures that local changes won't be lost even after page refresh.

Local storage functionality is set by adding a prefix of desired mode - cache or offline to you load and save scripts.

webix.ui({
    view:"datatable",
    ..config..
    url:"offline->load.php",
    save:"offline->save.php"
});

In either of these modes, serverside data is loaded to a component, and is additionally cached to your machine( webix.local.put() function is executed in background).

What happens next depends on the chosen mode:

Offline mode:

  • The component will always try to get up-to-date data data from server. If server is unavailable, data is reloaded from cache (webix.local.get() function is executed behind the scene). That's why you can refresh page as many times as you wish;
  • Data changes you make while online are pushed to server and to cache. So cache will always contain the latest copy of serverside data;
  • Data changes you make while offline, are pushed to cache only and should be sent to server manually.

Cache mode:

  • Once data has been loaded to a component it is put to cache (local storage) and later on the component will work only with cached data without trying to get to server;
  • Data changes you make while either offline or online are pushed to cache and should be sent to server manually.

Local mode:

  • The component works with in-browser local storage only. Data is loaded from there (is any), and all CRUD operations are saved to local storage;
  • You can access localStorage objects to get data from and put data to.

Read also main Offline Support article.

Working with cached data

Although Webix library offers a ready-to-use solution, you can write your own proxy object to enable offline support and set it as the component's url property:

webix.ui({
    view:"datatable",
    ..config..
    url:{
        $proxy: true,
        load: function(view) {//save data after editing
             view.attachEvent("onAfterEditStop", function(){
                webix.storage.local.put("app_data", this.serialize());
              });
             view.load("data/data.json", {
                success: function(text){//fresh data, save in cache
                     webix.storage.local.put("app_data", text)
                },
                error: function(){ //probably in offline mode
                     view.parse(webix.storage.local.get("app_data"));
                }
            });
        }
     }
});
  • onAfterEditStop event is used to catch data changes and put edited data to cache;
  • cached data is inline data, that's why it is parsed into a component, not loaded.


Saving Application State

There exist different ways to save the state of the application and its components after page refresh.

1) UIManager offers a possibility to save and restore the state of the whole Webix application. Get details.

2) Webix DataState module makes it possible to save state of any separate component. Get details.

3) Webix Histoty API makes it possible to track the latest opened tab in multiview applications. Get details.

The first and the second methods are available in Webix Pro edition only.


Available only in PRO Edition

Saving and Restoring Application State

Webix UIManager allows saving current visual scheme of the component, its 'state' with the following methods:

  • getState() - to capture current state of a Webix application;
  • setState() - to set the saved state for the application.

The data for the state itself is stored in the webix.storage.local object (non-pro), which is your browser cache. Simply put, data is saved to your local machine.

The state of any view included into the application state object contains the following information:

{
    id:"main",
    width:500,
    height:400,
    gravity:1
}

Some views featuring tabs, panels or cells in their configuration contain additional properties:

{
    collapsed:"tab1", //currently collapsed panel
    activeCell:"tab2" //currently active tab
}

Getting and Saving State

The getState method is called from the UIManager and gets the app's general structure (namely ID, width, height, gravity). It takes two arguments:

  • the ID of the component which state you'd like to save (as a rule, the ID of the top-most component, layout);
  • boolean true or false for component children. If true, state of nested components is saved alongside with layout state.

To save the data and make it usable later on, your should put it into the local storage, defining the key for it:

webix.attachEvent("unload", function(){
    webix.storage.local.put("stateApp", webix.UIManager.getState("main", true));
});

Restoring State

To use the method, you should firstly get the stored data from the local storage (using the key you defined for it at the previous step):

var stateApp = webix.storage.local.get("stateApp");

And then call setState from UIManager to restore the state of the application.

if(stateApp)
   webix.UIManager.setState(stateApp);

Related sample: Application state::Session


Saving and Restoring Component State

UIManager helps save and restore only the outer view parameters while inner ones like selection and scrolling direction are saved within the DataState module.

Webix components that use this module feature the saving and restoring functionaluty as well:

  • datatable;
  • treetable;
  • datatree.

Saving Datatable State

Webix datatable provides a possibility to store/restore the state of the tree to cookie, local or session storage.

The state object will contain information about current datatable state:

  • properties (keys) of each data item;
  • column sizes;
  • IDs of currently selected items (each ID is an object with row, column and id properties);
  • scroll position;
  • values of built-in filters;
  • IDs of currently hidden data items.
{
    ids: ["id", "value", "chapter"],
    size:[50, 250, 200],
    select:[{"row":217,"column":"title","id":"217_title"}],
    scroll:{ x:0, y:0},
    filter:{"year":"1924"},
    hidden:["votes"]
}
  • To save the current tree state to the local storage you should call the getState method as in:
var state = grid.getState();
webix.storage.local.put("state", state);
  • To restore the saved state you should call the setState method:
var state = webix.storage.local.get("state");
if (state)
    grid.setState(state);

Related sample: DataTable state object::Session

Saving Treetable State

Webix treetable provides a possibility to store/restore the state of the tree to cookie, local or session storage.

The state object will contain information about current treetable state:

  • IDs of currently hidden data items;
  • properties (keys) of each data item;
  • open treetable nodes;
  • scroll position;
  • IDs of currently selected items (each ID is an object with row, column and value properties);
  • column sizes.
{
    hidden:[],
    ids: ["id", "value", "chapter"],
    open:["1", "1.2"],
    scroll:{ x:0, y:0},
    select:[{"row":"1.2","column":"value","id":"1.2"}],
    size:[50, 250, 200]
}
  • To save the current tree state to the local storage you should call the getState method as in:
var state = grid.getState();
webix.storage.local.put("treetable_state", state);
  • To restore the saved state you should call the setState method:
var state = webix.storage.local.get("treetable_state");
if (state)
    grid.setState(state);

Related sample: TreeTable state object

Saving Tree State

Webix tree provides a possibility to store/restore the state of the tree to cookie, local or seccion storage.

The tree state object will contain information about opened and selected nodes:

{
    open:['1', '2', 'root'],
    select: ['1.3']
}

where '1', '2', 'root' and '1.3' are the ids of the related nodes.

  • To save the current tree state to the local storage you should call the getState method as in:

Saving the tree state to the local storage

var state = $$("tree").getState();
webix.storage.local.put("state", state);
  • To restore the saved state you should call the setState method:

Restoring the tree state from the local storage

var state = webix.storage.local.get("state");
if (state)
    $$("tree").setState(state);

Related sample: Tree State Object::Session


Intermediate

Tracking the Latest Opened Tab

Here we discuss the state of an application created with multiview layout.

With multiview application design you can create as many cells as you wish and switch between them with the help of dedicated buttons, namely tabbar and segmented, or resort to tabview functionality.

Tab values coincide with IDs of the views you place into multiview cells.

Initially, either the first tab is visible, or the one you've set to be "selected" during initialization. Normally, when you refresh the page, the application is redrawn according to this initialization pattern.

webix.ui({
    rows:[
      {view:"segmented", id:'tabbar', selected:"listView", multiview:true, options:[
            { value: 'List',  id:'listView'},
            { value: 'Form',  id:'formView'},
            { value: 'About', id:'aboutView'}]
      },
      {cells:[
            {id:"listView",  view:"list"},
            {id:"formView",  view:"form"},
            {id:"aboutView", view:"template"}]
      }
    ]
});

Nevertheless, the library offers history API to store the current application state, or simply put, to memorize the latest opened tab.

History track method allows remembering the currently opened tab and showing it after page loading. It takes two parameters:

  • id - the ID of the segmented, tabbar and tabview that is used for switching between multiview views.
  • url - ID of a multiview cell that forms the hashbang url that is loaded after page refresh. By default it's the ID of the currently opened cell.
webix.history.track('tabbar');

There's also the onBeforeHistoryNav event which allows adding some actions while working with history. The event is called before history is applied.

$$("tabbar").attachEvent("onBeforeHistoryNav", function(){
    //... some code here ...
});

The event is cancelable: returning false will cancel changes in the view.

Each time you click the tab to switch for another cell, a hashbang URL is generated on the base of cell ID (under http://current_url.html#!/cellID pattern) and memorized. You'll see it in the url bar of your browser.

If for the track() function you define the url parameter as cell ID, this cell will always be shown after refresh. If you don't specify this parameter, the last opened cell will be displayed.

Compare ID-s from the snippet above and hashbang URL-s for each of the tabs on the picture.

Related sample: History API with Multiview

Now, each time, you refresh the page, the url will be formed according to the info stored in the state object and the latest opened tab will be shown.

Pushing New State to History

In addition, there exists a possibility to programmatically add a new state to history with the dedicated push() method. Its arguments are:

  • view - ID of related switching control;
  • url - ID of the cell that will form in-page url for new state (if you pass cellID, the url will be formed as #!/cellID);
  • value - any related data in the form of a JSON object. If will be stored in the state object.

The method is applied to history object:

webix.history.push("tabbar", "detailView" "details");

..where details are

var details = {
    view:"template",
    template:"Some very long text"
};

However, this will cause the URL bar to display http://current_url.html#!/detailView, but won't cause the browser to look for detailView anchor or even check whether it exists. It just adds this info to window history object.


Extending components

  • Component Copying and Extending
  • Creating a Custom Component


Advanced

Component Copying and Extending

Components in webix UI library are objects that can be cloned and copied as well as inherit properties from each other.

Let's take for instance the toolbar component and play around with it. It has three properties - width, height and cols object with three buttons.

var barA = { view:"toolbar", width:500, paddingY:2, cols:[
    { view:"button", value:"Load" },
    { view:"button", value:"Save" },
    { view:"button", value:"Info" }
]};

Copying

Shallow Copying

Shallow copying is implemented via the clone(); method. A clone of an object is an empty object with a prototype reference to the original one.It doesn't go deep during copying and clones the structure of the source component. All the changes you make in the source object are reflected
in the target object.

var barB = webix.clone(barA);

barA.width = 400;

barA.width --> 400
barB.width --> 400

Deep Copying

During deep copying a physical copy of a parent object is being made. The copy is fully independent, so, if later on you make changes in the source object, the properties of the target object remain unchanged. However, the method doesn't work for structures with inner loops.

var barB = copy(barA);

barA.width = 400;

barA.width --> 400
barB.width --> 500 // initial value from the source object

The method is useful when you'd like to create two independant instances of one and the same object on the page.

This is how a new pager is created on the base of the pagerA one.

$$("pagerA").clone({
    container:"pagingB_here", //own parameters
    size:50,
    group:5
});

Related sample: Two-area pager

Inheritance

New components can be created on the base of already existing ones. There is an extend(); function that merges the properties of two objects into a new one. If any of the shared properties gets changed in the target object, it is changed as well in the source one. Native properties of the two objects are independent.

extend(object target, object source, [boolean overwrite])

  • Target is an object that is being extended. It receives new properties.
  • Source is a component that acts as a source for the target component;
  • Overwrite is false by default, yet it can be set to true. In this case, the properties that coincide are overwritten to the values of the source object (sometimes you can get a full copy).

barB = {view:"toolbar", cols: [{view:"button", value:"Accept"}]};

webix.extend(barB, barA);

//here we get:

barB = {view:"toolbar", width:500, paddingY:2, cols: [{view:"button", value:"Accept"}]};
//width and padding are inherited properties

Full (object-based) copy with the help of extend();

webix.extend(barB, barA, true);

//here we get a copy with all the properties overwritten:

var barB = {view:"toolbar", width:500, paddingY:2, cols:[
    { view:"button", value:"Load" },
    { view:"button", value:"Save" },
    { view:"button", value:"Info" }
]};

Extended Functionality

Late Binding

Here we try to find how to extend component functionality with properties that aren't typical of it and not stated in its API. For instance, we want a component to be movable. It can be enabled with the extend(); method while the source object here is webix.Movable module.

webix.ui({
    view:"toolbar",
    ...
});
webix.extend($$("my_toolbar"),webix.Movable);

Now our toolbar can can be moved across the screen.

It is a so-called late binding. In fact the target object here is supplied with some properties from the source object while preserving its native properties. Moreover, inherited methods won't overwrite existing methods with the same name.

Early Binding

If you want to put apart inherited and native methods of the same name, you should refer to early binding, where prototypes of two objects are merged.

Movable Toolbar

mytoolbar = webix.proto({webix.Movable},webix.ui.toolbar);
var obj = new mytoolbar({ view:"toolbar",... });
// outputs a movable toolbar

To extend component's existing functionality you can as well use protoUI(); method that creates the new view based on some of the existing ones. This is how it looks in case you want to make your list editable.

Editable List

webix.protoUI({
    name:"mylist"
}, webix.EditAbility, webix.ui.list);

webix.ui({
    view:"editlist",
    ...
});

Related sample: List: Editing


Advanced

Creating a Custom Component

You can create a custom component from any of the existing ones, assigning properties, methods and events to it.

The library allows extending functionality of any component by adding building modules to it (however, most components feature all the necessary functionality by default) as well as creating a totally custom component that inherits from the basic view.

Simply put, the technique uses the protoUI(); command to construct the new component with it own name, properties and functions. All the new components must be based on existing ones.

webix.protoUI({
   name:"newComponent", // the name of a new component
   $init:function(config){
        this.load(data.xml)
        //functions executed on component initialization
   },
   defaults:{
      width:200,
      on:{'onItemClick' : function(){}} //attached events
   },
   custom_func:function(){..function description..}, //any custom function
   $getSize: function(x, y){..},
   $setSize:function(x, y){..},
}, webix.Movable, // extended functionality
webix.ui.list); //the name of the base component

As a result, we get a custom component that

  • inherits from ui.list;
  • on its initialization loads data from the 'data.xml' file
  • can be moved over the screen (thanks to the webix.Movable module);
  • has a default width of 200px;
  • has a custom_func function;
  • is sized with the help of $getSize and $setSize methods (will be described later).

Later on, the component is inserted into the app the same way you do with library components:

webix.ui({
    view:"newComponent",
    ..config options..

})

The must-have elements for such constructor are new component's name and the component it inherits from. Additional functionality can be included to your choice.

Editable List

webix.protoUI({
    name:"editlist",
        },
webix.EditAbility, webix.ui.list);

The protoUI constructor eliminates the need of repeated usage of the extend(); method each time you want to initialize a new instance of your custom component. Read more about extended component functionality.

Main Methods and Properties

Before we describe how the mentioned technique works, it will be helpful to summarize the main methods and properties you may use while developing a component.

Properties:

  • $view - the HTML (<div>) component container.
  • $width - the width of the component container.
  • $height - the height of the component container.
  • $ready - an array of commands. You may use this property to call some function as soon as the $init method and all the setters are executed. The functions are added to the array through the command push (call this command in the method $init):
this.$ready.push(...);

Methods:

  • defaults - defines default settings of the component.
  • $init - for the most part defines component initialization. Called at the very beginning.

In this method you add HTML elements, specify event handlers. As a parameter the method takes the object 'config' that contains all the properties which a user set in the constructor. Inside the method you can refer to the HTML object of the component through this.$view.
Note, the method doesn't take properties set in the method 'defaults'. They are available just after initialization is finished completely (i.e. $init and all the property setters are executed).

  • $getSize - defines the size of the whole component. You should use this method to set the size of the component that differs from the size allocated by the parent view. Called when inner code inquires about height or width which should be set for the component.

The method returns the array [gravW;width;gravH;height] (width gravity, fixed width, height gravity, fixed height).

The values of the array conform to the following rules:

  • Width(height) can take the next values:
    • any natural number;
      This value is used as width(height) of the component.
    • -1;
      This value tells the script to ignore the parameter.
  • GravW(gravH) can take any natural value. The value '1' tells the script to ignore the parameter.
  • When width(height) is set to any natural value, gravW(gravH) is ignored. When width(height) is set to -1, the script asks for gravW(gravH) value.

The possible scenarios:

Sc.1 You want the parent container to set the size automatically (autosizing).

Solution: don't redefine the function or return [1;-1;1;-1]

Sc.2 You want to set relative width(height).

Solution:

a)for relative width return [yourValue;-1;1;-1]
b)for relative height return [1;-1;yourValue;-1]

Sc.3 You want to set fixed width(height).

Solution:

a)for fixed width return [1;yourValue;1;-1]
b)for fixed height return [1;-1;1;yourValue]

  • $setSize - defines behaviour and sizes of the specific elements of the component. You should use this method if your component has a complex structure. Called as soon as the size of the whole component is set (after $getSize method).

Let's consider some existing component, for example, window. It has a header and a body. Assume, you hide the header. The body of the window will keep the previous size but instead of the header you'll see empty space. To prevent this, you should specify a logic defining behaviour of the elements in such the situation. The appropriate logic must be specified in the method $setSize.

A Custom Component

Fully custom components inherit from view, as a rule, which is an empty container for library components. Basic modules are also included into your component to support app-user interaction.

Let's see how we can create a multi-colored header for a three-column app.

webix.protoUI({
    name:custom",
    ..configuration..},
    webix.MouseEvents, webix.EventSystem, webix.ui.view);
  • webix.MouseEvent - a module that makes your component support mouse events such as 'onItemClick';
  • webix.EventSystem - to support event handling functionality, such as attachEvent() method;

It's also possible to reuse the CSS class of some other view in order to apply it to your custom component. To do this, you need to use the $cssName property:

webix.protoUI({
    // a custom component
    name:"liveEditor",
    // inherits CSS class from the text component
    $cssName:"text",
}, webix.ui.text);

Adding Functionality to the Component:

1 . For a component you can set CSS classes with the help of the className(); method defined for $view property that points to an HTML container of the component. It is included into the $init function alongside with the innerHTML method to set containers for component items.

$init:function(config){
    this.$view.className = "my_control";
    this.$view.innerHTML = "<div class='item1'></div><div class='item2'></div>
    <div class='item3'></div>";
}

2 . Define default properties:

defaults:{ controlHeight:50 }

3 . Create component items by defining item setter functions:

item1_setter:function(value){
    if(value)
        this.$view.childNodes[0].innerHTML = value;
    return value;
}

These functions are used in the component code to set inner HTML for component items:

webix.ui({
    view:"custom",
    item1:"Reg Form",
    item2:"Filmset",
    item3:"Details"
})

4 . Size the component. Here two methods are used:

  • $getSize - returns the current size of the component in the form of an array (min width, max width, min height, max height, gravity). The method is optional here;
    • Use -1 if you want to ignore any of these parameters.
  • $setSize(x, y) - takes width and height as arguments and sets component dimensions.

Both of them are used for inner logic. To size and resize existing components refer to the dedicated article.

$getSize:function(){
    return [1,100000,this.config.controlHeight,this.config.controlHeight,1];
},

$setSize:function(x,y){
    if (webix.ui.view.prototype.$setSize.call(this,x,y)){
        var itemWidth = Math.round(this.$width/3);
        for(var i=0;i<3;i++){
            this.$view.childNodes[i].style.width = (i==2?this.$width-
            (itemWidth*2):itemWidth) +"px";
            this.$view.childNodes[i].style.height = this.$height+"px";
        }
    }
}

5 . Attach events to the component

on: {'onMouseOver': function(){...);}}

As a result, we've got a multi-colored header template within a three-columnn design and 'elastic' sizing, which means that the app can adjust its size to the current window size.

Related sample: Custom Component


Third party integration

  • JQuery Integration
  • Angular JS Integration
  • Backbone Integration
  • Integration with DHTMLX Components
  • DIY - Custom Integration Pattern

Also, be sure to check UI Extensions


Intermediate

JQuery Integration

webix library works in tandem with JQuery libraries as well, which is an obvious bonus for those who are used to working with JQuery.

JQuery is included by a link specified in your document's head section

<script src="../path/library_name.js" type="text/javascript" charset="utf-8"></script>

Working with JQuery, you can create all the components from the webix UI library. The syntax differs a little bit; however, it grants you new possibilities.

Component initialization:

$(#div ID/ .CSS selector').webix_component({config});

Let it be list:

<div id="listA"></div>
  ...
$("#listA").webix_list({
    width:320, height:600,
    template:"#votes# #rank# #title#",
    data:big_film_set
});

Related sample: JQuery List

Working with Components

You can get to any component using the same scheme and apply functions to it.

Counting data items

$('#div ID/ .CSS selector').webix_component().count()

Advantages of JQuery Integration

1 . An HTML container for any component can be specified by its ID or CSS class used with it. With the webix library means HTML container can be defined by its ID only:

<div class='calendar_here'></div>
<div id='list_here'></div>
...
$("#listA").webix_calendar({config}); // div ID
$(".calendar_here").webix_calendar(); //CSS selector

2 . If you use the same CSS class for several nodes, you can create multiple instances of the same view by pointing to this CSS class during component initialization.

Two calendars will be displayed

<div class='calendar_here'></div>
<div class='calendar_here'></div>
...
$(".calendar_here").webix_calendar();

Related sample: JQuery Calendar

3 . An HTML table can be the datasource for the component initialized in the same container. Each column in the table is reflected as a template item for the component:

Table row with three columns

<tr>
    <td>1</td>
    <td>Record #102</td>
    <td>5406</td>
</tr>

Columns in template are called ##data## and are numbered starting from 0.

List template to grab the data from the table

{
    template:"<div class='mark'>#data2# </div> #data0#. #data1#",
    ...
}

Related sample: Jquery List from HTML table


Angular JS Integration

Webix-Angular App Structure

To use Angular JS framework for Webix component you should:

  • include Angular and Webix scripts into the document. Note that order does matter here - Angular JS script must come first;
  • set ngApp directive to the document root to bootstrap an application. For convenience means, it's recommended to use "webixApp" as module name.
  • create a new module passing module name from the previous step and "webix" required parameter to connect it to Webix library.
<!doctype html> <!--setting directive-->
<html lang="en" ng-app="webixApp">
<head>
  <meta charset="utf-8">
  <title>Webix-Angular App</title>
  <script src="js/angular.min.js"></script>
  <script type="text/javascript" src="../../codebase/webix.js"></script>
  <link rel="stylesheet" type="text/css" href="../../codebase/webix.css">

  <script type="text/javascript">
    var app = angular.module('webixApp', [ "webix" ]); //creating module
    ..//app's js code (controllers)
  </script>
</head>
<body>
    <!-- app's html -->
</body>
</html>

However, since app logic is typically complex, it's a good practice to store controllers separately:

<script type="text/javascript" src="controllers.js">

Initializing Webix Components

Bound to Angular JS, Webix offers a special webix-ui directive that bootstraps an application. Here two methods are possible:

  • initializing from HTML markup - the directive is used without an argument, the application is initialized via HTML:
<div webix-ui type="space"> <!-- app html --> </div>
  • initializing from a JS configuration object - the directive is used with the app's config object as an argument, no additional markup is used. Config object is stored in the app's controller:
<div webix-ui="config" webix-ready="doSome(root)" style="width:450px; height:300px;">

Two patterns are equal in functionality yet differ in the way this functionality is implemented.

Initializing from from HTML markup

This method resembles Webix HTML Initialization technique but has its own peculiarities:

  • Webix application lies in a div block with webix-ui directive:
    • view attribute of such block specifies Webix component you want to init;
    • if you don't specify the view attribute - a layout row will be created;
  • all div blocks within "webix-ui block" are Webix views(components):
    • view attribute of a div specifies Webix component you want to init;
    • a div block without the view attribute inits Webix template;
    • other attributes of div blocks are component properties;
  • As with standard Angular JS, you can easily insert Angular directives into tags including inputs and buttons (like in standard HTML).

Layout with Tabbar and Multiview

<body>
  <div webix-ui type="space"> <!--layout rows with type "space" are created-->
    <div height="35">Header { {app} }</div> <!--Webix template is initialized -->
    <div view="cols" type="wide" margin="10"> <!--Webix layout cols are initialized-->
        <div width="200">
            <input type="text" placeholder="Type here" ng-model="app">
        </div>
        <div view="resizer"></div>
        <div view="tabview">
            <div header="Tab1">
                1. Some content here
            </div>
            <div header="Tab2">
                2. Other content here
            </div>
        </div>
    </div>
    <div height="35">Footer</div>
  </div>
</body>

Related sample: Webix - Angular : Layouts

The input and header template are bound together by ng-model directive.

You can check how these views are initialized in Webix: layout, resizer, tabview, template.

Datatable Component

Webix datatable is a complex component for working with large amounts of data. The table below features four columns, row selection and auto height. Each column has its own ID, sorting method and header (the latter is defined by innerHTML).

<div style="width:750px;">
 <div webix-ui view="datatable" webix-data="records" autoheight="true" select="row">
   <div view="column" id="rating" sort="int" css="rating">Rating</div>
   <div view="column" id="year"   sort="int">Year</div>
   <div view="column" id="votes"  sort="int">Votes</div>
   <div view="column" id="title"  sort="string" fillspace="true">Title</div>
 </div>
</div>

Related sample: Webix - Angular : Grid

Note that any HTML outside "webix-ui" block is parsed as standard markup while a div with webix-ui attribute constructs Webix app.

Data loading issues are explained separately.

Chart Component

Webix chart is a handy data visualization tool. The chart below is of a bar type, shows sale rates and comes without borders.

<div style="width:500px; height:200px;">
  <div webix-ui view="chart" id="mychart" webix-data="lines" type="bar" value="#sales#" borderless="true"></div>
</div>

Related sample: Webix - Angular : Chart

Note that any HTML outside "webix-ui" block is parsed as standard markup while a div with webix-ui attribute starts Webix app.

Data loading issues are explained separately.

Rendering Arrays

Webix to Angular integration allows for rendering both arrays of components as well as arrays in component configuration with Angulat ng-repeat directive.

Rendering an array of the same Webix components

Webix-ui directive can be combined with Angular ng-repeat to render an arry of views

<div webix-ui>
    <div ng-repeat="chart in charts" view="chart">
</div>

where chart is a scope variable that includes an array of component configurations:

$scope.charts = [
    { data:chart_data, series:[...] },
    { data:chart_data, series:[...] }
  ];

Rendering arrays within component configuration

Arrays in component config are denoted by stack property. Inside array notation you can use ng-repeat to iterate through it and specify the information to display:

<config stack='series'>
    <config ng-repeat="serie in chart.series" value="#.template#"></config>
</config>

where series is a property of scope chart variable that contains an object with chart series config:

{
    data:chart_data,
    series:[
        { template:"sales3", color:"#ff8" },
        { template:"sales", color:"#f8f" }
    ]
}

Related sample: Webix - Angular : Using ng-repeat

Rendering Complex Layouts

Webix-Angular integration allows for complex application design with different inter-related Webix components in it.

For more details, study the dedicated sample Related sample: Webix - Angular : Complex Init

Further Reading

  • Angular Controllers and Data Loading Webix-data directive;
  • Event Handling during Webix-Angular Integration Webix-event directive;
  • Changing Visibility of Components in the App Webix-show directive;

Initializing from Config Object

Initialization via config object helps get rid of markup and hence, markup-specific directives, and move the entire application code to Angular controller.

The only markup line you need is:

<body ng-controller="webixTestController">
    <div webix-ui="config" webix-ready="doSome(root)"></div>
</body>
  • This method is closer to Webix initialization pattern. Config object is JSON object you would pass into webix.ui() constructor if you were working with Webix alone;
  • Event handlers are attached with the help of webix-ready directive that executes a controller function taking config root as parameter. Described later.

Controller Code

var app = angular.module('webixApp', [ "webix" ]);

app.controller("webixTestController", function($scope){
    var header = { type:"header", template:"App header" };
    var left = { view:"list", id:"a1", select:true, data:["One", "Two", "Three"] };
    var right = { template:"Right area", id:"a2" };

    //config object
    $scope.config = {
        isolate:true, rows:[ //two rows
            header,
            { cols:[
                left,  //list
                { view:"resizer" }, //resizer line
                right //template
            ]}
        ]
    };
};

Related sample: Webix - Angular : Initing from Config

  • Components used in the sample are list, template, layout, resizer line.
  • Top parent view of the config object (here: two-row layout) should have an isolate property to avoid ID mess in a situation when there're same IDs in another config object on the page. Similar functionality is offered by Webix IdSpace mixin.

Attaching Events with webix-ready Directive

Webix-ready directive executes a controller function with a config root as an argument and makes it possible to attach event handlers for all components in current configuration. If you init from HTML markup, use webix-event directive for these needs.

<body ng-controller="webixTestController">
    <div webix-ui="config" webix-ready="doSome(root)"></div>
</body>

Root is a top parent view of your application config. Here root is a two-row layout.

Root has an isolate property, which means that the IDs of its child views (header, list, template) can be not unique within the page (there can be same IDs in another config object). But, when attaching event handlers, you should refer to components via their root.

Controller Code

app.controller("webixTestController", function($scope){
    $scope.doSome = function(root){
    var list = root.$$("a1"); //referring to list via root object
    var template = root.$$("a2"); //referring to template via root object

    list.attachEvent("onAfterSelect", function(id){
      template.setHTML(this.getItem(id).value);
    });

    list.select(list.getFirstId());
  };
};

Inside the fucntion invoked by webix-ready directive, Webix-Angular integrated app complies to standard Webix event handling pattern.


Angular Controllers and Data Loading

Since Angular controllers are heart of any Angular-based application, Webix-Angular integration preserves controller functionality.

As in Angular, controller directives are included into the app as an attribute of any tag.

<html ng-app="webixApp"> <!--Angular App initialized-->
 <body ng-controller="webixTestController"> <!--Angular controller-->
  <div webix-ui view="datatable" webix-data="records" select="row"> <!--Webix App-->
    ...<!--datatable config-->
  </div>
 </body>
</html>

Loading data via Controller

Scope variables are accessed by standard pattern except for data loading. To populate the datatable with data from controller $scope, use webix-data directive. It is used in a div that initiates this datatable.

The code below gets $scope.records and parses them into the datatable:

<div webix-ui view="datatable" webix-data="records" > ...</div>

Filtering and sorting options can be used as well:

<input ng-model="query" ... />
<select ng-model = "orderProp">...</select>

<div webix-ui view="datatable" webix-data="records|filter:query|orderBy:orderProp">
...
</div>

Controller code

var app = angular.module('webixApp', [ "webix" ]);

app.controller("webixTestController", function($scope){
  $scope.records = [
    { id:1, title:"The Shawshank Redemption", year:1994, votes:678790, rating:9.2, rank:1},
    { id:2, title:"The Godfather", year:1972, votes:511495, rating:9.2, rank:2},
    ...
  ];

  $scope.addRecord = function(){
    $scope.records.push({
        title:"New Record",
        rating:999,
        votes:0,
        year:2013
    });
  };

Related sample: Webix - Angular : Grid

As you might have already noticed in the code above, all data manipulations with datatable data are done by changing scope dataset. In HTML, the addRecords() function is called by an ng-click directive:

<body ng-controller="webixTestController"> <!--Angular controller-->
  <div webix-ui view="datatable" webix-data="records" select="row"> <!--Webix App-->
    ...<!--datatable config-->
  </div>
  <button ng-click="addRecord()">Add Row</button>

Datatable data will be updated the moment $scope.records is changed, which is ensured by Angular binding philosophy.

Using Component methods via Controller

To comply with Angular concept, any function you use with this or that component should be stored in the app's controller, even if it is the component's own method.

<body ng-controller="webixTestController">

    <div style="width:500px; height:200px;">
    <div webix-ui view="chart" id="mychart" webix-data="lines" type="bar" value="#sales#" borderless="true"></div>
    </div>

    <button ng-click="changeLine('line')">Show Line Chart</button>
</body>

ChangeLine() controller function redefines the chart by setting another type for it:

Controller Code

  $scope.lines = [
    //chart dataset
    { id:1, sales:20, year:"02"},
    { id:2, sales:55, year:"03"},
    ...
  ];

  $scope.changeLine = function(type){
    //methods are applied to the chart by its ID
    $$("mychart").define("type", type);
    $$("mychart").render();
  };

Related sample: Webix - Angular : Chart


Event Handling With Angular

To understand Webix event handling concept consult the corresponding documentation article.

Angular JS offer a number of directives to catch on-page events (ngClick, ngChange, ngKeyPress, ngMouseMove) and all of them can be successfully used in Angular-Webix integrated applications.

<button ng-click="changeLine('line')">Show Line Chart</button>

Related sample: Webix - Angular : Chart

At the same time, Webix library offers a set component-specific events such as onItemClick, onSelectChange, onAfterTabClick, etc that cannot be handled by Angular means.

webix-event Directive

All Webix events can be handled with a special webix-event directive that calls a scope function to perform a desired action:

<body ng-controller="webixTestController">

<div webix-ui view="cols" type="space">
  <!--datatable column-->-
  <div view="datatable" webix-data="records"
        webix-event="onItemClick = showDetails(id, details)" select="row">
    <!--datatable columns-->
  </div>
  <!-- template column -->
  <div>
    Selected ID: { { selectedId } }
  </div>
</div>

</body>

In the code above, an onItemClick datatable event is handled with showDetails() scope function to show an ID of any selected item in a template as {{ selectedId }}.

Event Handler in Controller

App's Controller

var app = angular.module('webixApp', [ "webix" ]);

app.controller("webixTestController", function($scope){
  $scope.records = [ ..datatable data..];

  $scope.showDetails = function(id, details){
    $scope.selectedId = id.row; //setting value for selectedId
    $scope.$digest();
  }
});

Related sample: Webix - Angular : Events

Note that the function called by webix-event directive is limited to have only two parameters:

  • ID of an item in question (sent by Webix event);
  • event details that encompass all params sent by Webix event.

For instance, datatable specific onItemClick event has three params - item info object (id, row, column), native event object and and target HTML element:

Webix Event Handling Pattern

grid.attachEvent("onItemClick", function(id, event, node){
    //... some code here ...
});

Handled by Angular, event object and target element are passed in details together with item info:

app.controller("webixTestController", function($scope){
 $scope.showDetails = function(id, details){
    $scope.selectedId = id.row;
    /*or you can get ID as*/
    $scope.selectedId = details[0].row;

    $scope.eventType = details[1].target.getAttribue("class");
    $scope.nativeElement = details[2].tagName;

    $scope.$digest();
  }
}

Note that HTML objects (event, element) are not processed by Angular and the object itself will come as if empty. Nevertheless, you can still retrieve all of its properties:

$scope.showDetails = function(id, details){
    $scope.eventType = details[1]; //returns {}
    $scope.nativeElement = details[2] //returns {}

    $scope.eventType = details[1].type; //returns "click"
    $scope.nativeElement = details[2].tagName; //returns "DIV"
}

Handling of Mupliple Events per Component

Webix-event directive allows attaching any number of events at a time:

<div view="datatable" webix-data="records"
webix-event="onItemClick = show1(id, details); onAfterSort = show2(id, details);">
    <!--datatable columns-->
</div>

Accordingly, you need to specify scope functions to handle each event (or a common function for the attached events):

app.controller("webixTestController", function($scope){
  $scope.show1 = function(id, details){
    ...
  };

  $scope.show2 = function(id, details){
    ...
  };
}

Study the sample to see how it works:

Related sample: Webix - Angular : Events


Changing View Visibility

From the very beginning it should be said that Webix views can't be hidden and shown back with Angular ngShow and ngHide directives that can still be used to manupulate visibility of pure HTML elements.

Let's remind us what are Webix views. They are created with the help of webix.ui() constructor that is called by webix-ui directive.

<body ng-app="Webix App">
    <div style="width:800px;"></div> <!--standard HTML element-->
    <div webix-ui type="wide">
        <!-- all divs inside this and including this are parsed as Webix views-->
    </div>
</body>

To show and hide Webix Views a special webix-show directive should be used. Remember that all divs without view attribute are parsed as Webix templates. Views are initially hidden.

<div webix-ui type="wide">
    <div width="200" webix-show="showLeft">Left</div>
</div>

The webix-show directive declares a variable which value (boolean) can be afterwards changed on some event. Here button click is used:

<!-- showing view -->
<button ng-click="showLeft=true">Show Left</button>

<!-- hiding view -->
<button ng-click="showLeft=false">Hide Left</button>

Related sample: Webix - Angular : Visibility


Advanced

Backbone Integration

Backbone.js is a lightweight Javascript framework that allows for adding structure to client-side code in the MVC pattern. Backbone works in conjunction with its hard-weight dependency, Underscore.js, the utility library that provides a lot of the functional programming support and contains a number of functions as well as specialized helpers for function binding, javascript templating,and so on.

Backbone is based on the MVC principle that translates as Model, View and Controller classes where:

Bonuses of Backbone usage:

  • The approach used in the framework helps get rid of unstructured 'Spaghetti' code in your applications;
  • All the changes are performed on Models. The corresponding views respond to these changes are re-render themselves according to the new info, which eliminates the need of either looking through the DOM structure to find the necessary ID or update HTML manually;
  • Tasks are clearly divided between application parts;
  • RESTful API (Representational state transfer).

To get the profound knowledge of the framework, go to the Backbone.js homepage.

How it can be used

Webix and Backbone can be cross-integrated on multiple levels:

  • Webix components can load data from backbone collection, check Backbone Collections for more details;
  • Webix components can be wraped in a Backbone Views, check Backbone Views for more details;
  • visibility of Webix Components can be controlled by Backbone router, check Working with Backbone Routers for more details.

Example of usage

To integrate Backbone framework into your webpage your should include links to it into the document head. Be attentive to specify the right relative paths to the places where the files are stored on your machine. The important point - library need to be included BEFORE webix.js:

<head>
  <script type="text/javascript" src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
  <script type="text/javascript" src="./common/underscore.js"></script>
  <script type="text/javascript" src="./common/backbone.js"></script>

  <link rel="stylesheet" href="../../codebase/webix.css" type="text/css" media="screen" charset="utf-8">
  <script src="../../codebase/webix.js" type="text/javascript" charset="utf-8"></script>
</head>

Creating Views

In an integrated app, pure Backbone views and Backbone-Webix views co-exist.

Backbone views are created under Backbone standard pattern:

cView = Backbone.View.extend({
    tagName: "h2",
    render: function(){
        $(this.el).html("Child View");
    },
});
var v2 = new cView();
v2.render();

Backbone-Webix integrated views resemble this pattern yet feature a config property where Webix configuration is stored. To instantiate such a view, a special WebixView() constructor is used:

var ui_config ={
    type:"wide", rows:[
        { template:"top", height:35 },
        { type:"wide", cols:[ ..cols ..]},
        { template:"bottom", height:35 }
    ]
};

var view  = new WebixView({
    el: ".app1_here", // will be rendered to div with "app1_here" class
    config:ui_config
}).render();

Related sample: Backbone integration - View

In the code above Webix layout with 3 rows and columns in the second row is created. It is rendered to a div block with "app1_here" class. As a rule, views should be manually rendered with a dedicated function.

For more into about Webix-Backbone integrated views, read the Backbone Views article.

Creating Models and Collections

FilmRecord = Backbone.Model.extend({});
FilmList = Backbone.Collection.extend({
    model: FilmRecord,
    url:"./common/data.json" //adding data to collection
});

Loading the Collection into a View

First, lets create a Webix data component, for instance view list:

View: Webix List

$(".app1_here").webix_list({
    id:"mylist", width:200,
    template:"#title#", select:true
});

Now, when we have a view and a model we can render the model into the list view with the syncing method:

//get data
var films = new FilmList();
films.fetch();

//sync collection data with list
$$("mylist").sync(films);

Related sample: Backbone Integration. Loading data from Collection

The code above renders list view and fills it with data from FilmList Collection that is comprised of FirmRecord Models.

The sync between data collection and the component can be as well removed by the opposite method:

$$("mylist").unsync(films);

Conclusion

It should be said that the above scenario is not the only way to use Webix and Backbone together. Check the below docs for more details.

Working with Backbone.js
  • Loading from Backbone Collections
  • Using Webix in Backbone Views
  • Working with Backbone Routers


Backbone Collections

While Webix components have their own logic to load and save data, you can also use Backbone Collection as data source, and handle loading and saving in Backbone's way.

Data Loading

First, we need to create a Backbone collection and add data to it:

FilmRecord = Backbone.Model.extend({});
FilmList = Backbone.Collection.extend({
    model: FilmRecord,
    url:"./common/data.json"
});

films = new FilmList();
films.fetch(); //getting collection data

Each data component has sync method that can be used to load data from a Backbone Collection.

There can be several methods to add data from a Backbone collection to a Webix view. It depends on how you init the view.

By direct rendering into the needed node

var list = $(".app1_here").webix_list({
    template:"#title#", select:true
});

list.sync(films);

Related sample: Backbone Integration. Loading data from Collection

By creating a Backbone view that houses this component

MyView = WebixView.extend({
    config:{
        view:"list", //Webix list config
        id:"mylist",
        width:200,
        template:"#title#",
        select:true
    },
    afterRender:function(){
        this.getChild("mylist").sync(this.options.collection); // syncing after rendering
    }
});

new MyView({
    el: ".app1_here",
    collection: films //defining collection as view option
}).render();

Related sample: Backbone Integration. Views and Models

After executing the sync command any changes to the "films" collection will be reflected in the list. Also, any changes, done by list API (adding, deleting, editing) will be reflected in a Backbone collection as well.

Data Saving

Nevetheless, changes in the component don't trigger saving to the Backbone Collection on their own. You need to use additional Webix events that are handled to enable data saving:

  • webix:add & webix:change - fire when a new item is added or an item is updated in the view (here:list);
  • webix:remove - fires when a record is removed from the view.
//films is Backbone collection with FilmRecord model
films.on("webix:add webix:change", function(model){ //no delimiter between events!
    model.save();
});
films.on("webix:remove", function(model){
    model.destroy();
});

Related sample: Backbone Integration. Saving data from collection.

Loading data in Form

Not all Webix components can work with Backbone Collections directly. Components that represent only one model can't use sync API, so instead of it you can use parse method to load data to them:

$$("form").parse( films.first().toJSON());

This command loads data from the model into Webix form, but any changes in the form or in the model are not reflected or saved.

Adding extra methods to Collections

Backbone collection can be extended to have as many various methods as you need. These are test methods that change collection data:

FilmRecord = Backbone.Model.extend({});

FilmList = Backbone.Collection.extend({
    //basic properties
    model: FilmRecord,
    url:"./common/data.json",

    //necessary for test buttons only
    addSample:function(){
        this.add(new FilmRecord({ //adds new record to collection
            title:"New Record"
        }));
    },
    deleteFirst:function(){ //removes first record from collection
        this.remove(this.first().cid);
    }
});

This is how these functions are triggered in the app:

<input type="button" value="Add" onclick='films.addSample()'>
<input type="button" value="Delete first" onclick='films.deleteFirst()'>

Related sample: Backbone Integration. Saving data from collection.


Backbone Views

This feature is fully optional, you can safely init Webix in any HTML container, so normal Backbone views will work fine enough.

Creating View

To create a new View you can use the next code:

var myview = new WebixView({
   el:".app1_here",
   config:{
      rows:[
        {template:"ABC"},
        {cols:[...]},
        {view:"some"}
      ]
   }
});
  • el - HTML locator or HTML node of the element in which a view needs to be rendered;
  • config - Webix UI configuration.

To render view somewhere on the page you should call:

myview.render();

Related sample: Backbone integration - View

Isolating Views

It's a good practive to isolate backbone views that are comprised of several Webix views so that you can use same IDs in another Backbone view on the page:

var ui_config={
    isolate:true, rows:[
        {template:"ABC", id:"abc"},
        {cols:[...]},
        {view:"some"}
    ]
};

var firstview = new WebixView({
   el:".app1_here",
   config: ui_config
});

var secondview = new WebixView({
   el:".app2_here",
   config:ui_config
});

Each Backbone view has a template with abc ID, but since config features an isolate property you can still refer to the necessary template (for instance in view functions that refer to these components).

You can also render any Webix view directly into an HTML element:

$(".app1_here").webix_list({
    id:"mylist", width:200, //config
    template:"#title#", select:true
});

Related sample: Backbone Integration. Loading data from Collection

Predefined methods of view

WebixView is an instance of Backbone.View.

There is a few methods that are already implemented in views created with this constructor:

  • render() - renders the view;
  • destroy() - calls the view destructor;
  • getRoot() - get the top Webix control in the view;
  • getChild(id) - get the child Webix control by its ID.

Nesting HTML view into Webix view

You can define a template view, and later render there a normal Backbone View by using the code like next:

//webix ui config
var ui_config ={
    isolate:true, type:"wide", rows:[
        { template:"top", height:35 },
        { type:"wide", cols:[
            { template:"left", id:"left" },
            { template:"center", id:"center" },
            { template:"right", id:"right" }
        ]},
        { template:"bottom", height:35 }
    ]
};

//create top level view
var v1 = new WebixView({
        config: ui_config,
        el: ".app1_here"
    });
    v1.render();

//html child view
cView = Backbone.View.extend({
    tagName: "h2",
    render: function(){
        $(this.el).html("Child View");
    },
});

//create child view
var v2 = new cView();
    v2.render();
    v1.getChild("left").setContent(v2.el);
  • getChild method is used here to get layout child with "left" ID;
  • setContent(content) method of Webix view is used here to attach Backbone View to template.

Related sample: Backbone integration - Nested Views

Nesting Webix view into another Webix view

Similar to the method above, you can render a Webix view as layout child view with the code like next:

//create top level view
var v1 = new WebixView({
        config: ui_config,
        el: ".app1_here"
    });
    v1.render();

//create child webix view
var v3 = new WebixView({
        config: ui_config,
        el:v1.getChild("right")
    });
    v3.render();

Related sample: Backbone integration - Nested Views

The place where a UI component need to be attached is defined through "el". New view (v3) will replace the child of v1 view.

Extending View

Same as with Backbone View you can extend WebixView:

MyView = WebixView.extend({
    config:{
       view:"list", url:"data.json"
    },
    afterRender:function(){ ...},
    beforeRender:fucntion(){ ...}
    someMethod:function(){ ...}
});

var view1 = new MyView({ el : "areaA" });

There are 2 special methods that can be defined in such way:

  • beforeRender() - will be called during rendering before creating a Webix view;
  • afterRender() - will be called during rendering when Webix view is already created. It's a good place to define event handlers for Webix components of this Backbone view or load collection data.

And at the same time you can add you custom methods here.

MyView = WebixView.extend({
    config:{
        rows:[
            {view:"list", id:"mylist", ..},
            {view:"template", id:"details", ..}
        ]
    },
    afterRender:function(){
        //adding a handler to list selection
        this.getChild("mylist").attachEvent("onAfterSelect",_.bind(this.listSelected,this));
        //syncing view data with collection
        this.getChild("mylist").sync(this.options.collection);
    },
    listSelected:function(id){
        this.getChild("details").parse({ "id": id });
    }
});

Related sample: Backbone Integration. Views and Models

Webix event handling pattern is described in the corresponding documentation article.


Working with Backbone Routers

Take that you have a list and a template and you want to show either one or another by clicking on their elements. There you can have different patterns depending on how you init the components:

  • Backbone Router for pure Webix Views
  • BackBone Router for Backbone-integrated Views
  • BackBone Router for Updating Layout Sections

Backbone Router for pure Webix Views

To create a UI we can use a Webix code like next:

webix.ui({
  container:"app1_here", rows:[
     {template:"Click on item", type:"header" },
     {cells:[
       {view:"list", url:"data.json", template:"#title#", select:true, id:"mylist"},
       {template:"<button onclick='history.back()'>Back</button>", id:"details" }
    ]}
  ]
});

Now, let's create a Backbone Router.

var routes = new (Backbone.Router.extend({
    routes:{
        "":"index",
        "films/:id":"details" //details() f-n is triggered
    },
    details:function(id){
        $$("details").show(); //it shows template with film details
    },
    index:function(){
        $$("mylist").show();
    }
}));

As you can see the router shows the necessary view based on current document URL. After switching to "details" template, the application receives a hashbang url localhost/myapp.html#films/id to show in it the ID of a currently selected list item.

To have the app working we need to add a few extra lines of code:

$$("mylist").attachEvent("onAfterSelect", function(id){  //navigation rule
    routes.navigate("films/"+id, { trigger:true });
});
Backbone.history.start(); //router starts memorizing its steps

Related sample: Routes. The Webix way.

These lines define the navigation rule after selecting an item in the list and starts the router. Template, in its turn, uses an existing router and makes a step back on button click (look at its code above).

BackBone Router for Backbone-integrated Views

Now lets try to recreate the same app, but stick closer to the native Backbone approach. Instead of creating Webix UI directly, lets define Backbone-Webix integrated views for both states:

var layout = new WebixView({
    el:"#app1_here",
    config:{
        rows:[
            { template:"Click on item", type:"header" },
            {
                view:"list", url:"common/data.json",
                template:"#title#", select:true,
                id:"mylist"
            }
        ]
    }
});

DView = Backbone.View.extend({
    el:"#app1_here", //the same element as above
    tagName: "div",
    render: function(){
        $(this.el).html("<button onclick='history.back()'>Back</button>");
    },
});
var template = new DView();

Now a router looks a bit more different:

var routes = new (Backbone.Router.extend({
    routes:{
        "":"index",
        "films/:id":"details" //details() f-n is triggered
    },
    details:function(id){
        template.render(); //it renders the template into its "el"
    },
    index:function(){
        layout.render(); //rendereing layout back
        //attaching select event after rendering
        $$("mylist").attachEvent("onAfterSelect", function(id){
            routes.navigate("films/"+id, { trigger:true });
        });
    }
}));

Related sample: Routes. The Backbone way.

Instead of switching between views in Webix layout we are rendering different Backbone Views into one and the same element depending on current state. Still, the resulting behavior is the same.

Yet, the router should be triggered separately at once after the app has been initialized:

//init app
Backbone.history.start();

Updating Layout Section

When using views we can update not only the top view, but any section of Webix layout in it.

Lets create 3 views, one is layout while the two others (list and template) are children of this layout. They will be shown in this layout in different cases:

var template = new WebixView({
    config:{ template:"<button onclick='history.back()'>Back</button>" }
});
var list = new WebixView({
    config:{
        view:"list", url:"common/data.json",
        template:"#title#", select:true,
        id:"mylist"
    }
});
//layout wil Webix config
var layout = new WebixView({
    el:"#app1_here",
    config:{
        rows:[
            { template:"Click on item", type:"header" },
            { }
        ]
    }
});

The router for such pattern is as follows:

var routes = new (Backbone.Router.extend({
    routes:{
        "":"index",
        "films/:id":"details"
    },
    details:function(id){
        //setting node for template as layout child view
        template.el = layout.root.getChildViews()[1];
        template.render();
    },
    index:function(){
        //setting node for list as layout child view
        list.el = layout.root.getChildViews()[1];
        list.render();
        $$("mylist").attachEvent("onAfterSelect", function(id){
            routes.navigate("films/"+id, { trigger:true });
        });
    }
}));

The code above locates the necessary cell in the layout and renders the needed view into the target cell.

Related sample: Routes. Changing the Webix Layout


Integration with DHTMLX Components

DHTMLX is a component Javascript Library for building enterprise-level Web apps with clean interface, fast performance, and rich user experience. Since, DHTMLX is our friendly project, Webix components resemble DHTMLX ones, so the views from both libraries can naturally co-exist in one and the same application.

JS file that contains the integration code can be taken from Github while the needed components are downloaded from DHTMLX site.

DHTMLX is comprised from various components each of which can be downloaded separately to minimize the total weight of dependent scripts in the application. Yet, you need to enumerate them all in your document head.

<!-- compulsory: JS file with the code that integrated Webix and DHTMLX -->
<script type="text/javascript" src="./dhtmlx.js"></script>

<!--up to your choice: dependencies for the needed components -->
<script type="text/javascript" src="./dhtmlx/dhtmlxcommon.js"></script>
<script type="text/javascript" src="./dhtmlx/dhtmlxcontainer.js"></script>
<script type="text/javascript" src="./dhtmlx/dhtmlxlayout.js"></script>
<link rel="stylesheet" href="./dhtmlx/dhtmlxlayout.css" type="text/css">

<!--up to your choice: skin for the needed component -->
<link rel="stylesheet" href="./dhtmlx/skins/dhtmlxlayout_dhx_skyblue.css">

The compulsory dependency creates a dhtmlx object on the page. It helps you to set the chosen skin:

dhtmlx.skin = "dhx_skyblue";

Now lets, create some DHTMLX component. Let it be the DHTMLX Layout where we put Webix layout and Webix Datatable.

//creating layout with 3 cells (3U type)
dhxLayout = new dhtmlXLayoutObject("parentId", "3U");

//setting header texts for each cell
dhxLayout.cells("a").setText("Main Page");
dhxLayout.cells("b").setText("Layout");
dhxLayout.cells("c").setText("DataTable");

To put Webix component into DHTMLX layout, use attachWebix() method with a configuration object inside:

//inserting Webix layout into the second cell
dhxLayout.cells("b").attachWebix({
    type:"wide", rows:[
        { template:"1" },
        { type:"wide", cols:[
            { template:"2" },
            { template:"3" }
        ]}
    ]
});

//inserting Webix datatable into the third cell
dhxLayout.cells("c").attachWebix({
    view:"datatable",
    columns:[...],
    data:[...]
});

Related Sample: Integration with DHTMLX Layout

All methods of DHTMLX Layout you can find in DHTMX documentation.


DIY - Custom Integration Pattern

Webix offers a number of ready-made solutions that integrate it with other Javascript libraries and frameworks.

  • integration with structural frameworks BackBoneJS and Angular JS;
  • integration with popular text editors;
  • intergation with charts and planning tools.

However, it's not possible to provide support for all the libraries or tools that exist in big quantities on the Web. If you haven't found the needed solution among built-in ones, you can write your own integration pattern. Webix offers rather an elegant way to do this.

The main thing here is to create a new Webix component that will display the needed tool on the page.

webix.protoUI({
    name:"myCustomName",
    $init:function(config){..},
    ..//other methods
}, webix.ui.view);

This prototype component should inherit from view, a base class for all the ui-related components. A pure view doesn't contain any into and acts as a placeholder for the real component.

It can have any number of properties and methods with two of them being mandatory:

  • name - property that defines view name you will use during initialization;
  • $init(config) - function that is executed on component initialization. It's argument is the component's configuration object.

The following code will then instantiate the above-created object and display it on the page:

webix.ui({
    view:"myCustomName",
    ..//config
});

To learn more about how to create a custom object in Webix, go to the corresponding documentation article.

HipChat Integration

Let's take a HipChat, a popular professional chat solution that has lately got an apportunity to work on the web.

Prototype Component

webix.protoUI({
    name:"hipchat",
    $init:function(config){
        //configuration params
        var params = [
            "anonymous=true",
            "minimal=true",
            "timezone="+config.timezone,
            "welcome_msg="+(config.welcome_msg||"Welcome to Webix Hub Chat")
        ];
        //building full url
        var url=config.url+(config.url.indexOf("?")>0?"&":"?")+params.join("&");
        if (url.indexOf("https://") !== 0)
            url = "https://" + url;

        //loading the hipchat
        var html="<iframe src='"+ url+"'frameborder='0' width='100%' height='100%'>
                    </iframe>";
        this.$view.innerHTML = html;
    },
}, webix.ui.view);

Initializing HipChat on a page:

webix.ui({
    view:"hipchat",  url: "YOUR_GUEST_ACCESS_URL", timezone: "PST"
});

You get the URL value through Hipchat client when you share the room access.

Related Sample: HipChat Integration


Auxiliary Resources

  • Top 10 Helpers You Should Know About
  • Ajax operations
  • Advanced Drag-and-Drop
  • Data Drivers
  • Number formatting methods
  • Date formatting methods
  • Ui.resizearea. Common tips


Intermediate

Top 10 Helpers You Should Know About

webix.ui

This method is used mainly to instantiate Webix component of any complexity level, either it is a control or the complete application layout.

It converts a JSON structure passed into it as parameter to client-side layout objects - this is what Webix is used for:)

webix.ui({ view:"", ... });

Normally, you need one webix.ui() contructor for the whole application while any window or popup needs an extra one as windows lie above page layout.

webix.ui({ view:"window", ... }).show();

More opportunities of using this method are described in the chapter Rebuilding Application Layout.

webix.ready

This method is a cross-browser alternative to the onDocumentReady event and can be used instead of onload() method. Code, which was put inside of it, will be called just after the complete page has parsed, protecting you from potential errors. The thing is optional but we recommend to use it.

It can be used multiple times.

 webix.ready(function(){
     webix.ui({
         container:"box",
         view:"window",
                ...
     });
 })

API reference

webix.bind

An easy way to bind a function to an object (inside bound function, this will point to an object instance).

var t = webix.bind(function(){
    alert(this);
}, "master");

t(); //will alert "master"

webix.copy

This method allows you to make a full (independent) copy of object

var new_obj = webix.copy(source_obj)// full copy

API reference

webix.extend

Adds method and properies of source object to the target object

var target_obj = new webix.ui.toolbar(config);
webix.extend(target_obj, webix.Movable);

Also, it can be used as one more method to get an object copy. In such case, you must specify an empty object as second parameter.

var new_obj = webix.extend({},source_obj) //object based copy

API reference

webix.exec

Next helper allows to execute code string at runtime.

webix.exec(" var t = 2; ");

It is have advantage over eval - variables defined in code will be defined in global scope, the same as in case of normal js code.

API reference

webix.delay

Delay routine. If you need to delay some code from executing at runtime you are at the right place. webix.delay waits for the specified number of milliseconds and then executes the specified code.

webix.delay(webix.animate, webix,[node,animation],10)

API reference

webix.uid

A tool for getting an unique id. ( id is unique per session, not globally unique )

var name = webix.uid();

API reference

webix.event

webix.event is used to attach event handler and webix.eventRemove - to remove it.

var display_handler = webix.event(document.body,'click',function(e){})
...
webix.removeEvent(display_handler);

API reference

webix.html.offset

With the help of this method you can get the position of any html element.

var offset = webix.html.offset(ev.target)

API reference

webix.html.addCss

Two methods implementing css manipulations. webix.html.addCss lets to add css class to element, webix.html.removeCss - removes some defined css class.

webix.html.addCss(this._headbutton, "collapsed");
...
webix.html.removeCss(this._headbutton, "collapsed");

API reference

All Webix helpers are listed in the related of API Reference section.


Intermediate

Ajax operations

Sending Data

Simplest ajax call can be done as:

webix.ajax("some.php", function(text){
    webix.message(text); //show server side response
});

The code above makes an asynchronous GET request to the "some.php" script and shows it response through callback function.

Passing parameters

You can pass extra parameters by including them in the request string:

webix.ajax("some.php?action=info&id=123");

by a separate string with parameters:

webix.ajax().get("some.php", "action=info&id=123");

or by using a separate JSON object:

webix.ajax().get("some.php",{ action:"info", id:123 });

//nested JSON object is possible
webix.ajax().get("some.php",{ action:"info", id:{ row:123, column:"title" }});

In case of object notation, the lib will escape values automatically.

Post mode

Same function can be used to make post requests:

webix.ajax().post("some.php");

Here you can use two methods to provide extra params:

//$_POST["action"]="info", $_POST["id"]="123"
webix.ajax().post("some.php","action=info&id=123");
webix.ajax().post("some.php", { action:"info", id:123});
webix.ajax().post("some.php", { action:"info", id:{ row:123, column:"title" }});

Note that when passing extra parameters into the server script by a separate string/object, you should specify the type of a request (GET or POST).

Sync mode

There are two ways that Ajax can access the server:

  • synchronous (before continuing, script waits for the server back reply).
  • asynchronous (script continues page processing and handles reply as it comes).

By default all request done in async. mode, but there is a sync. alternative

webix.ajax().sync().get("some.php");
webix.ajax().sync().post("some.php");

Callback

For async ajax calls you can define a callback function in the last parameters of the method. For GET and POST requests the syntax is the same.

The callback function takes the following arguments:

  • text - full text of response;
  • data - response data that should be parsed as JSON or XML, whichever is applicable. It features the following methods to get the data:
    • json() - parses data as JSON;
    • xml() - parses data as XML;
    • rawxml() - gets raw XML data;
    • text() - gets response text;
  • XmlHttpRequest - loader object.

GET requests:

webix.ajax("some.php", function(text, data, XmlHttpRequest){
    data = data.json();
    //..
});

webix.ajax().get("some.php", function(text, data, XmlHttpRequest){
    //...
});

POST request:

webix.ajax().post("some.php", function(text, data, XmlHttpRequest){
    //...
});

If you pass parameters to the serverside script, the syntax is as follows:

webix.ajax().get(url, params, callback);
webix.ajax().post(url, params, callback);

It's possible to define two callback methods, one for valid server side response and second for the error response

webix.ajax("some.php",{
    error:function(text, data, XmlHttpRequest){
        alert("error");
    },
    success:function(text, data, XmlHttpRequest){
        alert("success");
    }
});

If you need to trigger multiple callbacks after method finishing, you can define an array of callbacks as last parameter

//GET requests
webix.ajax().get(url, [array of callbacks]);
webix.ajax().get(url, params, [array of callbacks]);

//POST requests
webix.ajax().post(url, [array of callbacks]);
webix.ajax().post(url, params, [array of callbacks]);

In some cases you may need to provide some extra data for callback, which can be done in the next way:

function after_call(text){
     alert("Call: "+this.data+", response: "+text);
};
webix.ajax().get("some.php", after_call, { data:"my ajax"});

Basically, the parameter after callback will be accessible as "this" in the callback method

For sync requests, there is no callback, because there is no need for waiting

var xhr = webix.ajax().sync().get("some.php");
var text = xhr.responseText;

Extra headers

If server side code requires some extra headers you can send them as

webix.ajax().headers({
    "Sent-by":"My Script" //any custom headers can be define in such way
}).get("./data.php");

You can use headers in combination with async, get and post methods

JSON sending

If you are working with web service, you may need to send json content to the server side, it can be done as

webix.ajax().headers({
    "Content-type":"application/json"
}).post("./data.php", JSON.stringify(payload), function(text){
    //optional callback here
});

Incoming Data Parsing

Plain response

In common case you can use text parameter of callback to access the data

webix.ajax("./data.php", function(text){
    webix.message(text);
})

JSON response

While you can use the above code to access raw text response, there is a more neat solution

webix.ajax("some.php", function(text,data){
    //text = '{ some :"abc"}'
    alert(data.json().some); //abc
});

the second parameter of response can provide you with a ready-to-use json object

XML response

Same as above, you can use

webix.ajax("some.php", function(text,xml){
    //text = '<data some='abc'></data>'
    alert(obj.xml().some); //abc
});

If necessary you can access raw xml object by using data.rawxml();

Other formats

CVS

webix.ajax("some.php", function(text,xml){
    var obj = webix.DataDriver.csv.toObject(text,xml);
    alert(obj[0][0]); //row and column indexes
});

JSArray

webix.ajax("some.php", function(text,xml){
    var obj = webix.DataDriver.jsarray.toObject(text,xml);
    alert(obj[0][0]); //row and column indexes
});

HTML

webix.ajax("some.php", function(text,xml){
    //text = '<ul><li some='abc'></ul>'
    var obj = webix.DataDriver.html.toObject(text,xml);
    alert(obj[0].some); //abc
});

Extra parameters

If all above is not enough you can access raw xmlHttpRequest and poll it for additional data

webix.ajax("some.php", function(text,xml, ajax){
    alert(ajax.status);
});

Getting Binary Data

Webix Ajax class offers a pattern for retrieving binary data objects from the server.

It can be done with a dedicated response() method that allows to set responseType directly. Now only "blob" type is fully supported and "document" with some restrictions.

webix.ajax().response("blob").get("patch.zip", function(text, data){
  //data - is a data blob
});

Functionality will not work in IE8-IE9 as these browsers cannot work with blob objects at all.

Promise API for Ajax requests

Webix is integrated with the Promiz.js library, which allows treating the result of asynchronous operations without callbacks.

In other words, any Ajax request performed by Webix returns a promise object that represents the eventual result of this request and can be treated by then() method that is automatically executed when server response arrives.

//"promise" object is returned by either of these methods
var promise = webix.ajax("some.php");
var promise = webix.ajax().get("some.php");
var promise = webix.ajax().post("some.php");

//realdata - data that came from server
promise.then(function(realdata){
    ...
});

See how it is implemented in Webix data loading pattern.

Forming a chain of requests with Promises

webix.ajax("someA.php").then(function(realdataA){
    return webix.ajax("someB.php");
}).then(function(realdataB){
    return webix.ajax("someC.php")
}).then(function(realdataC){
    ...
});

Error handling with Promise objects

then() method can be used to treat errors:

var promise = webix.ajax("some.php")
promise.then(function success(realdata){}, function error(err){});

Additionally, fail() method can be used for error handling:

var promise = webix.ajax("a.php");
...
promise.then(function(realdata){ /*success*/});
promise.fail(function(err){/*error*/});

Or, you can do it in one and the same function:

promise.then(function(realdata){
    //success
}).fail(function(err){
    //error
});

All the methods of the promise object come from the Promiz.js lib and can be found there.

webix.promise interface

Webix offers an interface for working with promise objects - webix.promise - featuring a set of methods that duplicate Promise object methods.

It can be used, for instance, to treat several Ajax requests and perform action when callbacks have been received from all of them:

a = webix.ajax("someA.php");
b = webix.ajax("someB.php");
c = webix.ajax("someC.php");

webix.promise.all(a,b,c).then(function(a,b,c){
    ...
});


Advanced

Advanced Drag-and-Drop

Here we speak about advanced drag-n-drop options and find solutions how to make any elements on the page draggable and control each stage of DnD.

For simple dragging and dropping of items within one and the same component as well as between different views and their instances - study the article about built-in Webix DnD options.

DnD syntax

If you want to make some element on page draggable you can use

webix.DragControl.addDrag(node);

where node - id or html node object ( or object itself )

Related sample: Drag-and-Drop from HTML

If you want to define some area as drop target you can use

webix.DragControl.addDrop(node);

where node - id or html node object ( or object itself ).

Controlled DnD

If you want to control different aspects of dnd process, you can use the above methods but with an extra control parameter ($drag or $drop) with a custom function:

//for dragging
webix.DragControl.addDrag(node, $drag:function(source, target, event){...});
//for dropping
webix.DragControl.addDrop(node, $drop:function(source, target, event){...});

The control function takes three parameters:

  • source - source html object;
  • target - target html object;
  • event - native event.

This is how you can set value of an input by drag-n-drop

webix.DragControl.addDrop("mytext", {
    $drop:function(source, target, event){
        var dnd = webix.DragControl.getContext();
        target.value = dnd.from.getItem(dnd.source[0]).title; // setting source item title as input value
    }
});

Related sample: Drag-and-Drop to HTML

DnD context

Context object of dnd can be accessed as:

var state = webix.DragControl.getContext();

it is also available as parameter in all dnd related events

state = {
    source:[1,2,3], //array of IDs for dragged elements
    target:id, //ID of currently active target item
    from:some_obj, // reference to the source object
    to:some_obj, // reference to the target object
    html:text //optional, custom text, which is rendered as drag-item
}

Set of the drag control methods

There are 6 DnD control event: 3 of them are used for dragged element (addDrag) and 3 - for drop target (addDrop). All these events can be used to define a custom behavior for elements included in current drag-n-drop.

addDrag() related events:

  • onDrag - fires when the elements is dragged;
  • onDragCreate - fires the moment drag has been created;
  • onDragDestroy - fires when drag has been completed;

addDrop() related events:

  • onDragIn - fires when a dragged element enters the drop area (If you want to deny drop area, return false).
  • onDragOut - fires when a dragged elements leaves the drop area.
  • onDrop - fires when you drop the dragged element.
{
  onDragIn:function(source, target, event){ ... },   //drag moves in potential drop area
  onDragOut:function(source, target, event){ ... },  //drag moves out from the drop area
  onDrop:function(source, target, event){ ... },     //drag was released
  onDrag:function(source, target, event){ ... },     //drag is started
  onDragCreate:function(from, event){ ... }     //dnd is started
  onDragDestroy:function:(from, text){ ... } //dnd is finished
}

Where:

  • source - source html object;
  • target - target html object;
  • event - native event;
  • from - control object related to source of dnd;
  • text - content of drag marker.

If any of onDrag handlers redefined - there won't be the default processing of the action, code expects that your custom handler will do all job.

DnD masters

Master is a component object or a hash code of the control methods. It specifies how element will behave itself in the drop target.

If you specify the master, it will answer for the appropriate dnd behavior. If you don't do it, the standard dnd processing will occur.

For the methods, where source and target masters are not provided, you can get them by the getMaster method:

var source_master = webix.DragControl.getMaster(source);
var target_master = webix.DragControl.getMaster(target);

Interface-based DnD

You can make an element draggable by adding one of the 2 appropriate interfaces:

  • webix.Movable

Low level interface. A component which inherits it can be moved by dnd (to learn how to inherit the interface read the Component Copying and Extending article).

  • webix.DragItem

High level interface. Adds dnd ability to component which uses DataStore (to learn how to inherit the interface read the Component Copying and Extending article).

Samples of usage

Drag from custom HTML

<div package="DragPackage" version="1.0" maintainer="Webix Team"
    id="drag_1"
    style='width:150px; height:50px; color:white; background-color:navy;'>
    Drag me into the dataview
</div>
webix.DragControl.addDrag("drag_1");
data1.attachEvent("onBeforeDrop",function(context){
    if (context.from == webix.DragControl){
        this.add({
            Package:context.source.getAttribute("package"),
            Version:context.source.getAttribute("version"),
            Maintainer:context.source.getAttribute("maintainer")
        }), this.getIndexById(context.target || this.getFirstId());
        return false;
    }
    return true;
});

Drag to custom HTML

<div id="data_container2" style="width:400px;height:396px;border:1px solid red;">
    Drop some item here
</div>
webix.DragControl.addDrop("data_container2",{
    onDrop:function(source, target, d, e){
        var context = webix.DragControl.getContext();
        var item = context.from.getItem(context.source[0]);

        var d = document.createElement("DIV");
        d.innerHTML = item.Package+" - "+item.Version;
        target.appendChild(d);
    }
});


Advanced

Data Drivers

There are 6 default data drivers:

  • json
  • xml
  • html
  • csv
  • jsarray
  • excel

Customizing data driver

XML

In case of XML you can redefine

Element Type Code
data tag xpath
webix.DataDriver.xml.records = "/*/item";
configuration tag xpath
webix.DataDriver.xml.config = "/*/config";
child tag tag name
webix.DataDriver.xml.child = "item";

For example to alert the default processing of XML data you can add the following line to your code:

webix.DataDriver.xml.records = "/*/book";
webix.DataDriver.xml.child = "part";

The line above will redefine data parsing logic for all XML sources; if you wish to put apart default and custom logic you need to create a custom XML processor on the base of the default one.

var myxml = webix.DataDriver.myxml = webix.copy(webix.DataDriver.xml);
myxml.records = "/*/book";
myxml.child = "part";

Related sample: Tree: XML Dataset

Child tags can be specified by a function:

var myxml2 = webix.DataDriver.myxml2 = webix.copy(webix.DataDriver.xml);
myxml2.records = "/*/book";
myxml2.child = function(obj){
    if (obj.$level == 1)
        return obj.part;
    if (obj.$level == 2)
        return obj.page;
}

Related sample: Tree: XML Dataset

CSV

It is possible to define row and cell separators:

webix.DataDriver.csv.row = "\n";
webix.DataDriver.csv.cell = ",";

The above line resets processing of all the SCV sources in the application. To avoid this, create a custom CSV format:

var myscv = webix.DataDriver.myscv = webix.copy(webix.DataDriver.scv);
csv.row = "\n";
csv.cell = ",";

HTML

You can redefine which tag in html will be processed as data tag:

webix.DataDriver.html.tag = "LI";

The above line resets processing of all the HTML sources in the application. To avoid this, create a custom HTML format:

var myhtml = webix.DataDriver.myhtml = webix.copy(webix.DataDriver.html);
html.tag = "LI";

JSON

You can redefine which object propery stores sub-items ( used for hierarchical dataset, like one for tree, treegrid, grouplist etc. )

webix.DataDriver.json.child = "data";

The above line resets processing of all the JSON sources in the application. To avoid this, create a custom JSON format:

var myjson = webix.DataDriver.json = webix.copy(webix.DataDriver.json);
myjson.child = "data";

Methods of data driver

//convert string to object
var data = driver.toObject(data);
//return array of all records in datasource
var records = driver.getRecords(data)
//return single data object
var data = driver.getDetails(records[0]);

XML

//run xpath
var elements = driver.xpath("/some/xpath", data);
//convert xml tag to json object
var obj = driver.tagToObject(elements[0]);
//convert string to js data-types, numbers and booleans
obj = driver.assignTypes(obj);

Creating new data driver

In addition to built in data types, it possible to define custom ones

The structure of driver is the following:

Webix.DataDriver.some={ //some - the name of the type
    toObject:function(text,xml){
                ...
        return text;
    },
    getRecords:function(data){
                var result = [];
                ...
        return result;
    },
    getDetails:function(data){
                var result = {}
                ...
        return result;
    },
    getInfo:function(data){
        return {
         _size:some,
         _from:other
        };
    }
};

You can check the structure of the data driver in Webix sourse code (webix_debug.js)

For a start, we have some data that we want to use as a new data type. The first thing we need to make with this data - conversion into an intermediate object (an object that will be used as an input parameter in the other functions).

1 . So, our first step - toObject(text, xml) function. The function is called after data loading or directly in the parse method and returns the intermediate data object.

  • text - incoming data.
  • xml - xml object (for xml loading scenario. For other data types can be ignored).

2 . Then, we form an array of records using data from our intermediate object - getRecords(data) function.

  • data - the intermediate object from the previous step.

Having an array of records we need to specify a set of properties for each single record - the third step - getDetails(data).

  • data - an element of the array from the previous step.

3 . The last action has sense just for dynamic data loading scenarios. It's a function that gets count of data and position at which new data needs to be inserted.

4 . The fourth step - getInfo(data). The function returns count of data and the appropriate position mentioned above: '0' if a value is unknown or unnecessary.

  • data - the intermediate object from step 1

So, making these four or even three steps you can specify any data type and then use it while developing.

Creating new data driver based on an existing one

Creating a completely new driver is not the most common task, but a user may need to alter the processing logic of some built-in driver.

It can be done with the help of Webix extending pattern that allows to extend any JSON object:

webix.DataDriver.custom = webix.extend({
    records:"/data/items/item",
    getDetails:function(obj){
        var res = {};
        var cells = this.xpath(obj, "cell");
        for (var i = 0; i < cells.length; i++)
            res[cells[i].getAttribute("id")] = this.nodeValue(cells[i]);
        return res;
    }
}, webix.DataDriver.xml);

Related sample: Loading from custom XML


Intermediate

Number formatting methods

There are 2 predefined methods for number formatting:

Localization

var string1 = webix.i18n.numberFormat("123.45");
var string2 = webix.i18n.intFormat("123.45")
var string3 = webix.i18n.priceFormat("123.45");

They will format data according to rules stated in the current locale.

Applying locales within component:

//datatable
{ header:"LongDate", width:170,  id:"start", format:webix.i18n.numberFormat }

//other components
template:function(obj) {return webix.i18n.numberFormat(obj.start); }

Dive into Date and Number localization article.

Custom Formatting

If you need to format number with custom formatting rules you can use methods in the Number class that offers two methods: format and numToStr.

Here you need to specify rules right in a data component.

var string1 = webix.Number.format("123.45",{
    groupDelimiter:",",
    groupSize:3,
    decimalDelimiter:".",
    decimalSize:2
});

Applying format within a component:

//datatable
{ header:"LongDate", width:170,  id:"votes", format:webix.Number.numToStr({
                        groupDelimiter:"",
                        groupSize:0,
                        decimalDelimiter:",",
                        decimalSize:5})
}

//other components
template:function(obj) {
    return webix.Number.numToStr(obj.votes, {
        groupDelimiter:"",
        groupSize:0,
        decimalDelimiter:",",
        decimalSize:5
    });
}

Related sample: Using number templates


Intermediate

Date formatting methods

Formatting and parsing

There 8 predefined methods for date formatting, which can be used to convert dates to strings and strings to dates

Convert dates to strings

var str1 = webix.i18n.dateFormatStr(date_obj);  //date
var str2 = webix.i18n.longDateFormatStr(date_obj);//long date representation
var str3 = webix.i18n.timeFormatStr(date_obj);  //time
var str4 = webix.i18n.fullDateFormatStr(date_obj);//date + time
var str5 = webix.i18n.parseFormatStr(date_obj); //used for date serialization

Convert strings to dates

var date1 = webix.i18n.dateFormatDate(string);  //date
var date2 = webix.i18n.longDateFormatDate(string);//long date representation
var date3 = webix.i18n.timeFormatDate(string);  //time
var date4 = webix.i18n.fullDateFormatDate(string);//date + time
var date5 = webix.i18n.parseFormatDate(string); //used for date parsing

Formats can be defined by locales to adapt numbers and dates to the target location.

If necessary you can create your own conversion methods

Custom date convert

var format = webix.Date.dateToStr("%Y.%m");
var string = format(new Date()); //2012.05

var parser = webix.Date.strToDate("%Y.%m");
var date = parser("2012.05");

Supported format options
  • %d - the day as a number with a leading zero ( 01 to 31 );
  • %j - the day as a number without a leading zero ( 1 to 31 );
  • %D - the day as an abbreviation ( Sun to Sat );
  • %l - the day as a full name ( Sunday to Saturday );
  • %m - the month as a number with a leading zero ( 01 to 12 );
  • %n - the month as a number without a leading zero ( 1 to 12);
  • %M - the month as an abbreviation ( Jan to Dec );
  • %F - the month as a full name ( January to December );
  • %y - the year as a two-digit number ( 00 to 99 );
  • %Y - the year as a four-digit number ( 1900–9999 );
  • %h - the hour based on the 12-hour clock with a leading zero ( 00 to 11 );
  • %g - the hour based on the 12-hour clock ( 0 to 11 );
  • %H - the hour based on the 24-hour clock with a leading zero ( 00 to 23 );
  • %G - the hour based on the 24-hour clock ( 0 to 23 );
  • %i - the minute as a number with a leading zero ( 00 to 59 );
  • %s - the second as a number without a leading zero ( 00 to 59 );
  • %a - displays am (for times from midnight until noon) and pm (for times from noon until midnight);
  • %A - displays AM (for times from midnight until noon) and PM (for times from noon until midnight);
  • %c - displays date and time in the ISO 8601 date format (e.g. 2015-10-04T05:04:09)

For instance, "%d-%F-%Y,%D" will display the date as 11-September-2012, Tue.

strings like 20120502, where there are no separators between numbers, can't be parsed as dates


Ui.resizearea. Common tips

Limiting the area available for resizing

By default, the area available for resizing is the whole viewport. To limit the area, you should initialize the component in a container with style='position:relative'

<div id='mydiv' style='position:relative;width:600px; height:300px;border:1px solid;'></div>
webix.event(document.getElementById("mydiv"),"mousedown",function(e){
            var resizeStick = new webix.ui.resizearea({
                    container:"mydiv",
                    dir:"y",
                    eventPos:e.pageY,
                    start:e.pageY-webix.html.offset(webix.toNode("mydiv")).y
            });
})

DIVs created while resizing

While moving a resizearea object, 3 DIVs are created:

Table 1 Vertical resizing
Container Description
<div class="webix_resize_area"></div>
 the area available for resizing
<div class="webix_resize_handle_y"></div>
 the movable container
<div class="webix_resize_origin_y"></div>
 the initial fixed container
Table 1 Horizontal resizing
Container Description
<div class="webix_resize_area"></div>
 the area available for resizing
<div class="webix_resize_handle_x"></div>
 the movable container
<div class="webix_resize_origin_x"></div>
 the initial fixed container


Start

API Reference

Layouts

ui.accordion | a container control that presents multiple horizontal or vertical panes
ui.accordionitem | a singular pane of the accordion component
ui.carousel | a container control that provides continuous, circular navigation through a set of pictorial content blocks. One block is visible at a time
ui.form | a form that supports an extended set of elements
ui.headerlayout | a horizontal or vertical layout with the header(s)
ui.layout | a vertical or horizontal layout without the headers
ui.multiview | a container control that keeps a set of views and displays one view at a time
ui.portlet | a vertical or horizontal layout component that can contain other components
ui.tabview | a container control with a navigation tab panel that keeps a set of views and displays one view at a time
ui.toolbar | a horizontal toolbar
Data Components
ui.chart | a tool for creating various charts
ui.datatable | an editable table that can easily display huge data sets
ui.dataview | a control for displaying data in a tabular format
ui.grouplist | a vertical list of items grouped into sections by some category
ui.list | a regular list of items
ui.organogram | an organizational chart
ui.property | a structured table of 2 columns that presents 'name:value' pairs for a list of properties
ui.rangechart | a chart for detailed displaying of data contained a frame
ui.tree | a hierarchical structure of nodes
ui.treemap | a hierarchical structure of nodes
ui.treetable | a control for presenting tree in a grid cell
ui.unitlist | a vertical list of items united into groups according a template
Context Components
ui.context | a pop-up window displayed on firing the 'contextMenu' event (mouse right-clicks)
ui.contextmenu | a context menu
ui.datasuggest | a dataview-based suggest control
ui.gridsuggest | a datatable-based suggest control
ui.menu | a menu of individually selectable items
ui.popup | a static popup window
ui.sidemenu | a side panel menu
ui.submenu | a sub-menu
ui.suggest | a suggest control
ui.window | a movable popup window
HTML-oriented Components
ui.iframe | a view with the IFRAME element inside it
ui.htmlform | a control for integration with an HTML form
ui.scrollview | a container with scrolls
ui.template | a view with some HTML content inside
Form Controls
ui.button | a clickable button
ui.checkbox | a two-state check box
ui.colorpicker | a control for selecting a color from a swatch palette
ui.combo | an editable combo box
ui.counter | a spin box, aka an up-down control
ui.datepicker | a control that allows the user to select a date
ui.fieldset | a wrapper which renders an HTML fieldset
ui.icon | a static picture of an icon
ui.label | a non-editable text control
ui.multicombo | a multi-combo control
ui.multiselect | a multi-select control
ui.multitext | a multi-text control
ui.radio | a radio button
ui.rangeslider | a slider for selecting a range of numeric values
ui.richselect | a non-editable combo box
ui.search | a text edit field with the search icon in front
ui.segmented | a holistic panel that contains multiple buttons (two or more)
ui.select | a single-selection drop-down list box
ui.slider | a slider for selecting numeric values
ui.tabbar | a panel that contains multiple clickable items
ui.text | an one-line, editable text field with the label inside it
ui.textarea | a multiline, editable text field
ui.toggle | a two-state button
Auxiliary Components
ui.barcode | a machine-readable representation of data values
ui.calendar | a single-month calendar that allows users to select dates and move to the next/previous month
ui.colorboard | a color palette
ui.pager | page navigation controls
ui.resizer | a draggable border in layout
ui.spacer | a bordeless empty view
ui.spreadsheet | a component for creating tables with extended functionality
ui.tooltip | a static text that is rendered in the absolutely positioned container
ui.video | a video player component
Helpers
common helpers | helpers implemented in webix. and webix.ui
ajax | ajax operations (data loading, server side events)
clipbuffer | interface for clipboard
color | color transformation helpers
csv | csv serialzation and parsing
editors | set of editing tools
env | set of flags which describes current environment
history | implements history tracking
html | set of html|dom helpers
i18n | internationalization, number and date formatting methods
locale | localization strings
markup | implements loading from html
promise | interface for working with promise objects
rules | validation rules
storage.cookie | iterface for storing data in cookies
storage.local | interface for storing data in local storage
storage.session | interface for storing data in session storage
Other
Mixins building blocks for existing and new components


common helpers

Just a set of common helpers.

Methods
alert | creates an alert box
animate | animate some hmtl area
attachEvent |
bind | binds a function to an object
blockEvent |
callEvent |
clone | makes a shallow copy of an object
confirm | creates a confirm box
copy | makes a deep copy of an object
delay | delays a code from executing at runtime. The method waits for the specified number of milliseconds and then executes the specified code
detachEvent |
dp | returns dataprocessor object
editStop | closes active editor in all webix components
event | attaches an event handler to an HTML element
eventRemove | removes an event handler from an HTML element
exec | executes a code string at runtime
extend | merges the contents of 2 objects together into the first object
hasEvent |
isArray | checks whether the passed value is an array
isDate | checks whether the passed value is a date object
isUndefined | checks whether the passed value is undefined
jsonp | issues jsonP call
mapEvent |
message | shows a message box
modalbox | creates a modal box
once | allows to call code only once
proto | merges the contents of several objects together into the first object
protoUI | merges the contents of several objects together into the first object and creates from it a new view
proxy | creates proxy object
ready | event handler called just after the page has been completely parsed.
remote | mapping for server side API
require | includes and caches a Javascript module
send | sends an HTTP request to the server (emulates submitting a form)
single | implements the singleton pattern
template | converts string to templating function
toArray | extends the passed array with the methods of the PowerArray library
toExcel | exports data of a data component to an Excel document
toFunctor | converts a string to a function
toNode | returns an HTML node object
toPDF | exports data of a data component to a PDF file
toPNG | exports data of a component to a PNG file
type | defines new rendering type for the component
ui | the object constructor. Creates a new instance of the specified view
uid | returns a unique id
unblockEvent |
wrap | 'wraps' a function around the original function
Events
onClick | fires when the user clicks on an element
onRotate | occurs on screen rotating
Other
cdn | returns Webix cdn location
codebase | returns the path to the 'codebase' folder
name | returns the name of the component (by default, 'Core')
version | returns the current version of the library
scrollSize | returns the width of the scroll bar
zIndexBase | maximum used z-index


Methods

alert | creates an alert box
animate | animate some hmtl area
attachEvent |
bind | binds a function to an object
blockEvent |
callEvent |
clone | makes a shallow copy of an object
confirm | creates a confirm box
copy | makes a deep copy of an object
delay | delays a code from executing at runtime. The method waits for the specified number of milliseconds and then executes the specified code
detachEvent |
dp | returns dataprocessor object
editStop | closes active editor in all webix components
event | attaches an event handler to an HTML element
eventRemove | removes an event handler from an HTML element
exec | executes a code string at runtime
extend | merges the contents of 2 objects together into the first object
hasEvent |
isArray | checks whether the passed value is an array
isDate | checks whether the passed value is a date object
isUndefined | checks whether the passed value is undefined
jsonp | issues jsonP call
mapEvent |
message | shows a message box
modalbox | creates a modal box
once | allows to call code only once
proto | merges the contents of several objects together into the first object
protoUI | merges the contents of several objects together into the first object and creates from it a new view
proxy | creates proxy object
ready | event handler called just after the page has been completely parsed.
remote | mapping for server side API
require | includes and caches a Javascript module
send | sends an HTTP request to the server (emulates submitting a form)
single | implements the singleton pattern
template | converts string to templating function
toArray | extends the passed array with the methods of the PowerArray library
toExcel | exports data of a data component to an Excel document
toFunctor | converts a string to a function
toNode | returns an HTML node object
toPDF | exports data of a data component to a PDF file
toPNG | exports data of a component to a PNG file
type | defines new rendering type for the component
ui | the object constructor. Creates a new instance of the specified view
uid | returns a unique id
unblockEvent |
wrap | 'wraps' a function around the original function


alert

creates an alert box

HTMLElement alert(string text,function callback);

Parameters

text | string | the box text
callback | function | the callback function

Returns

HTMLElement the alert box

Example

webix.alert("Test alert", function(result){
    webix.alert({
        title:"Custom title",
        ok:"Custom text",
        text:"Result: "+result
   })
})
});

Details

The method can be used in 2 ways:

  • Basic or short form (contains just the box text - implicit usage of the parameter 'text'. The other parameters take default values).
  • Extended form (contains several available parameters. Non-specified parameters take default values).

Please note, created boxes:

  • Not modal (don't prevent the workflow on the application parent window).
  • Exist in the only copy (when a new window appears - the previous one disappears).

Extended initialization

In the extended form, the method takes as a parameter an object with box parameters. The parameters are:

  • title - (string) the text of the header
  • text - (string) the text of the window body
  • ok - (string) the text of the 'Ok' button
  • cancel - (string) the text of the 'Cancel' button
  • type - ('alert-warning' or 'alert-error') the alert type: warning or error
  • callback - (function) contains a code that will be called when the user clicks on the button. As a parameter takes the true/false value - the alert result status
webix.alert({
    title: "Close",
    text: "You can't close this window!",
    type:"alert-error"
})

See also

  • api
    • confirm
  • samples
    • Alert message
  • articles
    • Creating Message Boxes


animate

animate some hmtl area

void animate(HTMLElement html_element,object animation);

Parameters

html_element | HTMLElement | html object ( or html id ) which will be animated
animation | object | configuration of animation

Example

webix.animate("some_div", { type: "flip" });

Details

Method is not purposed for direct calls. It is called by multiview or some other components when necessary.

Configuration

  • type: {string} flip, slide, flipback, fade, show
  • direction: {string} right, left, top, bottom
  • subtype: {string }out, in (for slide), horizontal, vertical (for flip)
  • x: {int} slide value for X
  • y: {int} slide value for Y
  • duration: {int} transition duration in ms
  • delay: {int} delay before animation in ms
  • timing: {string} transition timing function
  • callback: {code} code to call after animation end
  • master: {obj} object, which will be accessible by "this" in the callback method


attachEvent

attaches the handler to an inner event of the component (allows behaviour customizations)

id attachEvent(string type,function functor, [string/number id] );

Parameters

type | string | the event name, case-insensitive
functor | function | the function object or name
id | string/number | the event id

Returns

id the id of the attached event handler

Example

dtable.attachEvent("onAfterLoad",function(){
    this.select(2);
})

- ...mixed... function the callback receives different set of parameters for different events. Check the documentation of the related events. - result boolean returning false will block the default behaviour (works not for all events, check the details below).
Details

How the handler is provided

You can use the method with an inline function or provide just the global function reference. In the second case, be sure that the function is visible from the calling point.

function doTask(){ ... };
dtable.attachEvent("onBeforeLoad", doTask); //uses the reference
dtable.attachEvent("onBeforeLoad", "doTask"); //will work as well, but not recommended

The handler id

The last parameter allows you to define the id of the attached handler. If it was not specified, some unique value will be assigned as the id. The only purpose of such id - detaching the handler from an event (in most cases you don't need to care about the handler's id).

Callback

Check the related documentation to get the full list of parameters. The amount and meaning will vary for different events.

The value which is returned by an event can change behavior of component. Returning true or nothing will be considered as the positive signal, while returning false will be considered as a signal to stop the current activity.

dtable.attachEvent("onBeforeSelect", function(id){
    if (id == 123)
        return false; //blocks selection of a specific element
});

Multiple handlers

You can attach multiple handlers to one and the same event and they won't overwrite each other. If some of handlers will return false - the related operation will be blocked.

Event handlers are processed in the same order as they were attached.

See also

  • api
    • EventSystem,
    • detachEvent,
    • hasEvent
    • callEvent
  • samples
    • Chart: Events
  • articles
    • Event Handling


bind

binds a function to an object

function bind(function code,object master);

Parameters

code | function | the function that will be bound
master | object | the object which the function will be bound to

Returns

function the bound function

Example

var grid = webix.ui({
    view:"datatable",
    on:{
        "onStoreUpdated":webix.bind(this.render, this)
    }
});
//'this' refers to a datatable object

Details

Inside the function the this keyword becomes a reference to the object's scope.

Function and component binding works as well during attaching the function with an attachEvent method:

grid.attachEvent("onStoreUpdated", webix.bind(this.render, this));
//'this' is still a grid object since attachEvent() is called from it


blockEvent

temporarily blocks triggering of ALL events of the calling object

void blockEvent();

Example

$$('list').blockEvent();
$$('list').add({ text:'abc'}); //will not trigger list events
$$('list').unblockEvent();

Details

Use the command with care, many actions in components are linked through events.

The most common use-case - preventing a component from repainting with each small operation:

//will repaint component 3 times

$$('list').add({ text:'111'});
$$('list').add({ text:'222'});
$$('list').add({ text:'333'});

//will repaint component only once (onStoreUpdated of List DataStore is blocked)
$$('list').data.blockEvent();
$$('list').add({ text:'111'});
$$('list').add({ text:'222'});
$$('list').add({ text:'333'});
$$('list').data.unblockEvent();
$$('list').refresh();

See also

  • api
    • EventSystem,
    • unblockEvent
  • articles
    • Event Handling


callEvent

calls an inner event

boolean callEvent(string name,array params);

Parameters

name | string | the event name, case-insensitive
params | array | an array of the event related data

Returns

boolean false, if some of the event handlers returns false. Otherwise, true

Example

//invokes triggering handlers of the 'onResize' event
var check = dtable.callEvent("onResize", [...]);

Details

Normally, events are called automatically and you needn't to use this method.

See also

  • api
    • EventSystem,
    • detachEvent,
    • hasEvent
  • articles
    • Event Handling


clone

makes a shallow copy of an object

object clone(object source);

Parameters

source object the source (passed) object

Returns

object the copy of the source object

Example

var obj1 = {name:"flower", type:"rose", colors: ['red','pink','white','yellow']  }
var obj2 = webix.clone(obj1);

obj1.type = 'tulip';

obj1.type // -> 'tulip'
obj2.type // -> 'tulip'

obj2.colors // -> ['red'] Warning! It's a shallow copy

See also

  • api
    • copy, extend


confirm

creates a confirm box

HTMLElement confirm(string text,function callback);

Parameters

text | string | the box text
callback | function | the callback function

Returns

HTMLElement the confirm box

Example

webix.confirm("Test confirm", function(result){
    webix.confirm({
        title:"Custom title",
        ok:"Yes",
        cancel:"No",
        text:"Result: "+result,
    });
});

Details

The method can be used in 2 ways:

  • Basic or short form (contains just the box text - implicit usage of the parameter 'text'. The other parameters take default values).
  • Extended form (contains several available parameters. Non-specified parameters take default values).

Please note, created boxes:

  • Not modal (don't prevent the workflow on the application parent window).
  • Exist in the only copy (when a new window appears - the previous one disappears).

Extended initialization

In the extended form, the method takes as a parameter an object with box parameters. The parameters are:

  • title - (string) the text of the header
  • text - (string) the box text
  • ok - (string) the text of the 'Ok' button
  • cancel - (string) the text of the 'Cancel' button
  • type - ('confirm-warning' or 'confirm-error') the confirm type: warning or error
  • callback - (function) contains a code that will be called when the user clicks on the button. As a parameter takes the true/false value - the alert result status
webix.alert({
    title: "Close",
    text: "You can't close this window!",
    type:"confirm-error"
})

See also

  • api
    • alert
  • samples
    • Confirm message
  • articles
    • Creating Message Boxes


copy

makes a deep copy of an object

object copy(object source);

Parameters

source object the source (passed) object

Returns

object the copy of the source object

Example

var obj1 = {name:"flower", type:"rose", colors: ['red','pink','white','yellow']  }
var obj2 = webix.copy(obj1);

obj1.type = 'tulip';

obj1.type // -> 'tulip'
obj2.type // -> 'rose'

obj2.colors // -> ['red','pink','white','yellow']

Details

Doesn't work for structures with inner loops.

See also

  • api
    • clone, extend


delay

delays a code from executing at runtime. The method waits for the specified number of milliseconds and then executes the specified code

number delay(function code, [object owner,array params,number delay] );

Parameters

code | function | the code you want to delay
owner | object | an object that the this keyword refers to
params | array | an array of callback parameters
delay | number | the delay in milisecods. By default, 1 millisecond

Returns

number the timeout id (can be used by the clearTimeout() method )

Example

webix.delay(function(){
    do_something();
});
//or
webix.delay(function(a, b){
    //a == 1
    //b == "abc"
    //this == dtable
    do_something();
}, dtable, [1, "abc"], 100);


detachEvent

detaches a handler from an event (which was attached before by the attachEvent method)

void detachEvent(id id);

Parameters

id id the event id (the result of the attachEvent operation)

Example

var myEvent = $$("mylist").attachEvent("onItemClick", function (){
    ...//event handler code
});
...
$$("mylist").detachEvent(myEvent);

See also

  • api
    • EventSystem,
    • attachEvent,
    • hasEvent
    • callEvent
  • articles
    • Event Handling


dp

returns dataprocessor object

object dp(string name);

Parameters

name string id of view, or view object

Returns

object dataprocessor object

Example

var dp1 = webix.dp("myview");
var dp2 = webix.dp(dtable);

var dp3 = webix.dp({
    master:$$('myview');
});

Details

If there wasn't a dataprocessor for the component - a new one will be created.


editStop

closes active editor in all webix components

void editStop();

Example

webix.editStop();

Details

still can be stopped through edit related events of components


event

attaches an event handler to an HTML element

id event(HTMLElement/string node,string event,function handler, [object context] );

Parameters

node | HTMLElement/string | the HTML node or its id
event | string | the name of an HTML event (without the 'on' prefix)
handler | function | the event handler
context | object | context object with additional setting (described below)

Returns

id event handler ID (can be used by the eventRemove() method)

Example

// adds a handler for the 'onclick' event of some HTML element
webix.event("divId", "click", function(e){
    //e - a native event object
    do_something();
});

// adds a handler for the 'onKeyUp' event of the List component
webix.event($$("list").getNode(), "keyup", function(e){
    //e - a native event object
    do_something();
}, {master:$$("list")});

Details

The optional context parameter may include:

  • master - (object) an object that the this keyword refers to;
  • capture - (boolean) a flag that indicates on which stage (capture or bubble) event should be captured. false by default;
  • id - (string) event handler ID (if not set, will be generated automatically).

See also

  • api
    • eventRemove
  • samples
    • Sizing and events
  • articles
    • Event Handling


eventRemove

removes an event handler from an HTML element

void eventRemove(id id);

Parameters

id id the id of an event handler

Example

var eventId = webix.event("divId", "click", function(e){
        do_something();
});

webix.eventRemove(eventId);

See also

  • api
    • event


exec

executes a code string at runtime

void exec(string code);

Parameters

code string the code that needs executing

Example

webix.exec("myobj = 123");
alert(myobj);


extend

merges the contents of 2 objects together into the first object

object extend(object target,object source,boolean overwrite);

Parameters

target | object | the object to extend. It receives the new properties
source | object | an object that contains properties to merge in
overwrite | boolean | if the value is true, the same properties will be overwritten by the values of the source object

Returns

object the target object with the new properties

Example

var obj1 = {name:"flower", type:"rose", colors: ['red','pink','white','yellow']}
var obj2 = {name:"flower", type:"tulip" }

webix.extend(obj2,obj1);
// -> obj2 = {name:"flower", type:"tulip", colors: ['red','pink','white','yellow']}

obj2.type = 'camomile';
obj2.type // -> 'camomile'
obj1.type // -> 'rose'

obj2.colors[0] = 'blue';
obj2.colors // -> ['blue','pink','white','yellow']
obj1.colors // -> ['blue','pink','white','yellow']

obj1 = {name:"flower", type:"rose", colors: ['red','pink','white','yellow']  }
obj2 = {name:"flower", type:"tulip" }

webix.extend(obj2,obj1, true);
// -> obj2 = {name:"flower", type:"rose", colors: ['red','pink','white','yellow']}

See also

  • api
    • clone, copy


hasEvent

checks whether the component has the specified event

boolean hasEvent(string name);

Parameters

name string the event name, case-insensitive

Returns

boolean true, if at least one handler was attached to the specified event. Otherwise, false

Example

var is_exit = mydata.hasEvent('onBeforeSelect');

Details

The method checks whether some handler was attached to the object, and doesn't check whether that object has such event

See also

  • api
    • EventSystem,
    • detachEvent,
    • attachEvent
    • callEvent
  • articles
    • Event Handling
    • Events Handling with DataTable


isArray

checks whether the passed value is an array

boolean isArray(any check);

Parameters

check any the value to check

Returns

boolean true, if the passed value is an array

Example

if (webix.isArray(value)){
    do_something();
}


isDate

checks whether the passed value is a date object

boolean isDate(any check);

Parameters

check any the value to check

Returns

boolean true, if the passed value is a date object

Example

if (webix.isDate(value)){
    do_something();
}


isUndefined

checks whether the passed value is undefined

boolean isUndefined(any check);

Parameters

check any the value to check

Returns

boolean true, if the passed value is undefined

Example

if (webix.isUndefined(obj)){
    do_something();
}


jsonp

issues jsonP call

void jsonp(string url, [object params,function callback,object master] );

Parameters

url | string | server side feed
params | object | hash of parameters which will be included in jsonp url
callback | function | callback method
master | object | value of "this" in callback

Example

//minimal call
webix.jsonp("http://some.com/some.php", function(data){
   ... do something...
})

//call with extra parameters
webix.jsonp("http://some.com/some.php", {
    user:12,
    action:"fetch"
}, function(data){
   ... do something...
})

- data object value returned by server
Details

http://en.wikipedia.org/wiki/JSONP


mapEvent

routes events from one object to another

void mapEvent(object map);

Parameters

map object the hash of event-object relations

Example

// As a result, when the second list is clicked, the function that was initially
// attached only to the first one, will be executed for it as well:
webix.ui({
    rows:[
        { view:"list", id:"list1", data:list_data, on:{
            onItemClick:getItemValue
        }},
        { view:"list", id:"list2", data:list_data}
    ]
});

//here event name should be in the lower case
$$("list2").mapEvent({onitemclick:$$("list1")});

//handler
function getItemValue(id){
    var obj = this.$eventSource || this;
    var value = obj.getItem(id).value;
    webix.message("List: "+obj.config.id+", clicked: "+id);

}

Details

Note that if you need to access the object for which the handler is called at the moment, you can do it via $eventSource property while this will always point to the object for which the handler is attached initially

See also

  • api
    • EventSystem
  • articles
    • Event Handling


message

shows a message box

void message(string text);

Parameters

text string the text to show

Example

webix.message("Some message");

Details

Supports many skins and configurations, check jsMessage for more details.


modalbox

creates a modal box

HTMLElement modalbox(string text,function callback);

Parameters

text | string | the box text
callback | function | the callback function

Returns

HTMLElement the modal box

Example

webix.modalbox({
        title:"Custom title",
        buttons:["Yes", "No", "Maybe"],
        width:"500px",
        text:"Any html content here"
    });

Details

The method can be used in 2 ways:

  • Basic or short form (contains just the box text - implicit usage of the parameter 'text'. The other parameters take default values).
  • Extended form (contains several available parameters. Non-specified parameters take default values).

Please note, created boxes:

  • Don't prevent the workflow on the application parent window

Extended initialization

In the extended form, the method takes as a parameter an object with box parameters. The parameters are:

  • title - (string) the text of the header
  • text - (string) the box text
  • buttons - (array) array of button labels
  • callback - (function) contains a code that will be called when the user clicks on the button. As a parameter takes the button index value as the alert result status.
webix.modalbox({
    title:"Custom title",
    buttons:["Yes", "No", "Maybe"],
    callback: function(result){
        switch(result){
        case 0:
            //statement
            break;
        case 1:
            //statement
            break;
        ...
        }
});

See also

  • api
    • alert
    • confirm
  • samples
    • Modal box
  • articles
    • Creating Message Boxes


once

allows to call code only once

void once(function code);

Parameters

code function code to execute

Example

datatable.attachEvent("onItemClick", webix.once(function(id){
    webix.message(id); //Will be shown only for the first click;
});


proto

merges the contents of several objects together into the first object

object proto(object target, [object mixin1,object mixinN] );

Parameters

target | object | the object to extend. It receives the new properties
mixin1 | object | an object that contains properties to merge in
mixinN | object | another objects that contains properties to merge in

Returns

object the target object with the new properties

Example

var code = webix.proto(myobject, webix.MouseEvents);

Details

The method is similar to extend.
The only difference between methods lies in the number of objects to merge: in case of the extend method you deal with one source object, in case of the proto method you have the unlimited number of the source objects.

See also

  • api
    • extend, copy, clone


protoUI

merges the contents of several objects together into the first object and creates from it a new view

object protoUI(object target,object view,object mixin1,object mixinN);

Parameters

target | object | the object to extend. It receives the new properties
view | object | the view object that a new view is inherited from
mixin1 | object | an object that contains properties to merge in
mixinN | object | another objects that contains properties to merge in

Returns

object the new view (target object) with the new properties

Example

webix.protoUI({
    name:"mylist"
}, webix.ui.list, webix.ActiveContent);

var list = webix.ui({
    view:"mylist"
});

Details

The method is similar to proto. The only difference is that protoUI creates a new view based on another view and proto doesn't. As for the rest, it's the same.

See also

  • api
    • extend, copy, clone, proto


proxy

creates proxy object

object proxy(string type,string source);

Parameters

type | string | type of proxy object
source | string | url or datasource name

Returns

object proxy object

Example

var proxy = webix.proxy("cache", "users/data.php");
mytable.load(proxy);

Details

Possible types of proxy objects are:

  • offline
  • cache
  • local
  • connector
  • rest
  • post
  • sync
  • indexdb
  • faye
  • binary
  • json

More information about each proxy can be found in the related article.

See also

  • samples
    • Datatable: REST
  • articles
    • Webix Proxy Objects


ready

event handler called just after the page has been completely parsed.

void ready(function code);

Parameters

code function event handler code

Example

webix.ready(function () {
  webix.ui({
    container: "box",
    view: "window",
    ...
  });
  ...
});

Details

This method is an alternative to the onDocumentReady event and can be used instead of the onload() method. The event handler code is called just after the page has been completely parsed, protecting you from potential errors. Placing your code in webix.ready() is optional but we strongly encourage using it.

Can be used multiple times.

See also

  • api
    • ready


remote

mapping for server side API

void remote();


require

includes and caches a Javascript module

void require(string url);

Parameters

url string the path to a Javascript file

Example

webix.require("extras.js");

Details

The method is called only once. If you try to include the same module the second time - the command will be ignored.


send

sends an HTTP request to the server (emulates submitting a form)

void send(string url,object values,string method,string target);

Parameters

url | string | the url of a file to load
values | object | the hash of parameters that need sending to the server
method | string | the type of request: "GET" or "POST". By default, "POST";
target | string | the page that will be shown after function execution: "_self" or "_blank". "_self" by default

Example

webix.send("page.php",{record:123}, "GET");

Details

One of the possible use cases for this method is various kinds of export:

webix.send(url, { grid_xml : encodeURI(xml) }, null, "_blank");


single

implements the singleton pattern

function single(function source);

Parameters

source function the constructor function

Returns

function the constructor function

Example

var myobj = function(){ ... };
myobj = webix.single(myobj);

var t1 = new myobj();
var t2 = new myobj(); //t2 === t1


template

converts string to templating function

function template(string template);

Parameters

template string template string

Returns

function templating function

Example

var line = webix.template("Some #name# code");
var text = line({ name:"Webix" });

Details

While this method is rarely used directly, the same templating logic is used during configuration of data components look.

See also

  • articles
    • Data Templates


toArray

extends the passed array with the methods of the PowerArray library

array toArray(array array);

Parameters

array array an array

Returns

array an array with the extra methods

Example

var arr1 = webix.toArray([1,2,3]);
var arr2 = webix.toArray();

See also

  • api
    • PowerArray, toFunctor, toNode


toExcel

exports data of a data component to an Excel document

void toExcel(string/object id,object options);

Parameters

id | string/object | the exported view or its id
options | object | optional, a set of configuration options that define what data will be displayed in the Excel file

Example

webix.toExcel($$("mylist"));

See also

  • api
    • toPNG
  • samples
    • Export to Excel
  • articles
    • Data Components Export to Excel


toFunctor

converts a string to a function

function toFunctor(string name);

Parameters

name string a string to convert

Returns

function a function object

Example

function check(){
    alert("I'm alive!");
}
webix.toFunctor("check")();

See also

  • api
    • toArray, toNode


toNode

returns an HTML node object

HTMLElement toNode(string id);

Parameters

id string the id of the element you want to access

Returns

HTMLElement an HTML node

Example

var node = webix.toNode("someId");

Details

The method works as the getElementById() method.

See also

  • api
    • toArray, toFunctor


toPDF

exports data of a data component to a PDF file

void toPDF(string id,string name);

Parameters

id | string | the id of the exported view
name | string | optional, the name of the created PDF file

Example

webix.toPDF($$("myChart"));

See also

  • api
    • toPNG
    • toExcel
  • samples
    • DataTable Export to PDF
  • articles
    • Data Components Export to PDF


toPNG

exports data of a component to a PNG file

void toPNG(string id,string name);

Parameters

id | string | the id of the exported view
name | string | optional, the name of the created PNG file

Example

webix.toPNG($$("myChart"));

See also

  • api
    • toExcel
  • samples
    • Export to PNG
  • articles
    • Components Export to PNG


type

defines new rendering type for the component

void type(object config);

Parameters

config object type configuration

Example

webix.type(webix.ui.list, {
   name:"myItems",
   template:"Item #name#, from #origin#"
});

//...
//defined type can be used during view creating
//...

webix.ui({ view:"list", type:"myItems" })

See also

  • articles
    • Type Implementation


ui

the object constructor. Creates a new instance of the specified view

WebixView ui(object config, [object/string parent,object/string/number replacement] );

Parameters

config | object | the view configuration
parent | object/string | object or id of parent component
replacement | object/string/number | object, id or index of the component being replaced

Returns

WebixView a view object

Example

var dtable = webix.ui({ view:"datatable", ... });

Details

If you want to init a Webix component, only the first parameter is needed.

If you want to rebuild the existing layout or replace some component in it, make use of additional parameters. Read more in the Dynamic UI Modifications article.

See also

  • api
    • addView
    • removeView
  • samples
    • Dynamic Layout Rebuilding
  • articles
    • Dynamic UI Modifications


uid

returns a unique id

number uid();

Returns

number a unique id

Example

var id = webix.uid();

Details

The generated id is unique per page but not globally.
So you can use the method in the on-page logic. It's not good enough for use as the DB id.


unblockEvent

cancels blocking events that was enabled by the 'blockEvent' command

void unblockEvent();

Example

$$('mylist').blockEvent();
$$('mylist').add({ text:'abc'}); //will not trigger any events
$$('mylist').unblockEvent();

See also

  • api
    • EventSystem,
    • blockEvent
  • articles
    • Event Handling


wrap

'wraps' a function around the original function

function wrap(function target,function source);

Parameters

target | function | the function to wrap. It receives the new logic
source | function | a function that contains the logic to wrap

Returns

function the target object 'wrapped' around by the new logic

Example

list.add = webix.wrap(list.add, function(obj, index){
    //log all data adding operations
    console.log("add "+obj.id);
});


Events

onClick | fires when the user clicks on an element
onRotate | occurs on screen rotating


onClick

fires when the user clicks on an element

void onClick(Event ev){ ... };

Parameters

ev Event a native event object

Example

webix.attachEvent("onClick", function(){
   webix.message("Something clicked");
})


onRotate

occurs on screen rotating

void onRotate(boolean orientation ){ ... };

Parameters

orientation boolean true - landscape, false - portrait

Example

webix.attachEvent("onRotate", function(orientation){
    //your code here
});


Others

cdn | returns Webix cdn location
codebase | returns the path to the 'codebase' folder
name | returns the name of the component (by default, 'Core')
version | returns the current version of the library
scrollSize | returns the width of the scroll bar
zIndexBase | maximum used z-index


cdn

returns Webix cdn location

string cdn;

Example

alert(webix.codebase); // "//cdn.webix.com"

Details

We strongly encourage you not to change the value of the property.


codebase

returns the path to the 'codebase' folder

string codebase;

Example

alert(webix.codebase);

Details

We strongly encourage you not to change the value of the property


name

returns the name of the component (by default, 'Core')

string name;

Example

alert(webix.name);

Details

We strongly encourage you not to change the value of the property


version

returns the current version of the library

string version;

Example

alert(webix.version);

Details

We strongly encourage you not to change the value of the property


scrollSize

returns the width of the scroll bar

number scrollSize;

Example

alert(webix.ui.scrollSize);

Details

We strongly encourage you not to change the value of the property


zIndexBase

maximum used z-index

number zIndexBase;

Example

alert(webix.ui.zIndexBase); //100

Details

We strongly encourage you not to change the value of the property


ui helpers

UI helpers.

Methods
delay | delays a view from initializing at runtime
fullScreen | hides Safari address bar on iPhone/iPod
hasMethod | check does view in question supports the method
resize | resizes all the top-level UI elements
zIndex | returns the maximum used z-index
Other
scrollSize | returns the width of the scroll bar
zIndexBase | maximum used z-index


Methods

delay | delays a view from initializing at runtime
fullScreen | hides Safari address bar on iPhone/iPod
hasMethod | check does view in question supports the method
resize | resizes all the top-level UI elements
zIndex | returns the maximum used z-index


delay

delays a view from initializing at runtime

void delay(object config);

Parameters

config object the view configuration

Example

webix.ui.delay({
    view:"window",
    ...
});

Details

The method is similar to ui. The difference is that ui creates the view immediately, while webix.delay initializes the view just when it will be requested by the $$('view_id') or webix.$$ method.


fullScreen

for mobile devices; makes the application take all available screen space

void fullScreen();

Example

webix.ui.fullScreen();

Details

To make an app work correctly in the full-screen mode you should fulfil 2 requirements:

  1. All the code must be placed into webix.ready() to ensure that it will be called just after the page has been completely parsed.
  2. webix.ui.fullScreen() must be placed before components' definitions, i.e. before webix.ui() blocks.
webix.ready(function(){
    webix.ui.fullScreen();
    webix.ui({
                ...
    })
})

If you need to return the address bar, just touch the status bar. To hide the address bar again - refresh the page.


hasMethod

check does view in question supports the method

boolean hasMethod(string name,string method_name);

Parameters

name | string | name of view
method_name | string | name of method

Returns

boolean is method supported or not

Example

var result = webix.ui("popup", "setPosition");

Details

Method is experimental and can be removed in the next version


resize

resizes all the top-level UI elements

void resize();

Example

webix.ui.resize();


zIndex

returns the maximum used z-index

number zIndex();

Returns

number the maximum z-index value

Example

//to be on the top
div.style.zIndex = webix.ui.zIndex();

Details

Each time you call the method, the maximum z-index increases. So each next method call retrieves the value bigger than older ones.


Others

scrollSize | returns the width of the scroll bar
zIndexBase | maximum used z-index


ajax

Ajax operations (data loading, server side events).

    webix.ajax("data.php");
    //or
    webix.ajax.post("data.php", {
        someParameter:"someValue"
    });

The lib can execute get and post requests in sync and async mode. For more details check Ajax operations article.

Methods
bind | binds callback function to object
del | issues a DELETE Ajax request to the server
get | issues a GET Ajax request to the server
getXHR | returns an xmlHttpRequest object
headers | sets the HTTP request header(s)
patch | issues a PATCH Ajax request to the server
post | issues a POST Ajax request to the server
put | issues a PUT Ajax request to the server
response | sets response type of the request
stringify | converts data object into a string before sending it to server
sync | 'says' to send requests synchronously
timeout | max time for ajax request in milliseconds
Other
master return a master component for the ajax request


Methods

bind | binds callback function to object
del | issues a DELETE Ajax request to the server
get | issues a GET Ajax request to the server
getXHR | returns an xmlHttpRequest object
headers | sets the HTTP request header(s)
patch | issues a PATCH Ajax request to the server
post | issues a POST Ajax request to the server
put | issues a PUT Ajax request to the server
response | sets response type of the request
stringify | converts data object into a string before sending it to server
sync | 'says' to send requests synchronously
timeout | max time for ajax request in milliseconds


bind

binds callback function to object

ajax bind(object master);

Parameters

master object desired content of "this" in the callback

Returns

ajax this instance of ajax object

Example

webix.ajax().bind(myobj).get("some.php", function(){
    //this == myobj
});


del

issues a DELETE Ajax request to the server

promise del(string url, [object params,function callback] );

Parameters

url | string | the url to load
params | object | the hash of parameters that need sending to the server
callback | function | the callback function

Returns

promise data "promise" object

Example

webix.ajax().del("data.php", { id : "11" }, function(text, xml, xhr){
    //response
    console.log(text);
});

Details

The callback function takes 3 parameters:

  • text - the full text of the response
  • xml - the response parsed as xml, if applicable
  • xhr - an xmlHttpRequest object

See also

  • articles
    • Ajax operations
    • Server-side Integration


get

issues a GET Ajax request to the server

promise get(string url, [object params,function callback] );

Parameters

url | string | the url to load
params | object | the hash of parameters that need sending to the server
callback | function | the callback function

Returns

promise data "promise" object

Example

webix.ajax().get("data.php", { filter : "123" }, function(text, xml, xhr){
    //response
    console.log(text);
});

Details

Callback

The callback function takes 3 parameters:

  • text - the full text of the response
  • xml - the response parsed as xml, if applicable
  • xhr - an xmlHttpRequest object

Return value

The method returns a promise object than contains the eventual result of an Ajax request.

More information on Webix and Promiz.js usage can be found at:

  • Data Loading
  • Ajax operations

See also

  • articles
    • Ajax operations
    • Server-side Integration


getXHR

returns an xmlHttpRequest object

object getXHR();

Returns

object an xmlHttpRequest object

Example

var ajax = webix.ajax();
console.log(ajax.getXHR);

See also

  • articles
    • Ajax operations
    • Server-side Integration


headers

sets the HTTP request header(s)

ajax headers(object values);

Parameters

values object the name-value pairs of header fields

Returns

ajax the ajax object

Example

webix.ajax().headers({
    'Accept-Encoding': 'gzip',
    'Accept-Language': 'en-US'
})

Details

The default header definition is { 'Content-type': 'application/x-www-form-urlencoded' }.

See also

  • articles
    • Ajax operations
    • Server-side Integration


patch

issues a PATCH Ajax request to the server

promise patch(string url, [object params,function callback] );

Parameters

url | string | the url to load
params | object | the hash of parameters that need sending to the server
callback | function | the callback function

Returns

promise data "promise" object

Example

webix.ajax().patch("data.php", { id : "11" }, function(text, xml, xhr){
    //response
    console.log(text);
});

Details

The callback function takes 3 parameters:

  • text - the full text of the response
  • xml - the response parsed as xml, if applicable
  • xhr - an xmlHttpRequest object

See also

  • articles
    • Ajax operations
    • Server-side Integration


post

issues a POST Ajax request to the server

promise post(string url, [object params,function callback] );

Parameters

url | string | the url to load
params | object | the hash of parameters that need sending to the server
callback | function | the callback function

Returns

promise data "promise" object

Example

webix.ajax().post("data.php", { filter : "123" }, function(text, xml, xhr){
    //response
    console.log(text);
});

Details

Callback

The callback function takes 3 parameters:

  • text - the full text of the response
  • xml - the response parsed as xml, if applicable
  • xhr - an xmlHttpRequest object

Return value

The method returns a promise object than contains the eventual result of an Ajax request.

More information on Webix and Promiz.js usage can be found at:

  • Data Loading
  • Ajax operations

See also

  • articles
    • Ajax operations
    • Server-side Integration


put

issues a PUT Ajax request to the server

promise put(string url, [object params,function callback] );

Parameters

url | string | the url to load
params | object | the hash of parameters that need sending to the server
callback | function | the callback function

Returns

promise data "promise" object

Example

webix.ajax().put("data.php", { id : "11" }, function(text, xml, xhr){
    //response
    console.log(text);
});

Details

The callback function takes 3 parameters:

  • text - the full text of the response
  • xml - the response parsed as xml, if applicable
  • xhr - an xmlHttpRequest object

See also

  • articles
    • Ajax operations
    • Server-side Integration


response

sets response type of the request

void response(string type );

Parameters

type string response type

Example

webix.ajax().response("blob").get("patch.zip", function(text, data){
  //data - is a data blob
});

Details

Possible values to pass into this method are:

  • "blob" - binary data object
  • "arraybuffer" - binary data object
  • "document" - web page object

See also

  • articles
    • Ajax operations


stringify

converts data object into a string before sending it to server

string stringify(object data );

Parameters

data object data object

Returns

string data string

Example

var str = webix.ajax().stringify({ some: "a" });

Details

The method is called automatically before data is sent to server. If there are dates within the data object they are formatted with the parseFormatStr method.

If you want to redefine the data serialization for all ajax calls you can use

webix.ajax.prototype.stringify = function(obj){
    //or use some custom serializer here
    return JSON.stringify(obj);
}

If you just need a method for object serialization, you may use JSON.stringify directly

var str = JSON.stringify({ some: "a" });


sync

'says' to send requests synchronously

ajax sync();

Returns

ajax this instance of ajax object

Example

webix.ajax().sync().get("data.php");

See also

  • articles
    • Ajax operations
    • Server-side Integration


timeout

max time for ajax request in milliseconds

void timeout(int time);

Parameters

time int timeout in milliseconds

Example

webix.ajax().timeout(3000).get("data.php");

Details

If connection is slow and data loading takes more than defined number of milliseconds, ajax call will be stop and will trigger a error callback.


Others

master return a master component for the ajax request


master

return a master component for the ajax request

object master;

Example

var master = webix.ajax().master;


clipbuffer

Interface for clipboard.

Because browsers doesn't allow direct comunication with clipboard, lib creates hidden textarea which always hold text for copy (ctr-c) operation. So you can't set text directly to clipboard but you can place it ready for ctrl-c operation.

Methods
destructor | destroys the clipbuffer, cleanin dom
focus | moves focus to the clipboard buffer
init | inits clipboard buffer
set | sets new value for clipboard buffer


Methods

destructor | destroys the clipbuffer, cleanin dom
focus | moves focus to the clipboard buffer
init | inits clipboard buffer
set | sets new value for clipboard buffer


destructor

destroys the clipbuffer, cleanin dom

void destructor();

Example

clipbuffer.destructor();

Details

There is no need to call this method directly, it will be executed automatically on page unload.


focus

moves focus to the clipboard buffer

void focus();

Example

webix.clipbuffer.focus();

Details

Normally you need not to call this method directly


init

inits clipboard buffer

void init();

Example

webix.clipbuffer.init();

Details

After initialization clipbuffer will monitor key events, and after ctrl-v will fire onPaste event for currently active component ( which can be catched by attachEvent method for related component )


set

sets new value for clipboard buffer

void set(string text);

Parameters

text string new text for clipboard buffer

Example

webix.clipboard.set("Some text");

Details

IMPORTANT - method doesn't place text in clipboard, value will be available in clipboard only if user will press ctrl-c after .set command


color

Color transformation helpers.

Methods
hexToDec | converts a hexadecimal color code to the decimal format
hsvToRgb | converts an HSV color code to the RGB format
rgbToHsv | converts an RGB color code to the HSV format
toHex | converts a decimal number to the hexadecimal format
toRgb | converts a hexadecimal color code or RGB code string to the RGB array


Methods

hexToDec | converts a hexadecimal color code to the decimal format
hsvToRgb | converts an HSV color code to the RGB format
rgbToHsv | converts an RGB color code to the HSV format
toHex | converts a decimal number to the hexadecimal format
toRgb | converts a hexadecimal color code or RGB code string to the RGB array


hexToDec

converts a hexadecimal color code to the decimal format

number hexToDec(string hex);

Parameters

hex string the hexadecimal color code

Returns

number the decimal color code

Example

webix.color.hexToDec("ff0066");// -> 16711782

See also

  • api
    • toHex


hsvToRgb

converts an HSV color code to the RGB format

array hsvToRgb(number h,number s,number v);

Parameters

h | number | the heu value from 0 to 360
s | number | the saturation value from 0 to 1
v | number | the brightness value from 0 to 1

Returns

array the array with RED GREEN BLUE values

Example

webix.color.hsvToRgb(0.29,0.62,0.74);// -> [188, 72, 71]

See also

  • api
    • rgbToHsv


rgbToHsv

converts an RGB color code to the HSV format

array rgbToHsv(number r,number g,number b);

Parameters

r | number | the Red color value
g | number | the Green color value
b | number | the Blue color value

Returns

array the array with HUE SATURATION BRIGHTNESS values

Example

webix.color.rgbToHsv(115,116,133);
// -> [236.66666666666669, 0.13533834586466165, 0.5215686274509804]

See also

  • api
    • hsvToRgb


toHex

converts a decimal number to the hexadecimal format

string toHex(number number, [number length] );

Parameters

number | number | the decimal number
length | number | the length of the hexadecimal number

Returns

string the hexadecimal number

Example

webix.color.toHex(123456);// -> "1E240"

webix.color.toHex(123456, 10);// -> "000001E240"

Details

Note, the length parameter is used to add leading zeros to the number.

See also

  • api
    • hexToDec


toRgb

converts a hexadecimal color code or RGB code string to the RGB array

array toRgb(string rgb);

Parameters

rgb string a hexadecimal color code or RGB code string

Returns

array the array with RED GREEN BLUE values

Example

webix.color.toRgb("rgb(255,0,255)");// -> [255, 0, 255]

webix.color.toRgb("FF00FF");// -> [255, 0, 255]

See also

  • api
    • hsvToRgb


csv

Csv serialzation and parsing.

Can convert data to the csv string or split csv string in data array (undestand and produces correct escaping, fully compatibly with Excel's CSV output)

Methods
parse | converts a CSV string in a Javascript data array
stringify | converts a Javascript data array in a CSV string
Other
delimiter | sets the default CSV delimiter
escape | enables/activates the escape mode (activated by default)


Methods

parse | converts a CSV string in a Javascript data array
stringify | converts a Javascript data array in a CSV string


parse

converts a CSV string in a Javascript data array

array parse(string text, [object delimiter] );

Parameters

text | string | a CSV string
delimiter | object | the rows/columns delimiters used while CSV parsing

Returns

array a Javascript array with parsed values

Example

var data = webix.csv.parse("a,b\n,c,d"); // output[[a,b],[c,d]]

Details

The delimiter is an object with the following properties:

var delimiter = {
    rows: "\n", // the rows delimiter
    cols: "\t"  // the columns delimiter
}
  • The default rows delimiter - '\n' (new-line character)
  • The default columns delimiter - '\t' (horizontal tab )
var csv = '1-The Shawshank Redemption|2-The Godfather';
var delimiter = {rows:"|",  cols:"-" };
var data  = webix.csv.parse(csv, delimiter);
//output [["1", "The Shawshank Redemption"], ["2", "The Godfather, "1972"]]

You can change delimiters globally by setting webix.csv.delimiter.rows and webix.csv.delimiter.cols properties.

webix.csv.delimiter.rows = "\b";
webix.csv.delimiter.cols = "\v";


stringify

converts a Javascript data array in a CSV string

string stringify(array data, [object delimiter] );

Parameters

data | array | a Javascript array of parsed values
delimiter | object | the rows/cells delimiters used for CSV serialization

Returns

string a CSV string

Example

var text = webix.csv.stringify([[a,b],[c,d]]); //"a,b\n,c,d"

Details

The delimiter is an object with the following properties:

var delimiter = {
    rows: "\n", // the rows delimiter
    cols: "\t"  // the columns delimiter
}
  • The default rows delimiter - '\n' (new-line character)
  • The default columns delimiter - '\t' (horizontal tab )

You can change delimiters globally by setting webix.csv.delimiter.rows and webix.csv.delimiter.cols properties.

webix.csv.delimiter.rows = "\b";
webix.csv.delimiter.cols = "\v";


Others

delimiter | sets the default CSV delimiter
escape | enables/activates the escape mode (activated by default)


delimiter

sets the default CSV delimiter

string delimiter;


escape

enables/activates the escape mode (activated by default)

boolean escape;

Example

webix.csv.escape = false;

Details

The CSV parser can work in two modes:

  • Simplified;
  • Escape (full escape processing)

The difference between modes is that the escape mode treats escaped data, special chars and the simplified mode doesn't.

Therefore:

  • The simplified mode is much faster than the escape one but can break the parser.
  • If your data might have some escaped or quoted text - use the escape mode.
  • If you sure that data doesn't contain any special chars - use the simplified mode which will improve performance of CSV parsing/serialization.


editors

Set of editing tools.

Editors are used for components in editable state. They define an editing pattern, whether it is text input, two-value choice, date and color selection.

webix.ui({
    view:"datatable",
    ..config..
    editable:true,
    editor:"text"
})

Editor type depends on data you'd like to edit.

For more details check Data Editors

Other
$popup | set of configuration options for popup editors
checkbox | a checkbox editor for a two-value choice
color | a popup editor for hex code values. Allows for picking a color from the colorboard.
combo | a popup list with predefined select options.
date | edits dates with the help of a popup calendar.
inline-checkbox | a customizable checkbox editor
inline-text | a customizable text editor
multiselect | a popup list of predefined values with multiple-choice ability
password | text editor for passwords
popup | a popup text editor for long texts
richselect | a popup list of predefined select options
select | a drowdown list of predefined values based on HTML select
text | a standard editor for editing text data


Others

$popup | set of configuration options for popup editors
checkbox | a checkbox editor for a two-value choice
color | a popup editor for hex code values. Allows for picking a color from the colorboard.
combo | a popup list with predefined select options.
date | edits dates with the help of a popup calendar.
inline-checkbox | a customizable checkbox editor
inline-text | a customizable text editor
multiselect | a popup list of predefined values with multiple-choice ability
password | text editor for passwords
popup | a popup text editor for long texts
richselect | a popup list of predefined select options
select | a drowdown list of predefined values based on HTML select
text | a standard editor for editing text data


$popup

set of configuration options for popup editors

object $popup;

Example

webix.editors.$popup = {
        text:{
            view:"popup",
            body:{view:"textarea", width:250, height:50}
        },
        color:{
            view:"popup",
            body:{ view:"colorboard", width:200, height:200, rows:20, cols:20 }
        },
        date:{
            view:"popup",
            body:{ view:"calendar", weekNumber:true, width: 220, height:200}
        }
    };

See also

  • samples
    • Editor Collection
  • articles
    • Data Editors
    • Details

    $popup allows for changing all the popup editors in one scope.

    Date and Color editors are popups by default. For text popup editor, you should specify the "popup" value for the editor property.


checkbox

a checkbox editor for a two-value choice

string checkbox;

Example

//for a datatable column
{ id:"ch1", editor:"checkbox", template:"{common.checkbox()}", width:40}

See also

  • samples
    • Editor Collection
    • Checkbox and radio in DataTable
  • articles
    • Data Editors
    • Details

    Customizing Value Display

    Checkbox editor can be customized to show predefined values for each of checkbox states.

    The component shows On/Off values, but as you click on the item a checkbox appears and you can check/uncheck it. When editing is finished, the cell value turns into "On"/"Off" text depending on the checkbox state.

    bool_set = {
    "true":"On",
    "false":"Off",
    "undefined":"Off" //initial checkbox state
};
..
{header:"", options:bool_set, template:"{common.checkbox()}",
        editor:"checkbox", width:40}

    Option for a checkbox can be set in a variable beforehand (as shown above) or inside the component constructor.

    Customizing Return Values

    You can redefine the states of the checkbox and set other values for default true and false

    { id:"ch1", checkValue:'on', uncheckValue:'off', template:"{common.checkbox()}"}


color

a popup editor for hex code values. Allows for picking a color from the colorboard.

string color;

Example

//for a datatable column
{ id:"start", editor:"color", template:tpl, header:"Color A", width:120}

See also

  • samples
    • Color Editor
  • articles
    • Data Editors
    • Details

    Data Item Template

    To display the necessary color in a component item, you should create a proper template for it:

    var tpl = "<span style='background-color:#value#; border-radius:4px; padding-right:10px;'>
 &nbsp</span> #value#";

    Here we have a square with rounded edges and a hex code for the corresponding color. Otherwise, just hex codes will be shown.

    Colorboard configutation

    By default, a standard colorboard is shown. For further customization, you should configure your popup:

    webix.editors.$popup = {
        color:{
            view:"popup",
            body:{ view:"colorboard", width:200, height:200, rows:20, cols:20 }
        }
    };


combo

a popup list with predefined select options.

string combo;

Example

//for a datatable column
{id:"name", header:"Name", editor:"combo", options:[...]}

See also

  • api
    • richselect
  • samples
    • Editor Collection
    • Datatable: Combo Editor
  • articles
    • Data Editors
    • Details

    Combo editor is initialized each time you click on the dedicated item. Moreover, the item is simultaneously opened in the text editor that acts like a filter input for list options.


date

edits dates with the help of a popup calendar.

string date;

Example

//for a datatble column
{id:"startdate", editor:"date", header:"Start date", width:120}

See also

  • samples
    • Editor Collection
  • articles
    • Data Editors
    • Details

    The calendar is shown automatically as soon as you trigger item editing. This is a default calendar. To change its properties you should configure your popup.

    webix.editors.$popup = {
  date:{
     view:"popup",
     body:{
        view:"calendar",
        timepicker:true,
        weekNumber:true,
        width: 220,
        height:200
     }
  }
};

    Timepicker allows selecting time in addition to dates.

    For more info on Calendar check the dedicated article.


inline-checkbox

a customizable checkbox editor

string inline-checkbox;

Example

//for a datatable column
{ id:"ch1", header:"", template:custom_checkbox, width:40, editor:"inline-checkbox"}

See also

  • samples
    • Editor Collection
  • articles
    • Data Editors
    • Details

    If you want to display a checkbox icon within the item you'd like to edit, you should inlcude {common.checkbox()} into the data item.

    At the same time, there can be eny template for data edited with the help of a checkbox editor. Checkboxes will appear only on the editing stage for you to check/uncheck it:

    function custom_checkbox(obj, common, value){
    if (value)
        return "<div class='webix_table_checkbox checked'> YES </div>";
    else
        return "<div class='webix_table_checkbox notchecked'> NO </div>";
}


inline-text

a customizable text editor

string inline-text;

Example

//for a datatable column
{ header:"", template:"<input type='text' value='#value#' style='width:130px;'>",
            editor:"inline-text", width:150 }

See also

  • samples
    • Using 'inline' editors
    • Editor Collection
  • articles
    • Data Editors
    • Details

    With an inline-text editor you should define its template (input type, dimensions, styling).


multiselect

a popup list of predefined values with multiple-choice ability

string multiselect;

Available only in PRO Edition

Example

//for a datatable column
{ id:"year", editor:"multiselect", options:years, header:"Released" }

See also

  • api
    • richselect
  • samples
    • Multi-select editor in the DataTable
  • articles
    • Data Editors
    • Editing Data Items
    • Details

    It looks very much the same like a non-pro richselect editor, but provides a possibility for choosing multiple options at a time.


password

text editor for passwords

string password;

Example

//for a property sheet element
{ label:"Password", type:"password", id:"pass"}

See also

  • api
    • password
  • samples
    • Property Sheet: Basic Initialization
  • articles
    • Editing Data Items
    • Data Editors


popup

a popup text editor for long texts

string popup;

Example

//for a datatable column
{ id:"title",   header:"Film title", editor:"popup", width:200}

See also

  • samples
    • Editor Collection
    • Pop-up editors
  • articles
    • Data Editors
    • Details

    There exist color and date popup editors. They are defined as editor:"color" and editor:date respectively.

    Popup text editor features a textarea input in tis body. To configure the popup use the following code: \

       webix.editors.$popup = {
        text:{
            view:"popup",
            body:{view:"textarea", width:250, height:50}
        }
    };


richselect

a popup list of predefined select options

string richselect;

Example

//for a datatable column
{ id:"year", editor:"richselect", options:years, header:"Released" }

See also

  • api
    • combo
    • multiselect
  • samples
    • Datatable: RichSelect Editor
    • Editor Collection
  • articles
    • Data Editors
    • Editing Data Items
    • Details

    It looks very much the same like a combo editor, but doesn't provide a possibility for option filtering.


select

a drowdown list of predefined values based on HTML select

string select;

Example

//for a datatable column
{ header:"Category", editor:"select", options:["","Thriller", "Crime"],  width:80}

See also

  • samples
    • Using the 'select' editor
  • articles
    • Data Editors
    • Details

    For better code understanding, select options can be defined in a variable outside the component constructor

    var sel_options = {
    "1" : "Thriller",
    "2" : "Crime",
    "3" : "Western"
};

{editor:"select", options:sel_options}

    However, in this case, the necessary data is stored in a dataset in the form of keys ("1", "2", "3") rather than values "Thriller".


text

a standard editor for editing text data

string text;

Example

//for a datatble column
{ id:"title",   header:"Film title", editor:"popup", width:200},

See also

  • api
    • popup
    • password
  • samples
    • Basic use of editors
  • articles
    • Data Editors
    • Details

    Editing area will be highlighted by a yellow border as soom as you trigger the editiong function.


env

Set of flags which describes current environment.

Changing flags manually may have an unpredictable result..

Other
cssPrefix | browser-specific prefix for CSS transforms and transitions
https | returns true if the protocol of the page is https and false, if it's http
isEdge | a read-only boolean indicating whether the current browser is Microsoft Edge
isFF | a read-only boolean indicating whether the current browser is Firefox
isIE | a read-only boolean indicating whether the current browser is Internet Explorer
isSafari | a read-only boolean indicating whether the current browser is Safari
isWebKit | a read-only boolean indicating whether the current browser is WebKit based (Google Chrome)
jsPrefix | browser-specific prefix for CSS transforms and transitions (in Javascript code)
mouse | set of mouse-specific properties
pointerevents | indicates whether pointer-events are supported
strict | enables strict mode for webix library.
svg | a read-only boolean indicating whether the current browser supports SVG
transform | a read-only boolean indicating whether the current browser supports CSS Transforms
transition | a read-only boolean indicating whether the current browser supports CSS Transitions
transitionDuration | the name of the browser-specific transition-duration event
transitionEnd | the name of the browser-specific transition-end event
translate | the name of the translate CSS style. Can be "translate" or "translate3d" (if the second one is supported)


Others

cssPrefix | browser-specific prefix for CSS transforms and transitions
https | returns true if the protocol of the page is https and false, if it's http
isEdge | a read-only boolean indicating whether the current browser is Microsoft Edge
isFF | a read-only boolean indicating whether the current browser is Firefox
isIE | a read-only boolean indicating whether the current browser is Internet Explorer
isSafari | a read-only boolean indicating whether the current browser is Safari
isWebKit | a read-only boolean indicating whether the current browser is WebKit based (Google Chrome)
jsPrefix | browser-specific prefix for CSS transforms and transitions (in Javascript code)
mouse | set of mouse-specific properties
pointerevents | indicates whether pointer-events are supported
strict | enables strict mode for webix library.
svg | a read-only boolean indicating whether the current browser supports SVG
transform | a read-only boolean indicating whether the current browser supports CSS Transforms
transition | a read-only boolean indicating whether the current browser supports CSS Transitions
transitionDuration | the name of the browser-specific transition-duration event
transitionEnd | the name of the browser-specific transition-end event
translate | the name of the translate CSS style. Can be "translate" or "translate3d" (if the second one is supported)


cssPrefix

browser-specific prefix for CSS transforms and transitions

string cssPrefix;

Example

alert(webix.env.cssPrefix);

See also

  • api
    • translate
    • transitionEnd
    • jsPrefix
    • transition
    • Details

    Possible values are '', '-webkit-', '-Moz-', '-o-', '-ms-';


https

returns true if the protocol of the page is https and false, if it's http

boolean https;

Example

if (webix.env.https)
    do_something();


isEdge

a read-only boolean indicating whether the current browser is Microsoft Edge

boolean isEdge;

Example

if (webix.env.isEdge)
    do_something();

See also

  • api
    • isIE
    • isSafari
    • isWebKit
    • isFF


isFF

a read-only boolean indicating whether the current browser is Firefox

boolean isFF;

Example

if (webix.env.isFF)
    do_something();

See also

  • api
    • isIE
    • isSafari
    • isWebKit


isIE

a read-only boolean indicating whether the current browser is Internet Explorer

boolean isIE;

Example

if (webix.env.isIE)
    do_something();

See also

  • api
    • isSafari
    • isWebKit
    • isFF


isSafari

a read-only boolean indicating whether the current browser is Safari

boolean isSafari;

Example

if (webix.env.isSafari)
    do_something();

See also

  • api
    • isIE
    • isWebKit
    • isFF


isWebKit

a read-only boolean indicating whether the current browser is WebKit based (Google Chrome)

boolean isWebKit;

Example

if (webix.env.isWebKit)
    do_something();

See also

  • api
    • isIE
    • isSafari
    • isFF


jsPrefix

browser-specific prefix for CSS transforms and transitions (in Javascript code)

string jsPrefix;

Example

alert(webix.env.jsPrefix);

See also

  • api
    • translate
    • transitionEnd
    • cssPrefix
    • transition
    • Details

    Possible values are '', 'webkit', 'Moz', 'O', 'ms'.


mouse

set of mouse-specific properties

object mouse;

Example

//attaching handler to the mousedown event on the document body
webix.event(document.body, webix.env.mouse.down, do_something);

Details
  • down - "mousedown";
  • up - "mouseup";
  • move - "mousemove";
  • context - mouse event context that contains:
    • target - target HTML element;
    • x - x coordinate value;
    • y - y coordinate value;
    • time - time of the event.


pointerevents

indicates whether CSS pointer-events property is supported in the current browser

boolean pointerevents;

Example

if (webix.env.pointerevents)
    do_something();

Details

You can read about pointer-events here.


strict

enables strict mode for webix library.

boolean strict;

Example

webix.env.strict = true;

Details

False by default.

In Strict mode Webix doesn't use "eval".

Should be enabled if Content Security Policy is switched on for the application or if the application runs in a "strict" mode The flag should be enabled before Webix files are included into the page.

Note that datatable math won't work with the webix.env.strict enabled.


svg

a read-only boolean indicating whether the current browser supports SVG

boolean svg;

Example

if (webix.env.svg)
    do_something();


transform

a read-only boolean indicating whether the current browser supports CSS Transforms

boolean transform;

Example

if (webix.env.transform)
    do_something();

See also

  • api
    • translate
    • transitionEnd
    • jsPrefix
    • cssPrefix
    • transition


transition

a read-only boolean indicating whether the current browser supports CSS Transitions

boolean transition;

Example

if (webix.env.transition)
    do_something();

See also

  • api
    • translate
    • transitionEnd
    • jsPrefix
    • cssPrefix
    • transform


transitionDuration

the name of the browser-specific transition-duration event

string transitionDuration;

Example

//in WebKit-based browser returns "webkitTransitionDuration"
alert(webix.env.transitionDuration);

See also

  • api
    • transitionEnd
    • jsPrefix
    • cssPrefix
    • transform
    • transition
    • translate


transitionEnd

the name of the browser-specific transition-end event

string transitionEnd;

Example

alert(webix.env.transitionEnd); // in WebKit-based browser returns "webkitTransitionEnd"

See also

  • api
    • jsPrefix
    • cssPrefix
    • transform
    • transition
    • transitionDuration
    • translate


translate

the name of the translate CSS style. Can be "translate" or "translate3d" (if the second one is supported)

string translate;

Example

alert(webix.env.translate);

See also

  • api
    • transitionEnd
    • jsPrefix
    • cssPrefix
    • transform
    • transition


history

Implements history tracking.

Methods
push | add new state to the history
track | remember the currently open tab to show it after page refresh


Methods

push | add new state to the history
track | remember the currently open tab to show it after page refresh


push

add new state to the history

void push(string view,string url,any value);

Parameters

view | string | id of related view
url | string | in-page url for new state
value | any | any related data

Example

webix.history.push("mytabs", "tabs/details" "details");

Details

When refreshing page, the component for which history record stored will be called like

$$(view).setValue(value);

See also

  • articles
    • Tracking the Latest Opened Tab


track

remember the currently open tab to show it after page refresh

void track(string view,string url);

Parameters

view | string | ID of the switching control (tabbar, segmented) or tabview ID.
url | string | hashbang url loaded after refresh. If not stated, the last opened tab URL is loaded.

Example

webix.history.track('tabbar');

Details

Each time you click the tab to switch for another cell, a hashbang URL is generated on the base of cell ID (under http://current_url.html#!/cellID pattern) and memorized. You'll see them in the address bar of your browser.

See also

  • samples
    • History API with Multiview
  • articles
    • Tracking the Latest Opened Tab


html

Set of html|dom helpers.

Methods
addCss | adds a CSS class to a DOM node
addMeta | adds metadata to the page
addStyle | adds a CSS rule to the page
allowSelect | enables selection in the document (disabled before by the denySelect method)
create | creates a new HTML element
createCss | converts a set of CSS rules to an active CSS class
denySelect | disables selection in the document
download | downloads a file from Blob data
getTextSize | changes the text's size in an HTML node and returns the result
getValue | returns the node content
index | returns the node index
insertBefore | inserts a new node into the specified position
locate | searches a node with the specified attribute in all parents of the specified node (or from the target of the specified event) inclusively and returns the value of the first occurrence
offset | returns the position of an HTML element on the page
pos | returns the position of the mouse pointer relative to the upper-left corner of the screen
posRelative | returns the pointer's position relative to the object firing the event
preventEvent | stops the event processing and cancels its default action (called in some event handler)
remove | removes an HTML element from DOM
removeCss | removes a CSS class from a DOM node
stopEvent | stops processing of an event beyond the current target (called in some event handler)


Methods

addCss | adds a CSS class to a DOM node
addMeta | adds metadata to the page
addStyle | adds a CSS rule to the page
allowSelect | enables selection in the document (disabled before by the denySelect method)
create | creates a new HTML element
createCss | converts a set of CSS rules to an active CSS class
denySelect | disables selection in the document
download | downloads a file from Blob data
getTextSize | changes the text's size in an HTML node and returns the result
getValue | returns the node content
index | returns the node index
insertBefore | inserts a new node into the specified position
locate | searches a node with the specified attribute in all parents of the specified node (or from the target of the specified event) inclusively and returns the value of the first occurrence
offset | returns the position of an HTML element on the page
pos | returns the position of the mouse pointer relative to the upper-left corner of the screen
posRelative | returns the pointer's position relative to the object firing the event
preventEvent | stops the event processing and cancels its default action (called in some event handler)
remove | removes an HTML element from DOM
removeCss | removes a CSS class from a DOM node
stopEvent | stops processing of an event beyond the current target (called in some event handler)


addCss

adds a CSS class to a DOM node

void addCss(HTMLElement node,string name);

Parameters

node | HTMLElement | a DOM node
name | string | the name of a CSS class to apply

Example

//any node
webix.html.addCss(node,"mycssrule");

//Webix component top node
webix.html.addCss( $$("dt").getNode(), "mycss");

See also

  • api
    • addStyle
    • removeCss


addMeta

adds metadata to the page

void addMeta(string name,string value);

Parameters

name | string | the metadata name
value | string | the metadata value

Example

webix.html.addMeta("apple-mobile-web-app-capable","yes");


addStyle

adds a CSS rule to the page

void addStyle(string css);

Parameters

css string the CSS text

Example

webix.html.addStyle(".myclass{ color:red; }");

See also

  • api
    • addCss


allowSelect

enables selection in the document (disabled before by the denySelect method)

void allowSelect();

Example

webix.html.allowSelect();

See also

  • api
    • denySelect


create

creates a new HTML element

HTMLElement create(string name,object attrs, [string html] );

Parameters

name | string | the name of an HTML element
attrs | object | the hash of attributes
html | string | the inner HTML of a new element

Returns

HTMLElement a newly-created HTML element

Example

webix.html.create("div", { name:"myname" }, "Some content");

See also

  • api
    • remove


createCss

converts a set of CSS rules to an active CSS class

string createCss(object data);

Parameters

data object the hash of CSS rules

Returns

string the name of a new CSS class

Example

node.className = webix.html.createCss({
     "color":"red",
     "text-align":"center"
});

See also

  • api
    • removeCss


denySelect

disables selection in the document

void denySelect();

Example

webix.html.denySelect();

See also

  • api
    • allowSelect


download

downloads a file from Blob data

void download(object data,string filename);

Parameters

data | object | Blob data for the file to download
filename | string | name of resulting file

Example

// var pdf = ..some created pdf data..
var blob = new Blob([pdf.toString()], { type: "application/pdf" });
webix.html.download(blob, "myfile.pdf");


getTextSize

changes the text's size in an HTML node and returns the result

object getTextSize(string text,string css);

Parameters

text | string | the text of the HTML node
css | string | the css style applied to the text

Returns

object an object with the text's width and height

Example

var text_size = webix.html.getTextSize("text", "css");


getValue

returns the node content

string getValue(HTMLElement node);

Parameters

node HTMLElement a DOM element

Returns

string the content of the node

Example

var content = webix.html.getValue("myDiv");


index

returns the node index

number index(HTMLElement node);

Parameters

node HTMLElement a DOM element

Returns

number the node index in the child nodes collection of the parent

Example

var ind = webix.html.index(someNode);


insertBefore

inserts a new node into the specified position

void insertBefore(HTMLElement node,HTMLElement before, [HTMLElement rescue] );

Parameters

node | HTMLElement | a new DOM node
before | HTMLElement | the sibling node that the new node will be inserted before
rescue | HTMLElement | the parent node used if the subling doesn't exist

Example

var newdiv=document.createElement("div");
webix.html.insertBefore(newdiv,document.getElementById("myDiv"))

Details

The method inserts a new node before the specified sibling (the before parameter) or as the last child of the specified parent (the rescue parameter) if the sibling doesn't exist.
The third parameter is optional and used just to avoid errors in case the specified subling doesn't exist.

See also

  • api
    • remove


locate

searches a node with the specified attribute in all parents of the specified node (or from the target of the specified event) inclusively and returns the value of the first occurrence

string locate(Event|HTMLElement ev,string name);

Parameters

ev | Event|HTMLElement | a DOM node or a native HTML event
name | string | the name of an attribute

Returns

string the attribute value or null

Example

<input type="radio" id="myradio" name="Color" value="Blue">
var elem = document.getElementById("myradio");
var ev = elem.onclick = locateFunc;

function locateFunc(e)
{
    alert(webix.html.locate(e, "name"));     //returns 'Color' (takes the event object)
    alert (webix.html.locate(elem, "value")); //returns 'Blue'  (takes the node)
}


offset

returns the position of an HTML element on the page

object offset(HTMLElement node);

Parameters

node HTMLElement an HTML element

Returns

object the position object

Example

var elem = document.getElementById("myDiv")
webix.html.offset(elem); //returns {y:100, x:500} - the top and left absolute position

See also

  • api
    • pos, posRelative


pos

returns the position of the mouse pointer relative to the upper-left corner of the screen

object pos(Event ev);

Parameters

ev Event a native HTML event

Returns

object the position object

Example

<input type="radio" id="myradio" name="Color" value="Blue">
document.getElementById("myradio").onclick = function (e){
    var pos = webix.html.pos(e||event);
    console.log(pos);                   //returns { x:21, y:500 }
}

See also

  • api
    • posRelative,offset


posRelative

returns the pointer's position relative to the object firing the event

object posRelative(Event ev);

Parameters

ev Event a native HTML event

Returns

object the position object

Example

<div id="mydiv" style="width:100px; height:100px;border: 1px solid #781351;"></div>
var elem = document.getElementById("mydiv");

elem.onclick = function (e){
    var posRel = webix.html.posRelative(e||event);
    var pos = webix.html.pos(e||event);

    console.log(pos);    // returns {x:20,y:501}
    console.log(posRel); // returns {x:20,y:21}
}

Details
  • Internet Explorer, WebKit-based browsers - the method retrieves the pointer's position relative to the object firing the event.
  • Firefox - the method the pointer's position relative to the last positioned ancestor element.

See also

  • api
    • pos, offset


preventEvent

stops the event processing and cancels its default action (called in some event handler)

boolean preventEvent(Event ev);

Parameters

ev Event a native HTML event

Returns

boolean false

Example

<a id="mylink" href='http://google.com'>Google</a>
document.getElementById("mylink").onclick = function(e)
{
    alert("The link doesn't redirect us to the Google page anymore");
    return webix.html.preventEvent(e);

}

Details

If the specified event is cancelable, the method signifies that it should be cancelled. If the event can't be cancelled the method has no effect.

See also

  • api
    • stopEvent


remove

removes an HTML element from DOM

void remove(HTMLElement|HTMLElement[] node);

Parameters

node HTMLElement|HTMLElement[] an HTML element (or an array of elements)

Example

<a id="l1" href='http://google.com'>Google</a>
<a id="l2" href='http://yahoo.com'>Yahoo</a>
<button type="text" onclick="myfunc()">Remove the link</button>
function myfunc ()
{
    var link1 = document.getElementById("l1");
    var link2 = document.getElementById("l2")

    webix.html.remove(link1);
    //or webix.html.remove([link1,link2])
}

See also

  • api
    • insertBefore


removeCss

removes a CSS class from a DOM node

void removeCss(HTMLElement node,string name);

Parameters

node | HTMLElement | a DOM node
name | string | the name of a CSS class to remove

Example

//any node
webix.html.removeCss(node, "selected");

//webix component top node
webix.html.removeCss( $$("dt").getNode(), "mycss");

See also

  • api
    • addCss


stopEvent

stops processing of an event beyond the current target (called in some event handler)

boolean stopEvent(Event ev);

Parameters

ev Event a native HTML event

Returns

boolean false

Example

<a id="mylink" href='http://google.com'>Google</a>
document.getElementById("mylink").onclick = function(e)
{
    alert("The link doesn't redirect us to the Google page anymore");
    return webix.html.stopEvent(e);

}

See also

  • api
    • preventEvent


i18n

Internationalization, number and date formatting methods.

Methods
dateFormatDate | converts a string in the default date format to a Date object
dateFormatStr | converts a Date object to a string in the default date format
fullDateFormatDate | converts a string in the default date-time format to a Date object
fullDateFormatStr | converts a Date object to a string in the full-date format
intFormat | converts a number into integer and formats according to the locale defaults.
longDateFormatDate | converts a string in the long date format to a Date object
longDateFormatStr | converts a Date object to a string in the long-date format
numberFormat | formats a number according to the locale defaults
parseFormatDate | converts a string in the parsing date format to a Date object
parseFormatStr | converts a Date object to a string in the parsing format
parseTimeFormatDate | converts a date object to a string in the parsing format with respect to time
parseTimeFormatStr | converts a Date object to a string in the parsing format with respect to time value
priceFormat | formats a number as a price string
setLocale | sets the locale in use
timeFormatDate | converts a string in the time format to a Date object
timeFormatStr | converts a Date object to a string in the time format
Other
calendar | the default locale months and days names
controls | sets text labels for some elements of Webix components
dataExport | sets text labels for the parts of the page numbering line
dateFormat | sets the default locale date format
decimalDelimiter | a char which separates the decimal part in the float number. The default value is ”.”
decimalSize | the number of decimal digits in the float number
fileSize | sets abbreviations for file sizes from byte to exabyte
fullDateFormat | sets the default locale date-time format
groupDelimiter | a char which separates groups of digits. The default value is ”,”;
groupSize | the number of digits in a group. The default value is 3
locales | creates a new locale
longDateFormat | sets the default locale the long-date format
parseFormat | sets the default locale parsing date format. Initially it is "**%Y-%m-%d "%H:%i**".
parseTimeFormat | sets the default locale parsing time format. Initially it is **%H:%i**.
price | sets the default locale price format
priceSettings | sets the format of the price number
spreadsheet | default locales for spreadsheet labels and tooltips
timeFormat | sets the default locale time format


Methods

dateFormatDate | converts a string in the default date format to a Date object
dateFormatStr | converts a Date object to a string in the default date format
fullDateFormatDate | converts a string in the default date-time format to a Date object
fullDateFormatStr | converts a Date object to a string in the full-date format
intFormat | converts a number into integer and formats according to the locale defaults.
longDateFormatDate | converts a string in the long date format to a Date object
longDateFormatStr | converts a Date object to a string in the long-date format
numberFormat | formats a number according to the locale defaults
parseFormatDate | converts a string in the parsing date format to a Date object
parseFormatStr | converts a Date object to a string in the parsing format
parseTimeFormatDate | converts a date object to a string in the parsing format with respect to time
parseTimeFormatStr | converts a Date object to a string in the parsing format with respect to time value
priceFormat | formats a number as a price string
setLocale | sets the locale in use
timeFormatDate | converts a string in the time format to a Date object
timeFormatStr | converts a Date object to a string in the time format


dateFormatDate

converts a string in the default date format to a Date object

object dateFormatDate(string date);

Parameters

date string a date as a string in the default date format

Returns

object a Date object

Example

var date = webix.i18n.dateFormatDate("16.02.2004");

Details

The default format is defined by the locale in use.


dateFormatStr

converts a Date object to a string in the default date format

string dateFormatStr(object date);

Parameters

date object a Date object

Returns

string a date as a string in the default date format

Example

var text = webix.i18n.dateFormatStr(new Date());

Details

The default format is defined by the locale in use.


fullDateFormatDate

converts a string in the default date-time format to a Date object

object fullDateFormatDate(string date);

Parameters

date string a date as a string in the default date-time format

Returns

object a Date object

Example

var date = webix.i18n.fullDateFormatDate("16-02-2004 02:25");

Details

The default format is defined by the locale in use.


fullDateFormatStr

converts a Date object to a string in the full-date format

string fullDateFormatStr(Date date);

Parameters

date Date a Date object

Returns

string a time as a string in the full-date format

Example

var text = webix.i18n.fullDateFormatStr(new Date());

Details

The default format is defined by the locale in use.


intFormat

converts a number into integer and formats according to the locale defaults.

string intFormat(number num);

Parameters

num number the number to format

Returns

string the formatted number as a string
Details

The method takes values of the following attributes from the locale in use:

  • groupSize - the number of digits in a group.
  • groupDelimiter - a char which separates groups of digits.


longDateFormatDate

converts a string in the long date format to a Date object

object longDateFormatDate(string date);

Parameters

date string a date as a string in the long-date format

Returns

object a Date object

Example

var date = webix.i18n.longDateFormatDate("Monday, 16 February 2004");

Details

The default format is defined by the locale in use.


longDateFormatStr

converts a Date object to a string in the long-date format

string longDateFormatStr(object date);

Parameters

date object a Date object

Returns

string a time as a string in the long-date format

Example

var text = webix.i18n.timeFormatStr(new Date());

Details

The default format is defined by the locale in use.


numberFormat

formats a number according to the locale defaults

string numberFormat(number number);

Parameters

number number the number to format

Returns

string a formatted number string

Example

var text = webix.i18n.numberFormat(1277344.5987); //1,277,344.59

Details

Alias to the webix.Number.format


parseFormatDate

converts a string in the parsing date format to a Date object

object parseFormatDate(string date);

Parameters

date string a date as a string

Returns

object a Date object

Example

var date = webix.i18n.parseFormatDate("2001-02-16");

Details

The default format is defined by the locale in use and initially it's "%Y-%m-%d" (the default MySQL date format).


parseFormatStr

converts a Date object to a string in the parsing format

string parseFormatStr(object date);

Parameters

date object a Date object

Returns

string a time as a string in the parsing format

Example

var text = webix.i18n.parseFormatStr(new Date());

Details

The default format is defined by the locale in use and initially it's "%Y-%m-%d "%H:%i" ( the default MySQL date format ).


parseTimeFormatDate

converts a date object to a string in the parsing format with respect to time

object parseTimeFormatDate(string date);

Parameters

date string string in the needed format with time value

Returns

object date object with the needed time

Example

var hours = webix.i18n.parseTimeFormatDate("10:00").getHours();

Details

The default parseTimeFormat is %H:%i.


parseTimeFormatStr

converts a Date object to a string in the parsing format with respect to time value

string parseTimeFormatStr(object date);

Parameters

date object date object with time value

Returns

string time string in default format

Example

var time = webix.i18n.parseTimeFormatStr(new Date());

Details

The default parseTimeFormat is %H:%i.


priceFormat

formats a number as a price string

string priceFormat(number number);

Parameters

number number the number to format

Returns

string a price string

Example

webix.i18n.priceFormat(1.23455); //$1.23


setLocale

sets the locale in use

void setLocale(string name);

Parameters

name string the locale name

Example

webix.i18n.setLocale("en-US")

Details

The method can take only one of a predefined set of values (locale names):

  • 'en-US' - North American (used by default);
  • 'ru-RU' - Russian;
  • 'fr-FR' - French;
  • 'ja-JP' - Japanese;
  • 'be-BY' - Belarusian;
  • 'de-DE' - German;
  • 'es-ES' - Spanish;
  • 'it-IT' - Italian;
  • 'zh-CN' - Chinese.

Webix Pro edition includes over 300 locales to match a great variety of cultures.

The method can be used to apply the changes done to the locale in use.

webix.i18n.parseFormat = "%d-%m-%Y";
webix.i18n.setLocale();

setLocal must be used before rendering the UI widgets. Calling setLocale after widgets are rendered will not force locale update in the already rendered UI.
You will need to recreate views to apply a new locale settings.

See also

  • api
    • locales
  • samples
    • Internationalization
  • articles
    • Date and Number Localization


timeFormatDate

converts a string in the time format to a Date object

object timeFormatDate(string time);

Parameters

time string a time as a string in the time format

Returns

object a Date object

Example

var date = webix.i18n.timeFormatDate("16:42");

Details

The default format is defined by the locale in use.


timeFormatStr

converts a Date object to a string in the time format

string timeFormatStr(object date);

Parameters

date object a Date object

Returns

string a time as a string in the time format

Example

var text = webix.i18n.timeFormatStr(new Date());

Details

The default format is defined by the locale in use.


Others

calendar | the default locale months and days names
controls | sets text labels for some elements of Webix components
dataExport | sets text labels for the parts of the page numbering line
dateFormat | sets the default locale date format
decimalDelimiter | a char which separates the decimal part in the float number. The default value is ”.”
decimalSize | the number of decimal digits in the float number
fileSize | sets abbreviations for file sizes from byte to exabyte
fullDateFormat | sets the default locale date-time format
groupDelimiter | a char which separates groups of digits. The default value is ”,”;
groupSize | the number of digits in a group. The default value is 3
locales | creates a new locale
longDateFormat | sets the default locale the long-date format
parseFormat | sets the default locale parsing date format. Initially it is "**%Y-%m-%d "%H:%i**".
parseTimeFormat | sets the default locale parsing time format. Initially it is **%H:%i**.
price | sets the default locale price format
priceSettings | sets the format of the price number
spreadsheet | default locales for spreadsheet labels and tooltips
timeFormat | sets the default locale time format


calendar

the default locale months and days names

object calendar;

Example

webix.i18n.calendar: {
    monthFull:["January", "February", "March", "April", "May", "June",
      "July", "August", "September", "October", "November", "December"],
    monthShort:["Jan", "Feb", "Mar", "Apr", "May", "Jun",
       "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
    dayFull:["Sunday", "Monday", "Tuesday", "Wednesday",
       "Thursday", "Friday", "Saturday"],
    dayShort:["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
}
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details
    • monthFull - the full names of months starting from January.
    • monthShort - the short names of months starting from January.
    • dayFull - the full names of week days starting from Sunday.
    • dayShort - the short names of week days starting from Sunday.

    You need to call setLocale to apply the new format settings


controls

sets text labels for some elements of Webix components

object controls;

Example

webix.i18n.control.select = "Done";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
    • Multi-select input
  • articles
    • Date and Number Localization
    • Details

    The settings contains a collection of localization options for the controls that are used as parts of other Webix components and are likely to be localized in a scope rather than redefining each instance separately:

    • select - text label of the 'Select' button of the multisuggest (used in multiselect input, editor and filter). The default value for North Americal locale is "Select".


dataExport

sets text labels for the parts of the page numbering line in the exported PDF document

object dataExport;

Example

webix.i18n.dataExport:{
    page:"Page",
    of:"of"
};
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • articles
    • Date and Number Localization
    • Data Components Export to PDF
    • Details

    You need to call setLocale to apply the new format settings.


dateFormat

sets the default locale date format

string dateFormat;

Example

webix.i18n.dateFormat = "%d-%m-%Y";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings.


decimalDelimiter

a char which separates the decimal part in the float number. The default value is ”.”

string decimalDelimiter;

Example

webix.i18n.decimalDelimiter = "'";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new configuration.


decimalSize

the number of decimal digits in the float number

number decimalSize;

Example

webix.i18n.decimalSize = 8;
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new configuration


fileSize

sets abbreviations for file sizes from byte to exabyte

array fileSize;
Details

The defaukt value for the North American locale is ["b","Kb","Mb","Gb","Tb","Pb","Eb"].


fullDateFormat

sets the default locale date-time format

string fullDateFormat;

Example

webix.i18n.fullDateFormat = "%d-%m-%Y %H:%i";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings


groupDelimiter

a char which separates groups of digits. The default value is ”,”;

string groupDelimiter;

Example

webix.i18n.groupDelimiter = "'";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new configuration


groupSize

the number of digits in a group. The default value is 3

number groupSize;

Example

webix.i18n.groupSize = 4;
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new configuration


locales

creates a new locale

object locales;

Example

webix.i18n.locales["es-ES"]={   //"es-ES" - the locale name, the same as the file name
  groupDelimiter:" ",       //a mark that divides numbers with many digits into groups
  groupSize:3,              //the number of digits in a group
  decimalDelimiter:",",     //the decimal delimiter
  decimalSize:2,            //the number of digits after the decimal mark

  //applied to columns with 'format:webix.i18n.dateFormatStr'
  dateFormat:"%d/%m/%Y",
  //applied to columns with 'format:webix.i18n.dateFormatStr'
  timeFormat:"%H:%i",
  //applied to columns with 'format:webix.i18n.longDateFormatStr'
  longDateFormat:"%d %F %Y",
  //applied to cols with 'format:webix.i18n.fullDateFormatStr'
  fullDateFormat:"%d.%m.%Y %H:%i",
  am:null,
  pm:null,
  //€ - currency name. Applied to cols with 'format:webix.i18n.priceFormat'
  price:"{obj} €",
  calendar:{
    monthFull:["Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio", "Julio", "Agosto",
         "Septiembre", "Octubre", "Noviembre", "Diciembre"],
    monthShort:["En", "Feb", "Mar", "Abr", "Mayo", "Jun", "Jul", "Ago", "Sep", "Oct",
         "Nov", "Dic"],
    dayFull:["Domingo", "Lunes", "Martes", "Miercoles", "Jueves", "Viernes", "Sabado"],
    dayShort:["Dom", "Lun", "Mar", "Mier", "Jue", "Vier", "Sab"]
  },
  hours: "Horas ",
  minutes: "Minutos",
  done:"Listo",

  controls:{
    select:"Seleccione"
  }
};

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization


longDateFormat

sets the default locale the long-date format

string longDateFormat;

Example

webix.i18n.longDateFormat = "%d %F %Y";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings


parseFormat

sets the default locale parsing date format. Initially it is "%Y-%m-%d "%H:%i".

string parseFormat;

Example

//altering format for North Americal locale
webix.i18n.parseFormat = "%d-%m-%Y";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings


parseTimeFormat

sets the default locale parsing time format. Initially it is %H:%i.

string parseTimeFormat;

Example

//altering format for North Americal locale
webix.i18n.parseTimeFormat = "%H:%i:%s";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings


price

sets the default locale price format

string price;

Example

webix.i18n.dateFormat = "${obj}";
webix.i18n.setLocale();

See also

  • api
    • setLocale, priceSettings
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings


priceSettings

sets the format of the price number

object priceSettings;

Example

webix.i18n.priceSettings:{
    groupSize:3,        // the number of digits in a group
    groupDelimiter:" ", // a mark that divides numbers with many digits into groups
    decimalDelimiter:"",// the decimal delimiter
    decimalSize:0       // the number of digits after the decimal mark
}
webix.i18n.setLocale();

See also

  • api
    • price,setLocale
  • articles
    • Date and Number Localization
    • Details

    As a string the parameter can take only one of a predefined set of values.
    The predefined values are:

    • 'null' - the value 'says' to apply the default number setting

    You need to call setLocale to apply the new format settings


spreadsheet

default locales for spreadsheet labels and tooltips

spreadsheet;

Example

webix.i18n.spreadsheet = {
    "labels": {
        // formats
        "common": "Common",
        "currency": "Currency",
        "number": "Number",
        "percent": "Percent",
        // titles
        "undo": "Undo/Redo",
        "font": "Font",
        "text": "Text",
        "cell": "Cell",
        "align": "Align",
        "format": "Format"
    },
    "tooltips": {
        "color": "Font color",
        "background": "Background color",
        "font-family": "Font family",
        "font-size": "Font size",
        "text-align": "Horizontal align",
        ...
    }
};

webix.i18n.setLocale();

See also

  • api
    • setLocale
  • articles
    • Localizing SpreadSheet


timeFormat

sets the default locale time format

string timeFormat;

Example

webix.i18n.timeFormat = "%H:%i";
webix.i18n.setLocale();

See also

  • api
    • setLocale
  • samples
    • Internationalization
  • articles
    • Date and Number Localization
    • Details

    You need to call setLocale to apply the new format settings


locale

Localization strings.

Currently, there is no so much here.

Other
pager the labels for the pager buttons


Others

pager the labels for the pager buttons


pager

the labels for the pager buttons

object pager;

Example

webix.locale.pager = {
    firts:"<<",
    prev:"<",
    next:">",
    last:">>"
};

See also

  • samples
    • Pager localization
  • articles
    • Paging with Datatable


markup

Implements loading from html.

Methods
init | inits Webix component defined by markup in HTML layout
parse | inits a component defined by markup
Other
attribute
dataTag
namespace


Methods

init | inits Webix component defined by markup in HTML layout
parse | inits a component defined by markup


init

inits Webix component defined by markup in HTML layout

WebixView init(string node,string target);

Parameters

node | string | datasource (by default data is taken from document body).
target | string | where should the newly created component be placed.

Returns

WebixView newly constructed UI

Example

//data is taken from and placed to document body
var ui = webix.markup.init();

Related sample: Load UI by ajax
Details

By default, markup is taken from document.body node while the target either concides with datasource node or specified manually.

Data can be as well taken from separate file or come as server response:

    webix.ajax("data/config.xml", function(text, data){
        var config = webix.markup.parse(text, "xml");
        webix.ui(config);
    });

Related sample: Load UI by ajax

See also

  • api
    • parse
  • samples
    • HTML initialization
    • XML initialization
  • articles
    • Initialization from Markup


parse

inits a component defined by markup

void parse(any data,string datatype);

Parameters

data | any | data for parsing (html or xml)
datatype | string | data type - "html" or "xml"

Example

webix.ui(
    webix.markup.parse(text, "xml")
);

See also

  • api
    • init
  • samples
    • Load UI by ajax
  • articles
    • Initialization from Markup


Others

attribute
dataTag
namespace


attribute

attribute;


dataTag

dataTag;


namespace

namespace;


promise

Interface for working with promise objects..

For more details, read the Ajax operations documentation.

Methods
all | resolves all promises in the result array
defer | create a new instance of a deferred object (a `promise`)
fcall | calls a function and resolves as a promise
nfcall | calls a node-style function (eg. expects callback as function(err, callback))


Methods

all | resolves all promises in the result array
defer | create a new instance of a deferred object (a `promise`)
fcall | calls a function and resolves as a promise
nfcall | calls a node-style function (eg. expects callback as function(err, callback))


all

resolves all promises in the result array

void all(promise promise, [promise morepromises] );

Parameters

promise | promise | 'promise' object
morepromises | promise | 'promise' object(s)

Example

a = webix.ajax("someA.php");
b = webix.ajax("someB.php");
c = webix.ajax("someC.php");

webix.promise.all([ a,b,c ]).then(function(results){
    var a_result = results[0];
    var b_result = results[1];
    var c_result = results[3];
    // do something
});

Details

The function is executed when callbacks have been received from all of the requests for which 'promise' objects have been passed into the function.


defer

create a new instance of a deferred object (a promise)

promise defer();

Returns

promise 'promise' object


fcall

calls a function and resolves as a promise

promise fcall();

Returns

promise 'promise' object


nfcall

calls a node-style function (eg. expects callback as function(err, callback))

promise nfcall();

Returns

promise 'promise' object


rules

Validation rules.

Those rules can be used as validation terms for data saving and data validation operations.

You are free to extend this collection.

Methods
isChecked | checks whether a checkbox is checked
isEmail | checks whether the typed data complies with the rules of email address writing
isNotEmpty | checks whether the text field is empty or not
isNumber | checks whether the value in the text field numeric or not


Methods

isChecked | checks whether a checkbox is checked
isEmail | checks whether the typed data complies with the rules of email address writing
isNotEmpty | checks whether the text field is empty or not
isNumber | checks whether the value in the text field numeric or not


isChecked

checks whether a checkbox is checked

boolean isChecked();

Returns

boolean true if value is positive

Example

rules:{ // component's name is used to apply the rule to it
         "accept": webix.rules.isChecked
       }

See also

  • api
    • validate
    • rules
    • ui.text
    • ui.form
    • ui.htmlform
  • samples
    • Basic Validation
  • articles
    • Data Validation


isEmail

checks whether the typed data complies with the rules of email address writing

boolean isEmail();

Returns

boolean true if value is email

Example

rules:{ // component's name is used to apply the rule to it
        "login":webix.rules.isEmail
       }

See also

  • api
    • validate
    • rules
    • ui.text
    • ui.form
    • ui.htmlform
  • samples
    • Basic Validation
  • articles
    • Data Validation


isNotEmpty

checks whether the text field is empty or not

boolean isNotEmpty();

Returns

boolean true if value is not empty

Example

rules:{ // component's name is used to apply the rule to it
        "login":webix.rules.isNotEmpty
       }

Details

There should be at least one character in the text field to pass validation.

See also

  • api
    • validate
    • rules
    • ui.text
    • ui.form
    • ui.htmlform
  • samples
    • Basic Validation
  • articles
    • Data Validation


isNumber

checks whether the value in the text field numeric or not

boolean isNumber();

Returns

boolean true if value is a number

Example

rules:{ //component's name is used to apply the rule to it
       login: webix.rules.isNumber
    }

Details

All characters typed into the specified text field must be numbers to pass validation.

See also

  • api
    • validate
    • rules
    • ui.text
    • ui.form
    • ui.htmlform
  • samples
    • Validation with Predefined Rules
  • articles
    • Data Validation


storage.cookie

Interface for storing data in cookies.

Methods
clear | clears browser cookie
get | gets data from the storage
put | puts data into the storage
remove | removes a data item associated with the specified key from the storage


Methods

clear | clears browser cookie
get | gets data from the storage
put | puts data into the storage
remove | removes a data item associated with the specified key from the storage


clear

clears browser cookie

void clear();


get

gets data from the storage

object get(string name);

Parameters

name string the data key

Returns

object a data item from the storage associated with the key or null

Example

var weather = webix.storage.cookie.get('weather');


put

puts data into the storage

void put(string name,object value);

Parameters

name | string | the data key
value | object | a data item that should be associated with the specified data key

Example

webix.storage.cookie.put('weather', { temperature: 23, rain: false });


remove

removes a data item associated with the specified key from the storage

void remove(string name);

Parameters

name string the data key

Example

webix.storage.cookie.remove('weather');


storage.local

Interface for storing data in local storage.

Methods
clear | clears all data in the browser local storage
get | gets data from the storage
put | puts data into the storage
remove | removes a data item associated with the specified key from the storage


Methods

clear | clears all data in the browser local storage
get | gets data from the storage
put | puts data into the storage
remove | removes a data item associated with the specified key from the storage


clear

clears all data in the browser local storage

void clear();


get

gets data from the storage

object get(string name);

Parameters

name string the data key

Returns

object a data item from the storage associated with the key or null

Example

view.parse(webix.storage.local.get("app_data"));

See also

  • api
    • put
  • articles
    • Webix Storage Interface


put

puts data into the storage

void put(string name,object value);

Parameters

name | string | the data key
value | object | a data item that should be associated with the specified data key

Example

//data that was just changed
view.attachEvent("onAfterEditStop", function(){
        webix.storage.local.put("app_data", this.serialize());
});

See also

  • api
    • get
  • articles
    • Webix Storage Interface


remove

removes a data item associated with the specified key from the storage

void remove(string name);

Parameters

name string the data key

Example

webix.storage.local.remove("app_data");


storage.session

Interface for storing data in session storage.

Beware that data will be lost after browser closing.

Methods
clear | clears all the session data
get | gets data from the storage
put | puts data into the storage
remove | removes a data item associated with the specified key from the storage


Methods

clear | clears all the session data
get | gets data from the storage
put | puts data into the storage
remove | removes a data item associated with the specified key from the storage


clear

clears all the session data

void clear();


get

gets data from the storage

object get(string name);

Parameters

name string the data key

Returns

object a data item from the storage associated with the key or null

Example

var weather = webix.storage.session.get('weather');


put

puts data into the storage

void put(string name,object value);

Parameters

name | string | the data key
value | object | a data item that should be associated with the specified data key

Example

webix.storage.session.put('weather', { temperature: 23, rain: false });


remove

removes a data item associated with the specified key from the storage

void remove(string name);

Parameters

name string the data key

Example

webix.storage.session.remove('weather');


ui.accordion

A container control that presents multiple horizontal or vertical panes.

A collection of panes that make up the component allows you to organize the content in a space-saving way.
The main difference from a standard layout is that accordion can be collapsed/expanded by clicking on the header of a pane. Check accordion documentation for more detailed description.

Constructor

var accordion = webix.ui({
    view:"accordion",
    type:"wide",
    cols:[
        { header:"col 1", body:"content 1", width:150 },
        { header:"col 2", body:"content 2", width:150 },
        { header:"col 3", body:"content 3", width:150 },
        { header:"col 4", body:"content 4", width:150 },
        { header:"col 5", body:"content 5", width:150 }
    ]
});

Where to start

  • Overview of Accordion Widget
  • Samples
Based on: ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterCollapse | fires after an item collapses in the accordion
onAfterExpand | fires after an item expands in the accordion
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
collapsed | 'says' to display initially all accordion cells collapsed
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multi | enables/disables mode when several panels can be visible at once
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
panelClass | returns the name of a css class applied to the accordion panels
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


addView

add new view to layout-like component

WebixView addView(object view, [number index] );

Parameters

view | object | configuration of new view
index | number | index, at which new view will be added

Returns

WebixView new view object

Example

webix.ui({
    id:"mylayout",
    rows:[...]
});
//adds template as third cell to some existing layout
$$("smylayout").addView({ template:"New one" }, 2);

Details

The method works for layout rows and cols, multiview cells, accordion and carousel panels, toolbar and form controls.

See also

  • api
    • removeView
    • ui
  • samples
    • Dynamic Layout Rebuilding
  • articles
    • Dynamic UI Modifications


adjust

adjusts the component to the size of the parent HTML container

void adjust();

Example

$$('view').adjust();

Details

The method changes the width and height of the component to fit the parent HTML container.
If you want to resize the component in the layout according to its widht and height settings, you need to use the resize method.

<div id='mybox' style='width:100px; height:200px;'></div>
webix.ui({ view:"tree", id:"mytree", container:"mybox"});
...
document.getElementById('mybox').style.width = "200px"; //after the container box is resized
$$('mytree').adjust();                           //component needs adjusting to the new size

See also

  • api
    • resize
  • samples
    • Dynamical adjusting to the parent container
  • articles
    • Resizing Components,
    • Sizing components


bind

binds components

void bind(object target, [function rule,string format] );

Parameters

target | object | an object that binds to the calling component
rule | function | sets the rule according which components will be bound
format | string | the format of bound data

Example

$$('form1').bind($$('list1'));

gridb.bind(grida, function(slave, master){
        if (!master) return false;
    return master.id == slave.movie;
});

Details

Behavior of data binding differs for different components a lot. Basically, it fills component with data based on selection in the master component.

The technique allows you to create complex data updates schemes, but you can ignore it as the same use case can be implemented through events and custom logic.

Binding rule defines a rule according to which records in the slave component are filtered. It can be defined only in case slave component is based on DataStore (all data management components except for tree-like) or TreeStore (tree and treetable).

See also

  • api
    • unbind
  • samples
    • Binding to List
    • Linking tables
    • List Data Bound to Richselect
  • articles
    • Data Binding and Syncing
    • Working with Bound Components


define

redefines a single configuration property (or a hash of properties)

void define(string property,any value);

Parameters

property | string | the property name or a hash of properties that need redefining
value | any | the new property value

Example

//redefines the datafeed url
$$('mylist').define("url", "new_data.xml");
$$('mylist').refresh();

//changes the label of the button
$$('button1').define("label", "New value");
$$('button1').refresh();

//change multiple properties at once
$$('text2').define({
    value:"123",
    label:"New label"
});
$$('text2').refresh();

Details

The component should be refreshed to make the changes come into force.

Redefining "config" object

You can use the config property to get the desired configuration option:

var width = $$("myList").config.width;

config is especially useful when a property is presented by an object:

var fieldWidth = $$('myGrid').config.fields['field_1'].width;

Note, in this case after $$("component_id").config you should write the complete dependency property inheritance chain.

See also

  • api
    • config
    • refresh
    • customize
  • samples
    • Dynamical adjusting to the parent container
    • Named Templates
  • articles
    • Resizing Components


destructor

destructs the calling object

void destructor();

Example

function recreate_grid(){
    if (grid)
        grid.destructor();

    grid = new webix.ui({
    ..//new grid config
    });
}

Details

The destructor removes all HTML elements of the object, and detaches all related events.

Unloading destructors for all on-page components are called automatically and generally, you don't need to care about this.

See also

  • samples
    • Internationalization
  • articles
    • Start Coding with Webix


disable

disables the calling view (makes it dimmed and unclickable)

void disable();

Example

$$('mylist').disable();

See also

  • api
    • enable
  • samples
    • Disabling Components
  • articles
    • Disabling/Enabling Components


enable

enables the calling view that was disabled by the 'disable' method

void enable();

Example

$$('mylist').disable();
...
$$('mylist').enable();

See also

  • api
    • disable
  • samples
    • Disabling Components
  • articles
    • Disabling/Enabling Components


getChildViews

returns child views of the calling component

array getChildViews();

Returns

array an array of child views objects

Example

webix.ui({
    id:"mylayout",
    rows:[
        { view:"toolbar", type:"MainBar" },
        ...
    ]
});

var toolbar = $$('myLayout').getChildViews()[0];
var tbarName = $$('myLayout').getChildViews()[0].name;

See also

  • api
    • getParentView
  • articles
    • View


getFormView

returns master form for the input

WebixView getFormView();

Returns

WebixView view object of master form

Example

$$("mytext").getFormView().validate();


getNode

returns the main HTML container for the calling object

object getNode();

Returns

object the HTML container object

Example

var box = dtable.getNode();

See also

  • articles
    • View


getParentView

returns the parent view of the component

object getParentView();

Returns

object the parent object

Example

webix.ui({
  rows:[
    { id:"myview", template:"some" }
  ]
});

var layout = $$('myview').getParentView();

See also

  • api
    • getChildViews
  • samples
    • Colorpicker in Form
  • articles
    • View


getTopParentView

returns top parent view

WebixView getTopParentView();

Returns

WebixView top parent view

Example

this.getTopParentView().hide();

Details
  • For layout element - top layout
  • For element in window - window
  • For element in custom component based on IdSpace - custom component


hide

hides the view

void hide();

Example

$$('mylist').hide();

Details

The same effect can be achieved if you set the hidden parameter in the view constructor.

Performance tip

As alternative to the hide, show api, you can use the ui.multiview component to switch between views.

See also

  • api
    • show
    • hidden
  • samples
    • Popup Menu
  • articles
    • Common Functions to Switch Between Views
    • Managing Visibility of Components


index

returns the cell index in the accordion collection

number index(object obj);

Parameters

obj object the cell object

Returns

number the cell index in the collection of the parent accordion

Example

$$("myAcc").index($$('cell1'))

See also

  • articles
    • View


isEnabled

checks whether the view is enabled

boolean isEnabled();

Returns

boolean true if the view is enabled, otherwise - false

Example

$$('mylist').isEnabled();

See also

  • api
    • enable
    • disable
  • samples
    • Disabling Components
  • articles
    • Disabling/Enabling Components


isVisible

checks whether the view is visible

boolean isVisible();

Returns

boolean true, if the calling object is visible

Example

$$('my_list').isVisible();

See also

  • api
    • hide
    • show
  • articles
    • Managing Visibility of Components


reconstruct

rebuilds the layout

void reconstruct();

Example

$$('mylayout').reconstruct();

See also

  • articles
    • Changing Properties of Components


removeView

removes view from layout-like component

void removeView(id id);

Parameters

id id id of child view, which need to be removed

Example

webix.ui({
    id:"mylayout"
    cols:[
      { id:"mytemplate1" },
      { id:"mytemplate2" },
      { id:"mytemplate3" }
   ]
})
...
$$("mylayout").removeView("mytemplate2");

Details

The method works for layout rows and cols, multiview cells, accordion and carousel panels, toolbar and form controls.

See also

  • api
    • addView
    • ui
  • samples
    • Dynamic Layout Rebuilding
  • articles
    • Dynamic UI Modifications


resize

adjusts the view to a new size

void resize();

Example

dtable = new webix.ui({
        view:"datatable",
        ...
})

dtable.define("width", 700);
dtable.resize();

Details

You may need to use this method if you want to change the width or height of the component.

$$('list1').config.width = 200;
$$('list1').config.height = 200;
$$('list1').resize();

If a component is placed into some layout - you need not to call resize for the parent layout, it will adjust automatically.

Performance tip

If you set sizes for multiple components,it makes sense to set sizes for all of them at first and only then call resize().

$$('list1').config.width = 200;
$$('list1').config.height = 200;

$$('list2').config.width = 600;
$$('list2').config.height = 400;

$$('list1').resize();
$$('list2').resize();

See also

  • api
    • adjust
    • config
    • define
  • samples
    • Dynamical adjusting to the parent container
  • articles
    • Sizing components
    • Sizing and Resizing


resizeChildren

resizes all children of the calling component

void resizeChildren();

Example

$$('myAccord').resizeChildren();

See also

  • articles
    • Resizing Components


show

makes the component visible

void show( [boolean force,boolean animation] );

Parameters

force | boolean | when set to true command will show not only the current view but all parent views as well (can be used for nested tabviews or nested mutliviews )
animation | boolean | enables|disables animation during view showing

Example

//default
$$("list").show();
//without animation
$$("list").show(false, false);

Details

This method helps showing the views that were hidden before:

  • either with hide method;
  • or with hidden parameter.

The same effect as show() can be achieved if you set the hidden parameter in the view constructor to the true value.

Performance tip

With standard views (not windows) you can use an alternative to the hide, show api, namely the ui.multiview functionality to switch between views.

See also

  • api
    • hide
    • hidden
  • articles
    • Common Functions to Switch Between Views
    • Managing Visibility of Components


showBatch

makes visible those elements which parameter 'batch' is set to the specified name

void showBatch(string name);

Parameters

name string the batch name

Example

webix.ui({ view:"toolbar", id:"mybar", visibleBatch:"b2", cols:[
    {view:"button",  value:"Save",   batch:"b1"},
    {view:"button",  value:"Cancel", batch:"b1"},
    {view:"button",  value:"Edit",   batch:"b2"},
    {view:"button",  value:"Back",   batch:"b2"}]
});
...
$$("mybar").showBatch("b1");

See also

  • api
    • visibleBatch
  • samples
    • Hiding and Showing Groups of Controls
  • articles
    • Managing Visibility of Components


unbind

breaks "bind" link

void unbind();

Example

$$("table").unbind();

Details

The opposite to the "bind" command. Can be used if master control need to be changed.

See also

  • api
    • bind


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
collapsed | 'says' to display initially all accordion cells collapsed
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multi | enables/disables mode when several panels can be visible at once
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
panelClass | returns the name of a css class applied to the accordion panels
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


animate

defines or disables view change animation.

boolean|object animate;

Example

webix.ui({
   view:"multiview",
   cells:[{ ... }],
   animate:{type:"flip", subtype:"vertical"}
});

See also

  • samples
    • DataTable paging animation types
    • Animated Multiview
  • articles
    • Animation
    • Details

    Disabling animation

    To totally disable animation, set the parameter to the false value:

    webix.ui({
    view:"multiview",
    animate:false
});

    Object properties

    As an object, the parameter takes 3 properties:

    • direction - the animation direction (optional).
      • left, right, top, bottom
    • type - the type of animation. The default value - 'slide'.
      • slide, flip
    • subtype - the subtype of animation. The default value - 'together'.
      • if type:slide
        • together, in, out
      • if type:flip
        • horizontal, vertical


borderless

used to hide the component borders

boolean borderless;

Example

webix.ui({
    view:"list",
    borderless:true
});

See also

  • samples
    • Toolbar: Multiple Rows
  • articles
    • Setting Borders to the Components


collapsed

'says' to display initially all accordion cells collapsed

boolean collapsed;

Example

webix.ui({
    view:"accordion",
    collapsed:true,
    cols:[{..}]
    ...
})

See also

  • api
    • collapse
  • samples
    • Horizontal Accordion
  • articles
    • Accordionitem Configuration


cols

array of cells objects arranged horizontally

array cols;

Example

webix.ui({
    container:"box",
    view:"accordion",
    cols:[
        { header:"col 1", body:"content 1", width:150},
        { header:"col 2", body:"content 2", width:250}
    ]
});

See also

  • api
    • rows
  • samples
    • Horizontal Accordion
  • articles
    • Layout and Resizer


container

an html container (or its id) where the component needs initializing

HTMLElement container;

Example

<div id="box" style="width:320px; height:600px;"></div>
webix.ui ({
    container:"box",
    view:"list",
    ...
});

See also

  • samples
    • List
  • articles
    • Start Coding with Webix
    • View


css

the name of a css class that will be applied to the view container

string css;

Example

<style>
.myClass {
    font-style: italic;
}
</style>
webix.ui({
    css:"myClass",
    view:"dataview",
    ...
});

See also

  • samples
    • Basic styling
  • articles
    • Component Styling
    • Details

    Setting the parameter, for example, to the "myClass" value will produce HTML like this:

    <div class='myClass'>...</div>


disabled

indicates whether an item is enabled or not

boolean disabled;

Example

webix.ui({
    view:"button",
    disabled:true
});

Details

By dafaults all items are enabled, i.e. the value is false.

A disabled item looses focus and will not react on mouse events.

Same state can be forced through Webix API:

$$("button1").disable();
$$("button1").enable();


gravity

sets the view gravity (1 by default)

number gravity;

Example

//equal sizes
webix.ui({
    cols:[
        { gravity:1, template:"left" },
        { gravity:1, template:"right" }
    ]
});

//the left area two times wider than the right one
webix.ui({
    cols:[
        { gravity:2, template:"left" },
        { gravity:1, template:"right" }
    ]
});

See also

  • samples
    • Minimum Size for Layout's Cells
  • articles
    • Sizing components
    • Details

    The parameter is used to set relative size proportions for the elements within the common parent container.


height

sets the height of the component

number height;

Example

webix.ui ({
    view:"window",
    height:300,
    width:300,
    ...
});

See also

  • api
    • width
  • samples
    • Horizontal Accordion
  • articles
    • Sizing components


hidden

defines whether the view will be hidden initially

boolean hidden;

Example

webix.ui ({
    view:"window",
    hidden:true,// the window will be hidden initially.
    ...         // To show it again, use the show() method.
});

See also

  • api
    • show
    • hide
  • articles
    • Managing Visibility of Components


id

the component ID

string|number id;

Example

webix.ui({
    view:"window",
    id:"win3",
    ...
});

$$('win3').close();

See also

  • samples
    • Windows: Basic Initialization
  • articles
    • Start Coding with Webix
    • View
    • Details

    The parameter can contain any string or numeric value and doesn't have a limit on length.

    It is used when referring to the component to apply and methods to it, attach events and getting to its properties.


isolate

masks IDs of all inner element

boolean isolate;

Example

webix.ui({
        isolate:true,
        cols:[
            { view:"button", value:"Load" },
            { view:"button", value:"Save" },
            { view:"button", value:"Delete" }
        ]
});

Details

This property allows to reuse the same IDs
For example you can use something like this

webix.ui({
   cols:[
     { id:"col1", isolate:true, rows:[
        { view:"list", id:"mylist" },
        { template:"Details", id:"details" }
     ]},
     { id:"col2", isolate:true, rows:[
        {view:"list", id:"mylist" },
        { template:"Details", id:"details" }
     ]}
   ]
});

In above code snippet there are two blocks which are using the same IDs, so there is no way to access the list by its ID directly. Because of isolate property - two elements with the same ID can exists , and can be located in the next way

//will not work
var list = $$("mylist"); // will return second list

//will work
var list1 = $$("col1").$$("mylist");
var list2 = $$("col2").$$("mylist");


margin

defines the space around elements (applies the specified value to all elements)

number margin;

Example

webix.ui({
        container:"box",
        view:"toolbar",
        margin:20,
        cols:[
            { view:"button", value:"Load" },
            { view:"button", value:"Save" },
            { view:"button", value:"Delete" }
        ]
});

Details

The image below shows how the script above applies the margin property.


maxHeight

sets the maximum height for the view

number maxHeight;

Example

webix.ui({
    view:"some",
    maxHeight:1000,
    ...
});

See also

  • api
    • minHeight
    • maxWidth
    • minWidth
  • samples
    • Minimum Size for Layout's Cells
  • articles
    • Layout and Resizer
    • Sizing components
    • Controls Guide
    • Details
    • The view can take the height not bigger than the specified value.
    • If there is not enough space for the specified height - the view will shrink down.
    • During resizing the view can't take the size bigger than the value of maxHeight.


maxWidth

sets the maximum width for the view

number maxWidth;

Example

webix.ui({
    view:"some",
    maxWidth:1000,
    ...
});

See also

  • api
    • minWidth
    • maxHeight
    • minHeight
  • samples
    • Limits on Resizing
  • articles
    • Layout and Resizer
    • Sizing components
    • Controls Guide
    • Details
    • The view can take the width not bigger than the specified value.
    • If there is not enough space for the specified width - the view will shrink down.
    • During resizing the view can't take the size bigger than the value of maxWidth.


minHeight

sets the minimal height for the view

number minHeight;

Example

webix.ui({
    view:"some",
    minHeight:100,
    ...
});

See also

  • api
    • maxHeight
    • maxWidth
    • minWidth
  • samples
    • Minimum Size for Layout's Cells
  • articles
    • Layout and Resizer
    • Sizing components
    • Controls Guide
    • Details
    • The view can take the height not less than the specified value.
    • If more (free) space is available - the view will take it.
    • During resizing the view can't take the size lesser than the value of minHeight.


minWidth

sets the minimal width for the view

number minWidth;

Example

webix.ui({
    view:"some",
    minWidth:100,
    ...
});

See also

  • api
    • maxWidth
    • maxHeight
    • minHeight
  • samples
    • Limits on Resizing
  • articles
    • Layout and Resizer
    • Sizing components
    • Controls Guide
    • Details
    • The view can take the width not less than the specified value.
    • If more (free) space is available - the view will take it.
    • During resizing the view can't take the size lesser than the value of minWidth.


multi

enables/disables mode when several panels can be visible at once

boolean|string multi;

Example

webix.ui({
    cols:[{ view:"accordion",
        multi:true,
        ...
    }]
})

See also

  • samples
    • Horizontal Accordion
  • articles
    • Accordion
    • Details

    Possible value here are:

    • true (default) - all panels can be expanded as well as collapsed at a time;
    • false - only one panel can be (and must be) visible at a time;
    • "mixed" - all panels can be expanded at a time, but you cannot close them all. One pane remains visible.


on

allows attaching custom handlers to inner events of the component

object on;

Example

webix.ui({
    view:"list",
    ...
    on:{
        'onItemClick': function(id){ alert("you have clicked on an item with id="+id); }
    }
});

See also

  • api
    • EventSystem,
    • detachEvent,
    • attachEvent
    • callEvent
  • samples
    • Context Menu
  • articles
    • Event Handling
    • Details

    All keys defined in the object will be processed as the names of events, and their values as the related handlers.

    The property can be used as an alternative to the attachEvent method.


padding

defines the space between the element borders and content (applies the specified value to all sides).

number padding;

Example

webix.ui({
        container:"box",
        view:"toolbar",
        padding:10,
        cols:[
            { view:"button", value:"Load" },
            { view:"button", value:"Save" },
            { view:"button", value:"Delete" }
        ]
});

See also

  • api
    • paddingX
    • paddingY
    • Details

    The image below shows how the script above applies the padding property.


paddingX

sets the right and left padding (applies the specified value to both sides)

number paddingX;

Example

webix.ui({
        container:"box",
        view:"toolbar",
        paddingX:20,
        cols:[
            { view:"button", value:"Load" },
            { view:"button", value:"Save" },
            { view:"button", value:"Delete" }
        ]
});

See also

  • articles
    • paddingY
    • padding
    • Details

    The image below shows how the script above applies the paddingX property.


paddingY

sets the top and bottom padding (applies the specified value to both sides)

number paddingY;

Example

webix.ui({
        container:"box",
        view:"toolbar",
        paddingY:10,
        cols:[
            { view:"button", value:"Load" },
            { view:"button", value:"Save" },
            { view:"button", value:"Delete" }
        ]
});

See also

  • api
    • paddingX
    • padding
    • Details

    The image below shows how the script above applies the paddingY property.


panelClass

returns the name of a css class applied to the accordion panels

string panelClass;

Example

var class = $$('myaccordion').config.panelClass;

See also

  • articles
    • Accordionitem Configuration
    • Accordion CSS
    • Details

    The default value is "accordionitem".


responsive

enables responsive mode for horizontal layout

string responsive;

Example

{ cols:[a,b,c], responsive:"hide" }

Details

When screen width is too small to fit all views, the leftmost one will be hidden or moved to different layout

{
   id:"a1", rows:[
      { cols:[a,b,c], responsive:"a1" } //a1 - id of target layout
   ]
}


rows

array of views objects arranged vertically

array rows;

Example

webix.ui({
    container:"box",
    view:"accordion",
    rows:[
        { header:"col 1", body:"content 1", width:150},
        { header:"col 2", body:"content 2", width:250}
    ]
});

See also

  • api
    • cols
  • samples
    • Layout and Resizer
  • articles
    • Layout and Resizer


type

defines the accordion borders

string type;

Values

  • line
    cells with border (default)
  • clean
    cells without border
  • wide
    cells with border and small space between siblings
  • space
    cells with border and wide space between siblings
  • head
    similar to "wide", but there is any border between the first and second cells

    • Example

    webix.ui({
    type: "space",
    rows: [
    ...
    ]
});

    See also

  • samples
    • Complex Accordion
  • articles
    • Setting Borders to the Components


visibleBatch

sets the batch that will be shown initially

string visibleBatch;


width

sets the width of the component

number width;

Example

webix.ui ({
   view:"window",
   height:300,
   width:300,
   ...
});

See also

  • api
    • height
  • samples
    • Horizontal Accordion
  • articles
    • Sizing components


Events

onAfterCollapse | fires after an item collapses in the accordion
onAfterExpand | fires after an item expands in the accordion
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed


onAfterCollapse

fires after an item collapses in the accordion

void onAfterCollapse(string| number id){ ... };

Parameters

id string| number ID of an item that has just been collapsed

Example

some.attachEvent("onAfterCollapse", function(id){
    //code
});

See also

  • api
    • onAfterExpand
  • articles
    • Accordion


onAfterExpand

fires after an item expands in the accordion

void onAfterExpand(string| number id){ ... };

Parameters

id string| number ID of an item that has just been expanded

Example

some.attachEvent("onAfterExpand", function(id){
    //code
});

See also

  • api
    • onAfterCollapse
  • articles
    • Accordion


onBindRequest

fires when the component is ready to receive data from the master component

void onBindRequest(){ ... };

Example

some.attachEvent("onBindRequest", function(){
    //... some code here ...
});

Details

The event is a part of bind API. Doesn't make sense if it's used stand-alone

See also

  • api
    • bind
  • articles
    • Data Binding and Syncing


onDestruct

occurs when component destroyed

void onDestruct(){ ... };

Example

$$("mygrid").attachEvent("onDestruct", function(){
    this.some = null;
    webix.message("This is the end.");
})

Details

Can be used to free memory or delete the related objects


Others

$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


$getSize

returns the current size of the component

array $getSize();

Returns

array an array of sizes
Details

The method is used in the inner sizing logic and not intended for direct use.
To get component sizes, please use the $width and $height properties

An array of sizes

The returning array contains 5 sizes of the components:

  • min width
  • max width
  • min height
  • max height
  • gravity

See also

  • articles
    • Creating a Custom Component


$height

current height of the view

number $height;

Example

var height = $$("mylist").$height;

Details

Value is not really actual, but last applied

Do not try to set this value


$setSize

sets the component size

boolean $setSize(number x,number y);

Parameters

x | number | the component width
y | number | the component height

Returns

boolean returns true if new size differs from the previous one
Details

The method is used in the inner logic and not intended for direct use.
To set a new size, please define new width, height values and call the resize method.

See also

  • api
    • $getSize, resize
  • articles
    • Creating a Custom Component


$skin

the method which will be called when skin is defined

$skin;

Example

webix.protoUI({
    view:"myview",
    $skin:function(){
         this._settings.height = webix.skin.$active.inputHeight;
    }
}, webix.ui.view);

Details

Can be used to define custom per-skin logic

Method called only once per component type ( like static constructor )

Beware that newly defined method will override the same method of base component.


$view

reference to top html element of the view

HTMLElement $view;

Example

var node = $$("mylist").$view;

Details

Do not try to set this value


$width

current width of the view

number $width;

Example

var height = $$("mylist").$width;

Details

Value is not really actual, but last applied

Do not try to set this value


config

all options from initial component configuration

hash config;

Example

var width = $$("mylist").config.width;

See also

  • api
    • define
    • Details

    Do not try to set this value, if you need to set value - use "define" method


name

indicates the name of the component (a read-only property)

string name;

Example

var data = new webix.DataCollection({
    url:"some_data.json"
});

var name = data.name; //returns 'DataCollection'

Details

The hardcoded value of the property is "DataCollection".


ui.accordionitem

A singular pane of the accordion component.

Each accordion pane consists of a header and a body. The body of a pane can be collapsed/expanded by clicking on the appropriate header. Check accordionitem documentation for more detailed description.

Constructor

var accordionitem = webix.ui({
    view:"accordion",
    height:600,
    rows:[
    {
      view:"accordionitem",
      header:"Pane 1",
      headerHeight:50,
      body:"Pane body 1",
    },
    {
      view:"accordionitem",
      header:"Pane 2",
      body:"Pane body 2",
      collapsed: true
    }]
});

Where to start

  • Overview of Accordionitem
  • Samples
Based on: MouseEvents, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
collapse | collapses the specified accordion item
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
expand | expands the specified accordion item
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | refreshes the header label
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterContextMenu | fires after the context menu was called in the item area
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
body | defines the cell content (a view or some HTML)
borderless | used to hide the component borders
collapsed | displays the cell collapsed initially
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
header | sets the label of the header in the expanded state
headerAlt | sets the label of the header in the collapsed state
headerAltHeight | the height of the header in the collapsed state
headerHeight | the header height
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
collapse | collapses the specified accordion item
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
expand | expands the specified accordion item
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | refreshes the header label
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


collapse

collapses the specified accordion item

void collapse();

Example

webix.ui({
    container:"layout_div",
    view:"accordion",
    multi:true,
    cols:[
        { header:"col 1", id:"item1", body:"content 1"},
        { header:"col 2", id:"item2", body:"content 2"},
    ]
});
...
$$('item1').collapse();

See also

  • api
    • expand
  • articles
    • Accordionitem Configuration


expand

expands the specified accordion item

void expand();

Example

webix.ui({
    container:"layout_div",
    view:"accordion",
    multi:true,
    cols:[
        { header:"col 1", id:"item1", body:"content 1"},
        { header:"col 2", id:"item2", body:"content 2"},
    ]
});
...
$$('item1').expand();

See also

  • api
    • collapse
  • articles
    • Accordionitem Configuration


refresh

refreshes the header label

void refresh();

Example

webix.ui({
    container:"layout_div",
    view:"accordion",
    cols:[
        { header:"col 1", id:"a1", body:"content 1"},
        { header:"col 2", id:"a2", body:"content 2"}
    ]
});

$$("a1").define("header","new header");
$$("a1").refresh(); // header:'col1' -> header:'new header'

See also

  • articles
    • Changing Properties of Components


Properties

animate | defines or disables view change animation.
body | defines the cell content (a view or some HTML)
borderless | used to hide the component borders
collapsed | displays the cell collapsed initially
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
header | sets the label of the header in the expanded state
headerAlt | sets the label of the header in the collapsed state
headerAltHeight | the height of the header in the collapsed state
headerHeight | the header height
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
width | sets the width of the component


body

defines the cell content (a view or some HTML)

string|object body;

Example

webix.ui({
    view:"accordion",
    rows:[{
        header:"panel 1",
        body:{
            id:"films",
            view:"list",
            template:"#title#",
            data: film_set
        }
    },
    {
        header:"panel 2",
        body:"this is the second pane"
    }]
})

See also

  • samples
    • Horizontal Accordion
    • Windows: Basic Initialization
  • articles
    • Accordionitem Configuration
    • Window


collapsed

displays the cell collapsed initially

boolean collapsed;

Example

webix.ui({
    view:"accordion",
    rows:[{
        header:"panel 1",
        body:"content 1"
    },
    {
        header:"panel 2",
        body:"content 2",
        collapsed:true //the second cell will be collapsed initially
    }]
})

See also

  • samples
    • Horizontal Accordion
  • articles
    • Accordionitem Configuration


header

sets the label of the header in the expanded state

boolean|string|function header;

Example

webix.ui({
    view:"accordion",
    rows:[{
        header:"panel 1",
        body:"content 1"
    },
    {
        header:false //hides the header for the second cell
        body:"content 2"
    }]
})

See also

  • api
    • headerHeight
    • headerAlt
    • headerAltHeight
  • samples
    • Horizontal Accordion
  • articles
    • Adding Headers to Components
    • Accordionitem Configuration
    • Details

    The false value will hide the header.


headerAlt

sets the label of the header in the collapsed state

string|function headerAlt;

Example

webix.ui({
    view:"accordion",
    rows:[{
        header:"panel 1",
        headerAlt:"panel 1 (closed)",
        body:"content 1"
    },
    {
        header:"panel 2",
        headerAlt:"panel 2 (closed)",
        body:"content 2"
    }]
});

See also

  • api
    • headerAltHeight
    • header
    • headerHeight
  • samples
    • Horizontal Accordion
  • articles
    • Accordionitem Configuration


headerAltHeight

the height of the header in the collapsed state

number headerAltHeight;

Example

webix.ui({
    view:"accordion",
    rows:[{
        header:"panel 1",
        headerAlt:"panel 1 (closed)",
        headerAltHeight:22,
        body:"content 1"
    },
    {
        header:"panel 2",
        headerAlt:"panel 2 (closed)",
        headerAltHeight:24,
        body:"content 2"
    }]
});

See also

  • api
    • headerAlt
    • header
    • headerHeight
  • articles
    • Accordionitem Configuration


headerHeight

the header height

number headerHeight;

Example

webix.ui({
    view:"accordion",
    rows:[{
        header:"panel 1",
        headerHeight:22,
        body:"content 1"
    },
    {
        header:"panel 2",
        headerHeight:22,
        body:"content 2"
    }]
});

See also

  • api
    • header
    • headerAlt
    • headerAltHeight
  • articles
    • Accordionitem Configuration


mouseEventDelay

the delay between a real mouse action and invoking the related events

number mouseEventDelay;

Example

webix.ui({
   view:"menu",
   mouseEventDelay:100,
   ...
});

See also

  • articles
    • Event Handling
    • Details

    Actual for the onMouseMove and onMouseOut events only.

    The default value is 500ms.


onClick

attaches a click behavior for component items with the specified CSS class.

hash onClick;

See also

  • api
    • onItemClick
    • onClick
    • click
  • samples
    • Progress bar
  • articles
    • Event Handling
    • Details
    • "onClick" behavior is defined for component items rather than for the whole component
    • Use the 'onItemClick' handler to attach function to item clicking regardless of the CSS class;
    • For standard Webix buttons you'd better use the click property to attach a function;
    • on_click handler can override the default onclick event:

grid = new webix.ui({
view:"datatable",
columns:[
        { id:"rank",    header:"", css:"rank",          width:50},
        { id:"title",   header:"Film title",width:200},
        {   id:"", template:"<input class='delbtn' type='button' value='Delete'>",
            css:"padding_less",width:100 }],
on:{
    "onItemClick":function(id, e, trg){
        webix.message("Click on row: " + id.row+", column: " + id.column);}
    } //default click behavior that is true for any datatable cell
},
// click behavior for the cell with a button styled with 'delbtn' class
onClick:{
    "delbtn":function(e, id, trg){
        webix.message("Delete row: "+id);
        return false; //here it blocks default behavior
    }
});


onContext

a property used to define custom context-click (right click) handlers for elements in the DataTable cells

hash onContext;

Example

var dtable = webix.ui({
    view:"datatable",
    ...
    data:[
        { text:"<div class='myActive'>click here</div>" }
    ],
    onContext:{
        "myActive":function(id, event, target){
            webix.message("Active area was right-clicked");
        }
    }
});

Details

It's a hash property that contains all available handlers.
All the handlers (existing and newly-) are specified by the related class name.


onDblClick

attaches a dblclick behavior for component items with the specified CSS class.

function onDblClick;

Example

webix.ui({
    view:"list",
    template:"#value# <div class='webix_remove_upload'>Del</div>"
    onDblClick:{
        "webix_remove_upload":function(ev, id){
              this.remove(id);
        }
    }
});

See also

  • api
    • onItemDblClick
    • onDblClick
  • articles
    • Event Handling
    • Details
    • "onDblClick" behavior is defined for component items rather than for the whole component
    • Use the 'onItemDblClick' handler to attach function to item clicking regardless of the CSS class;


onMouseMove

attaches a mousemove behaviour for component items with the specified CSS class.

function onMouseMove;

Example

webix.ui({
    view:"list",
    template:"#value# <div class='webix_remove_upload'>Del</div>"
    onMouseMove:{
        "webix_remove_upload":function(ev, id){
              webix.message("Danger area");
        }
    }
});

See also

  • api
    • onMouseMove
    • onMouseMoving
    • onMouseMove
  • articles
    • Event Handling
    • Details
    • "onMouseMove" behavior is defined for component items rather than for the whole component
    • Use the "onMouseMove" handler to attach function to item clicking regardless of the CSS class;


Events

onAfterContextMenu | fires after the context menu was called in the item area
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterContextMenu

fires after the context menu was called in the item area

void onAfterContextMenu(string id,Event e,HTMLElement node){ ... };

Parameters

id | string | the id of the clicked item
e | Event | a native event object
node | HTMLElement | the target HTML element

Example

$$('list').attachEvent('onAfterContextMenu', function(id, e, node){
     webix.message("Right mouse button was pressed");
});

See also

  • api
    • onBeforeContextMenu
  • articles
    • ContextMenu


onAfterScroll

occurs when some webix view has been scrolled

void onAfterScroll(object pos ){ ... };

Parameters

pos object object with two values: e - horizontal scroll offset and f - vertical scroll offset

Example

view.attachEvent("onAfterScroll", function(pos){
    //your code here
});


onBeforeContextMenu

fires before the context menu is called in the item area

boolean onBeforeContextMenu(string id,Event e,HTMLElement node){ ... };

Parameters

id | string | the id of the clicked item
e | Event | a native event object
node | HTMLElement | the target HTML element

Returns

boolean returning false will block the event

Example

$$('list').attachEvent('onBeforeContextMenu', function(id, e, node){
     if (some_check(id))
          return false; //blocks the context menu
     else
          return true;
});

See also

  • api
    • onAfterContextMenu
  • articles
    • ContextMenu


onBlur

fires when focus is moved out of the view

void onBlur(object prev_view){ ... };

Parameters

prev_view object the view that has previously been in focus

Example

$$("datatable1").attachEvent("onBlur", function(prev_view){
    // prev_view is the datatable in question
});

See also

  • api
    • onFocus
  • articles
    • Keyboard Events. Focusing. Navigation


onFocus

fires when a view gets focus

void onFocus(object current_view,object prev_view){ ... };

Parameters

current_view | object | the view that is in focus now
prev_view | object | the view that has previously been in focus

Example

$$("datatable1").attachEvent("onFocus", function(current_view, prev_view){
    // current_view is the datatable in question
});

See also

  • api
    • onBlur
  • articles
    • Keyboard Events. Focusing. Navigation


onItemClick

fires when a component item was clicked

void onItemClick(string id,Event e,HTMLElement node){ ... };

Parameters

id | string | the id of the clicked item
e | Event | a native event object
node | HTMLElement | the target HTML element

Example

list.attachEvent("onItemClick", function(id, e, node){
    var item = this.getItem(id);
    //... some code here ...
});

Details

The most common use case for such events is getting info about the component item that has just been clicked. It can be done with a common getItem method that requires item ID as parameter.

See also

  • api
    • onItemDblClick
  • samples
    • 'Show/Back' Navigation
  • articles
    • Event Handling


onItemDblClick

fires when a component item was double-clicked

void onItemDblClick(string id, [ e,HTMLElement node] ){ ... };

Parameters

id | string | the id of the clicked item
e |  | Event a native event object
node | HTMLElement | the target HTML element

Example

grid.attachEvent("onItemDblClick", function(id, e, node){
    //... some code here ...
});

See also

  • api
    • onItemClick
  • samples
    • Chart: Events
  • articles
    • Event Handling


onKeyPress

occurs when keyboard key is pressed for the control in focus

void onKeyPress(number code,event e){ ... };

Parameters

code | number | key code
e | event | event object

Example

text.attachEvent("onKeyPress", function(code, e){
    //code
});

See also

  • api
    • onKeyPress
  • articles
    • Event Handling
    • Keyboard Events. Focusing. Navigation


onLongTouch

fires on holding finger in some position for a certain period of time

void onLongTouch(object context ){ ... };

Parameters

context object object with event parameters

Example

webix.attachEvent("onLongTouch",function(context){
    //your code here
})

Details

The time period is defined by the webix.Touch.longTouchDelay property.

Parameters of the context object are the following:

  • x - {number} horizontal event position
  • y - {number} vertical event postion
  • target - {object} the html element where the event started
  • time - {Date object} the time of event start


onMouseMove

fires when the mouse was moved over the specified component

void onMouseMove(string id,Event e,HTMLElement node){ ... };

Parameters

id | string | the component id
e | Event | a native event object
node | HTMLElement | the target HTML element

Example

some.attachEvent("onMouseMove", function(id, e, node){
    //... some code here ...
});

See also

  • api
    • onMouseOut
    • onMouseMoving
  • samples
    • Chart: Events
  • articles
    • Event Handling


onMouseMoving

fires when the mouse was moved over the component

void onMouseMoving(Event ev){ ... };

Parameters

ev Event a native event object

Example

some.attachEvent("onMouseMoving", function(ev){
    //... some code here ...
});

See also

  • articles
    • Event Handling


onMouseOut

fires when the mouse was moved out from the specified item

void onMouseOut(Event e){ ... };

Parameters

e Event a native event object

Example

some.attachEvent("onMouseOut", function(e){
    //... some code here ...
});

See also

  • api
    • onMouseMove
    • onMouseMoving
  • samples
    • Chart: Events
  • articles
    • Event Handling


onSwipeX

occurs on a horizontal swipe movement

void onSwipeX(object start_context,object current_context){ ... };

Parameters

start_context | object | object with parameters of swipe event start
current_context | object | object with parameters of swipe event end

Example

webix.attachEvent("onSwipeX",function(start_context,current_context){
    //your code here
});

Details

Parameters of the start_context and current_context objects are given below:

  • x - {number} horizontal event position
  • y - {number} vertical event position
  • target - {object} the html element where the event started/ended
  • time - {Date object} the time of event start/end

To check whether the swipe direction is "from right to left" or "from left to right", you can calculate the difference between currentContext.x and startContext.x. If the difference is positive, swipe movement direction was "from left to right". In case of a negative value, the direction was "from right to left".

// example of usage
webix.attachEvent("onSwipeX",function(c1,c2){
   if( c2.x - c1.x > 0 ){
        // swipe from left to right
    }
   else{
       // swipe from right to left
   }
});


onSwipeY

occurs on a vertical swipe movement

void onSwipeY(object start_context,object current_context){ ... };

Parameters

start_context | object | object with parameters of swipe event start
current_context | object | object with parameters of swipe event end

Example

webix.attachEvent("onSwipeX",function(start_context,current_context){
    //your code here
});

Details

Parameters of the start_context and current_context objects are given below:

  • x - {number} horizontal event position
  • y - {number} vertical event position
  • target - {object} the html element where the event started/ended
  • time - {Date object} the time of event start/end

To check whether the swipe direction is "from bottom to top" or "from top to bottom", you can calculate the difference between currentContext.y and startContext.y. If the difference is positive, swipe movement direction was "from bottom to top". In case of a negative value, the direction was "from top to bottom".

// example of usage
webix.attachEvent("onSwipeY",function(c1,c2){
   if( c2.y - c1.y > 0 ){
        // swipe from bottom to top
    }
   else{
       // swipe from top to bottom
   }
});


onTimedKeyPress

fires after typing has been finished in the field

void onTimedKeyPress(){ ... };

Example

text.attachEvent("onTimedKeyPress", function(){
    //code
});

Details

Event will not occur while user typing. But will occur after some delay in typing.

It is a best play to start filtering or some other heavy operation.

You can change default 250ms delay, by using keyPressTimeout property

webix.ui({
    view:"search",
    keyPressTimeout:100 //100ms delay
});

See also

  • api
    • onKeyPress
  • articles
    • Event Handling
    • Keyboard Events. Focusing. Navigation


onTouchEnd

occurs when the touch event is ended

void onTouchEnd(object start_context,object current_context){ ... };

Parameters

start_context | object | object with parameteres of touch event start
current_context | object | object with parameteres of touch event end

Example

webix.attachEvent("onTouchEnd",function(start_context,current_context){
    //your code here
});

Details

Parameters of the start_context and current_context objects are given below:

  • x - {number} horizontal event position
  • y - {number} vertical event position
  • target - {object} the html element where the event started/ended
  • time - {Date object} the time of event start/end


onTouchMove

occurs during touch movement

void onTouchMove(object start_context,object current_context){ ... };

Parameters

start_context | object | object with parameteres of touch movement start
current_context | object | object with parameteres of touch movement end

Example

webix.attachEvent("onTouchMove",function(start_context,current_context){
    //your code here
});

Details

Parameters of the start_context and current_context objects are given below:

  • x - {number} horizontal event position
  • y - {number} vertical event position
  • target - {object} the html element where the event started/ended
  • time - {Date object} the time of event start/end


onTouchStart

when some webix view has been touched

void onTouchStart(object context ){ ... };

Parameters

context object object with event parameters

Example

webix.attachEvent("onTouchStart",function(context){
    //your code here
})

Details

Parameters of the context object are the following:

  • x - {number} horizontal event position
  • y - {number} vertical event position
  • target - {object} the html element where the event started
  • time - {Date object} the time of event start


onViewResize

view size was changed by resizer

void onViewResize(){ ... };

Example

view.attachEvent("onViewResize", function(){
   //...
})

Details

Called only when size of view was changed by layout's resizer


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.


$scope

scope for resolving event and method names

object $scope;

Example

some.$scope = {
   action:function(){ alert("works"); }
};
some.attachEvent("onItemClick", "action");

Details

When event name or click handler defined as string name, component will check is the handler with such name exists in the $scope object first, and only after that will try to locate the global handler with the same name.


on_click

redefines default click behavior for component items.

function on_click;

Example

webix.protoUI({
    name:"mylist",
    defaults:{
        template:"#value# <div class='webix_remove_upload'>Del</div>"
    },
    on_click:{
        "webix_remove_upload":function(ev, id){
              this.remove(id);
        }
    }
}, webix.ui.list);

See also

  • api
    • onItemClick
    • onClick
    • click
  • samples
    • Progress bar
  • articles
    • Event Handling
    • Details
    • "on_click" stores default and attached click behavior for component items;
    • Additional click events are attched with the 'onItemClick' handler;
    • For standard Webix buttons you'd better use the click property to attach a function;
    • on_click handler is used to redefine the default onclick event right in the component constructor:

grid = new webix.ui({
view:"datatable",
columns:[
        { id:"rank",    header:"", css:"rank",          width:50},
        { id:"title",   header:"Film title",width:200},
        {   id:"", template:"<input class='delbtn' type='button' value='Delete'>",
            css:"padding_less",width:100 }],
on:{
    "onItemClick":function(id, e, trg){
        webix.message("Click on row: " + id.row+", column: " + id.column);}
    } //default click behavior that is true for any datatable cell
});

// click behavior for the cell with a button styled with 'delbtn' class
grid.on_click.delbtn=function(e, id, trg){
    webix.message("Delete row: "+id);
    return false; //here it blocks default behavior
};

    Related sample: Datatable: Custom Handler


on_context

a property used to define custom context-click (right click) handlers for elements in the DataTable cells

hash on_context;

Example

var dtable = webix.ui({
    view:"datatable",
    ...
    data:[
        { text:"<div class='myActive'>click here</div>" }
    ]
});
dtable.on_context.myActive = function(id, event, target){
    webix.message("Active area was right-clicked");
};
//or
dtable.on_context["myActive"] = function(id, event, target){
    webix.message("Active area was right-clicked");
};

Details

It's a hash property that contains already available handlers.
All the handlers (existing and newly-added) are specified by the related class name.


on_dblclick

attaches a dblclick behavior for component items with the specified CSS class.

function on_dblclick;

Example

webix.protoUI({
    name:"mylist",
    defaults:{
        template:"#value# <div class='webix_remove_upload'>Del</div>"
    },
    on_dblclick:{
        "webix_remove_upload":function(ev, id){
              this.remove(id);
        }
    }
}, webix.ui.list);

See also

  • api
    • onItemDblClick
    • onDblClick
  • articles
    • Event Handling
    • Details
    • "on_dblclick" behavior is defined for component items rather than for the whole component
    • Use the 'onItemDblClick' handler to attach function to item clicking regardless of the CSS class;


on_mouse_move

attaches a dblclick behavior for component items with the specified CSS class.

function on_mouse_move;

Example

webix.protoUI({
    name:"mylist",
    on_mouse_move:{
        "webix_remove_upload":function(ev, id){
            webix.message("Danger area");
        }
    }
}, webix.ui.list);

See also

  • api
    • onMouseMove
    • onMouseMoving
    • onMouseMove
  • articles
    • Event Handling
    • Details
    • "on_mousemove" behavior is defined for component items rather than for the whole component
    • Use the 'onMouseMove' handler to attach function to item clicking regardless of the CSS class;


Available only in PRO Edition

ui.barcode

A machine-readable representation of data values.

The library supports 3 most common barcode types: ean8, ean13 and upcA. You can customize the barcode bars colors, text height and dimensions of the view. It's also possible to create a custom barcode. Check Barcode documentation for more detailed description.

Constructor

var barcode = webix.ui({
    view: "barcode",
    id:"barcode",
    type: "ean13",
    value: "123456789012"
});

Where to start

  • Overview of the Barcode Widget
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the Barcode
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
render | renders barcode on a page
resize | adjusts the view to a new size
setValue | sets a value for Barcode
show | makes the component visible
unbind | breaks "bind" link
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
color | sets the bar color
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
paddingX | sets the left and right paddings (space between widget border and bars)
paddingY | sets the top and bottom paddings
textHeight | sets the height of the text block
type | sets the barcode type
value | sets barcode value (text)
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
types | the collection of barcode types


Methods

adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the Barcode
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
render | renders barcode on a page
resize | adjusts the view to a new size
setValue | sets a value for Barcode
show | makes the component visible
unbind | breaks "bind" link


getValue

returns the current value of the Barcode

string getValue();

Returns

string the current Barcode value

Example

var barcode = new webix.ui({
    view:"barcode",
    value:"123456789012",
});

barcode.getValue(); //returns "123456789012"


render

renders barcode on a page

void render();

Example

barcode.render();


setValue

sets a value for Barcode

void setValue(string value);

Parameters

value string a new value for Barcode

Example

var barcode = new webix.ui({
   view:"barcode",
   value: "123456789012"
});
// set the new value
barcode.setValue("453456789015");


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
color | sets the bar color
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
paddingX | sets the left and right paddings (space between widget border and bars)
paddingY | sets the top and bottom paddings
textHeight | sets the height of the text block
type | sets the barcode type
value | sets barcode value (text)
width | sets the width of the component


color

sets the bar color

string color;

Example

webix.ui({
    view:"barcode",
    color: "#000"
});


height

sets the height of the component

number height;

Example

webix.ui ({
    view:"window",
    height:300,
    width:300,
    ...
});

See also

  • api
    • width
  • samples
    • Horizontal Accordion
  • articles
    • Sizing components
    • Details

    If you want to set flexible height, you need to set the -1 value for this property:

    webix.ui({
    view:"barcode",
    height: -1
});


paddingX

sets the left and right paddings (space between widget border and bars)

number paddingX;

Example

webix.ui({
    view:"barcode",
    paddingX: 20
});


paddingY

sets the top and bottom paddings

number paddingY;

Example

webix.ui({
    view:"barcode",
    paddingY: 10
});


textHeight

sets the height of the text block

number textHeight;

Example

webix.ui({
    view:"barcode",
    textHeight: 20
});


type

sets the barcode type

string type;

Example

webix.ui({
    view:"barcode",
    type: "upcA"
});

//or
var barcode = webix.ui({
    view:"barcode"
});
barcode.define("type", "upcA");

Details

there are 3 built-in types: "ean8", "ean13" and "upcA" ("ean13" is the default one)


value

sets barcode value (text)

string value;

Example

webix.ui({
    view:"barcode",
    value: "123456789012"
});


width

sets the width of the component

number width;

Example

webix.ui ({
   view:"window",
   height:300,
   width:300,
   ...
});

See also

  • api
    • height
  • samples
    • Horizontal Accordion
  • articles
    • Sizing components
    • Details

    If you want to set flexible width, you need to set the -1 value for this property:

    webix.ui({
    view:"barcode",
    width: -1
});


Events

onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
types | the collection of barcode types


types

the collection of barcode types

array types;

See also

  • samples
    • Custom types
    • Details

    Each type is a set of rendering helpers and templates. Barcode can have multiple types, but only one can be active per component instance.


ui.button

A clickable button.

The control has a collection of preset looks and can be used both as a stand-alone view and as a part of a form or a toolbar. Fully customizable. Check button documentation for more detailed description.

Constructor

var button = webix.ui({
    view:"button",
    id:"my_button",
    value:"Button",
    type:"form",
    inputWidth:100
});

Where to start

  • Overview of the Button Control
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
label | the text label of the control
labelPosition | positions label in relation to the control
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


blur

removes the focus from the control

void blur();

Example

webix.ui({
    view:"button",
    id:"b1",
    value:"Save"
});

$$('b1').focus();
...
$$('b1').blur();

See also

  • api
    • focus
  • articles
    • Keyboard Events. Focusing. Navigation


focus

sets focus to the control

void focus();

Example

webix.ui({
    view:"button",
    id:"b1",
    value:"Save"
});

$$('b1').focus();

See also

  • api
    • blur
  • articles
    • Keyboard Events. Focusing. Navigation


getInputNode

gets the HTML element related to the component

HTMLElement getInputNode();

Returns

HTMLElement the component HTML element

Example

webix.ui({
    container:"box",
    view:"form",
    elements:[
        { view:"text",   id:"f1", label:"Email"},
        { view:"text",   id:"f2", label:"Password", type:'password' },
        { view:"button", id:"b1", value:"Login",  type:"form" }
    ]
});

$$("b1").getInputNode();//-> <input type="button" style="height:27px; width:149px" value="Login">

Details

Dimension you get equal to library defauls defined for a standard button. They can be as well set in JS object:

{ view:"button", id:"b1", value:"Login",  type:"form", width: 300, height: 50 }

See also

  • articles
    • View


getValue

returns the current value of the control

string getValue();

Returns

string the current value of the control

Example

webix.ui({
    view:"form",
    elements:[
        { view:"button", id:"b1", value:"Edit", type:"form" },
        { view:"button", id:"b2", value:"Back", type:"form" }
    ]
});

$$('b1').getValue(); //returns "b1"

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
    • getValues
  • articles
    • Controls Guide


refresh

repaints the component

void refresh();

Example

webix.ui({
    container:"box",
    view:"form",
    elements:[
        { view:"button", id:"b1", value:"Edit", type:"form" },
        { view:"button", id:"b2", value:"Back", type:"form" }
    ]
});
...
$$("b1").define("value","Save");
$$("b1").refresh(); // value:"Edit" -> value:"Save"

See also

  • api
    • render
  • articles
    • Changing Properties of Components


render

renders the specified item or the whole component

void render(id id,object data,string type);

Parameters

id | id | the item id
data | object | the hash of data for the rendered item
type | string | the type of the operation: 'update', 'add', 'delete', 'move'

Example

$$('view').render();

Details

When no parameters are specified, the method renders the whole view.

Types of the operation:

  • update - replaces the existing HTML with the new one
  • add - place a new HTML at the required position
  • delete - removes the related HTML
  • move - simulates add-delete sequence

See also

  • samples
    • Customizing Pager Controls
  • articles
    • Changing Properties of Components


setValue

sets a new value for the component

void setValue(string value);

Parameters

value string a new value for the control

Example

webix.ui({
    container:"box",
    view:"form",
    elements:[
        { view:"button", id:"b1", value:"Edit", type:"form" },
        { view:"button", id:"b2", value:"Back", type:"form" }
    ]
});
...
$$('b1').setValue("Save");
$$('b2').setValue("Cancel");

See also

  • api
    • getValue
  • articles
    • Controls Guide


sync

allows you to sync two copy of data (all or just a part of it) from one DataCollection to another

void sync(object source,function filter,boolean silent);

Parameters

source | object | the object that the method is assigned to
filter | function | the filtering function
silent | boolean | if you set the parameter to true, the object won't be repainted after synchronization

Example

//full copy
$$('list').data.sync(data);

//partial copy
$$('dview').data.sync(data, function(){
    this.filter(function(data){
    return data.year > 1994;
    });
});

See also

  • api
    • filter
    • silent
  • samples
    • DataCollection Syncing
    • Get Popup View
  • articles
    • Data Binding and Syncing
    • Data Binding and Syncing with Non-UI Objects


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
label | the text label of the control
labelPosition | positions label in relation to the control
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
value | sets the initial value for a control
width | sets the width of the component


align

the alignment of the control within the parent container

string align;

Values

  • 'left'
    aligns the control to the left (the default value)
  • 'center'
    centers the control
  • 'right'
    aligns the control to the right

    • Example

    webix.ui({
    container:"box",
    cols:[
        { view:"form", elements:[
            { view:"checkbox", id:"ch1", label:"Block", align:"left"},
            { view:"checkbox", id:"ch2", label:"Load"},
            { view:"checkbox", id:"ch3", label:"Enable"}
        ]}
    ]
});

    See also

  • samples
    • Buttons: Alignment
  • articles
    • Controls Guide


autowidth

adjusts button to its text content

boolean autowidth;

Example

{ view:"button", autowidth:true }


click

click action handler

function click;

Example

webix.ui({
   view:"button", click:"alert('handler');"
});
//or
function handler(){
    alert('handler');
}
webix.ui({
   view:"button", click:handler
});

Details

Short alias for some.attachEvent("onItemClick", code);

Inside handler "this" points to the view object


hotkey

sets a hotkey that triggers button clicking

string hotkey;

Example

{ view:"button", label:"Login" , click: doOnClick, hotkey: "enter" }

See also

  • api
    • ui.button
  • samples
    • Hotkeys for buttons
  • articles
    • Button
    • Keyboard Events. Focusing. Navigation
    • Details

    It's also possible to set combinations of keys joined by '+' or '-' sign.

    { view:"button", label:"Login" , click: doOnClick, hotkey: "enter+shift" }


inputHeight

the height of the input area, or a button's text value area.

number inputHeight;

Example

{view:"text", label:"Password", type:"password", inputHeight:50}

See also

  • api
    • inputWidth
  • samples
    • Toolbar: Multiple Rows
  • articles
    • Controls Guide


inputWidth

the width of the input area, or a button's text value area.

number inputWidth;

Example

{view:"text", label:"Password", type:"password", inputWidth:200}

See also

  • api
    • inputHeight
  • articles
    • Controls Guide


label

the text label of the control

string label;

Example

webix.ui({
    container:"box",
    view:"form",
    elements:[
        { view:"text", label:"Email"},
        { view:"text", label:"Password"},
        { cols:[
                { view:"button", label:"Login" , type:"form" },
                { view:"button", label:"Cancel" }
        ]}
    ]
});

See also

  • samples
    • Buttons: Different Sizes
  • articles
    • Controls Guide
    • Details

    The property should not be mixed with the label control.

    Moreover, label control can have a label as well, but there's no sense in it.


labelPosition

positions label in relation to the control

string labelPosition;

Values

  • top
    places label above the control

    • Example

    {view: "text", label:"Some Text", labelPosition:"top"}

    See also

  • api
    • bottomLabel
  • samples
    • Positioning Labels
  • articles
    • Controls Guide
    • Details

    By default label features left alignment, so the top label will be placed to the left upper corner of the control.

    Top right alignment is achieved by applying both properties:

    {view: "text", label:"Some Text", labelAlign:"right", labelPosition:"top"}


name

name of the control

string name;

Example

webix.ui({
  view:"text",
  name:"FirstName"
});

Details

Is necessary to use the control inside of other form or other toolbar

Works the same as name of an input


placeholder

placeholder text for the input area

string placeholder;

Example

{ view:"colorpicker", placeholder:"Add value here" }


popup

allows to attach pop-up menu to the button

string popup;

Example

webix.ui({
  view:"toolbar",
  elements:[
    {view:"button", label: 'Menu', popup:"my_pop"},
    ...
  ]
});

webix.ui({
  view:"popup",
  id:"my_pop",
  body:{
    view:"list"
  }
}).hide();

See also

  • samples
    • Popup Menu
  • articles
    • Popup
    • Details

    The property's value is the ID of pop-up object that should appear on clicking the button. The object is initialized in the separate webix.ui() constructor. It's initially hidden.


tabFocus

defines whether the control will be included in the tab navigation order

boolean tabFocus;

Example

webix.ui({
    view:"combo",
    label: 'Fruit',
    tabFocus:false,
    ...
});

See also

  • samples
    • Tab Navigation
  • articles
    • Keyboard Events. Focusing. Navigation
    • Details

    The default value is true, the control is included in the tab navigation order.


tooltip

tooltip for the input

string tooltip;

Example

{ view:"icon", icon:"user", tooltip:"Details" }


type

the type of the control

string type;

Values

  • base (default)
  • danger
  • form
  • prev
  • next
  • image
  • imageTop
  • imageButtonTop
  • icon
  • iconTop
  • IconButtonTop

    • Example

    { view:"button", id:"button1", type:"form", label: "Button"}
//
{view:"text", label:"text", type:"password", align:"left"}

    See also

  • articles
    • Button


value

sets the initial value for a control

string| number value;

Example

rows:[
    { view:"text", name:"country", label:"Country", value:"Belarus" },
    {
        view:"combo", value:1, options:[
            { id:1, value:"Banana" },
            { id:2, value:"Papaya" },
            { id:3, value:"Apple" }
        ]
    },
    { view:"button", type:"form", value:"Submit data"}
]

See also

  • api
    • getValue
    • setValue
  • samples
    • Editable Combo Box ('combo')
  • articles
    • Controls Guide
    • Details

    All controls fall into:

    • single-value - those containing a string of a number;
    • multiple-value - those containing an array of values;

    In case of multiple controls value property defines the one initially chosen.

    Value of the control may be:

    • text value in the input text and textarea field;
    • selected item like date in calendar and color in the colorboard;
    • state of the two-state control (checkbox, radio, toggle);
    • selected option of integral buttons (tabbar, tabview, segmented;
    • selected option of select, richselect, and combo;
    • string with selected options of a multiselect and multicombo control.


Events

onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterRender

occurs immediately after the component has been rendered.

void onAfterRender(){ ... };

Example

some.attachEvent("onAfterRender", function(){
    //... some code here ...
});

Details

The event fires each time the component is redrawn, not only after the component has been created.

To catch the moment of creation, supply it with webix.once() helper:

some.attachEvent("onAfterRender", webix.once(function(){
    console.log('called once after first rendering:');
});

See also

  • api
    • onBeforeRender
  • articles
    • UI Components
    • View


onBeforeRender

occurs immediately before the component has been rendered

void onBeforeRender(object data){ ... };

Parameters

data object a hash of data that is used for rendering

Example

some.attachEvent("onBeforeRender", function(data){
    //... some code here ...
});

Details

Returning false from the event handler will block further processing.

See also

  • api
    • onAfterRender
  • articles
    • UI Components
    • View


onChange

fires when the value of the control is changed

void onChange(){ ... };

Example

$$("my_input").attachEvent("onChange", function(newv, oldv){
    webix.message("Value changed from: "+oldv+" to: "+newv);
});

Details

The function executed on this event, takes two arguments - newv and oldv that correspond to the initial control value and the newly set one.

See also

  • samples
    • 'onChange' Event
  • articles
    • Form


onItemClick

fires after the control has been clicked

void onItemClick(string| number id,event e){ ... };

Parameters

id | string| number | control ID
e | event | event object

Example

button.attachEvent("onItemClick", function(id, e){
    //code
});

See also

  • api
    • click
  • samples
    • List: Active Content
  • articles
    • Event Handling


Others

$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


$getValue

called each time when component need to get value from related html input

string $getValue();

Returns

string value from the html input

Example

var value = button.$getValue();

Details

not purposed for direct calls

Can be redefined in a custom view to support custom html inputs
Is called only when component was rendered for sure ( and components html is ready and accessible )


$renderInput

called each time when component need to paint control's input

HTMLElement $renderInput(object config);

Parameters

config object the configuration object of the control

Returns

HTMLElement HTML for rendering the control


$setValue

called each time when component need to set value in related html input

void $setValue(string value);

Parameters

value string new value for the input

Example

input.$setValue("new value");

Details

Not purposed for direct calls

Can be redefined in a custom view
Is called only when component was rendered for sure ( and components html is ready and accessible )


on_click

attaches a click behavior for component items with the specified CSS class.

function on_click;

Example

webix.protoUI({
    name:"mylist",
    defaults:{
        template:"#value# <div class='webix_remove_upload'>Del</div>"
    },
    on_click:{
        "webix_remove_upload":function(ev, id){
              this.remove(id);
        }
    }
}, webix.ui.list);

See also

  • api
    • onItemClick
    • onClick
    • click
  • samples
    • Progress bar
  • articles
    • Event Handling
    • Details
    • "on_click" stores default and attached click behavior for component items;
    • Additional click events are attched with the 'onItemClick' handler;
    • For standard Webix buttons you'd better use the click property to attach a function;
    • on_click handler is used to redefine the default onclick event right in the component constructor:

grid = new webix.ui({
view:"datatable",
columns:[
        { id:"rank",    header:"", css:"rank",          width:50},
        { id:"title",   header:"Film title",width:200},
        {   id:"", template:"<input class='delbtn' type='button' value='Delete'>",
            css:"padding_less",width:100 }],
on:{
    "onItemClick":function(id, e, trg){
        webix.message("Click on row: " + id.row+", column: " + id.column);}
    } //default click behavior that is true for any datatable cell
});

// click behavior for the cell with a button styled with 'delbtn' class
grid.on_click.delbtn=function(e, id, trg){
    webix.message("Delete row: "+id);
    return false; //here it blocks default behavior
};

    Related sample: Datatable: Custom Handler


touchable

flag, which force touch reaction on touch screen devices

touchable;

Example

myview.touchable = true;

Details

Main view object ( myview.$view ) will take webix_touch css class Css class will be removed after end of touch actions

This feature is used mainly by buttons.

Enabled by default


ui.calendar

A single-month calendar that allows users to select dates and move to the next/previous month.

The control supports all date and time formats. Besides the days of the month, it can display day headings for the week days, the week number, a title with the month name and year, hour and minite selectors. Customizable and mostly used as a flat calendar. Check calendar documentation for more detailed description.

Constructor

var calendar = webix.ui({
    view:"calendar",
    date:new Date(2015,3,16),
    events:webix.Date.isHoliday,
    weekHeader:true
});

Where to start

  • Overview of the Calendar Widget
  • Samples
Based on: MouseEvents, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSelectedDate | gets the current selected date
getTopParentView | returns top parent view
getValue | returns the current value of the component
getVisibleDate | gets visible date
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
selectDate | selects the specified date
setValue | sets a new value for the component
show | makes the component visible
showCalendar | makes the specified date displayed in the calendar
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDateSelect | fires after a user has selected a date
onAfterMonthChange | called after month in selector is changed.
onAfterRender | called after the rendering of calendar is complete.
onAfterScroll | occurs when some webix view has been scrolled
onAfterZoom | fires after zoom level of the calendar has been changed
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDateSelect | fires when a user clicks on a date but before it is selected in the calendar
onBeforeMonthChange | triggered immediately before month in selector is changed.
onBeforeRender | triggered immediately before rendering of calendar is started.
onBeforeZoom | fires before zoom level of the calendar is changed
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fired when a user changes month, year or time in selector.
onDateClear | fires on clicking the [Clear](Calendar) button
onDateSelect | fires when a user selects a date.
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTodaySet | fires on clicking the [Today](Calendar) button
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
blockDates | defines the selectable range
borderless | used to hide the component borders
calendarHeader | the format for the title with the month name and year
calendarTime | defines calendar time format (with timepicker enabled)
calendarWeekHeader | specifies the label for the column with weeks numbers
cellHeight | the height of the cell with day
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
date | sets the initial date of the calendar (particularly month and year).
dayTemplate | defines a template for a calendar day cell
disabled | indicates whether an item is enabled or not
events | sets an additional css class that will be applied to days
gravity | sets the view gravity (1 by default)
headerHeight | total height of the area not taken by calendar body
height | sets the height of the component
hidden | defines whether the view will be hidden initially
icons | sets an array of icons in the calendar or hides them
id | the component ID
maxDate | set man limit for selected date
maxHeight | sets the maximum height for the view
maxTime | maximum allowed time
maxWidth | sets the maximum width for the view
minDate | set min limit for selected date
minHeight | sets the minimal height for the view
minTime | minimal allowed time
minWidth | sets the minimal width for the view
minuteStep | step of time selector
monthSelect | enables the ability to select month by clicking the "month" panel
mouseEventDelay | the delay between a real mouse action and invoking the related events
navigation | enables/disables month navigation in header - the possibility to change months (true)
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
select | enables date selection within the calendar.
skipEmptyWeeks | enables/disables displaying empty weeks (true)
timepicker | enables clock for time selection
timepickerHeight | sets height of timepicker area
type | type of calendar view
weekHeader | enables/disables additional header with week days (false)
weekNumber | enables/disables additional left column with weeks' numbers (false)
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSelectedDate | gets the current selected date
getTopParentView | returns top parent view
getValue | returns the current value of the component
getVisibleDate | gets visible date
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
selectDate | selects the specified date
setValue | sets a new value for the component
show | makes the component visible
showCalendar | makes the specified date displayed in the calendar
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getSelectedDate

gets the current selected date

object getSelectedDate();

Returns

object a Date object that represents the current selected date

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});
$$('calendar1').selectDate(new Date(2012,3,30));

$$("calendar1").getSelectedDate(); // -> Mon Apr 30 2012 00:00:00 GMT+0300 (EEST)

Details

The method is analogous to getValue.

See also

  • api
    • selectDate
    • getVisibleDate
    • getValue
  • articles
    • Calendar


getValue

returns the current value of the component

object getValue();

Returns

object a Date object that represents the current selected date

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});
$$('calendar1').selectDate(new Date(2012,3,30));

$$("calendar1").getValue(); // -> Mon Apr 30 2012 00:00:00 GMT+0300 (EEST)

Details

The method is analogous to getSelectedDate.

See also

  • api
    • getSelectedDate
    • getVisibleDate
    • setValue
  • articles
    • Calendar


getVisibleDate

gets visible date

object getVisibleDate();

Returns

object a Date object that represents the current visible date

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});

$$("calendar1").getVisibleDate();

Details

The visible date takes its value according to this priority list:

  1. If some date is selected in the calendar - visible date == selected date
  2. If no date is selected, but the initial date is set - visible date == initial date
  3. If no date is selected, the initial date isn't set and the calendar displays the current month -
    visible date ==today's date
  4. If no date is selected, the initial date isn't set and the calendar doesn't display the current month -
    visible date == the first day of the displayable month

See also

  • api
    • getValue
    • getSelectedDate
  • articles
    • Calendar


locate

gets the id of an item from the specified HTML event

id locate(Event e);

Parameters

e Event a native event

Returns

id the item id

Example

$$('view').locate(e);


refresh

repaints the component

void refresh();

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});

$$("calendar1").define("weekNumber", true);
$$("calendar1").refresh();

See also

  • api
    • render
  • articles
    • Changing Properties of Components


selectDate

selects the specified date

void selectDate(string/object date,boolean mode);

Parameters

date | string/object | a Date object or a string representing a date
mode | boolean | true - to show the selected date in the calendar, false - not to show the selected date

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});
$$('calendar1').selectDate(new Date(2012,3,30));

Details

The method is analogous to setValue.

See also

  • api
    • getSelectedDate
    • setValue
  • articles
    • Calendar


setValue

sets a new value for the component

void setValue(string| object date);

Parameters

date string| object a Date object or a string representing a date

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});
$$('calendar1').setValue(new Date(2012,3,30));

Details

The method is analogous to selectDate.

See also

  • api
    • getValue
    • selectDate
  • articles
    • Calendar


showCalendar

makes the specified date displayed in the calendar

void showCalendar(string| object date);

Parameters

date string| object a Date object or a string representing a date

Example

webix.ui({
    container:"box",
    view:"calendar",
    id:"calendar1"
});
$$('calendar1').showCalendar(new Date(2011,5,13));

Details

Note, the method doesn't selects the specified date.

See also

  • articles
    • Calendar


Properties

animate | defines or disables view change animation.
blockDates | defines the selectable range
borderless | used to hide the component borders
calendarHeader | the format for the title with the month name and year
calendarTime | defines calendar time format (with timepicker enabled)
calendarWeekHeader | specifies the label for the column with weeks numbers
cellHeight | the height of the cell with day
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
date | sets the initial date of the calendar (particularly month and year).
dayTemplate | defines a template for a calendar day cell
disabled | indicates whether an item is enabled or not
events | sets an additional css class that will be applied to days
gravity | sets the view gravity (1 by default)
headerHeight | total height of the area not taken by calendar body
height | sets the height of the component
hidden | defines whether the view will be hidden initially
icons | sets an array of icons in the calendar or hides them
id | the component ID
maxDate | set man limit for selected date
maxHeight | sets the maximum height for the view
maxTime | maximum allowed time
maxWidth | sets the maximum width for the view
minDate | set min limit for selected date
minHeight | sets the minimal height for the view
minTime | minimal allowed time
minWidth | sets the minimal width for the view
minuteStep | step of time selector
monthSelect | enables the ability to select month by clicking the "month" panel
mouseEventDelay | the delay between a real mouse action and invoking the related events
navigation | enables/disables month navigation in header - the possibility to change months (true)
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
select | enables date selection within the calendar.
skipEmptyWeeks | enables/disables displaying empty weeks (true)
timepicker | enables clock for time selection
timepickerHeight | sets height of timepicker area
type | type of calendar view
weekHeader | enables/disables additional header with week days (false)
weekNumber | enables/disables additional left column with weeks' numbers (false)
width | sets the width of the component


blockDates

defines the selectable range

function blockDates;

Example

{ view:"calendar", blockDates:function(date){
   if (date.getMonths() > 2) return false;
   return true;
}}

See also

  • api
    • minDate
    • maxDate
  • samples
    • Disabled dates
  • articles
    • Calendar


calendarHeader

the format for the title with the month name and year

string calendarHeader;

Example

webix.ui({
        container:"box",
        date:new Date(2012,3,16),
        view:"calendar",
        calendarHeader:"%F, %Y"
});

See also

  • articles
    • Calendar
    • Date formatting methods
    • Details

    The default value of the parameter is "%F %Y".


calendarTime

defines calendar time format (with timepicker enabled)

string calendarTime;

Example

webix.ui({
    view:"calendar",
    timepicker:true,
    calendarTime:"%H:%i"
});

See also

  • articles
    • Calendar
    • Date formatting methods
    • Working with Dates
    • Details

    By default, time is formatted according to the above mentioned scheme. More about date and time formatting methods.


calendarWeekHeader

specifies the label for the column with weeks numbers

string calendarWeekHeader;

Example

webix.ui({
    container:"box",
    view:"calendar",
    weekNumber:true,
    calendarWeekHeader:"W/"
});

See also

  • articles
    • Calendar
    • Details

    The parameter makes sense only when the weekNumber parameter is set to true.

    The default value is 'W#'.


cellHeight

the height of the cell with day

number| string cellHeight;

See also

  • articles
    • Calendar
    • Details

    Cell height can be calculated automatically from calendar size if the property is set to auto.


date

sets the initial date of the calendar (particularly month and year).

Date|string date;

Example

webix.ui({
    weekHeader:true,
    date:new Date(2012,3,16),
    view:"calendar"
});

See also

  • samples
    • Calendar
  • articles
    • Calendar
    • Date formatting methods
    • Working with Dates
    • Details

    Value can be either a string formatted with the current parseFormat or Date object.


dayTemplate

defines a template for a calendar day cell

function dayTemplate;

Example

view:"calendar",
dayTemplate: function(date){
    var html = "<div class='day'>"+date.getDate()+"</div>";
    if(date.getDay() == 5){
        html += "<div class='day_marker'></div>";
    }
    return html;
}

See also

  • samples
    • Day template
  • articles
    • Calendar
    • Details

    The default template displays a date without any extra styling.


events

sets an additional css class that will be applied to days

function events;

Example

webix.ui({
    container:"listA",
    view:"calendar",
    events:webix.Date.isHoliday // the webix.Date.isHoliday function marks weekend days in red
});

See also

  • articles
    • Calendar
    • Calendar CSS
    • Details

    The function is called for all days and must return the name of a css class to apply.


headerHeight

total height of the area not taken by calendar body

number headerHeight;

Example

{ view:"calendar", headerHeight:100 }

See also

  • api
    • headerHeight
  • articles
    • Calendar
    • Details

    By default the free area is 70px regardless of calendar dimensions. The rest of the space is taken by month title, week header and timepicker (if any).

    If you increase parameter value, calendar body (the area with dates) shrinks and free space appears at the bottom of calendar area. Then, you are free to change the height of any calendar element with the help of CSS classes:

    • webix_cal_month - month title area;
    • webix_cal_header - week header area;

    ..or special properties:

    • timepickerHeight - height of timepicker area


icons

sets an array of icons in the calendar or hides them

boolean| object icons;

Example

webix.ui({
    view:"calendar",
    icons: [
        {
            template: function(){
                return "<span class='webix_cal_icon_today webix_cal_icon'>"
                    +webix.i18n.calendar.today
                    +"</span>";
            },
            on_click:{
                "webix_cal_icon_today": function(){
                    this.setValue(new Date());
                    this.callEvent("onTodaySet",[this.getSelectedDate()]);
                }
            }
        },
        {
            template: function(){
                return "<span class='webix_cal_icon_clear webix_cal_icon'>"
                    +webix.i18n.calendar.clear
                        +"</span>";
            },
            on_click:{
                "webix_cal_icon_clear": function(){
                    this.setValue("");
                    this.callEvent("onDateClear",[this.getSelectedDate()]);
                }
            }
        }
    ]
});

Details

Disabling icons

To hide "Today" and "Clear" icons in the calendar, set the parameter to false:

webix.ui({
    view:"calendar",
    icon:false,
    ...
});

Object properties

As an object the parameter redefines buttons:

webix.ui({
    view: "calendar",
    icons: [
        template: function(){
            return "<span class='my_button'>My Button</span>";
        },
        on_click:{
            "my_button": function(){
                alert("Button is clicked")
            }
        }
    ]
});


maxDate

set man limit for selected date

Date|string maxDate;

Example

{ view:"calendar", maxDate:"2012-04-05" }

See also

  • api
    • minDate
    • blockDates
  • samples
    • Disabled dates
  • articles
    • Calendar
    • Details

    Dates greater than the defined one can't be selected.

    Value can be either a string formatted with the current parseFormat or Date object.


maxTime

maximum allowed time

string maxTime;

Example

{ view:"calendar", maxTime:"18:00" }

See also

  • api
    • minTime
  • samples
    • Disabled time
  • articles
    • Calendar


minDate

set min limit for selected date

Date|string minDate;

Example

{ view:"calendar", minDate:"2012-04-05" }

See also

  • api
    • blockDates
    • maxDate
  • samples
    • Disabled dates
  • articles
    • Calendar
    • Details

    Dates less than defined one can't be selected.

    Value can be either a string formatted with the current parseFormat or Date object.


minTime

minimal allowed time

string minTime;

Example

{ view:"calendar", minTime:"08:00" }

See also

  • api
    • maxTime
  • samples
    • Disabled time
  • articles
    • Calendar


minuteStep

step of time selector

number minuteStep;

Example

weibix.ui({view:"calendar", minutestep:10 })

Details

Value must be greater or equal to 5
Value must be a divider of 60 ( 60 mod step == 0 )


monthSelect

enables the ability to select month by clicking the "month" panel

boolean monthSelect;

See also

  • articles
    • Calendar
    • Details

    True by default.


navigation

enables/disables month navigation in header - the possibility to change months (true)

boolean navigation;

See also

  • articles
    • Calendar
    • Details

    True by default.


select

enables date selection within the calendar.

boolean select;

See also

  • articles
    • Calendar
    • Selection
    • Details

    False by default


skipEmptyWeeks

enables/disables displaying empty weeks (true)

boolean skipEmptyWeeks;

See also

  • articles
    • Calendar
    • Details

    Defines whether 6 weeks (42 days) must be displayed all the time or weeks which completely belong to the next month should be skipped.


timepicker

enables clock for time selection

boolean timepicker;
Details

False by default


timepickerHeight

sets height of timepicker area

number timepickerHeight;

Example

{view:"calendar", timepicker:true, timepickerHeight:50 }

See also

  • api
    • timepicker
  • articles
    • Calendar
    • Details

    The default timepicker height is 30px.


type

type of calendar view

string type;

Values

  • time
    switches calendar to time view

    • Example

    webix.ui({
    view:"calendar",
    type:"time"
});


weekHeader

enables/disables additional header with week days (false)

boolean weekHeader;

See also

  • articles
    • Calendar


weekNumber

enables/disables additional left column with weeks' numbers (false)

boolean weekNumber;

See also

  • articles
    • Calendar


Events

onAfterContextMenu | fires after the context menu was called in the item area
onAfterDateSelect | fires after a user has selected a date
onAfterMonthChange | called after month in selector is changed.
onAfterRender | called after the rendering of calendar is complete.
onAfterScroll | occurs when some webix view has been scrolled
onAfterZoom | fires after zoom level of the calendar has been changed
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDateSelect | fires when a user clicks on a date but before it is selected in the calendar
onBeforeMonthChange | triggered immediately before month in selector is changed.
onBeforeRender | triggered immediately before rendering of calendar is started.
onBeforeZoom | fires before zoom level of the calendar is changed
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fired when a user changes month, year or time in selector.
onDateClear | fires on clicking the [Clear](Calendar) button
onDateSelect | fires when a user selects a date.
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTodaySet | fires on clicking the [Today](Calendar) button
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterDateSelect

fires after a user has selected a date

void onAfterDateSelect(date date){ ... };

Parameters

date date the selected date object

Example

$$('calendar1').attachEvent("onAfterDateSelect", function(date){
    //... some code here ...
});

See also

  • api
    • onBeforeDateSelect
    • onDateSelect
  • articles
    • Calendar


onAfterMonthChange

called after month in selector is changed.

void onAfterMonthChange(date prev_date,date next_date){ ... };

Parameters

prev_date | date | the previously selected date
next_date | date | the currently selected date

Example

$$(calendar1).attachEvent("onAfterMonthChange", function(prev_date, next_date){
    //... some code here ...
});

See also

  • articles
    • Calendar


onAfterRender

called after the rendering of calendar is complete.

void onAfterRender(){ ... };

Example

some.attachEvent("onAfterRender", function(){
    //... some code here ...
});

See also

  • articles
    • View


onAfterZoom

fires after zoom level of the calendar has been changed

void onAfterZoom(number level){ ... };

Parameters

level number new zoom level

Example

calendar.attachEvent("onAfterZoom", function(level){
    //code
});

Details

Webix calendar features 3 zoom levels:

  • 0 - the initial zoom level, month view is displayed;
  • 1 - year view with month names is displayed;
  • 2 - ten-year period with year numbers is displayed

See also

  • api
    • onBeforeZoom


onBeforeDateSelect

fires when a user clicks on a date but before it is selected in the calendar

void onBeforeDateSelect(date date){ ... };

Parameters

date date the selected date object

Example

$$('calendar1').attachEvent("onAfterDateSelect", function(date){
    //... some code here ...
});

See also

  • api
    • onAfterDateSelect
    • onDateSelect
  • articles
    • Calendar


onBeforeMonthChange

triggered immediately before month in selector is changed.

void onBeforeMonthChange(date prev_date,date next_date){ ... };

Parameters

prev_date | date | the previously selected date
next_date | date | the currently selected date

Example

$$("calendar1").attachEvent("onBeforeMonthChange", function(prev_date, next_date){
    //... some code here ...
});

See also

  • articles
    • Calendar


onBeforeRender

triggered immediately before rendering of calendar is started.

void onBeforeRender(){ ... };

Example

some.attachEvent("onBeforeRender", function(){
    //... some code here ...
});

See also

  • articles
    • View


onBeforeZoom

fires before zoom level of the calendar is changed

void onBeforeZoom(number level ){ ... };

Parameters

level number new zoom level

Example

calendar.atachEvent("onBeforeZoom", function(level){
    //code
});

Details

Webix calendar features 3 zoom levels:

  • 0 - the initial zoom level, month view is displayed;
  • 1 - year view with month names is displayed;
  • 2 - ten-year period with year numbers is displayed

See also

  • articles
    • onAfterZoom


onChange

fired when a user changes month, year or time in selector.

void onChange(date date){ ... };

Parameters

date date the selected date.

Example

$$("calendar1").attachEvent("onChange", function(date){
    //... some code here ...
});

See also

  • articles
    • Calendar
    • Form


onDateClear

fires on clicking the Clear button

void onDateClear(){ ... };

Example

$$('myCalendar').attachEvent("onDateClear", function(){
    //some code here
});


onDateSelect

fires when a user selects a date.

void onDateSelect(date date){ ... };

Parameters

date date the selected date

Example

$$('calendar1').attachEvent("onDateselect", function(date){
    //... some code here ...
});

See also

  • api
    • onBeforeDateSelect
    • onAfterDateSelect
  • articles
    • Calendar


onTodaySet

fires on clicking the Today button

void onTodaySet(object date){ ... };

Parameters

date object the calendar object date

Example

$$('calendar').attachEvent("onTodaySet", function(date){
    //some code here
});


ui.carousel

A container control that provides continuous, circular navigation through a set of pictorial content blocks. One block is visible at a time.

The control supports any content inside of it. The content blocks can be arranged vertically or horizontally, supplemented or not with the navigation control panel. Check carousel documentation for more detailed description.

Constructor

var carousel = webix.ui({
    view:"carousel",
    id:"carousel",
    width:464,
    height:275,
    cols:[
      { css:{"background-color":"#ffc4c4"}, template:"view1" },
      { css:{"background-color":"#ffffb1"}, template:"view2" },
      { css:{"background-color":"#c4ffc4"}, template:"view3" }
    ]
});

Where to start

  • Overview of the Carousel Widget
  • Samples
Based on: EventSystem, NavigationButtons, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
adjustScroll | adjusts scrolling direction to screen mode (vertical or horizontal)
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getActiveId | gets the id of the current selected item
getActiveIndex | gets the index of the current active item
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getLayout | gets layout object with carousel views
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
scrollTo | scrolls the carousel and scrollview container to a certain position
setActive | selects the item with the specified id
setActiveIndex | selects the item with the specified index
show | makes the component visible
showNext | shows the next item of the carousel
showPrev | shows the previous item of the carousel
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when a new view is shown in carousel
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
navigation | defines navigation parameters
on | allows attaching custom handlers to inner events of the component
rows | array of views arranged vertically
scrollSpeed | speed of scrolling ('300ms' by default)
type | defines the layout borders
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
adjustScroll | adjusts scrolling direction to screen mode (vertical or horizontal)
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getActiveId | gets the id of the current selected item
getActiveIndex | gets the index of the current active item
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getLayout | gets layout object with carousel views
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
scrollTo | scrolls the carousel and scrollview container to a certain position
setActive | selects the item with the specified id
setActiveIndex | selects the item with the specified index
show | makes the component visible
showNext | shows the next item of the carousel
showPrev | shows the previous item of the carousel
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


adjustScroll

adjusts scrolling direction to screen mode (vertical or horizontal)

void adjustScroll( matrix);

Parameters

matrix screen

Example

$$("carousel1").adjustScroll();

See also

  • articles
    • Carousel


getActiveId

gets the id of the current selected item

string getActiveId();

Returns

string the id of the current selected item

Example

webix.ui({
    view:"carousel",
    id:"carousel1",
    container:"box",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});
$$('carousel1').setActive("cell2");
$$('carousel1').getActiveId(); // -> 'cell2'

See also

  • api
    • getActiveIndex
    • setActive
    • setActiveIndex
  • articles
    • Carousel


getActiveIndex

gets the index of the current active item

number getActiveIndex();

Returns

number index of the current active item

Example

var index = $$("mycarousel").getActiveIndex();

See also

  • api
    • getActiveId
    • setActive
    • setActiveIndex
  • articles
    • Carousel


getLayout

gets layout object with carousel views

object getLayout();

Returns

object layout object

Example

var obj = carousel.getLayout();


scrollTo

scrolls the carousel and scrollview container to a certain position

void scrollTo(number x,number y);

Parameters

x | number | the value of the horizontal scroll
y | number | the value of the vertical scroll

Example

webix.ui({
    view:"carousel",
    container:"box",
    id:"carousel1",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});

$$('carousel1').scrollTo(100,0);

See also

  • articles
    • Scrollview


setActive

selects the item with the specified id

void setActive(string id);

Parameters

id string the item id

Example

webix.ui({
    view:"carousel",
    container:"box",
    id:"carousel1",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});
$$('carousel1').setActive("cell2");

See also

  • api
    • getActiveId
    • getActiveIndex
    • setActiveIndex
  • articles
    • Carousel


setActiveIndex

selects the item with the specified index

void setActiveIndex(number index);

Parameters

index number the item index (zero-based numbering)

Example

webix.ui({
    view:"carousel",
    container:"box",
    id:"carousel1",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});
$$('carousel1').setActiveIndex(0);

See also

  • api
    • getActiveIndex
    • getActiveId
    • setActive
  • articles
    • Carousel


showNext

shows the next item of the carousel

void showNext();

Example

webix.ui({
    view:"carousel",
    container:"box",
    id:"carousel1",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});
$$('carousel1').showNext();

See also

  • api
    • showPrev
  • samples
    • Carousel
  • articles
    • Carousel


showPrev

shows the previous item of the carousel

void showPrev();

Example

webix.ui({
    view:"carousel",
    container:"box",
    id:"carousel1",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});
$$('carousel1').showPrev();

See also

  • api
    • showNext
  • samples
    • Carousel
  • articles
    • Carousel


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
navigation | defines navigation parameters
on | allows attaching custom handlers to inner events of the component
rows | array of views arranged vertically
scrollSpeed | speed of scrolling ('300ms' by default)
type | defines the layout borders
width | sets the width of the component


cols

array of views objects arranged horizontally

array cols;

Example

webix.ui({
    view:"carousel",
    cols:[
        { css: "image", template:img, data:{src:"imgs/image001.jpg"} },
        { css: "image", template:img, data:{src:"imgs/image002.jpg"} },
        ...
    ]
});

See also

  • api
    • rows
  • samples
    • Carousel Initialization
  • articles
    • Carousel


navigation

defines navigation parameters

object navigation;

Example

webix.ui({
    view:"carousel",
    ...
    navigation:{
        items: false,
        type: "side"
    }
})

See also

  • samples
    • Navigation types
  • articles
    • Carousel
    • Details

    The available attributes of the property are:

    items | (boolean) enables navigation items (by default, true)
buttons | (boolean) enables "previos" and "next" arrow buttons (by default, true)
type | (string) defines navigation styling (by default, corner)


rows

array of views arranged vertically

array rows;

Example

webix.ui({
    view:"carousel",
    rows:[
        { css: "image", template:img, data:{src:"imgs/image001.jpg"} },
        { css: "image", template:img, data:{src:"imgs/image002.jpg"} },
        ...
    ]
});

See also

  • api
    • rows
  • articles
    • Carousel


scrollSpeed

speed of scrolling ('300ms' by default)

string scrollSpeed;

Example

webix.ui({
    view:"carousel",
    id:"carousel1",
    container:"box",
    scrollSpeed:"500ms",
    cols:[
       { id:"cell1", template:"<img src='spring.jpg'/>" },
       { id:"cell2", template:"<img src='summer.jpg'/>" }
    ]
});

See also

  • articles
    • Carousel


type

defines the layout borders

string type;

Values

  • line
    cells with border
  • clean
    cells without border (default)
  • wide
    cells with border and small space between siblings
  • space
    cells with border and wide space between siblings
  • head
    similar to wide, but there is no border between the first and second cells

    • Example

    webix.ui({
    view:"carousel",
    type:"space",
    rows:[
        ...
    ]
});

    See also

  • articles
    • Setting Borders to the Components


Events

onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when a new view is shown in carousel
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onShow

fires when a new view is shown in carousel

void onShow(string id){ ... };

Parameters

id string the id of displayed view

Example

carousel.attachEvent("onShow", function(id){
    //... some code here ...
});

See also

  • samples
    • List navigation
  • articles
    • Carousel


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.chart

A tool for creating various charts.

The library supports the most common chart types:line, spline, area, bar, pie, donut, scatter, radar. You can customize appearance of a chart through colors, tooltips, templates, scales, labels. It's possible to present multiple data sets on the same chart. Check chart documentation for more detailed description.

Constructor

var chart = webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    label:"#sales#",
    barWidth:35,
    radius:0,
    gradient:"falling",
    data: [
        { id:1, sales:20, year:"02"},
        { id:2, sales:55, year:"03"},
        { id:3, sales:40, year:"04"},
        { id:4, sales:78, year:"05"}
    ]
});

Where to start

  • Overview of the Chart Widget
  • Samples
Based on: Group, AutoTooltip, DataLoader, DataStore, AtomDataLoader, MouseEvents, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
add | adds an item to the store
addSeries | adds an additional graph to the chart
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCanvas | clears the component canvas
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getTopParentView | returns top parent view
group | groups data by the specified data property
hasEvent | checks whether the component has the specified event
hide | hides the view
hideSeries | hides the chosen graph in the chart with several graphs
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeAllSeries | removes all series from the chart
render | renders the specified item or the whole component
resize | adjusts the view to a new size
serialize | serializes data to a JSON object
show | makes the component visible
showSeries | shows the hidden graph in the chart
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
updateItem | sets properties of the data item
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterRender | called after the rendering of calendar is complete.
onAfterScroll | occurs when some webix view has been scrolled
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
alpha | defines the opacity of chart items
animate | defines or disables view change animation.
barWidth | the width of bars
border | enables/disables the bar borders
borderColor | sets the border color of each item in the graph
borderless | used to hide the component borders
cant | defines the slope angle of 3D pie
color | defines items colors
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disableLines | disapbles graph lines with radar chart
disabled | indicates whether an item is enabled or not
eventRadius | sets the radius (in pixels) of the virtual circle which events will fire for items within
fill | fills the chart area with the specified background color.
fixOverflow | chart max limit mode
gradient | specifies the chart gradient
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
item | defines markers that present chart's data items
label | sets the template for items' labels
labelOffset | the offset of sector labels from the pie frame
legend | defines the chart legend
line | defines chart lines
lineColor | sets the color for strips dividing the pie sectors
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
offset | defines whether the first item of the scale will be drawn with the offset equal to the half of the scale's step (relative to the origin of the chart) or not.
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
origin | sets the scale origin
padding | sets paddings of the chart content
pieHeight | the height of the 3d pie
pieInnerText | sets the template for the pie inner labels
preset | applies the predefined chart configuration object with the specified name
radius | the radius of the bar's rounding
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scale | type of chart scale, logarithic or plain
scheme | defines schemes for data processing
series | defines graphs presented on the chart
shadow | enables/disables the pie shadow
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | sets the chart type
url | the URL which the component will use to load data after its initialization
value | defines values for the vertical axis
width | sets the width of the component
x | the horizontal position of the pie center
xAxis | defines the horizontal axis
xValue | a property of the dataset that defines values for the horizontal axis
y | the vertical position of the pie center
yAxis | defines the vertical axis
yValue | a property of the dataset that defines values for the vertical axis.
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
colormap | collection of coloring strategies
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
presets | collection of styling presets


Methods

add | adds an item to the store
addSeries | adds an additional graph to the chart
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCanvas | clears the component canvas
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getTopParentView | returns top parent view
group | groups data by the specified data property
hasEvent | checks whether the component has the specified event
hide | hides the view
hideSeries | hides the chosen graph in the chart with several graphs
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeAllSeries | removes all series from the chart
render | renders the specified item or the whole component
resize | adjusts the view to a new size
serialize | serializes data to a JSON object
show | makes the component visible
showSeries | shows the hidden graph in the chart
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
updateItem | sets properties of the data item


add

adds an item to the store

id add(object obj, [number index] );

Parameters

obj | object | the item object
index | number | the item position

Returns

id the item id

Example

function addData() {
    $$("data").add({
        title: document.getElementById("title").value,
        year: document.getElementById("year").value
    },0)
}

Details

Object can contain any properties:

$$('mygrid').add({
  some:"some string",
  other:123,
  complex:{
    contain:"any",
    content:"inside"
  }
}, 0);

See also

  • api
    • remove
    • clearAll
    • DataStore
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


addSeries

adds an additional graph to the chart

void addSeries(object obj);

Parameters

obj object the graph configuration object

Example

var barchart = webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    color:"#58dccd"
    ...
});

barchart.addSeries({
    value:"#sales2#",
    color:"#36abee",
});
barchart.parse(multiple_dataset);

Details

The method is used to present multiple graphs on a chart. It's an analog to the series property.
Graphs are specified in a standard way.

If you add to the chart graphs of the same type, you can omit the type attribute.

See also

  • api
    • series
  • articles
    • Chart Series


clearAll

removes all items from the component

void clearAll();

Example

$$("data").clearAll();
//"data" is the ID of the dedicated dataview

See also

  • api
    • remove
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


clearCanvas

clears the component canvas

void clearCanvas();

Example

var mychart = webix.ui({
    view:"chart",
    ...
});

mychart.clearCanvas();


count

returns the number of currently visible items

number count();

Returns

number the count of items

Example

var dtable = webix.ui({
   view:"datatable",
   ...
});

var items = dtable.count();

Details

The method can be used set the component behavior in case no data is loaded into it:

webix.ui({
  view:"list",
  ready:function(){
    if (!this.count()){ //if there are no data items
      webix.extend(this, webix.OverlayBox);
      this.showOverlay("<div style='margin:75px; font-size:20px;'>There's no data</div>");
    }
  }
});

See also

  • samples
    • Empty list
  • articles
    • Data Object Operations


exists

checks whether an item with the specified id exists

boolean exists(id id);

Parameters

id id the id of an item

Returns

boolean returns true if the item exists. Otherwise, false

Example

if(!$$("my_dataview").exists())// -> returns boolean value
    var dataview = new webix.UI({
        view:"dataview",
        id:"my_dataview",
        ..config
    });

See also

  • articles
    • Start Coding with Webix
    • Data Object Operations


filter

filters the component

void filter(template|function text,string value,boolean preserve);

Parameters

text | template|function | a template of filtered value or function
value | string | the filtering mask
preserve | boolean | if set to true, each next filtering criteria will be applied to the already filtered list

Example

//filters all fields with 'abc' in the 'text' property
//using a template
list.filter('#text#',"abc")

//using a function
list.filter(function(obj){
    return obj.text.toString().indexOf("abc") != -1;
});

See also

  • api
    • samples
      • Chart: Filtering
    • articles
      • Operations with Chart Data


find

returns rows that match the criterion

array|object find(function criterion, [boolean first] );

Parameters

criterion | function | match criteria
first | boolean | if true, only the first found result is returned. False by default.

Returns

array|object array of found rows or a row object in case of "first".

Example

//finds all rows which title match the given value
table.find(function(obj){
    return obj.title.toLowerCase().indexOf(value) != -1;
});

See also

  • api
    • filter
  • samples
    • "Find" API


getFirstId

returns the ID of the first item

id getFirstId();

Returns

id the id of the first item

Example

//"data" is the ID of dataview
$$('data').select($$('data').getFirstId());

See also

  • api
    • getLastId
    • getNextId
    • getPrevId
  • samples
    • Selection
  • articles
    • Selection
    • Data Object Operations


getIdByIndex

returns the id of the item with the specified index

id getIdByIndex(number index);

Parameters

index number the item index (zero-based numbering)

Returns

id the item id
Details

if item with such index doesn't exists method returns undefined value

See also

  • articles
    • Data Object Operations


getIndexById

returns the index of the item with the specified id

number getIndexById(id id);

Parameters

id id the item id

Returns

number the item's index
Details

if id is not found then method returns -1

With tree-like structures, use the getBranchIndex method.

See also

  • articles
    • Data Object Operations


getItem

gets the object of the data item with the specified id

object getItem(id id);

Parameters

id id the item id

Returns

object the object of a data item

Example

//'record' variable will contain an object of the related DataTable row,
var record = grid.getItem("rowId");

//you can access data members directly
var title = record.title;

See also

  • articles
    • Data Object Operations


getLastId

returns the id of the last item

id getLastId();

Returns

id the id of the last item

Example

//"data" is the ID of dataview
$$('data').showItem($$('data').getLastId())

See also

  • api
    • getFirstId
    • getNextId
    • getPrevId
  • samples
    • Selection
  • articles
    • Selection
    • Data Object Operations


getNextId

returns the ID of an item which is positioned the specified step after the specified item

id getNextId(id id,number step);

Parameters

id | id | the item id
step | number | the step (by default, 1)

Returns

id the item id

See also

  • api
    • getLastId
    • getFirstId
    • getPrevId
  • articles
    • Selection
    • Data Object Operations


getPrevId

returns the ID of an item which is positioned the specified step before the specified item

id getPrevId(id id,number step);

Parameters

id | id | the item id
step | number | the step (by default, 1)

Returns

id the item id

See also

  • api
    • getLastId
    • getNextId
    • getFirstId
  • articles
    • Selection
    • Data Object Operations


group

groups data by the specified data property

void group(object config,boolean mode);

Parameters

config | object | an object with grouping parameters
mode | boolean | defines whether the component should be re-rendered after grouping ( by default, true)

Example

myview.group({
    by:"#company#", // 'company' is the name of data property
    map:{
        sales:["#sales#","sum"]
    }
});

Details

The method is called for each data item.

The config object has 2 properties:

  • by – a data property according which items will be united in groups

  • map – an object that specifies new data properties that the items in a group will have. Properties are specified by an array. The first element of this array is a template with a property from original data, the second one – the functor that will be applied to all values of the property (set by the first element) in the group.
    Grouping provides the following functors:

    • sum – gets the sum of values in a group;
    • max – gets the maximum value in a group;
    • min - gets the minimum value in a group;
    • count - gets the number of items in a group;
    • any - gets a random property value from a group;
    • string - adds a custom data property to group items.

      It’s possible to define custom functor. Read on the topic in the related article - 'Custom Functor for Data Grouping'.

To group data initially (just after data has been loaded) you may use the scheme parameter, to be accurate, its $group key.

webix.ui({
    view:"chart",
    ...
    scheme:{
        $group:{
            by:"#company#", // 'company' is the name of data property
            map:{
                sales:["#sales#","sum"],
                state:["grouped","string"]
            }
        }
    }
});

See also

  • api
    • ungroup
    • scheme
  • samples
    • Grouping
  • articles
    • Grouping Data Items


hideSeries

hides the chosen graph in the chart with several graphs

void hideSeries(string series );

Parameters

series string ID of the series that should be hidden
Related sample: Bar Chart: Several Graphs in One Chart
Details

The method allows for programmatical hiding of the dedicated series. At the same time, series can be shown and hidden by clicking the corresponding icon in the chart legend. Like here: Related sample: Bar Chart: Several Graphs in One Chart

See also

  • api
    • showSeries
  • articles
    • Chart Series


load

loads data from an external data source.

promise load(string url, [string type,function callback] );

Parameters

url | string | the data url
type | string | (optional) the type of data to load: 'json' (default), 'xml', 'jsarray', 'csv'
callback | function | (optional) the callback function

Returns

promise "promise" object

Example

$$("mylist").load("data.xml", "xml");

Details

Function signatures

The load method can be used with up to three parameters:

  • By default, the data type is set to 'json':
$$("component_id").load("some/path/data.json");
  • You can also pass a callback function:
$$('component_id').load("some/path/data.json", function(text, data, http_request){
  // do something with data.json()
});
  • If you need to specify both the data type and the callback:
$$("component_id").load("some/path/data.xml", "xml", function(text, data, http_request){
  // do something with the data object
});
//or
$$("component_id").load("some/path/data.xml", "xml", {
  error: function(text, data, http_request){
    webix.alert("error");
  },
  success:function(text, data, http_request){
    webix.message("success");
  }
});

Callback

By default, the loading is asynchronous, so you will need to use the callback to trigger some action after loading is finished.

The callback function takes 3 parameters:

  1. The text of the response
  2. The data object of the response
  3. The raw HTTP request object

Return Value

The method returns a Promises/A+ compatible promise object than contains the eventual result of an AJAX request.

Webix uses the Promiz.js library for promises. Learn more at:

  • Data Loading
  • Ajax operations

Error handlers

The callback can be defined as a combination of error and success functions (you can use only one of them if you want to).

Post and synchronous loading

As the load method doesn't provide direct ability to use post and sync, you can use the parse method instead:

// sync data loading
var result = webix.ajax().sync().get("some.json");
$$("component_id").parse(result.responseText);
// using POST for data loading
var result = webix.ajax().post("mydata.php", "some=value", function (text) {
  $$("component_id").parse(text);
});

See also

  • api
    • url
    • parse
    • data
    • datatype
  • samples
    • Form: Loading
  • articles
    • Data Loading


loadNext

sends a request to load the specified number of records to the end of the clientside dataset or to the specified position

void loadNext(number count,number start,function callback,string url,boolean now);

Parameters

count | number | the number of records fetch
start | number | the start position to load data from
callback | function | the callback function
url | string | the data url
now | boolean | specifies whether the incoming data request should be satisfied immediately. If it's set to true the datathrottle property will be ignored.

Example

//without callback
grida.loadNext(10,0,null,"data/data.php");

//with callback
gridb.loadNext(50,900,function(){
    this.showItem(903);
}, "data/data_dyn.php");

See also

  • api
    • datathrottle
  • samples
    • Dynamic loading with removing the existing content
    • Setting loading position
  • articles
    • Dynamic Loading


parse

loads data to the component from an inline data source

void parse(string| object data,string type);

Parameters

data | string| object | the data to add
type | string | the data type: 'json' (default), 'xml', 'csv', 'jsarray'

Example

webix.ui({
    id:"data",
    view:"dataview",
    ...
});

var str = "<data><item id='1'><title>The Lord of the Rings</title><year>2003</year></item>";
str += "<item id='2'><title>Star Wars: Episode V</title><year>1980</year></item></data>";

$$("data").parse(str,"xml");

Details

If you want to parse data in addition to the existing dataset, specify position of parsing, namely the index from which you insert new data:

$$("datatable").parse({
   pos: $$("datatable").count(), //number of records will be right the last index +1
   data:dataset
});

See also

  • api
    • load
    • data
    • url
    • datatype
  • samples
    • Dataview: JSON Dataset
    • Dataview: XML Dataset
  • articles
    • Data Loading


refresh

repaints the whole view or a certain item

void refresh( [id id] );

Parameters

id id the item id. If the parameter is set, just the specified item will be repainted

Example

$$("button1").define("label", "New value");
$$("button1").refresh();

See also

  • articles
    • Getting/setting the cell value
    • Changing Properties of Components


remove

removes the specified item/items from datastore

void remove(string/number/array id);

Parameters

id string/number/array the item id or an array of items' ids

Example

$$("my_list").remove(1); //removes the item with ID=1
$$("my_list").remove($$("data").getSelectedId()); //removes the selected item

$$("my_list").remove([1,3,5]); // removes multiple items

See also

  • api
    • add
    • clearAll
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


removeAllSeries

removes all series from the chart

void removeAllSeries();

Example

$$("mygantt").removeAllSeries();

Details

Can be used, if you want to define different set of series for the same chart


serialize

serializes data to a JSON object

object serialize();

Returns

object serialized JSON object


showSeries

shows the hidden graph in the chart

void showSeries(string series);

Parameters

series string ID of th series that should be shown.
Details

Works with already defined series and allows for manipulating their visibility. The method works for series that was previously hidden by hideSeries() method.

See also

  • api
    • hideSeries
  • articles
    • Chart Series


sort

sorts datastore

void sort(string by, [string dir,string as] );

Parameters

by | string | the name(s) of property(s) by which data will be sorted
dir | string | the sorting direction, default is "asc"
as | string | the type of data , default is "string"

Example

data.sort("price", "asc");

Details

Usage examples

The method sort can be used with different count of parameters.

The most common use case of the sort method is using the first parameter as the name of a property:

//sorts by name value; ascedent; sorted values as strings
data.sort("#name#","asc","string");
//sorts by price value; descedant; sorted values as numbers
data.sort("#price#","desc","int");

The property name should be included into sharps.

Instead of default sorting types, you can use your own method ( can be used for complex data types ):

function sort_by_length(data1, data2){
    return data1.length>data2.length ? 1:-1;
}

data.sort("#name#","asc",sort_by_length);

Possible return values of this function are 0,1,-1.

  • 1 means that the first object is greater than the second object;
  • -1 means that the first object is less than the second object;
  • 0 means that 2 objects are equal.

If you need to access multiple properties of an object during sorting or you need to have some complex sorting logic, use a function as the first parameter.

function my_sorting(a,b){
    //a, b - data objects
    return a.Version > b.Version ? 1 : -1;
}
data.sort(my_sorting, "des"); //3rd parameter will be ignored

Alternative syntax

You can use a hash of sorting settings as the first parameter of the sort method:

data.sort({
    as:"string",
    dir:"desc",
    by:"#Package#"
});

Sorting directions

Possible values for the second parameter of the sort method is string which represents sorting direction:

  • "asc" - for ascending sorting
  • "desc" - for decrescent sorting

Sorting types

The third parameter of the sort method may be string which represents the data type:

  • "int" - sorts as interger values
  • "string" - sorts as string
  • "string_strict" - sorts as string, case-sensitive

See also

  • samples
    • Sorting Datatable. Using sorting methods
  • articles
    • Operations with Chart Data


sync

allows syncing two copies of data (all or just a part of it) from one DataCollection to another

void sync(object source,function filter,boolean silent);

Parameters

source | object | the object that the method is assigned to
filter | function | the filtering function
silent | boolean | if you set the parameter to `true`, the object won't be repainted after synchronization

Example

// full copy
$$("list").data.sync(data);

// partial copy
$$("dview").data.sync(data, function(){
    this.filter(function (data) {
    return data.year > 1994;
    });
});

See also

  • api
    • filter
    • silent
    • unsync
  • samples
    • DataCollection Syncing
    • Get Popup View
  • articles
    • Data Binding and Syncing
    • Data Binding and Syncing with Non-UI Objects


ungroup

ungroups data

void ungroup(boolean mode);

Parameters

mode boolean defines whether the component should be re-rendered after ungrouping ( by default, true)

Example

myview.group({
    by:"#company#", // 'company' is the name of data property
    map:{
        sales:["#sales#","sum"]
    }
});
...
myview.ungroup();

See also

  • api
    • group
  • articles
    • Grouping Data Items


updateItem

sets properties of the data item

void updateItem(id id,object data);

Parameters

id | id | the item id
data | object | the hash of properties

Example

var sel = dtable.getSelectedId();
var row = dtable.getItem(sel.row);
row[sel.column] = "some_new_value";

dtable.updateItem(sel.row, row);

See also

  • samples
    • Server-side Integration: Datatable
  • articles
    • Data Updating
    • Tree Nodes manipulations


Properties

alpha | defines the opacity of chart items
animate | defines or disables view change animation.
barWidth | the width of bars
border | enables/disables the bar borders
borderColor | sets the border color of each item in the graph
borderless | used to hide the component borders
cant | defines the slope angle of 3D pie
color | defines items colors
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disableLines | disapbles graph lines with radar chart
disabled | indicates whether an item is enabled or not
eventRadius | sets the radius (in pixels) of the virtual circle which events will fire for items within
fill | fills the chart area with the specified background color.
fixOverflow | chart max limit mode
gradient | specifies the chart gradient
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
item | defines markers that present chart's data items
label | sets the template for items' labels
labelOffset | the offset of sector labels from the pie frame
legend | defines the chart legend
line | defines chart lines
lineColor | sets the color for strips dividing the pie sectors
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
offset | defines whether the first item of the scale will be drawn with the offset equal to the half of the scale's step (relative to the origin of the chart) or not.
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
origin | sets the scale origin
padding | sets paddings of the chart content
pieHeight | the height of the 3d pie
pieInnerText | sets the template for the pie inner labels
preset | applies the predefined chart configuration object with the specified name
radius | the radius of the bar's rounding
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scale | type of chart scale, logarithic or plain
scheme | defines schemes for data processing
series | defines graphs presented on the chart
shadow | enables/disables the pie shadow
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | sets the chart type
url | the URL which the component will use to load data after its initialization
value | defines values for the vertical axis
width | sets the width of the component
x | the horizontal position of the pie center
xAxis | defines the horizontal axis
xValue | a property of the dataset that defines values for the horizontal axis
y | the vertical position of the pie center
yAxis | defines the vertical axis
yValue | a property of the dataset that defines values for the vertical axis.


alpha

defines the opacity of chart items

number alpha;

Example

webix.ui({
    view:"chart",
    container:"chartDiv",
    type:"bar",
    ...
    alpha:0.5
});

See also

  • samples
    • Basic Coloring
  • articles
    • Settings for Bar Charts
    • Details

    The parameter can take value from 0.0 (fully transparent) to 1.0 (fully opaque).
    The default value - 1.


barWidth

the width of bars

number barWidth;

Example

webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    label:"#sales#",
    barWidth:35,
    data: dataset
});

See also

  • samples
    • Bar Chart: Basic Initialization
  • articles
    • Settings for Bar Charts
    • Details

    The default value is 30.


border

enables/disables the bar borders

boolean border;

Example

webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    label:"#sales#",
    border:false,
    data: dataset
})

See also

  • api
    • borderColor
  • samples
    • Basic Coloring
  • articles
    • Chart Types
    • Details

    The default value is true.


borderColor

sets the border color of each item in the graph

string borderColor;

See also

  • api
    • border
  • samples
    • Scatter Chart: Basic Initialization
  • articles
    • Chart Types
    • Details

    color is set in a hexadecimal format. By default, borders and colored greay (#636363).


cant

defines the slope angle of 3D pie

number cant;

Example

webix.ui({
    view: "chart",
    type:"pie3D",
    container:"chartDiv",
    value:"#sales#",
    label:"#month#",
    cant:0.7,
    data:month_dataset
});

See also

  • articles
    • Settings for Pie Charts
    • Details

    The parameter can take value from 0 to 1.
    The default value is 0.5 .


color

defines items colors

string|function color;

Example

webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    label:"#sales#",
    color:"#66ccff",
    data: dataset
});

See also

  • samples
    • Basic Coloring
    • Specifying Color as a Function
  • articles
    • Color Effects


data

JavaScript array containing data for the component

string|array data;

Example

var books = [
    [ "War and Peace", "Leo Tolstoy" ],
    [ "Hamlet", "Shakespeare" ],
    [ "Madame Bovary", "Gustave Flaubert" ]
];

webix.ui({
    view: "list",
    data: books,
    datatype: "jsarray",
    template: "#data0# (#data1#)"
});

See also

  • api
    • datatype
  • samples
    • DataView Basic Initialization
  • articles
    • Data Loading
    • Details

    For data types other than JSON the property is used in conjunction with the datatype parameter.


datathrottle

sets the polling interval (the time period between the completion of a network request and the next request for data)

number datathrottle;

Example

grid = new webix.ui({
    view:"datatable",
    columns:[{...}, {...}],
    datathrottle:500,
    url:"data/data_dyn.php"
});

See also

  • samples
    • Setting polling interval
  • articles
    • Dynamic Loading
    • Details
    • The option is used during dynamical loading and allows you to skip unnecessary data requests during fast scrolling the dataset.
    • If a new request for data will be received during the waiting period, the timer will be reset and original loading command will be ignored.


datatype

the type of loaded data

string datatype;

Values

  • JSON (default)
  • XML
  • JSArray
  • CSV

    • Example

    webix.ui({
    view:"datatable",
    url:"data.xml",
    datatype:"xml"
});

    See also

  • api
    • data
    • url
  • samples
    • Dataview: XML Dataset
  • articles
    • Data Loading
    • Supported Data Types
    • Details

    With JSON data type you can omit this property.


disableLines

disapbles graph lines with radar chart

boolean disableLines;

See also

  • samples
    • Radar Chart: Points
  • articles
    • Settings for Radar Chart
    • Details

    False by default. Set to true it leaves only points on the radar map while the joining line is missing.


eventRadius

sets the radius (in pixels) of the virtual circle which events will fire for items within

number eventRadius;

Example

webix.ui({
    container:"chartDiv",
    view:"chart",
    type:"area",
    xAxis:{
        template:"'#year#"
    },
    eventRadius: 5
})

See also

  • samples
    • Area Chart: Several Graphs in One Chart
  • articles
    • Setting for Line Charts
    • Settings for Radar Chart
    • Settings for Scatter Chart
    • Details

    By default, item-related events, such as onItemClick, onMouseMove etc., occur when the user clicks or holds the mouse over the item point. To increase the area where these events are listened to, you should use eventRadius.

    Let's take a simple example - a line chart with enabled tooltips.

    var lineChart =  new WebixChart({
    view:"line",
    ...
    tooltip:{
         template:"itemId=#id#"
    }
});

    As you probably know, tooltips are displayed/hidden when the onMouseMove / onMouseOut events occur for an item.
    So, to see the tooltip the user should hold the mouse over the item point.

    If you want to give users a bit of freedom and display tooltips not only when the mouse is over the point but also when it's some distance away, you can specify eventRadius:

    var lineChart =  new WebixChart({
    view:"line",
    ...
    tooltip:{
         template:"itemId=#id#"
    },
    eventRadius:10
});


fill

fills the chart area with the specified background color.

string fill;

Example

webix.ui({
    view:"chart",
    type:"radar",
    ...
    fill:"#3399ff"
})

See also

  • samples
    • Radar Chart: Areas
  • articles
    • Settings for Radar Chart
    • Details

    The property is applicable only to radar charts.


fixOverflow

chart max limit mode

boolean fixOverflow;

Example

$$("chart1").define("fixOverflow", true);

Details

When enabled, chart lines will not be rounded by max scale value


gradient

specifies the chart gradient

boolean|string|function gradient;

Example

webix.ui({
    view:"chart",
    type:"bar",
    gradient:"falling",
    ...
})

See also

  • samples
    • Basic Coloring
  • articles
    • Color Effects
    • Settings for Bar Charts
    • Settings for Pie Charts
    • Details

    The property is applicable only to the bar, pie charts

    Bar charts

    In bar charts the property can be defined as:

    • a string
    • a function

    String definition

    As a string, the propperty takes one of predefined values, which are:

    • 'light' (default value)
    • '3d'
    • 'rising'
    • 'falling'
    webix.ui({
    view:"chart",
    type:"bar",
    gradient:"rising",
    ...
})

    Related sample: Chart: XML Dataset

    Function definition

    As a function, the property accepts 1 parameter - a canvas gradient object.
    You may use the addColorStop(position, color) method to assign the required colors to the gradient object:

    • addColorStop(position, color)
      • position - a number between 0.0 and 1.0 that defines the relative position of the color in the gradient
      • color - a string representing a CSS color
    webix.ui({
    view:"chart",
    type:"bar",
    gradient:function(gradient){
        gradient.addColorStop(0.0,"#FF0000");
        gradient.addColorStop(0.8,"#FFFF00");
        gradient.addColorStop(1.0,"#00FF22");
    },
    ...
})

    Related sample: Color Gradient

    Pie Charts

    In pie charts the property can have only a bool value.

    The true value enables the gradient in the chart:

    webix.ui({
    view:"chart",
    type:"pie",
    gradient:true
    ...
})

    Related sample: Donut Pie Chart


item

defines markers that present chart's data items

object item;

Example

webix.ui({
    view:"chart",
    type:"line",
    item:{
        borderColor:"#ffffff",
        color:"#000000"
    }
    ...
})

See also

  • samples
    • Line Chart: Basic Initialization
    • Line Chart: Styling
  • articles
    • Chart Types
    • Settings for Scatter Chart
    • Setting for Line Charts
    • Settings for Radar Chart
    • Details

    The property is applicable only to line, radar and scatter charts

    The available attributes of the property are:

    alpha | (number from 0 to 1) the marker opacity (by default, 1)
    borderColor | (string,function) the outer color of a marker (by default, "#636363"). As a function, it accepts a data object and is called for each data item
    borderWidth | (number) the width of the border line in pixels (by default, 1)
    color | (string,function) the inner color of a marker (by default, "#ffffff"). As a function, it accepts a data object and is called for each data item
    radius | (number) the marker radius in pixels (by default, 3)
    shadow | (bool) enables the marker shadow (by default, false)
    type (string) the shape of a marker ( by default, 'r')
    The predefined values are:
    • 'r' - round
    • 'd' - diamond
    • 's' - square


label

sets the template for items' labels

string|function label;

Example

webix.ui({
    view:"chart",
    type:"bar",
    label:"#year#",
    ...
})

See also

  • samples
    • Pie Chart: Basic Initialization
    • Bar Chart: Basic Initialization
    • Line Chart: Styling
  • articles
    • Chart Types
    • Details

    Generally, charts show labels above data items.
    Pie charts show labels outside sectors. To define labels within pie's sectors, use the pieInnerText property.


labelOffset

the offset of sector labels from the pie frame

number labelOffset;

Example

webix.ui({
    view: "chart",
    type:"pie",
    label:"#month#",
    labelOffset:40,
    ...
})

See also

  • api
    • label
  • articles
    • Settings for Pie Charts
    • Details

    The default value of the property is 20.


legend

defines the chart legend

object legend;

Example

webix.ui({
    view:"chart",
    ...
    legend:{
        width:90,
        values:[{text:"Type A",color:"#58dccd"},{text:"Type B",color:"#a7ee70"}],
        align:"right"
    }
})

See also

  • samples
    • Radar Chart: Areas
    • Bar Chart: Several Graphs in One Chart
  • articles
    • Setting Legend for a Chart
    • Details

    The available attributes of the property are:

    width | (number) the legend block's width (by default, 150)
    height | (number) the legend block's height (by default, 18)
    layout | ('x' or 'y') defines whether items should be placed vertically or horizontally (by default, y)
    align | ('left', 'right', 'center') the horizontal alignment of the block (by default, "left")
    valign | ('top', 'bottom, 'middle') the vertical alignment of the block (by default, 'bottom')
    margin | (number) sets all four margins of the legend block to the specified value (by default, 4)
    padding | (number) sets all four paddings of the legend block to the specified value (by default, 3)
    template | (string) the template for legend items. Creates an individual legend item for each object the data source. If you want to present just specific data objects (not all of them), use the values attribute
    toggle | (bool) enables/disables the possibility to hide/show a graph by clicking on the graph legend item. For all charts, except for Stacked Vertical Bar, Stacked Horizontal Bar and Stacked Area, the default value is true. For the excepted charts the default value is false.
    values (array ) an array of objects, each one of which specified a discrete legend item. If it's set, the template attribute is ignored.
    Can have the following attributes:
    • text - (string) the item text
    • color - (string,function) the item color. As a function, the property accepts a data object and is called for each data item
    • markerType - ('square', 'round' or 'item') the marker type: 'square', 'round' or 'item' (by default, 'square'). If you set the 'item' type, the legend marker will use the same template as items in the chart
    • toggle - (bool) enables/disables the possibility to hide/show a graph by clicking on the specified legend item
    marker (object) an object that defines item markers in the legend.
    Can have the following attributes:
    • type - ('square', 'round' or 'item') the marker type (by default, 'square'). If you set the 'item' type, the legend marker will use the same template as items in the chart
    • width - (number) the marker width (by default, 15)
    • height - (number) the marker height (by default, 15)
    • radius - (number) the marker radius (by default, 3)


line

defines chart lines

object line;

Example

webix.ui({
    view:"chart",
    type:"spline",
    ...
    line:{
        color:"#ff9900",
        width:3
    }
})

See also

  • samples
    • Line Chart: Basic Initialization
    • Line Chart: Styling
  • articles
    • Setting for Line Charts
    • Settings for Scatter Chart
    • Settings for Radar Chart
    • Details

    The property is applicable only to line, radar and scatter charts

    The available attributes of the property are:

    width | (number) the line width (by default, 2)
color | (string,function) the line color (by default, "#1293f8"). As a function,it accepts a data object and is called for each data item


lineColor

sets the color for strips dividing the pie sectors

string lineColor;

Example

webix.ui({
    view: "chart",
    type:"pie",
    lineColor:"#A5A5A5",
    ...
})

See also

  • articles
    • Settings for Pie Charts
    • Details

    The property is applicable only to pie charts

    The default value of the property is "#ffffff".


offset

defines whether the first item of the scale will be drawn with the offset equal to the half of the scale's step (relative to the origin of the chart) or not.

boolean offset;

Example

webix.ui({
    view:"chart",
    type:"line",
    offset:false,
    ...
})

See also

  • samples
    • Line Chart: Axes
  • articles
    • Setting Chart Scales
    • Details

    The property is applicable only to line, scatter, area charts


origin

sets the scale origin

number origin;

Example

webix.ui({
    view:"chart",
    type:"bar",
    origin:30,
    ...
})

See also

  • samples
    • Bar Chart: Axis Origin
  • articles
    • Setting Chart Scales
    • Details

    The property is applicable only to line, bar charts

    As a string, the property can have value 'auto'. Actually, it's the default value of the property.


padding

sets paddings of the chart content

object padding;

Example

webix.ui({
    view:"chart",
    ...
    padding:{
        top: 6,
        left:10
    }
})

See also

  • samples
    • Bar Chart: Basic Initialization
  • articles
    • Settings for Bar Charts
    • Details

    The available attributes of the property are:

    • top - (number) the top padding
    • bottom - (number) the bottom padding
    • left - (number) the left padding
    • right - (number) the right padding


pieHeight

the height of the 3d pie

number pieHeight;

Example

webix.ui({
    view: "chart",
    type:"pie3D",
    pieHeight:50,
    ...
});

See also

  • articles
    • Settings for Pie Charts
    • Details

    The property is applicable only to pie3D charts


pieInnerText

sets the template for the pie inner labels

string|function pieInnerText;

Example

webix.ui({
    view:"chart",
    type:"pie",
    label:"#month#",
    pieInnerText:"#sales#",
    ...
})

See also

  • samples
    • 3D Pie Chart
  • articles
    • Settings for Pie Charts
    • Details

    The property is applicable only to pie charts

    As a function, the property accepts a data object and is called for each data item:

    webix.ui({
    view:"chart",
    type:"pie",
    pieInnerText:function(obj){ return obj.sales;},
    ...
})


preset

applies the predefined chart configuration object with the specified name

string preset;

Values

  • column
    bar charts
  • stick
    bar charts
  • alpha
    bar charts
  • area
    radar charts
  • line
    radar charts
  • point
    radar charts
  • simple
    line, scatter charts
  • plot
    line, scatter charts
  • round
    line, scatter charts
  • square
    line, scatter charts
  • diamond
    line, scatter charts

    • Example

    webix.ui({
    view:"chart",
    type:"radar",
    value:"#companyA#",
    preset:"line",
    xAxis:{ template:"#month#"},
    data:companies
)}

    See also

  • samples
    • Scatter Chart: Style Presets
    • Line Chart: Style Presets
    • Radar Chart: Style Presets
  • articles
    • Settings for Bar Charts
    • Settings for Radar Chart
    • Setting for Line Charts


radius

the radius of the bar's rounding

number radius;

Example

webix.ui({
    view:"chart",
    type:"bar",
    radius:0,
    ...
});

See also

  • samples
    • Bar Chart: Labels
  • articles
    • Settings for Bar Charts
    • Details

    The property is applicable to bar charts.

    When used within item object of scatter, radar and line charts, the property defines radius of the point on the map.


ready

event handler called just after the component has been completely initialized

function ready;

Example

webix.ui({
  view: "tree",
  ready: function() {
    ...  // called after the component has been initialized
  },
});

See also

  • samples
    • Empty list
  • articles
    • Event Handling
    • Start Coding with Webix
    • Details

    The ready event handler will be called only once. Dynamic data loading won't trigger the handler. This is a good place for post-initialization code.

    The example below shows the succession of event handler calls (first data, then ready) and demonstrates how to set the URL of a component without triggering data loading.

    webix.ui({
  view: "tree",
  data: function () {
    webix.message("data");  // displayed first
    return [
      { id: "1", value: "Branch", webix_kids: true }
    ]
  }(),
  ready: function() {
    // displayed second
    webix.message("ready");
    // set the DataStore URL without triggering data loading
    this.data.url = "data/data_dyn.php";
  },
});

    The line this.data points to a TreeStore object, which was parsed from the inline data property passed to the Tree constructor.


removeMissed

defines how to treat items in case of reloading

boolean removeMissed;

Example

dtable.config.removeMissed = true;
dtable.load("updated.json");

See also

  • articles
    • Data Loading
    • Details

    The property specifies how to treat data items that were deleted from the data source but still exist on the client.

    • false - (default value) the items will be left on the client after reloading data.
    • true - the items will be removed from the client after reloading data.


save

defines URLs for data saving

string save;

Example

webix.ui({
  id: "mylist",
  view: "list",
  url: "data.php",
  save: "save.php"
});

See also

  • articles
    • DataProcessor
    • Server-side Integration
    • Details

    If the property is set, the component will create a DataProcessor instance, and initialize it with the defined URL.

    If you need to get the DataProcessor, you can use:

    var view = $$("myview");
var dp = webix.dp(view);  // the dataprocessor that was assigned to the view

    To use a server-side connector, you can initialize save as follows:

    webix.ui({
  view: "list",
  url: "data.php",
  save: "connector->save.php"
})


scale

type of chart scale, logarithic or plain

string scale;

Values

  • logarithmic
    sets a logarithmic scale
  • linear
    sets a linear scale

    • Example

    webix.ui({
  view:"chart",
  scale:"logarithmic"
});


scheme

defines schemes for data processing

object scheme;

Example

var list1 = webix.ui({
    view:"list",
    ...
    scheme:{
        name:"Unknown",
        age:16
    }
});
list1.add({}); //adds { name:"Unknown", age:16} record

See also

  • samples
    • List: Grouping
    • Grouping
  • articles
    • Defining Data Scheme


series

defines graphs presented on the chart

object series;

Example

webix.ui({
    view:"chart",
    type:"bar",
    ...
    series:[
        {
            value:"#sales#",
            color:"#58dccd"
        },
        {
            value:"#sales2#",
            color:"#36abee",
        }
    ]
});

See also

  • api
    • addSeries
  • samples
    • Bar Chart: Several Graphs in One Chart
  • articles
    • Chart Series
    • Details

    The property is used to present multiple graphs on a chart. Graphs are specified in a standard way.

    If you add to the chart graphs of the same type, you can omit the type attribute.


shadow

enables/disables the pie shadow

boolean shadow;

Example

webix.ui({
    view: "chart",
    type:"pie",
    shadow:0,
    ...
})

See also

  • samples
    • 3D Pie Chart
    • Details

    The property is applicable only to pie charts


tooltip

sets a popup message appearing on pointing a mouse cursor over the dedicated item.

object tooltip;

Example

webix.ui({
     view:"dataview",
     tooltip:"Rating: #rating#<br/> Votes: #votes#",
     ...
});

See also

  • samples
    • Template of Tooltips
  • articles
    • Chart Tooltip
    • Details

    In the tooltip template there're values transmitted from the dataset.


type

sets the chart type

string type;

Values

  • area
  • bar
  • barH
  • donut
  • line
  • pie
  • pie3D
  • radar
  • scatter
  • spline
  • stackedArea
  • stackedBar
  • stackedBarH

    • Example

    webix.ui({
    view:"chart",
    type:"barH",
    ...
});

    See also

  • samples
    • Chart: XML Dataset
    • Area Chart: Basic Initialization
  • articles
    • Chart Types


url

the URL which the component will use to load data after its initialization

string url;

Example

webix.ui({
  datatype: "xml",
    url: "data.xml"
    ...
});

See also

  • api
    • load
    • parse
    • data
    • datatype
  • samples
    • Loading Data from URL
  • articles
    • Data Loading
    • Details

    Used in conjunction with the datatype parameter. If datatype isn't provided, the component will expect data in JSON format.


value

defines values for the vertical axis

template value;

Example

webix.ui({
    view:"chart",
    type:"bar",
    value:"#sales#",
    label:"#year#",
    ...
});

See also

  • samples
    • Chart: XML Dataset
    • Area Chart: Basic Initialization
  • articles
    • Chart Types
    • Setting Chart Scales
    • Details

    As a function, the property accepts a data object and is called for each data item:

    webix.ui({
    view:"chart",
    value:"#sales#",
    ...
})
//is equal to
webix.ui({
    view:"chart",
    value:function(obj){ return obj.sales; },
    ...
})


x

the horizontal position of the pie center

number x;

Example

webix.ui({
    view: "chart",
    type:"pie",
    x:180,
    y:120
    ...
})

See also

  • api
    • y
  • samples
    • Pie Chart: Basic and Custom Legend
  • articles
    • Settings for Pie Charts
    • Details

    The property is applicable only to pie charts


xAxis

defines the horizontal axis

object xAxis;

Example

webix.ui({
    view:"chart",
    ...
    xAxis:{
        title: "Years",
        template: "#year#",
        lines: true
    }
});

See also

  • api
    • yAxis
  • samples
    • Bar Chart: Axes
  • articles
    • Setting Chart Scales
    • Custom X-Axis Formation
    • Details

    The property is applicable only to bar, line, area, scatter, radar charts.
    Only the 'template' attribute is mandatory

    Attributes of the property differ for different chart types:

    template | (string,function) the template for the scale labels | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
title | (string) the axis title | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH
lines | (bool, function) enables/disables vertical lines for the scale units (by default, true) | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
lineColor | (string,function) the color of the scale lines (by default, "#cfcfcf") | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
color | (string) the axis color (by default, "#000000") | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH
start | (number) the minimum value of the scale | barH, stackedBarH
end | (number) the maximum value of the scale | barH, stackedBarH
step | (number) the scale step | barH, stackedBarH

    If attributes end, start, step are not set, they will be automatically calculated.
    However, you may control the minimum value of the scale by using the origin property. For example, if you set origin:0, the scale will start from '0', even if the minimum value in the dataset is greater.

    'template' attribute. Function definition

    As a function, 'template' is called for each data item of the chart and takes the item object as a parameter.

    template: function(obj){
       return webix.i18n.dateFormatStr("%F")(obj.date); //returns the month name
}

    'lineColor' attribute. Function definition

    Function definition allows you have different lines in different colors.

    As a function, 'lineColor' is called for each data item of the chart and takes the item object as a parameter. Must return the true(show the line) or false(hide the line) value.

    lineColor:function(obj){
       return (obj.year%2?"#e9eef9":"#f3f7ff") //colors lines for odd and even years in different colors
}

    'lines' attribute. Function definition

    Function definition allows you to manipulate the visibility of lines: to hide/show them depending on the specified rules. We reccomend to use such a definition in case you have a lot of items, to prevent the chart from looking overloaded.

    As a function, 'lines' is called for each data item of the chart and takes the item object as a parameter. Must return the true(show the line) or false(hide the line) value.

    lines:function(obj){
       return (obj.year%2?true:false) // hides lines for odd years
}


xValue

a property of the dataset that defines values for the horizontal axis

string xValue;

Example

webix.ui({
    view:"chart",
    type:"scatter",
    xValue: "#a#",
    ...
});

See also

  • api
    • yValue
  • samples
    • Scatter Chart: Basic Initialization
    • Scatter Chart: Templates
    • Details

    The property is applicable only to scatter charts


y

the vertical position of the pie center

number y;

Example

webix.ui({
    view: "chart",
    type:"pie",
    x:180,
    y:120
    ...
});

See also

  • api
    • x
  • samples
    • Pie Chart: Basic and Custom Legend
  • articles
    • Settings for Pie Charts
    • Details

    The property is applicable only to pie charts


yAxis

defines the vertical axis

object yAxis;

Example

webix.ui({
    view:"chart",
    ...
    yAxis:{
        start:-10,
        end:10,
        step:2,
        title:"Sales"
    },
    origin:0
});

See also

  • api
    • xAxis
  • samples
    • Bar Chart: Axes
  • articles
    • Setting Chart Scales
    • Details

    The property is applicable only to bar, line, area, scatter, radar charts.
    All the attributes are optional

    Available set of attributes depends on the chart type:

    start | (number) the minimum value of the scale | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
end | (number) the maximum value of the scale | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
step | (number) the scale step | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
template | (string,function) the template for the scale labels | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
title | (string) the axis title | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH
lines | (bool, function) enables/disables horizontal lines for the scale units (by default, true) | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
color | (string) the axis color (by default, "#000000") | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH
lineColor | (string,function) the color of the scale lines (by default, "#cfcfcf") | bar, stackedBar, line, spline, area, stackedArea, scatter, barH, stackedBarH, radar
lineShape | ("arc" or "line") the shape of lines (by default, "line") | radar
bg | (string,function) the background color (by default, "#ffffff") | radar

    If attributes end, start, step are not set, they will be automatically calculated.
    However, you may control the minimum value of the scale by using the origin property. For example, if you set origin:0, the scale will start from '0', even if the minimum value in the dataset is greater.

    'template' attribute. Function definition

    As a function, 'template' is called for each scale item of the chart and takes the item numeric value as a parameter.

    template: function(value){
    return value%10?"":value
}

    'lines' attribute. Function definition

    Function definition allows you to manipulate the visibility of lines: to hide/show them depending on the specified rules. We reccomend to use such a definition in case you have a lot of items, to prevent the chart from looking overloaded.

    As a function, 'lines' is called for each scale item of the chart and takes the item index as a parameter. Must return the true(show the line) or false(hide the line) value.

    lines: function(index){
    return index%2?false:true // hides even lines
}

    'lineColor' attribute. Function definition

    Function definition allows you have different lines in different colors.

    As a function, 'lineColor' is called for each scale item of the chart and takes the item index as a parameter. Must return string with the desired color.

    lineColor: function(index){
    return index%2?"#e9eef9":"#f3f7ff";// colors odd and even lines in different colors
}

    Function definition allows you have different lines in different colors.

    As a function, 'lineColor' is called for each data item of the chart and takes the item object as a parameter. Must return the true(show the line) or false(hide the line) value.

    'bg' attribute. Function definition

    As a function, 'bg' is called for each scale item of the chart and takes 2 parameters: the yAxis item index and the xAxis item index.

    bg: function(yIndex, xIndex){
    return yIndex%2?"#e9eef9":"#f3f7ff";
}


yValue

a property of the dataset that defines values for the vertical axis.

string yValue;

Example

webix.ui({
    container:"chartDiv",
    view:"chart",
    type:"scatter",
    xValue: "#a#",
    yValue: "#b#"
    ...
});

See also

  • api
    • xValue
  • samples
    • Scatter Chart: Basic Initialization
  • articles
    • Setting Chart Scales
    • Details

    The method is analog to the value property.

    The property is applicable only to scatter charts


Events

onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterRender | called after the rendering of calendar is complete.
onAfterScroll | occurs when some webix view has been scrolled
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterAdd

fires after adding item to datastore

void onAfterAdd(number| string id,number index){ ... };

Parameters

id | number| string | clientside ID of the new data item
index | number | index, at which new item was added

Example

$$('some').attachEvent("onAfterAdd", function(id, index){
    webix.message("New record was added!");
});

Details

Event doesn't fire for rows which were added during loading(parsing) from external file or object.

See also

  • api
    • onBeforeAdd
    • add
    • DataStore
  • articles
    • Tree Nodes manipulations
    • Adding/Deleting Data Items


onAfterDelete

fires after item deleting

void onAfterDelete(id id){ ... };

Parameters

id id id of item in question

Example

some.attachEvent("onAfterDelete", function(id){
    //... some code here ...
});

See also

  • api
    • onBeforeDelete
    • remove
  • articles
    • Tree Nodes manipulations
    • Operations with Chart Data
    • Adding/Deleting Data Items


onAfterLoad

fires after data loading is complete

void onAfterLoad(){ ... };

Example

mygrid.attachEvent("onAfterLoad", function(){
    webix.message("Data loaded");
})

See also

  • api
    • onBeforeLoad
  • samples
    • Loading screen
  • articles
    • Data Loading


onAfterRender

called after the rendering of calendar is complete.

void onAfterRender(){ ... };

Example

some.attachEvent("onAfterRender", function(){
    //... some code here ...
});

See also

  • api
    • onBeforeRender
  • articles
    • View


onAfterSort

fires after sorting dataset

void onAfterSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Example

some.attachEvent("onAfterSort", function(by, dir, as){
    //... some code here ...
});

See also

  • api
    • sort
    • onBeforeSort
  • articles
    • Operations with Chart Data


onBeforeAdd

fires before adding item to datastore

boolean onBeforeAdd(string|number id ,object obj,number index){ ... };

Parameters

id | string|number | id of the newly added data item
obj | object | data for new item
index | number | index, at which new item will be added

Returns

boolean false if operation need to be blocked

Example

$$('some').attachEvent("onBeforeAdd", function(obj, index){
    if (obj.text == "")
        return false;
});

See also

  • api
    • onAfterAdd
    • add
    • DataStore
  • articles
    • Tree Nodes manipulations
    • Adding/Deleting Data Items


onBeforeDelete

fires before item deleting

boolean onBeforeDelete(id id){ ... };

Parameters

id id id of item in question

Returns

boolean returning false will prevent item deleting

Example

some.attachEvent("onBeforeDelete", function(id){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • onAfterDelete
    • remove
  • articles
    • Tree Nodes manipulations
    • Operations with Chart Data
    • Adding/Deleting Data Items


onBeforeLoad

occurs immediately before data loading has been started

void onBeforeLoad(){ ... };

Example

mygrid.attachEvent("onAfterLoad", function(){
    webix.message("Loading...");
})

See also

  • api
    • onAfterLoad
  • samples
    • Loading screen
  • articles
    • Data Loading
    • Supported Data Types


onBeforeRender

occurs immediately before the component has been rendered

void onBeforeRender(object data){ ... };

Parameters

data object the DataStore object that the chart gets data from

Example

some.attachEvent("onBeforeRender", function(){
    //... some code here ...
});

Details

Returning false from the event handler will block further processing.

See also

  • api
    • onAfterRender
  • articles
    • View


onBeforeSort

fires before sorting dataset

boolean onBeforeSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Returns

boolean returning false will prevent sorting

Example

some.attachEvent("onBeforeSort", function(by, dir, as){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • sort
    • onAfterSort
  • articles
    • Operations with Chart Data


onDataRequest

fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading

void onDataRequest(number start,number count, [function callback,string url] ){ ... };

Parameters

start | number | the position which data starts to be loaded from
count | number | the count of records that need loading
callback | function | the method called after data loading
url | string | the data URL

Example

dtable.attachEvent("onDataRequest", function (start, count) {
  var data = custom_load_data(start, count);
  dtable.parse(data, "json");
  return false; //cancelling default behaviour
));

Details

Dynamic loading for linear data structures is triggered during scrolling and paging. For hierarchical data structures such as Tree or TreeTable, dynamic data loading is triggered when nodes with the webix_kids flag are expanded.

The component will use the data source specified by its url property or via the url parameter passed to the load method.

See also

  • articles
    • Server-side Integration
    • Dynamic Loading
    • Dynamic Loading for Plain Structures


onDataUpdate

fires when data item is in update process

void onDataUpdate(id id,object data){ ... };

Parameters

id | id | id of item
data | object | new data hash

Example

some.attachEvent("onDataUpdate", function(id, data){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • onStoreUpdated
    • updateItem
  • articles
    • Data Updating
    • Tree Nodes manipulations


onLoadError

fires when an error occurs during data loading ( invalid server side response )

void onLoadError(string text,object xml,object xhr){ ... };

Parameters

text | string | the server side response as plain text
xml | object | an xml object ( may be null if XML data was corrupted )
xhr | object | an xhr object

Example

dtable.attachEvent("onLoadError", function(text,xml,xhr){
    webix.message("Loading error");
));

Details

The event occurs after XML loading is complete.

See also

  • articles
    • Management of loading errors
    • Data Loading


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
colormap | collection of coloring strategies
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
presets | collection of styling presets


colormap

collection of coloring strategies

hash colormap;
Details

When bar colors not defined, chart will take one of possible coloring strategies and will use it for bar coloring. Default one is "RAINBOW"


presets

collection of styling presets

hash presets;

Example

webix.ui.chart.presets["mystyle"] = {
    line:{
        color:"#ff0000",
        width:2
    }
};


ui.checkbox

A two-state check box.

The control allows users to make multiple choices from a number of options. Fully customizable and can be used both as a stand-alone view and as a part of a form. Check checkbox documentation for more detailed description.

Constructor

var checkbox = webix.ui({
    view:"checkbox",
    id:"field_a",
    label:"Second age",
    value:1
});

Where to start

  • Overview of the Checkbox Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
toggle | swiches between states of the control ('checked' to 'unchecked' and vice-versa)
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
checkValue | result of getValue for checked checkbox
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
customCheckbox | enables/disables custom checkbox in some skins
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelRight | sets the text of the right-hand label. Only checkbox features this functionality
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
uncheckValue | result of getValue for unchecked checkbox
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
toggle | swiches between states of the control ('checked' to 'unchecked' and vice-versa)
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


toggle

swiches between states of the control ('checked' to 'unchecked' and vice-versa)

void toggle();

Example

webix.ui({
    container:"box",
    cols:[
        { view:"form", elements:[
            { view:"checkbox", id:"ch1", label:"Block pop-up windows"},
            { view:"checkbox", id:"ch2", label:"Load images automatically"},
            { view:"checkbox", id:"ch3", label:"Enable JavaScript"}
        ]}
    ]
});

$$('ch1').toggle(); //checks the checkbox
$$('ch1').toggle(); //unchecks the checkbox


validate

validates value of input

boolean validate();

Returns

boolean result of validation

Example

if ($$("mytext").validate()){
    ....
}

Details

Note that for proper validation:

  • input should be nested into a form;
  • but only its own validation rule will be considered.
webix.ui({
    view:"form",
    elements:[
        { view:"text", required:true, name:"text1" },
        { view:"text", validate:webix.rules.isNumber, name:"text2" },
    ],
    elementsConfig:{
        on:{
           'onChange':function(newv, oldv){
              this.validate();
            }
        }
    }
});

See also

  • samples
    • Per Item Validation with Predefined Rules
  • articles
    • Data Validation


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
checkValue | result of getValue for checked checkbox
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
customCheckbox | enables/disables custom checkbox in some skins
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelRight | sets the text of the right-hand label. Only checkbox features this functionality
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
uncheckValue | result of getValue for unchecked checkbox
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


attributes

sets a hash of HTML input attributes that will be parsed for the Webix input control

object attributes;

Example

{ view:"text", id:'field_a', attributes:{ maxlength:10 }}
//will result in the following html
//<input type='text' maxlength='10'>

Details

Webix control input generates an HTML input with a specific number of attributes. But you can define a set of extra ones ( which is not generated by default )


bottomLabel

sets a label under a control

string bottomLabel;

Example

{ view:"text", label:"Username", bottomLabel: "* spaces are allowed"},

See also

  • api
    • bottomPadding
    • labelPosition
  • samples
    • Input Description at the Bottom
  • articles
    • Data Validation
    • Details

    To specify the height of the bottom label, the bottomPadding property should be set.


bottomPadding

sets the bottom offset of the control input

number bottomPadding;

Example

{ view:"text", type:"password", label:"Password", bottomPadding: 35,
    bottomLabel: "* The password must have at least 6 characters"}

See also

  • api
    • bottomLabel
    • invalidMessage
  • samples
    • Validation Message
    • Input Description at the Bottom
  • articles
    • Data Validation
    • Details

    The property can be used for setting space for a bottom label or an invalid message.
    The property is 18 px by default.


checkValue

result of getValue for checked checkbox

string checkValue;

Example

webix.ui({ view:"checkbox", checkValue:"on" })

See also

  • api
    • uncheckValue
  • samples
    • Check Box ('checkbox')
  • articles
    • Checkbox
    • Details

    Default value is 1.


customCheckbox

enables/disables custom checkbox in some skins

boolean customCheckbox;

Example

{ view:"checkbox", customCheckbox:false }

Details

Webix checkbox control is based on standard HTML checkbox, but some skins use a FontAwesome icon to render it. Then the value of customCheckbox parameter is true by default.

To switch to a standard HTML checkbox, use customCheckbox property.


inputPadding

padding of text in the input

number inputPadding;

Example

webix.ui({
    view:"text",
    inputPadding:10
})

Details

Normally you will set the padding through custom css class, this property is necessary for different skin support and some corner cases.


invalidMessage

sets the text of a validation message

string invalidMessage;

Example

{view:"text", label:'E-mail address', name:"email",
    invalidMessage: "Incorrect e-mail address"}

See also

  • api
    • bottomPadding
  • samples
    • Validation Message
  • articles
    • Data Validation


label

the text label of the control

string label;

Example

webix.ui({
    container:"box",
    cols:[
        { view:"form", elements:[
            { view:"checkbox", id:"ch1", label:"Block pop-up windows"},
            { view:"checkbox", id:"ch2", label:"Load images automatically"},
            { view:"checkbox", id:"ch3", label:"Enable JavaScript"}
        ]}
    ]
});

See also

  • samples
    • Buttons: Different Sizes
  • articles
    • Controls Guide
    • Details

    The property should not be mixed with the label control.

    Moreover, label control can have a label as well, but there's no sense in it.


labelPosition

positions label in relation to the control

string labelPosition;

Values

  • top
    places label above the control

    • Example

    {view: "text", label:"Some Text", labelPosition:"top"}

    See also

  • api
    • bottomLabel
  • samples
    • Positioning Labels
  • articles
    • Controls Guide
    • Details

    By default label features left alignment, so the top label will be placed to the left upper corner of the control.

    Top right alignment is achieved by applying both properties:

    {view: "text", label:"Some Text", labelAlign:"right", labelPosition:"top"}

    To apply right alignment to the label of a checkbox, use the labelRight property.


labelRight

sets the text of the right-hand label. Only checkbox features this functionality

string labelRight;

Example

{view:"checkbox", labelRight:"New Label"}

See also

  • api
    • label
  • samples
    • Check Box ('checkbox')
  • articles
    • Checkbox


labelWidth

the width of the label

number labelWidth;

Example

webix.ui({
    container:"box",
    cols:[
        { view:"form", elements:[
            { view:"checkbox", id:"ch1", label:"Block pop-up windows", labelWidth:80},
            { view:"checkbox", id:"ch2", label:"Load images automatically"},
            { view:"checkbox", id:"ch3", label:"Enable JavaScript"}
        ]}
    ]
});

See also

  • api
    • label
  • samples
    • Text Input ('text')
  • articles
    • Controls Guide


relatedAction

action to call when value of cell changes

string relatedAction;

Values

  • show
    if true, shows related view
  • enable
    if true, enabled related view

    • Example

    webix.ui({
   view:"checkbox", relatedAction:"show", relatedView:"detailsArea"
})

    Details

    Possible values are "show", "enable"


relatedView

id of view, that will be affected by relatedAction operation

string relatedView;

Example

webix.ui({
   view:"checkbox", relatedAction:"show", relatedView:"detailsArea"
})


required

marks field as required

boolean required;

Example

webix.ui({ view:"text", required:true });


suggest

links suggest list to the input

string|object suggest;

Example

webix.ui({
    view:"text",
    suggest:"my_suggest_list"
})

See also

  • samples
    • Suggest List for Input: Populating with Server-side Data
    • Suggest List for Input: Populating with Client-side Data
  • articles
    • Suggest List


uncheckValue

result of getValue for unchecked checkbox

string uncheckValue;

Example

webix.ui({ view:"checkbox", uncheckValue:"off" })

See also

  • api
    • checkValue
  • samples
    • Check Box ('checkbox')
  • articles
    • Form Controls
    • Details

    Default value is 0.


validate

adds validation to the field

function validate;

Example

webix.ui({ view:"text", validate:webix.rules.isNumber });


validateEvent

on which event validation fires

string validateEvent;

Values

  • key
    validation starts on key pressing within the imput
  • blur
    validation starts when focus is removed from the control

    • Example

    webix.ui({ view:"text", validate:"isNumber", validateEvent:"key" });


Others

$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


$render

code called after rending control

function $render;


$renderIcon

renders icon for the control

function $renderIcon;

Example

webix.protoUI({
   name:"mytext",
   $renderIcon:function(){
       return "<span class='webix_icon fa-user'></span>";
   }
})


$renderInput

renders html for the input

string $renderInput(object obj,string html,id id);

Parameters

obj | object | input configuration
html | string | inner html of the input
id | id | unique id

Returns

string html string with full code of input

Example

var id = webix.uid();
var html = "some html content"
var text = input.$renderInput(input.config, html, id);

Details

Not purposed for direct calls

Can be used in custom view to redefine html content of the input.


$renderLabel

renders html for the label

string $renderLabel(object config,id id);

Parameters

config | object | control configuration
id | id | unique id of the control

Returns

string html code of control label

Example

var label = input.$renderLabel(input.config, "id");

Details

Not purposed for direct calls

Can be used in custom views to redefine html content of the control's label.


ui.colorboard

A color palette.

The component presents a div that contains a set of color swatches. Used as a part of the ui.colorpicker component. Check colorboard documentation for more detailed description.

Constructor

var colorboard = webix.ui({
    view:"colorboard",
    cols:20,
    rows:20,
    width:300,
    height:300
});

Where to start

  • Overview of the Colorboard Widget
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the component
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | sets the number of columns in the palette
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxLightness | sets the end value of lightness for the default color palette
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minLightness | sets the start value of lightness for the default color palette
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
palette | sets palette colors
rows | sets the number of rows in the palette
template | defines a custom template that will be applied to the component
value | currently selected color
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | highlights the color with the specified value in the colorboard
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the component
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getValue

returns the current value of the component

string getValue();

Returns

string a color in the hex format

Example

webix.ui({
    view:"colorboard",
    id:"color",
    cols    :30,
    rows    :30,
    width   :400,
    height  :400
});
$$('color3').setValue("#2626FF")

$$('color').getValue();// -> "#2626FF"

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
  • articles
    • Controls Guide


setValue

sets a new value for the component

string setValue(string value);

Parameters

value string a color in the hex format

Returns

string a color in the hex format

Example

webix.ui({
    view:"colorboard",
    id:"color",
    cols    :30,
    rows    :30,
    width   :400,
    height  :400
});
$$('color3').setValue("#2626FF");

$$('color').getValue();// -> "#2626FF"

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • getValue
    • value
  • articles
    • Controls Guide


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | sets the number of columns in the palette
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxLightness | sets the end value of lightness for the default color palette
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minLightness | sets the start value of lightness for the default color palette
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
palette | sets palette colors
rows | sets the number of rows in the palette
template | defines a custom template that will be applied to the component
value | currently selected color
width | sets the width of the component


cols

sets the number of columns in the palette

number cols;

Example

webix.ui({
    view:"colorboard",
    id:"color",
    cols    :30,
    rows    :30,
    width   :400,
    height  :400
});

See also

  • api
    • rows
  • samples
    • Colorboard


height

sets the height of the component

number height;

Example

webix.ui({
    view:"colorboard",
    id:"color",
    cols    :30,
    rows    :30,
    width   :400,
    height  :400
});

See also

  • api
    • rows
    • width
  • samples
    • Colorboard
  • articles
    • Sizing components
    • Colorboard


maxLightness

sets the end value of lightness for the default color palette

number maxLightness;

See also

  • api
    • minLightness
  • articles
    • Colorboard
    • Details

    The default palette has a gradient background, lightness of which changes from minLightness to maxLightness.

    //the default values of parameters
minLightness:0.15,
maxLightness:1

    The parameter is ignored in case of using custom color palettes


minLightness

sets the start value of lightness for the default color palette

number minLightness;

See also

  • api
    • maxLightness
    • Details

    The default palette has a gradient background, lightness of which changes from minLightness to maxLightness.

    //the default values of parameters
minLightness:0.15,
maxLightness:1

    The parameter is ignored in case of using custom color palettes


palette

sets palette colors

array palette;

Example

webix.ui({
    view:"colorboard",
    id:"color3",
    cols    :2,
    rows    :3,
    width   :60,
    height  :60,
    palette:[
        ["#FF2626", "#26FF26"],
        ["#2626FF", "#F3FC49"],
        ["#1BE07A", "#FC49D9"]
    ]
})

See also

  • samples
    • Colorboard - Colors
  • articles
    • Colorboard


rows

sets the number of rows in the palette

number rows;

Example

webix.ui({
    view:"colorboard",
    id:"color",
    cols    :30,
    rows    :30,
    width   :400,
    height  :400
});

See also

  • api
    • cols
  • samples
    • Colorboard


template

defines a custom template that will be applied to the component

function template;

Example

webix.ui({
    container:"box",
    view:"colorboard",
    cols    :7,
    rows    :4,
    width   :600,
    height  :370,
    template:"<div class=\"value_cell\">" +
            "<div>{obj.val}</div>" +
            "<div class=\"color_block\" style=\"background:{obj.val};\"></div>" +
            "</div>"
});

See also

  • samples
    • Palette - Templates
  • articles
    • Data Templates
    • Colorboard


value

currently selected color

string value;

Example

webix.ui({
      view:"colorboard",
      value:"#ffaa00"
    });


Events

onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterRender

occurs immediately after the component has been rendered

void onAfterRender(){ ... };

Example

some.attachEvent("onAfterRender", function(){
    //... some code here ...
});

See also

  • api
    • onBeforeRender
  • articles
    • UI Components
    • View


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | highlights the color with the specified value in the colorboard
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


$setValue

highlights the color with the specified value in the colorboard

void $setValue(string value);

Parameters

value string a color in the hex format


ui.colorpicker

A control for selecting a color from a swatch palette.

The component handles RGB, HSL and hex formats and allows setting custom colors blocks. Check colorpicker documentation for more detailed description.

Constructor

var colorpicker = webix.ui({
    view:"colorpicker",
    label:"Color1",
    name:"color",
    value:"#00DDDC"
});

Where to start

  • Overview of the Colorpicker Control
  • Samples
Based on: ui.datepicker, ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | gets actual text value from the control's input
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
editable | allows entering characters in datepicker input, false by default
format | sets date format in the control
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icons | shows "Today" and "Clear" icons for calendar and datepicker popup
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
stringResult | if the parameter is set to true, the method getValue returns data as string (otherwise, as object)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
timeIcon | sets an icon for time in the datepicker
timepicker | enables optional timepicker in the calendar
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | gets actual text value from the control's input
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


getPopup

returns popup element of the input

WebixView getPopup();

Returns

WebixView popup element ( webix view )

Example

var popup = $$("select").getPopup();


getText

gets actual text value from the control's input

string getText();

Returns

string text displayed in the input field

Example

$$("mydatepicker").getText();
$$("mycolorpicker").getText();

Details

To get the control's value you should use the getValue method.

See also

  • api
    • getValue


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
editable | allows entering characters in datepicker input, false by default
format | sets date format in the control
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icons | shows "Today" and "Clear" icons for calendar and datepicker popup
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
stringResult | if the parameter is set to true, the method getValue returns data as string (otherwise, as object)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
timeIcon | sets an icon for time in the datepicker
timepicker | enables optional timepicker in the calendar
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


editable

allows entering characters in colorpicker input, false by default

boolean editable;

Example

webix.ui({
    view:"colorpicker",
    editable:true
});


format

sets date format in the control

string format;

Example

{ view:"datepicker", label:"Start date", name:"start", format:"%d  %M %Y" },

See also

  • samples
    • Date Picker ('datepicker')
  • articles
    • Date formatting methods
    • Working with Dates
    • Details

    Date formatting specifiers are described in the related article


icons

shows "Today" and "Clear" icons for calendar and datepicker popup

boolean icons;

Example

{ view:"datepicker", icons:true }

See also

  • samples
    • 'Today' and 'Clear' buttons
  • articles
    • Calendar
    • Controls Guide
    • Date and Number Localization
    • Details

    Text of the icons may be altered within the current locale as:

    webix.i18n.calendar.clear: "Clear New";
webix.i18n.calendar.today: "Today New";
webix.i18n.setLocale();

    Locales can take HTML as well, e.g. you can include span elements with icons.


placeholder

placeholder text for the input

string placeholder;

Example

{ view:"text", placeholder:"Type something here" }


readonly

configures readonly mode for the input

boolean readonly;

Example

{ view:"text", readonly:true }


stringResult

if the parameter is set to true, the method getValue returns data as string (otherwise, as object)

boolean stringResult;

Example

{ view:"datepicker", stringResult:true, format:"%d  %M %Y" },

See also

  • samples
    • Date Picker ('datepicker')
  • articles
    • Controls Guide
    • Details

    The default value is false.


timeIcon

sets an icon for time in the datepicker

string timeIcon;

Example

webix.ui({
    view:"datepicker",
    timeIcon:"clock-o"
});


timepicker

enables optional timepicker in the calendar

boolean timepicker;
Details

Disabled by default


ui.combo

An editable combo box.

The control combines an editable text field with a drop-down list of predefined values. Provides autocomplete feature that suggests possible matches while a user types in the text field. Check combo documentation for more detailed description.

Constructor

var combo = webix.ui({
    view:"combo",
    label: 'Combo',
    value:"One",
    yCount:"3",
    options:["One", "Two", "Three"]
});

Where to start

  • Overview of the Combo Control
  • Samples
Based on: ui.richselect, ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getList | returns list view of the control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | returns text of currently selected option
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getList | returns list view of the control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | returns text of currently selected option
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


getInputNode

gets the HTML element related to the component

HTMLElement getInputNode();

Returns

HTMLElement the component HTML element

Example

var unit = $$('unit').getInputNode().value;

Details

The method can be used to get the actual text value of the combo while the getValue() function will return the ID of the chosen option.

The same is true abour select and richselect.

See also

  • samples
    • Working with UnitList Items
  • articles
    • View


getList

returns list view of the control

view getList();

Returns

view list view

Example

webix.ui({ view:"richselect", id:"r1", options:[]});
$$("r1").getList().load("data.php");

Details

It is a shorthand alternative to the this.getPopup().getList();


getText

returns text of currently selected option

string getText();

Returns

string text value of control

Example

var value = $$("select").getValue();
var text = $$("select").getText();


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


icon

sets an icon type

string icon;

Example

webix.ui({
    rows:[
        { view:"icon", icon:"mail"},
        { view:"icon", icon:"users"}
        ]
});

See also

  • samples
    • Icons
  • articles
    • Icons with UI Components
    • Details

    Icons can be defined as

    • separate views;
    • button types;
    • CSS classes.

    Icon types are taken from Font Awesome.


label

the text label of the control

string label;

Example

webix.ui({
    view:"combo",
    label: 'Fruit',
    data:[ //you can use the "options" property instead
        { id:1, value:"Banana"   },
        { id:2, value:"Papai"   },
        { id:3, value:"Apple" }
    ]
})

See also

  • samples
    • Editable Combo Box ('combo')
  • articles
    • Controls Guide
    • Details

    The property should not be mixed with the label control.

    Moreover, label control can have a label as well, but there's no sense in it.


labelWidth

the width of the label

number labelWidth;

Example

webix.ui({
    view:"combo",
    label: 'Fruit',
    labelWidth:100,
    ...
})

See also

  • api
    • label
  • samples
    • Text Input ('text')
  • articles
    • Controls Guide


options

defines data items of the drop-down list

object options;

Example

webix.ui({
    view:"combo",
    value:1, //the initially selected one
    label: 'Fruit',
    options:[
        { value:1, label:"Banana"},
        { value:2, label:"Papai" },
        { value:3, label:"Apple" }
    ]
});

webix.ui({
    view:"combo",
    value:"Apple",
    options:["Banana", "Papai", "Apple"]
});

webix.ui({
    view:"combo",options:"server/options.php"
});

See also

  • api
    • getValue
    • setValue
    • value
  • samples
    • Editable Combo Box ('combo')
  • articles
    • Controls Guide
    • Details

    Each option presents a singular select option in the drop-down list. Options can be set as:

    • a simple array;
    • an associative array of objects with id and value properties;
    • a string with a path to a script that loads options from server.

    The initially selected option is defined by a value property.


popupWidth

width of the popup window

number popupWidth;

Example

var myPopup = webix.ui({
    view:"popup",
    id:"popup1",
    ...
    body:{
        view:"list",
        ...
    }
});

webix.ui({
        view:"combo",
        ...
        popup: myPopup, // or popup:'popup1'
        popupWidth: 300
});

See also

  • articles
    • Popup


text

visible text in the related input

string text;

Example

var now = $$("richselect").config.text;


ui.context

A pop-up window displayed on firing the 'contextMenu' event (mouse right-clicks).

The component presents a plain window that can contain any content. Check context documentation for more detailed description.

Constructor

HTML .

<!--Right click the area-->
<div id="areaA" style=" background-color:#ffffbb; width:500px; height:300px;"></div>

JS .

var context = webix.ui({
    view:"context",
    body:{  template:"text" },
    width:300,
    height:200,
    master:"areaA"
});

Where to start

  • Overview of the Context Widget
  • Samples
Based on: ContextHelper, ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
attachTo | attaches a context menu to a Webix component
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getContext | gets the master area for contextmenu
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setContext | allows customizing target context properties: view object and item id
setPosition | sets window's position
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
master | the area for which context object in initialized
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
attachTo | attaches a context menu to a Webix component
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getContext | gets the master area for contextmenu
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setContext | allows customizing target context properties: view object and item id
setPosition | sets window's position
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


attachTo

attaches a context menu to a Webix component

void attachTo(object view);

Parameters

view object **ID** of the Webix view

Example

webix.ui({
    view: "list",
  ...  // list config
});

webix.ui({
    view: "contextmenu",
  ...  // contextmenu config
});

$$("contextmenu1").attachTo($$("list1"));

Details

The component and context object are initialized in different Webix constructors (as seen above). The context menu isn't shown initially and becomes visible on right mouse click with the cursor pointed over the list area.

See also

  • api
    • getContext
  • samples
    • Context Menu: Attaching to List
  • articles
    • ContextMenu


close

removes a window

void close();

Example

{ view:"button", label: 'Close Me', width: 100, align: 'right', click:"$$('win3').close();"}

Details

Removes the window from the app with no possibility to show it back. To hide the window, use the corresponding method.

See also

  • api
    • show
    • hide
  • samples
    • Windows: Basic Initialization
  • articles
    • Window


getBody

gets the ui view of the window body

object getBody();

Returns

object the window body object

See also

  • api
    • getHead
  • articles
    • Window
    • Popup


getContext

gets the master area for contextmenu

object getContext();

Returns

object webix component or HTML object

Example

$$("contextmenu1").attachTo($$("list1")); //menu is initialized for list

var context = this.getContext(); //gets master area (where list item is)
var list = context.obj; //gets list item object
var listId = context.id; //gets the id of the right-clicked list item

See also

  • api
    • attachTo
    • setContext
  • samples
    • Context Menu: Attaching to List
  • articles
    • Context
    • ContextMenu


getHead

gets the ui view of the window header

object getHead();

Returns

object the window header object

Example

win = webix.ui({
  view:"window",
  head:"My text",
  body:"My content",
}).show();

win.getHead().setHTML("New text");

Details

The method returns the object of a Webix component that currently builds window head, so you can use its API to modify the window head.

If head is defined via a string, then Webix template is used.
To change template text dynamically, setHTML method is applied.

See also

  • api
    • head
  • articles
    • Window
    • Popup


resizeChildren

resizes all children of the calling component

void resizeChildren();

Example

$$('mylayout').resizeChildren();

See also

  • articles
    • Resizing Components


setContext

allows settings master properties: view object and item id

void setContext(object context);

Parameters

context object context object

Example

menu.setContext({obj: $$("list"), id: "itemId"})

Details

Target context object includes:

  • obj - (object) master view object for which context or contextmenu is defined
  • id - (string/number) id of an item in the master view

The object can be retrieved by the getContext method.

See also

  • api
    • getContext
  • articles
    • Context
    • ContextMenu


setPosition

sets window's position

void setPosition(number x,number y);

Parameters

x | number | horizontal position in pixel
y | number | vertical position in pixel

Example

$$('my_context').setPosition(100, 100);

See also

  • articles
    • Window
    • Popup
    • Context
    • ContextMenu


show

makes the component visible

void show( [DOMElement node,object position ,string point ] );

Parameters

node | DOMElement | optional, html element where the popup is shown
position | object | optional, object that may contain pos, x and y properties (see details)
point | string | optional, the popup pointer (arrow) direction ("top", "left", "right", "bottom")

Example

//specifying an HTML node near which a window will be shown
$$("window").show(node);

// placing the window above the node
$$("window").show(node, {pos:"top"});

// setting the window's position
$$("window"). show({
    x:300, //left offset from the right side
    y:50 //top offset
});

Details

Position

The properties of the position object are:

  • pos - {string} optional, "top", "left", "right", "bottom";
  • x - {number} horizontal offset;
  • y - {number} vertical offset.

Position object may be passed as the first argument instead of node.

Method usage

This method helps showing the views that were hidden before:

  • either with hide method;
  • or with hidden parameter.

The same effect as show() can be achieved if you set the hidden parameter in the view constructor to the true value.

Performance tip

With standard views (not windows) you can use an alternative to the hide, show api, namely the ui.multiview functionality to switch between views.

See also

  • api
    • hide
    • hidden
  • articles
    • Popup and Window Positioning
    • Common Functions to Switch Between Views
    • Managing Visibility of Components


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
master | the area for which context object in initialized
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component


autofit

adjusts window size to the size of an html node it is initiated in

boolean autofit;
Details

True by default.


autofocus

sets focus on the window the moment it appears on the page

boolean autofocus;
Details

True by default.


body

the content of window body: template or view

string|WebixView body;

Example

<div id="details">
    <img src='images/html5.png'>
</div>

<script type="text/javascript" charset="utf-8">
    var menu = webix.ui({
        view:"context",
        body:{ content:"details" },
        master:"areaA"
});

See also

  • api
    • head
  • samples
    • Context Menu: HTML Content
  • articles
    • Window
    • Popup
    • Context


head

sets the view header

object| string head;

Example

webix.ui({
        view:"popup",
        height:250,
        head:"My Window",
        body:{
            template:"Some text"
        }
}).show();

See also

  • api
    • body
  • samples
    • Popup Window
  • articles
    • Window
    • Details

    If head value is a string, then Webix template is used to build the head.

    If you need a more complex header, define the needed configuration through object definition:

    head:{
    view:"toolbar", cols:[
        {view:"label", label: "This window can be closed" },
        { view:"button", label: 'Close Me', click:"$$('win3').close();"}
    ]}
}


headHeight

defines the header height (43 by default)

number headHeight;

See also

  • api
    • head
  • articles
    • Window
    • Popup


left

the left offset of the window

number left;

Example

webix.ui({
    view:"window",
    left:100,
    head:"..",
    body:{...}
})

See also

  • api
    • top
    • position
  • samples
    • Windows: Basic Initialization
  • articles
    • Window
    • Popup
    • Details

    If you set position and left or top at the same time - left and top parameters will be ignored.


master

the area for which context object in initialized

string master;

Example

webix.ui({
    view:"context",
    body:{ content:"details" },
    master:"areaA" //the ID of div container or ID of webix view
});

See also

  • samples
    • Context Menu: HTML Content
  • articles
    • Context
    • ContextMenu


modal

switches window modality

boolean modal;

Example

webix.ui({
    view:"window",
    modal:true,
    ...//config
});

See also

  • articles
    • Window
    • Details

    By default, Webix window is not modal and its appearance on the page doesn't prevent from working with the main application.

    If modality is set to true, users ought to perform actions required by this window before going to the main app.


move

makes view movable

boolean move;

Example

webix.ui({
    view:"window",
    move:true,
    head:"This window can be moved",
    body:{
        template:"Some text"
    }
}).show();

See also

  • samples
    • Windows: Basic Initialization
  • articles
    • Window


position

sets position of the window relative to the the screen

string| function position;

Values

  • center
    places the window in the center of the viewport
  • top
    forces the window to appear from the top of the page with slide animation and horizontal centering

    • Example

    webix.ui({
    view:"window",
    position:"center",
    //..window config
}).show();

    See also

  • api
    • top
    • left
  • samples
    • Window: Centralization
  • articles
    • Popup and Window Positioning
    • Details

    The positioning function takes default window position as parameter and allow to modify its aspects.

    webix.ui({
    view:"window",
    head:"",
    body:{...},
    position:function(state){
        state.left = 20; //fixed values
        state.top = 20;
        state.width -=60; //relative values
        state.height +=60;
    }
});

    Default window position is a top left corner of the viewport.


relative

positions a popup window relative to the component it's connected with

string relative;

Example

{ view:"text", suggest:{
    data:countries, relative:"right" }
}

See also

  • samples
    • Attaching Suggest List to Input
  • articles
    • Suggest List


resize

enables/disables window resizing

boolean resize;

Example

webix.ui({ view:"window", resize:true });

See also

  • samples
    • Windows: Resize
    • Details

    Resize mode provides users with a possibility to resize the window in browser.


toFront

places window above other windows on clicking it

boolean toFront;


top

the top offset of a window

number top;

Example

webix.ui({
    view:"window",
    top:100,
    head:"..",
    body:{...}
}).show();

See also

  • api
    • left
    • position
  • articles
    • Window
    • Popup
    • Details

    If you set position and left or top at the same time - left and top parameters will be ignored.


zIndex

stack order of the component

number zIndex;

Example

webix.ui({
    view:"window",
    zIndex:1,
    ..//config
});

Details

Use zIndex:"auto" for setting zIndex equal to that ot its parent.

By default modal window has the same zIndex as for the previous absolutely positioned element, but because of attaching order modal layer will be on top anyway.


Events

onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer


onBeforeShow

fires right after show() method is called for the context view and before the context is shown

void onBeforeShow(){ ... };

Example

some.attachEvent("onBeforeShow", function(){
    //... some code here ...
});

Details

The event takes all parameters passed to show method. Return false to block popup displaying.

See also

  • api
    • show
  • articles
    • Window
    • Popup
    • ContextMenu
    • Context


onHide

fires when window is hidden

void onHide(){ ... };

Example

some.attachEvent("onHide", function(){
    //... some code here ...
});

See also

  • articles
    • onShow


onShow

fires when window is shown

void onShow(){ ... };

Example

some.attachEvent("onShow", function(){
    //... some code here ...
});

See also

  • api
    • onHide
  • articles
    • Window
    • Popup
    • ContextMenu
    • Context
    • Managing Visibility of Components


onViewMove

fires while view is moving

void onViewMove(object pos,Event e){ ... };

Parameters

pos | object | current position
e | Event | mouse event object

Example

window.attachEvent("onViewMove", function(pos, e){
    //code
});

Details

Position object (pos) contains coordinates:

  • pos.x - horizontal offset;
  • pos.y - versical offset.

The event fires each time the view is moved to the new position, so you'll have multiple move events during the view moving.

See also

  • api
    • onViewMoveEnd
  • articles
    • Window


onViewMoveEnd

fires when view has stopped moving

void onViewMoveEnd(){ ... };

Example

window.attachEvent("onViewMoveEnd", function(){
    //code
});

Details

The event does not have any parameters, but you can always get view coordinates via its getNode method that returns view HTML:

var top = window.getNode().offsetTop;
var left = window.getNode().offsetLeft;

See also

  • api
    • onViewMove
  • articles
    • Window


ui.contextmenu

A context menu.

The component presents a pop-up menu that is displayed when the user clicks the right mouse button in the client area. You can configure any nesting level complexity. Check contextmenu documentation for more detailed description.

Constructor

HTML .

<!--Right click the area-->
<div id="areaA" style=" background-color:#ffffbb; width:500px; height:300px;"></div>

JS .

var contextmenu = webix.ui({
    view:"contextmenu",
    data:[
        { value:"Translate...", submenu:[
        "English",
        "Slavic",
        "German"
        ]},
        { value:"Info" }
    ],
    master:"areaA"
});

Where to start

  • Overview of the ContextMenu Widget
  • Samples
Based on: ContextHelper, ui.submenu, ui.menu, ui.list, KeysNavigation, DataMove, DragItem, MouseEvents, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, CopyPaste, ui.popup, ui.window, Movable, Modality
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
attachTo | attaches a context menu to a Webix component
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | removes a window
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
disableItem | disables menu item
enable | enables the calling view that was disabled by the 'disable' method
enableItem | enables menu item
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getContext | gets the master area for contextmenu
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getMenu | gets object of a menu/submenu where an item is located
getMenuItem | search for menu item in submenus
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getSubMenu | gets the submenu object of a menu item (if any)
getTopMenu | returns top menu object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideItem | hides menu item
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setContext | allows customizing target context properties: view object and item id
setPage | makes the specified page visible (assuming that the pager was defined )
setPosition | sets window's position
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sizeToContent | adjusts the size of menu and its submenus to their content
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMenuItemClick | fires when menu item has been clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
body | the content of window body: template or view
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
left | the left offset of the window
master | the area for which context object in initialized
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
mouseEventDelay | the delay between a real mouse action and invoking the related events
move | makes view movable
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
openAction | alters the way of submenu opening to "click"
padding | sets paddings of the chart content
pager | defines paging configuration ( creates a 'ui.pager' object)
position | sets position of the window relative to the the screen
ready | event handler called just after the component has been completely initialized
relative | positions a popup window relative to the component it's connected with
removeMissed | defines how to treat items in case of reloading
resize | enables/disables window resizing
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subMenuPos | aligns submenu towards main menu
submenuConfig | defines submenu configuration
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
toFront | places window above other windows on clicking it
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
top | the top offset of a window
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
zIndex | stack order of the component
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
attachTo | attaches a context menu to a Webix component
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | removes a window
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
disableItem | disables menu item
enable | enables the calling view that was disabled by the 'disable' method
enableItem | enables menu item
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getContext | gets the master area for contextmenu
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getMenu | gets object of a menu/submenu where an item is located
getMenuItem | search for menu item in submenus
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getSubMenu | gets the submenu object of a menu item (if any)
getTopMenu | returns top menu object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideItem | hides menu item
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setContext | allows customizing target context properties: view object and item id
setPage | makes the specified page visible (assuming that the pager was defined )
setPosition | sets window's position
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sizeToContent | adjusts the size of menu and its submenus to their content
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


addCss

applied CSS class to a component item

void addCss(string|number id,string css, [boolean silent] );

Parameters

id | string|number | ID of the neccessary item
css | string | CSS class name
silent | boolean | if true the component is not redrawn

Example

//this points to a component object
//context.target is a data item id in drag-n-drop context
this.addCss(context.target, "my_custom_mark");

See also

  • api
    • removeCss
  • samples
    • Custom Target Drag Marker
  • articles
    • Defining Drag Marker


clearCss

removes css class from all items

void clearCss(string css, [boolean silent ] );

Parameters

css | string | name of css class to remove
silent | boolean | if true the component is not redrawn

Example

list.clearCss("xw_checked");


clearValidation

removes all validation marks from the component

void clearValidation();

Example

$$("mylist").clearValidation();

See also

  • api
    • validate
  • samples
    • Validation with Predefined Rules
  • articles
    • Data Validation


copy

copies an item to the same or another object

void copy(id sid,number tindex, [object tobj,object details] );

Parameters

sid | id | the id of the copied object
tindex | number | the index of the copy
tobj | object | the object that an item is copied to
details | object | extra parameters for copying

Example

gridb.attachEvent("onBeforeDrop", function(context, ev){
    for (var i=0; i< context.source.length; i++){
        context.from.copy(context.source[i],context.start,this,{newId:webix.uid()});
    }
    return false;
});

Details

In the sample above:

  • sid is the ID of each dragged item;
  • tindex is the ID from which DnD was started;
  • tobj is a datatable object where the items are dropped to;
  • newId is generated automatically with webix.uid() method.

Details object can contain the next properties:

details = {};
details.newId = "123"; //new id for moved item

Note that in case newId is not defined, the new ID will be the same as the ID of the source item (sid), which is not desirable during moving within one and the same component.

See also

  • samples
    • Attributes
    • Using events for customizing dnd
  • articles
    • Component Copying and Extending
    • Drag-and-Drop Events


customize

redefines the "type" property

void customize(object obj);

Parameters

obj object the hash of new 'type' settings

Example

mylist = webix.ui({
    view:"list",
    ...
    type:{
        height:50
    }
});

mylist.customize({ height:30});
mylist.refresh();

Details

Remember, the method doesn't cause repainting of the component. That's why after calling the customize() method you should call method refresh or render to apply the newly-specified value

To change any component property (not the "type") - use define method.

See also

  • api
    • type
    • define
  • articles
    • Changing Properties of Components


disableItem

disables menu item

void disableItem(id id);

Parameters

id id id of item which need to be disabled

Example

$$("somemenu").disableItem("about");


enableItem

enables menu item

void enableItem(id id);

Parameters

id id id of item which need to be enabled

Example

$$("somemenu").enabledItem("about");


filter

filters the component

void filter(template|function text,string value,boolean preserve);

Parameters

text | template|function | a template of filtered value or function
value | string | the filtering mask
preserve | boolean | if set to true, each next filtering criteria will be applied to the already filtered list

Example

//filters all fields with 'abc' in the 'text' property
//using a template
list.filter('#text#',"abc")

//using a function
list.filter(function(obj){
    return obj.text.toString().indexOf("abc") != -1;
});

See also

  • api
    • samples
      • Chart: Filtering
      • Filtering via a separate input element
      • List: Filtering
    • articles
      • DataTable Filtering
      • Filtering in the Tree
      • Data Filtering and Sorting


getItemNode

returns HTML element of the item

void getItemNode(id id);

Parameters

id id data item ID

Example

var node = mylist.getItemNode(123);
node.innerHTML = "some text";


getMenu

gets object of a menu/submenu where an item is located

object getMenu(string| number id);

Parameters

id string| number id of a menu item

Returns

object object of menu (or submenu) where the item is located

Example

$$("mymenu").attachEvent("onItemClick", function(id){
    var menu = this.getMenu(id);
    webix.message("Click: "+menu.getItem(id).value);
    }
});

See also

  • api
    • getSubMenu
  • samples
    • HTML Elements as Menu Items
  • articles
    • Menu


getMenuItem

search for menu item in submenus

object getMenuItem(id id);

Parameters

id id id of item

Returns

object related data item

Example

$$("topmenu").getMenuItem("open");

Details

Method can be called from the top menu to locate data item in one of sub-menus


getPage

returns the currently visible page in case of paged view

number getPage();

Returns

number the index of the currently visible page, zero-based numbering

Example

var page = $$('dtable').getPage();

See also

  • api
    • setPage
  • samples
    • Static Paging
  • articles
    • Paging


getPager

returns the pager object associated with the component

object getPager();

Returns

object the pager object

Example

grida.getPager().clone({
                container:"paging_here_too",
                size:10,
                group:5
            });

See also

  • samples
    • Defining several pagers on a page
  • articles
    • Paging


getScrollState

returns the scroll position

object getScrollState();

Returns

object scroll position object as ({x:scrollLeft,y:scrollTop})

Example

var scPos = $$("mylist").getScrollState(); // ({x:some,y:some})
var posx = scPos.x;
var posy = scPos.y;

See also

  • articles
    • Scroll Control


getSelectedId

returns the id(s) of the selected item(s)

string/array getSelectedId(boolean as_array);

Parameters

as_arrayboolean specifies whether the result should always be returned as an array.
The default value is false

Returns

string/array the single item id or an array of ids

Example

//single select mode
var id = list.getSelectedId(); // id = someid

//multiselect mode
var id = list.getSelectedId(); // id = [someid1, someid2, someid3]

See also

  • api
    • isSelected
    • select
    • selectAll
    • unselect
    • unselectAll
  • samples
    • Adding/Removing Items
  • articles
    • Selection


getSelectedItem

returns selected object

object getSelectedItem(boolean as_array);

Parameters

as_array boolean if set, always returns an array of objects

Returns

object currently selected item

Example

var item = list.getSelectedItem();
var ar_selected = list.getSelectedItem(true);


getSubMenu

gets the submenu object of a menu item (if any)

object getSubMenu(string| number id);

Parameters

id string| number menu item ID

Returns

object object of a child menu (submenu), if any

Example

$$("mymenu").getSubmenu(id);

Details

The method helps retrieve properties of submenu items:

$$("mymenu").attachEvent("onItemClick", function(id){
    var submenu = this.getSubMenu(id);
    if(submenu)
        //returns text value of a clicked menu item
        webix.message("Click: " + submenu.getItem(id).value);
});

See also

  • api
    • getMenu
  • samples
    • Context Menu
  • articles
    • Menu


getTopMenu

returns top menu object

object getTopMenu();

Returns

object top menu object

Example

var top = $$("somemenu").getTopMenu();

Details

Can be used to access top menu object from the sub-menu


getVisibleCount

returns the number of items that can be seen with the current view height

number getVisibleCount();

Returns

number the count of visible items

Example

var count = $$("myview").getVisibleCount();

See also

  • articles
    • Data Object Operations


hasCss

checks if item has specific css class

boolean hasCss(id id,string css);

Parameters

id | id | item's id
css | string | name of css class that needs to be checked

Returns

boolean returns true if such css class was set

Example

list.hasCss(12, "xw_second");


hideItem

hides menu item

void hideItem(id id);

Parameters

id id id of item which need to be hidden

Example

$$("somemenu").hideItem("about");

Details

use showItem to revert effect
this API uses filtering under hood, so if you are using hideItem, you can use filter api, and visa verse.


isSelected

checks whether the specified item is selected or not

boolean isSelected(id id);

Parameters

id id the id of the item in question

Returns

boolean true if the specified item is selected, otherwise - false

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').select(2);     //selects an item with the id=2
$$('data').isSelected(2); //-> 'true'

See also

  • api
    • getSelectedId
    • select
    • selectAll
    • unselect
    • unselectAll
  • articles
    • Selection


move

moves the specified item to the new position

string move(string sid,number tindex, [object tobj,object details] );

Parameters

sid | string | the id of the item to move
tindex | number | the new position of the item (new index)
tobj | object | the object that the item is moved to
details | object | extra parameters for moving

Returns

string the item id

Example

//moving in the same list
$$('list').move("a12", 0);
$$('list').move("a13", -1);
//moves an item to a different list
var id = $$('list').move("a13", 0, $$("list2"));

See also

  • api
    • moveBottom
    • moveDown
    • moveUp
    • moveTop
  • articles
    • Data Object Operations


moveBottom

moves the specified item to the last position

void moveBottom(id id);

Parameters

id id the item id

Example

$$('view').moveBottom("a12"); //moves the item with id="a12" 2 to the very end

See also

  • api
    • moveTop
    • moveUp
    • moveDown
    • move
  • articles
    • Data Object Operations


moveDown

increases the item index and moves the item to the new position

void moveDown(id id,number step);

Parameters

id | id | the item id
step | number | the step of moving

Example

$$('view').moveDown("a12", 2); //moves the item with id="a12" 2 items down

See also

  • api
    • moveUp
    • moveTop
    • moveBottom
    • move
  • articles
    • Data Object Operations


moveSelection

moves selection in the specified direction

void moveSelection(string direction);

Parameters

direction string the move direction

Example

$$("list").moveSelection("top");

Details

The method can take only one of a predefined set of values.
The predefined values are:

  • 'top' - the selection is moved to the first item of the dataview
  • 'bottom' - the selection is moved to the last item of the dataview
  • 'up' ('left') - the selection is moved one item left
  • 'down' ('right') - the selection is moved one item right
  • 'pgup' - the selection is moved to the first item of the previous page ( a page is the currently visible dataview)
  • 'pgdown' - the selection is moved to the first item of the next page(a page is the currently visible dataview)

See also

  • api
    • getSelectedId
    • select
    • unselect
  • articles
    • Selection


moveTop

moves the specified item to the first position

void moveTop(id id);

Parameters

id id the item id

Example

$$('view').moveTop("a12"); //moves the item with id="a12" to the very beginning

See also

  • api
    • moveUp
    • moveDown
    • moveBottom
    • move
  • articles
    • Data Object Operations


moveUp

decreases the item index and moves the item to the new position

void moveUp(id id,number step);

Parameters

id | id | the item id
step | number | the step of moving

Example

$$('view').moveUp("a12",2); //moves the item with id="a12" 2 items up

See also

  • api
    • moveDown
    • moveTop
    • moveBottom
    • move
  • articles
    • Data Object Operations


removeCss

removes CSS class from a component item

void removeCss(string|number id,string css, [boolean silent] );

Parameters

id | string|number | ID of the necessary item
css | string | CSS class name
silent | boolean | if true, the component is not redrawn

Example

//this points to a component object
//this.my_marked is an id of a previously marked data item
this.removeCss(this.my_marked, "my_custom_mark");

Details

The method is true for removing CSS only from those items which CSS was previously added by addCSS().

See also

  • api
    • addCss
  • samples
    • Custom Target Drag Marker
  • articles
    • Defining Drag Marker


scrollTo

scrolls the data container to a certain position

void scrollTo(number x,number y);

Parameters

x | number | the value of horizontal scroll
y | number | the value of vertical scroll

Example

$$("view").scrollTo(0, 40);

See also

  • samples
    • Scrollview
  • articles
    • Scroll Control


select

selects the specified item(s)

void select(string| array id,boolean preserve);

Parameters

id | string| array | the id of a single item or an array of items ids
preserve | boolean | if it's set to true, the method won't affect the existing selection (will select new items but preserve selection of old items). The default value - false

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').select(2);               //selects an item with the id=2
$$('data').select(3, true);         //selects an extra item, preserving previos selection

$$('data').select([2,3,5]);         //selects a group of items with ids: 2,3,5

Details

If the parameters aren't specified, all items will be selected.

    $$('data').select();                     //selects all items

See also

  • api
    • selectAll
    • isSelected
    • getSelectedId
    • unselect
    • unselectAll
  • samples
    • DataView Basic Initialization
  • articles
    • Selection


selectAll

selects all items or the specified range

void selectAll( [string from,string to] );

Parameters

from | string | the id of an item that selection will be started from
to | string | the id of an item that selection will be ended with

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').select();//selects all items in dataview

Details

If the parameters aren't specified, all items will be selected.

See also

  • api
    • select
    • isSelected
    • getSelectedId
    • unselect
    • unselectAll
  • articles
    • Selection


setPage

makes the specified page visible (assuming that the pager was defined )

void setPage(number page);

Parameters

page number the page number (zero-based numbering)

Example

dtable.setPage(2); // makes the third page visible

See also

  • api
    • getPage
  • articles
    • Paging


setPosition

sets window's position

void setPosition(number x,number y);

Parameters

x | number | horizontal position in pixel
y | number | vertical position in pixel

Example

$$('my_window').setPosition(100, 100);

See also

  • articles
    • Window
    • Popup


showItem

scrolls the component to make the specified item visible

void showItem(id id);

Parameters

id id the item's id

Example

list = webix.ui({
    view:"list",
    ...
});
list.showItem('item1'); // 'item1' is the item's id

Details

For menu, showItem call can be used to revert hideItem call, it makes item in qustion visible.

See also

  • api
    • scrollTo
  • samples
    • Horizontal List
  • articles
    • Scroll Control


sizeToContent

adjusts the size of menu and its submenus to their content

void sizeToContent();

Example

$$("mymenu").setToContent();


sort

sorts datastore

void sort(string by, [string dir,string as] );

Parameters

by | string | the name(s) of property(s) by which data will be sorted
dir | string | the sorting direction, default is "asc"
as | string | the type of data , default is "string"

Example

data.sort("price", "asc");

Details

Usage examples

The method sort can be used with different count of parameters.

The most common use case of the sort method is using the first parameter as the name of a property:

//sorts by name value; ascedent; sorted values as strings
data.sort("#name#","asc","string");
//sorts by price value; descedant; sorted values as numbers
data.sort("#price#","desc","int");

The property name should be included into sharps.

Instead of default sorting types, you can use your own method ( can be used for complex data types ):

function sort_by_length(data1, data2){
    return data1.length>data2.length ? 1:-1;
}

data.sort("#name#","asc",sort_by_length);

Possible return values of this function are 0,1,-1.

  • 1 means that the first object is greater than the second object;
  • -1 means that the first object is less than the second object;
  • 0 means that 2 objects are equal.

If you need to access multiple properties of an object during sorting or you need to have some complex sorting logic, use a function as the first parameter.

function my_sorting(a,b){
    //a, b - data objects
    return a.Version > b.Version ? 1 : -1;
}
data.sort(my_sorting, "des"); //3rd parameter will be ignored

Alternative syntax

You can use a hash of sorting settings as the first parameter of the sort method:

data.sort({
    as:"string",
    dir:"desc",
    by:"#Package#"
});

Sorting directions

Possible values for the second parameter of the sort method is string which represents sorting direction:

  • "asc" - for ascending sorting
  • "desc" - for decrescent sorting

Sorting types

The third parameter of the sort method may be string which represents the data type:

  • "int" - sorts as interger values
  • "string" - sorts as string
  • "string_strict" - sorts as string, case-sensitive

See also

  • samples
    • Sorting Datatable. Using sorting methods
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree


unselect

removes selection from the specified item

void unselect( [string id] );

Parameters

id string the item id

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').unselect($$('data').getFirstId()); //removes selection from the first item

See also

  • api
    • unselectAll
    • isSelected
    • getSelectedId
    • select
    • selectAll
  • articles
    • Selection


unselectAll

removes selection from all items

void unselectAll();

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').unselectAll();

See also

  • api
    • unselect
    • isSelected
    • getSelectedId
    • select
    • selectAll
  • articles
    • Selection


validate

validates one record or all dataset against validation rules

boolean validate( [string id] );

Parameters

id string id of record to validate

Returns

boolean true if record is valid

Example

mygrid = webix.ui({
    view:"list",
    ...
    rules:{
        "text":webix.rules.isNotEmpty
    }
});

/*validate all records*/
var result = mygrid.validate();

/*validate first record*/
var result = mygrid.validate( mygrid.getFirstId() );

Details

If id was not provided - component will validate all records.

Methods uses config.rules for validation

Invalid rows has "webix_invalid" marker on them

See also

  • api
    • clearValidation
  • samples
    • List: Validation
  • articles
    • Data Validation


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
body | the content of window body: template or view
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
left | the left offset of the window
master | the area for which context object in initialized
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
mouseEventDelay | the delay between a real mouse action and invoking the related events
move | makes view movable
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
openAction | alters the way of submenu opening to "click"
padding | sets paddings of the chart content
pager | defines paging configuration ( creates a 'ui.pager' object)
position | sets position of the window relative to the the screen
ready | event handler called just after the component has been completely initialized
relative | positions a popup window relative to the component it's connected with
removeMissed | defines how to treat items in case of reloading
resize | enables/disables window resizing
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subMenuPos | aligns submenu towards main menu
submenuConfig | defines submenu configuration
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
toFront | places window above other windows on clicking it
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
top | the top offset of a window
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
zIndex | stack order of the component


autoheight

height of view will be adjusted to show all items

boolean autoheight;

Example

webix.ui({
    view:"list",
    autoheight:true
});

See also

  • articles
    • Sizing components


autowidth

width of view will be adjusted to show all items

boolean autowidth;

Example

webix.ui({
    view:"list",
    autowidth:true
});

See also

  • articles
    • Sizing components


body

the content of window body: template or view

string|WebixView body;

Example

webix.ui({
    view:"window",
    head:"This window can be moved",
    body:{
        template:"Some text"
    }
}).show();

See also

  • api
    • head
  • samples
    • Windows: Basic Initialization
  • articles
    • Window
    • Popup
    • Context


click

sets an action happening on a button click

string|function click;

Example

{ view:"button", value: "Submit", click:function(){....} }

See also

  • api
    • onItemClick
  • articles
    • Event Handling
    • Details

    The click property may have the function as value as well as the name of this function.

    { view:"button", value: "Submit", click:filter_tree}

function filter_tree(){
    $$("tree1").filter("#value#",this.getValue()
});

    The property is used with a JS button only, while other components have "onItemClick" inner event to respond to this mouse action.


clipboard

enables/disables clipboard support

boolean|string clipboard;

Values

  • modify (true)
  • insert
  • custom

    • Example

    tree = new webix.ui({
    view:"tree",
    ...
    clipboard:"insert"
});

    See also

  • samples
    • Copying Items
    • List: Work with Clipboard
  • articles
    • Copy-Pasting Tree Data
    • Working with the clipboard
    • Details

    If cliboard is defined as "custom", you need to specify onPaste behavior attached to the same-name event.


dataFeed

the URL that the component will use to reload data during binding

string| function dataFeed;

Example

var myform = new webix.ui({
  container: "box",
  view: "form",
  ...
  dataFeed: "data/form.php"
});
myform.bind(mygrid);

See also

  • api
    • bind
    • sync
  • articles
    • Working with Bound Components
    • Data Loading
    • Details

    Using during binding

    In the related sample the property is used in the 'binding' context. This allows you to reload data in the bound component directly from the server, not from the master component as expected.

    For example, you have a form bound to a grid. The form displays details of the record selected in the grid. Let's assume you select a record. What happens with the slave component?

    • Default behaviour: the form takes record details from the grid (the data is on the client);
    • Using "dataFeed": the form loads record details directly from the server (data comes from the server).

    Using dataFeed for Forms and Collections

    The logic of "dataFeed" behaviour is the same for forms and collections (i.e. data components), yet the difference lies in the parameters for the URL that is formed to send requests to server:

    Let's assume that dataFeed is "data/form.php":

    • for forms the request URL looks like: "data/form.php?action=get&id=" + obj.id
    • for data components the request URL is as follows: "data/form.php?filter[id]=" + obj.id

    where obj is the selected data item in the master component.

    Datafeed as function

    Datafeed can be also defined as a function that reloads data for the component.

    In the code below, the suggest component linked to an input reloads data based on the current input value:

    webix.ui({
  view: "suggest",
  keyPressTimeout: "1000",
  input: $$("text_search"),
  body: {
    dataFeed: function (text) {
      this.clearAll();
      this.load("data/search/" + text);
    }
  }
});


drag

enables or disables drag-and-drop

boolean|string drag;

Values

  • true
    enables DnD within the component, allows taking items into its other instances and different components on the page;
  • order
    enables DnD in the reorder mode, allows dragging component item within one component thus changing their order;
  • source
    enables dragging items from the component without an ability to drop data from other components;
  • target
    enables dropping data to the component. It can take data from outside, but you cannot drag anything from it;
  • false
    disables DnD within the component.

    • Example

    webix.ui({
        view:"datatable",
        ...
        drag:true
});

    See also

  • samples
    • Drag-and-Drop between tables in DataTable
    • Enabling Drag-and-drop in Tree
    • DnD with List Items
  • articles
    • Drag-n-Drop within Webix Views


dragscroll

enables autoscroll of component during drag-n-drop

boolean|string dragscroll;

Values

  • x
    only X axis drag scroll
  • y (true)
    only Y axis drag scroll
  • xy
    drag scroll in both directions
  • false
    disables drag scroll

    • Example

    webix.ui({
        view:"datatable",
        ...
        dragscroll:true
});

    See also

  • articles
    • Drag-n-Drop within Webix Views


externalData

allows defining custom 'move' logic for the component.

function externalData;

Example

var dtable = {
        view:"datatable",
        ...
        drag:true,
        externalData: function (data, id){
                data.rank = data.rank || -1;
                data.title = data.title || data.value;
                return data;
        }
};

See also

  • samples
    • Basic Drag-and-Drop
  • articles
    • Drag-and-Drop between Different Components
    • Details

    The property function takes 2 parameters:

    • data - (object) the data item to move.
    • id - (string) the item id in the source element.

    When you drag an item to another element, it will be moved to the target element with the same id it has in the source element. If the target element already contains an item with such id, the id for the item will be set randomly. At the same time, the second parameter of externalData will store the initial id of the item (the id in the source element).


head

sets the view header

object| string head;

Example

webix.ui({
    view:"window",
    height:250,
    head:"My Window",
    body:{
        template:"Some text"
    }
}).show();

See also

  • api
    • getHead
    • body
  • samples
    • Windows: Basic Initialization
  • articles
    • Window
    • Details

    If head value is a string, then Webix template is used to build the head.

    If you need a more complex header, define the needed configuration through object definition:

    head:{
    view:"toolbar", cols:[
        {view:"label", label: "This window can be closed" },
        { view:"button", label: 'Close Me', click:"$$('win3').close();"}
    ]}
}


layout

defines x or y orientation of layout

string layout;

Values

  • y (default)
    vertical orientation
  • x
    horizontal orientation

    • Example

    webix.ui({
    view:"list",
    layout:"x"
});

    See also

  • samples
    • Horizontal List
  • articles
    • X-list


multiselect

enables multiselect mode

boolean multiselect;

Example

{
  view:"list",
  select:true,
  multiselect:true
}

Details

In the multiselect mode api allows marking multiple elements as selected at the same time.

If a component supports direct selection, it may be possible to use Ctrl-click and Shift-click to select multiple elements at once.


navigation

activates the selection keyboard navigation

boolean navigation;

Example

webix.ui({
    view:"datatable",
    navigation:true,
    ...
});

See also

  • samples
    • Navigation in DataTable
  • articles
    • Selection
    • Details
    Table 1 Keyboard commands
Command | Description
Up arrow key | moves one cell (row) to the up
Down arrow key | moves one cell (row) to the down
Left arrow key | moves one cell (column) to the left
Right arrow key | moves one cell (column) to the right
Home | moves to the top left cell(row, column) in the grid
End | moves to the bottom right cell(row, column) in the grid
PGUP | scrolls the table up
PGDN | scrolls the table down


openAction

alters the way of submenu opening to "click"

string openAction;

Example

webix.ui({
    view:"menu",
    id:"my_menu",
    data:[ //menu data
        { value:"Translate...", submenu:["English", "Slavic...", "German"]},
    ],
    openAction:"click"
});

Details

If the parameter is set, you should first click menu item to enable submenu opening and hiding on "onMouseOver" and "onMouseOut" events.

To hide submenus, you need to click somewhere outside the menu.


pager

defines paging configuration ( creates a 'ui.pager' object)

string| object pager;

Example

webix.ui({
    view:"datatable",
    pager:{
        container:"paging_here",
        size:100,
        group:5
    }
})

See also

  • api
    • ui.pager
  • samples
    • Dynamic Paging
  • articles
    • Paging
    • Details

    The parameter has the following attributes:

    • container - the container where the pager controls will be placed into;
    • size - the number of records per page;
    • group - the number of pages in the pager.


rules

set of validation rules for the component

object rules;

Example

webix.ui({
    view:"datatable",
    rules:{
        "year": webix.rules.isNotEmpty,
        "value": function(value){ return value > 0 }
    }
})

See also

  • api
    • rules
  • articles
    • Data Validation
    • Details

    You will not be able to save data to server side if it doesn't conform to validation rules.


scroll

enables/disables the scroll bar

boolean|string scroll;

Values

  • y (true)
    enables vertical scroll (the default value)
  • x
    enables horizontal scroll
  • xy
    enables both scrolls
  • false
    disables both scrolls

    • See also

  • samples
    • Grouplist
    • Horizontal List
    • Attributes
  • articles
    • Scroll Control


scrollSpeed

the time during which the component is scrolled to the specified position (in milliseconds)

string scrollSpeed;

Example

webix.ui({
    view:"some",
    scrollSpeed:"100ms",
    ...
})

See also

  • api
    • scrollTo
  • articles
    • Scroll Control
    • Details

    The property is used by the scrollTo method and sets the time during which the method scrolls the component to the specified position.

    The default value is 0ms.


select

enables/disables item selection or multiselection in grouplist

boolean|string select;

Values

  • true
    allows single selection
  • false
    denies selection
  • "multiselect"
    allows multiselection

    • Example

    webix.ui({
    view:"list",
    select:true,
    ..//config
});

    See also

  • samples
    • Selection
  • articles
    • Selection


subMenuPos

aligns submenu towards main menu

string subMenuPos;

Values

  • top
  • bottom (default)
  • right
  • left

    • Example

    webix.ui({
    view:"menu",
    width:150,
    subMenuPos:"right"
});

    See also

  • samples
    • Basic Menu
  • articles
    • Menu


submenuConfig

defines submenu configuration

object submenuConfig;

Example

webix.ui({
    view:"menu",
    width:150,
    submenuConfig:{
        width:250,
        template:"SUB #value#"
    }
});

See also

  • articles
    • Menu
    • Details

    This options defines not the data of submenu but its sizing, styling, templates, handlers etc.

    In case of context menu - settings will be applied to a top level menu as well.


template

the component template

string|function template;

Example

{view:"list", template:"#id#.#title#"}

See also

  • samples
    • Template as a String
    • Template as a Function
    • Template Types
  • articles
    • Template
    • Data Templates
    • Details

    1 . Above is the common text template for template component:

    2 . Data template for data-containing components:

    { view:"list", template:"#id#.#title#" }
 // the list will show ID and title of each data item from the specified datasource

    3 . Function template (takes data object and function parameter):

    { view:"list", template:function(obj){
    return "<div class='overall'><div class='rank'>"
        +obj.rank+"</div>"+
        "<div class='title'>"+obj.title+"</div></div>"
}}
//the list will show rank and title of each item styled with specified CSS

    4 . HTML templates defined within an HTML container:

    { view: "dataview", template:"html->template_container" }

    5 . HTML template defined in the external file:

    { view:"dataview", template:"http->template.html" }

    6 . Template component can load the external template by Ajax:

    { view:"template", src:"loadtext.php" }


templateCopy

sets the template according to which data will be copied to the clipboard

function templateCopy;

Example

webix.ui({
    view:"list",
    ...
    clipboard: "custom",
    templateCopy: function(item) {
        return [item.title, item.year, item.votes, item.rating, item.rank].join(" , ")
    }
});

See also

  • api
    • clipboard
  • samples
    • List: Work with Clipboard
    • List: Grouping
  • articles
    • Working with the clipboard
    • Details

    As a parameter, the template function takes the data item object.


tooltip

sets a popup message appearing on pointing a mouse cursor over the dedicated item.

object tooltip;

Example

webix.ui({
     view:"dataview",
     tooltip:"Rating: #rating#<br/> Votes: #votes#",
     ...
});

See also

  • samples
    • Template of Tooltips
  • articles
    • Tooltip Implementation
    • Data Templates
    • Details

    In the tooltip template there're values transmitted from the dataset.


type

object that specifies items presentation

object| string type;

Example

list = webix.ui({
    view:"list",
    ...
    type:{
        height:50
    }
})

See also

  • samples
    • Search Field
  • articles
    • Data Templates
    • Type Implementation
    • Details

    Attributes of the type as object:

    • css - (string) the name of a css class that will be applied to component's items (the default name of the applied class is 'default').
    • height - (number) the height of an item in the component.
    • template - (function, string) an html template that will define item presentation in the component.
    • width - (number) the width of the items list.
    • subsign - (bool) - for menu: if true shows an array of menu items that feature a submenu.

    Named type

    It is possible to create a type object separately and then refer to it by its name:

    webix.type(webix.ui.dataview,{
    name:"typeA",
    width: 260,
    height: 90
});

webix.ui({
    view:"dataview",
    type:"typeA",
    ..
});

    Related sample: Named Templates

    More information about Type Implementation can be found in a separate article of the main documentation.


xCount

defines width of view in items

number xCount;

Example

//width of view will be enough to show 2 items
webix.ui({
    view:"list",
    xCount:6,
    scroll:"x",
    layout:"x",
});

See also

  • api
    • yCount
  • samples
    • Horizontal List
  • articles
    • List
    • Details

    The property make sense only for a horizontal list (the one featuring "x" layout).

    Possible values for the property are:

    • desired number;
    • 0 to disable xCount ( calculate the number of item on the base of component size).


yCount

defines height of view in items

number yCount;

Example

//height of view will be enough to show 10 items
webix.ui({
    view:"list",
    yCount:10
})

See also

  • api
    • xCount
  • samples
    • List: Controlling a Number of Displayed Items
  • articles
    • List
    • Details

    Possible values for the property are:

    • desired number;
    • 0 to disable yCount ( calculate the number of item on the base of component size).

    Related sample: Popup Menu


Events

onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMenuItemClick | fires when menu item has been clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer


onAfterDrop

fires after drag-n-drop was finished

void onAfterDrop(object context,Event e){ ... };

Parameters

context | object | the drag-n-drop context
e | Event | a native event object

Example

gridb.attachEvent("onBeforeDrop", function(context, ev){
    for (var i=0; i< context.source.length; i++){
        context.from.copy(context.source[i],context.start,this,webix.uid());
    }
    return false;
});

some.attachEvent("onAfterDrop", function(context, native_event){
    //... some code here ...
});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeDrop
    • copy
  • samples
    • Using events for customizing dnd
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onAfterRender

occurs immediately after the component has been rendered

void onAfterRender(){ ... };

Example

some.attachEvent("onAfterRender", function(){
    //... some code here ...
});

Details

The event fires each time the component is redrawn, not only after the component has been created.

To catch the moment of creation, supply it with webix.once() helper:

some.attachEvent("onAfterRender", webix.once(function(){
    console.log('called once after first rendering:');
});

See also

  • api
    • onBeforeRender
  • articles
    • UI Components
    • View


onAfterSelect

fires after item was selected

void onAfterSelect(id id){ ... };

Parameters

id id the id of an item

Example

some.attachEvent("onAfterSelect", function (id) {
  // ... some code here ...
});

Details

If multiselect mode is enabled, the event will fire only when additional items are selected with Ctrl+click, while passing the ID of a recently selected item. The event wil not fire when the selection is extended via Shift+click.

It is safer to use the onSelectChange event, which catches all selection state changes in the component, combined with the getSelectedId method.

See also

  • api
    • onBeforeSelect
  • articles
    • Selection


onAfterSort

fires after sorting dataset

void onAfterSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Example

some.attachEvent("onAfterSort", function(by, dir, as){
    //... some code here ...
});

See also

  • api
    • onBeforeSort
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree


onBeforeDrag

fires before the mouse button is pressed and the cursor is moved over a draggable item

boolean onBeforeDrag(object context,Event native_event){ ... };

Parameters

context | object | the drag-n-drop context
native_event | Event | an HTML event object

Returns

boolean returning false will prevent dragging of the element

Example

grida.attachEvent("onBeforeDrag", function(context, ev){
        context.html = "<div style='padding:8px;'>";
        for (var i=0; i< context.source.length; i++){
            context.html += context.from.getItem(context.source[i]).title + "<br>" ;
        }
        context.html += "</div>";
});

Details

If you drag multiple items, the event will be called once, for the entire batch of items.

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for dropping on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeDragIn
    • onDragOut
  • samples
    • Drag and Drop with Drag Handle
    • Using events for customizing dnd
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onBeforeDragIn

fires before a dragged element is moved over the droppable area

void onBeforeDragIn(object context,Event native_event){ ... };

Parameters

context | object | the drag-n-drop context
native_event | Event | an HTML event object

Example

some.attachEvent("onBeforeDragIn", function(context, native_event){
    //... some code here ...
});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for dropping on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeDrag
    • onDragOut
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onBeforeDrop

fires before a dragged element is released over the droppable area

boolean onBeforeDrop(object context,Event native_event){ ... };

Parameters

context | object | the drag-n-drop context
native_event | Event | an HTML event object

Returns

boolean returning false will prevent further drag-and-drop processing

Example

some.attachEvent("onBeforeDrop", function(context, native_event){
    //... some code here ...
    //return false to block operation
    return true;
});

Details

If you drag multiple items, the event will be called once, for the entire batch of items.

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onAfterDrop
  • samples
    • Using events for customizing dnd
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onBeforeDropOut

fires before a dragged element is released over the droppable area

void onBeforeDropOut(object context,Event native_event){ ... };

Parameters

context | object | the drag-n-drop context
native_event | Event | an HTML event object

Example

some.attachEvent("onBeforeDropOut", function(context, native_event){
    //... some code here ...
    //return false to block operation
    return true;
});

Details

Event is similar to onBeforeDrop, but occurs in a drag SOURCE component, not in a drag target one

See also

  • api
    • onAfterDrop
  • samples
    • Using events for customizing dnd
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onBeforeSelect

fires before item selection is started

void onBeforeSelect(id id,boolean selection){ ... };

Parameters

id | id | id of item
selection | boolean | true if the item was selected, false if it was unselected

Example

some.attachEvent("onBeforeSelect", function (id, selection){
  // ... some code here ...
});

See also

  • api
    • onAfterSelect
  • articles
    • Selection


onBeforeShow

fires the moment context menu is called

void onBeforeShow(){ ... };

Example

some.attachEvent("onBeforeShow", function(){
    //... some code here ...
});

See also

  • articles
    • Window
    • Popup
    • ContextMenu
    • Context


onBeforeSort

fires before sorting dataset

boolean onBeforeSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Returns

boolean returning false will prevent sorting

Example

some.attachEvent("onBeforeSort", function(by, dir, as){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • onAfterSort
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree
    • Operations with Chart Data


onDragOut

fires when a dragged element is moved outside of the droppable area

void onDragOut(object context,Event native_event){ ... };

Parameters

context | object | the drag-n-drop context
native_event | Event | an HTML event object

Example

some.attachEvent("onDragOut", function(context, native_event){
    //... some code here ...
});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeDragIn
    • onBeforeDrag
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onHide

fires when window is hidden

void onHide(){ ... };

Example

some.attachEvent("onHide", function(){
    //... some code here ...
});

See also

  • api
    • onShow
  • articles
    • Window
    • Popup
    • ContextMenu
    • Context
    • Managing Visibility of Components


onItemClick

fires when a component item was clicked

void onItemClick(string id,Event e,HTMLElement node){ ... };

Parameters

id | string | the id of the clicked item
e | Event | a native event object
node | HTMLElement | the target HTML element

Example

list.attachEvent("onItemClick", function(id, e, node){
    var item = this.getItem(id);
    //... some code here ...
});

Details

The event scope is limited to menu level. It can be attached either to a top-level menu, or to any submenu, but not for the whole menu.

At the same time, the onMenuItemClick can catch item clicks on any level.

See also

  • api
    • onItemDblClick
    • onMenuItemClick
  • samples
    • Configuring Submenus
  • articles
    • Event Handling


onItemRender

for each item rendering, occurs only for items with custom templates

void onItemRender(object obj){ ... };

Parameters

obj object data hash of rendered item

Example

some.attachEvent("onItemRender", function(obj){
    //... some code here ...
});

See also

  • articles
    • UI Components
    • View


onMenuItemClick

fires when menu item has been clicked

void onMenuItemClick(id id,Event e,HTMLElement node){ ... };

Parameters

id | id | item ID
e | Event | mouse event object
node | HTMLElement | target HTML element

Example

menu.attachEvent("onMenuItemClick", function(id, e, node){
    //code
});

Details

Unlike the onItemClick, this event fires for all menu item regardless of their nesting level.

See also

  • api
    • onItemClick


onPaste

fires when the user presses CTRL+V keys combination

void onPaste(string text){ ... };

Parameters

text string the text to paste

Example

tree.attachEvent("onPaste", function(text) {
        webix.message("Node is pasted: " + text);
});

See also

  • samples
    • List: Work with Clipboard
    • Custom Clipboard Operations
    • Custom clipboard (Datatable)
  • articles
    • Working with the clipboard


onSelectChange

fires after selection state was changed

void onSelectChange(array ids){ ... };

Parameters

ids array array of IDs, which selection state was changed

Example

webix.ui({
  view: "datatable",
  on: {
    onSelectChange:function () {
      var text = "Selected: " + grid.getSelectedId(true).join();
      document.getElementById('testB').innerHTML = text;
    }
  }
});

See also

  • samples
    • Block selection
    • DataView Basic Initialization
  • articles
    • Selection


onValidationError

fires when newly loaded/added/edited data fails to pass validation

void onValidationError(number| string id,object obj,object details){ ... };

Parameters

id | number| string | id of the data item that is being validated
obj | object | data item object
details | object | validation result for data keys under validation

Example

webix.ui({
    view:"datatable",
    rules:{
        title:webix.rules.isNotEmpty,
        rating:webix.rules.isNumber
    },
    on:{
        onValidationError:function(id, obj, details){
            var index = this.getIndexById(id)+1;
            webix.message({ type:"error", text:"Empty title for row "+index });
        }
     }
});

Details

The last parameter, details, contains invalid markers for each data key that has been validated and looks like:

{
    title:true,//haven't passed validation
    rating:false //have passed validation
}

See also

  • api
    • onValidationSuccess
  • samples
    • Validation with Message
    • Validation with Complex Message
  • articles
    • Data Validation


onValidationSuccess

fires after the newlyloaded/added/edited data has passes validation successfully

void onValidationSuccess(){ ... };

Example

some.attachEvent("onValidationSuccess", function(){
    //... some code here ...
});

See also

  • api
    • onValidationError
  • articles
    • Data Validation


Others

$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


$drag

method called when drag operation initiated

string $drag(HTMLElement source,Event ev);

Parameters

source | HTMLElement | DOM element on which dnd action started
ev | Event | native html event

Returns

string text which will be used in dnd placeholder, returning false or empty string will block dnd
Details

method not purposed for direct call! It is an extension point.

You can override it with your own logic, but be sure to check dnd related events first, as they are provide much more convinient way for dnd handling.


$dragHTML

defines how dragged item will look

function $dragHTML;

Example

grid.$dragHTML = function(obj, e){
    return "Moving "+obj.text;
}


$dragIn

method called when item moved on possible drop landing during dnd

HTMLElement $dragIn(HTMLElement source,HTMLElement target,Event ev);

Parameters

source | HTMLElement | DOM element on which dnd action started
target | HTMLElement | DOM element of possible drop landing
ev | Event | native html event

Returns

HTMLElement DOM element which will be saved as drop target ( to ignore drop landing - return null value )
Details

The method isn't purposed for direct call! It is an extension point.

You can override it with your own logic, but be sure to check dnd related events first, as they are provide much more convinient way for dnd handling.


$dragMark

method called during dnd when some item in the component need to be marked as active drop target

boolean $dragMark(object context,Event ev);

Parameters

context | object | dnd context
ev | Event | native html event

Returns

boolean returning false will prevent drag operation
Details

The method isn't purposed for direct call! It is an extension point.

You can override it with your own logic, but be sure to check dnd related events first, as they are provide much more convinient way for dnd handling.

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started


$dragOut

method called when item moved out of possible drop landing during dnd

void $dragOut(HTMLElement source,HTMLElement old_target,HTMLElement new_target,Event ev);

Parameters

source | HTMLElement | DOM element on which dnd action started
old_target | HTMLElement | DOM element of drop from which item was moved out
new_target | HTMLElement | new DOM element which will be used as drop target ( can be null )
ev | Event | native html event
Details

method not purposed for direct call! It is an extension point.

You can override it with your own logic, but be sure to check dnd related events first, as they are provide much more convinient way for dnd handling.


$drop

method called when item dragged and dropped on valid target

void $drop(HTMLElement source,HTMLElement target, ev);

Parameters

source | HTMLElement | DOM element on which dnd action started
target | HTMLElement | DOM element of possible drop landing
ev |  | Event native html event

Example

webix.DragControl.addDrop("myDrop",{
    $drop:function(source, target){...}
});

Details

The method isn't purposed for direct call! It is an extension point.

You can override it with your own logic, but be sure to check dnd related events first, as they are provide much more convinient way for dnd handling.

See also

  • samples
    • DataTable. Custom drag-and-drop behaviour
  • articles
    • Advanced Drag-and-Drop


$dropAllow

can be redefine if you need custom drop rules

function $dropAllow;

Example

$$("somelist").$dropallow = function(context, e){
   //context - drag context
   return true;
};


type

set of properties and helpers for item rendering

hash type;


types

collection of possible types

hash types;
Details

Each type is a set of rendering helpers and templates
Component can have multiple types, but only one can be active per component instance


ui.counter

A spin box, aka an up-down control.

The control allows users to precisely change numeric data. It provides up/down buttons that increment or decrement the value with a predefined step. Check counter documentation for more detailed description.

Constructor

var counter = webix.ui({
    view:"counter",
    label:"Age",
    step:3,
    value:5
});

Where to start

  • Overview of the Counter Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
next | set next value in counter input
prev | set previous value in counter input
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
shift | adds value to the counter
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
max | the maximum value of the control
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
min | the minimum value of the control
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
step | the step of the control (the difference between two successive values)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
next | set next value in counter input
prev | set previous value in counter input
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
shift | adds value to the counter
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


getValue

returns the current value of the control

number getValue();

Returns

number the current value of the control

Example

webix.ui({
    view:"counter",
    id:"counter1"
    label:"First age"
});
$$('counter1').setValue(30);
..
$$('counter1').getValue();// -> 30

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
  • articles
    • Controls Guide


next

set next value in counter input

void next( [number step] );

Parameters

step number increase step , 1 by default

Example

$$("counter").next();
//or
$$("counter").next(5);


prev

set previous value in counter input

void prev( [number step] );

Parameters

step number decrease step , 1 by default

Example

$$("counter").prev();
//or
$$("counter").prev(5);


setValue

sets a new value for the component

void setValue(number value);

Parameters

value number a new value for the button

Example

webix.ui({
    view:"counter",
    id:"counter1"
    label:"First age"
});
$$('counter1').setValue(30);
..
$$('counter1').getValue();// -> 30

See also

  • api
    • getValue
  • articles
    • Controls Guide


shift

adds value to the counter

void shift( [number value] );

Parameters

value number value which will be added to the current one

Example

$$("counter").shift(2);
//or
$$("counter").shift(-3);


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
max | the maximum value of the control
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
min | the minimum value of the control
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
step | the step of the control (the difference between two successive values)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


label

the text label of the control

string label;

Example

webix.ui({
    view:"counter",
    container:"box",
    label:"First age"
})

See also

  • api
    • labelPosition
    • labelWidth
  • samples
    • Spin Box ('counter')
  • articles
    • Controls Guide
    • Details

    The property should not be mixed with the label control.

    Moreover, label control can have a label as well, but there's no sense in it.


labelWidth

the width of the label

number labelWidth;

Example

webix.ui({
    view:"counter",
    container:"box",
    label:"First age",
    labelWidth:200
})

See also

  • api
    • label
  • samples
    • Text Input ('text')
  • articles
    • Controls Guide


max

the maximum value of the control

number max;

Example

webix.ui({
    view:"counter",
    container:"box",
    label:"First age",
    min:20,
    max:100,
    value:25
})

See also

  • api
    • min
  • articles
    • Counter


min

the minimum value of the control

number min;

Example

webix.ui({
    view:"counter",
    container:"box",
    label:"First age",
    min:20,
    value:25
})

See also

  • api
    • max
  • articles
    • Counter


step

the step of the control (the difference between two successive values)

number step;

See also

  • articles
    • Counter


Available only in PRO Edition

ui.datasuggest

A dataview-based suggest control..

Offers select options in the form of Webix dataview component.

Can be used standalone or as a suggest list for text, combo and richselect controls as well as the editor component.

Constructor

webix.ui({
  view:"richselect",
  label:"Data",
  value:1, options:{
    view:"datasuggest", data:[
        {id:1, value:"One", year:1988, color:"Red"},
        {id:2, value:"Two", year:1996, color:"Blue"},
        {id:3, value:"Three", year:1997, color:"Green"},
        {id:4, value:"Four", year:2011, color:"Orange"},
        {id:5, value:"Five", year:2000, color:"Grey"},
        {id:6, value:"Six", year: 1994, color:"Yellow"}]
    }
});

Where to start

  • Overview of Dataview Suggest
  • Samples
Based on: ui.suggest, ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValueSuggest | some item selected in the suggest control
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getItemText

returns rendered text of suggest's item

string getItemText(id id);

Parameters

id id id of item in question

Returns

string text or related item

Example

var text = $$("mysuggest").getItemText("d12");

Details

Text will take templating logic of suggest control in account.


getList

returns inner data control from suggest

WebixView getList();

Returns

WebixView inner data control

Example

var list = $$("suggest").getList();

Details

For different suggests it will return different views ( list for default one, calendar for datepicker and etc. )


getMasterValue

returns current value of master control

any getMasterValue();

Returns

any value of master control

Example

var value = $$("mysuggest").getMasterValue();


getSuggestion

returns id of top suggestion from the suggest list

string getSuggestion();

Returns

string id of top suggestion

Example

var id = $$("suggest").getSuggestion();


getValue

gets the ID of a selected item in the option list

string| number getValue();

Returns

string| number ID of a selected option

Example

//master is a control with a popup list of options
var suggest = master.getPopup();
var sel = master.setValue();

Details

The method doesn't get value of the master control (text, combo, multicombo, richselect, multiselect), it gets the ID of a highlighted (selected) option in the suggest list only.

To get the value of the master control, apply the the getValue method to it.

See also

  • api
    • setValue
  • articles
    • Suggest List


linkInput

links a suggest list to an input field

void linkInput(HTMLElement input);

Parameters

input HTMLElement input object

Example

var year_suggest = webix.ui({
                view: "suggest",
                data:years,
                width: 70, yCount:8
            });

var grid =  new webix.ui({
    view:"datatable",
    ..//congig
});

grida.attachEvent("onAfterEditStart", function(object) {
        if (object.column == "year") { // links suggest to the "year" column
            var editor = this.getEditor(object);
            year_suggest.linkInput(editor.type.getInputNode());
        }
});

See also

  • api
    • input
  • samples
    • Datatable: Autosuggest
  • articles
    • Suggest List


setMasterValue

set value in master control

void setMasterValue(any value);

Parameters

value any new value of master control

Example

$$("mysuggest").setMasterValue(new_value);


setValue

selects an item in the option list

void setValue(string| number value);

Parameters

value string| number ID of an option to select

Example

//master is a control with a popup list of options
var suggest = master.getPopup();
master.setValue(2);

Details

The method doesn't set value for the master control (text, combo, multicombo, richselect, multiselect), it selects an option in the suggest list only.

To set the value of the master control, apply the the setValue method to it.

See also

  • api
    • getValue
  • articles
    • Suggest List


show

makes the component visible

void show(DOMElement node, [object position ,string point ] );

Parameters

node | DOMElement | html element where the popup is shown
position | object | optional, object that may contain pos, x and y properties (see details)
point | string | optional, the popup pointer (arrow) direction ("top", "left", "right", "bottom")

Example

//specifying an HTML node near which a window will be shown
$$("window").show(node);

// placing the window above the node
$$("window").show(node, {pos:"top"});

// setting the window's position
$$("window"). show({
    x:300, //left offset from the right side
    y:50 //top offset
});

Details

Position

The properties of the position object are:

  • pos - {string} optional, "top", "left", "right", "bottom";
  • x - {number} horizontal offset;
  • y - {number} vertical offset.

Position object may be passed as the first argument instead of node.

Method usage

This method helps showing the views that were hidden before:

  • either with hide method;
  • or with hidden parameter.

The same effect as show() can be achieved if you set the hidden parameter in the view constructor to the true value.

Performance tip

With standard views (not windows) you can use an alternative to the hide, show api, namely the ui.multiview functionality to switch between views.

See also

  • api
    • hide
    • hidden
  • articles
    • Popup and Window Positioning
    • Common Functions to Switch Between Views
    • Managing Visibility of Components


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
width | sets the width of the component
zIndex | stack order of the component


filter

custom filtering function

function filter;

Example

webix.ui({
    view:"suggest",
    filter:function(obj, value){
         return item.value == value; //strict match
    }
})

Details

will be called when suggest need to be filtered, by users text
by default suggest uses case insensitive partial match filtering


fitMaster

size suggest box to the master control

boolean fitMaster;

Example

webix.ui({
   view:"text",
   suggest:{
      data:some_data,
      fitMaster:false, width:800
   }
})

Details

Enabled by default.


input

points to an HTML input field that houses the suggest list

input;

Example

webix.ui({
    width: 300,
    container:"data_container3",
    rows: [
        { template:"<label for='country3'>Country</label>
                <input type='text' id='country3' value='Colombia' />",
          height: 36,
          borderless:true
        },
    ...
        ]
});

webix.ui({
    view: "suggest",
    input: "country3",
    data:countries
});

See also

  • api
    • linkInput
  • samples
    • Suggest List for Input: Populating with Server-side Data
  • articles
    • Suggest List


keyPressTimeout

time between key pressing and filtering start

number keyPressTimeout;

Example

webix.ui({ view:"suggest", keyPressTimeout: 500 });

Details

Time in milliseconds. 1ms by default.


master

reference to the master view

WebixView master;


template

template which will be used to fill parent input from selected record

template template;

Example

webix.ui({
    view:"select",
    options:{
       template:"#name# from #city#",
       data:[
          { name:"Mark", city:"Hrodno" },
          { name:"Anna", city:"Brest" }
       ]
    }
})


textValue

defines which field from suggest list will be used as text after selecting an option

string textValue;

Example

webix.ui({
    view:"select",
    options:{
       textValue:"name",
       data:[
          { name:"Mark", city:"Hrodno" },
          { name:"Anna", city:"Brest" }
       ]
    }
})


type

defines type of suggest control

string type;
Details

The only possible type for now is "list". It is set by default and you don't need to specify it.


Events

onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValueSuggest | some item selected in the suggest control
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer


onBeforeShow

fires right after show() method is called for the window (popup) and before the window is shown

void onBeforeShow(){ ... };

Example

some.attachEvent("onBeforeShow", function(){
    //... some code here ...
});

Details

The event takes all parameters passed to show method. Return false to block popup displaying.

See also

  • api
    • show
  • articles
    • Window
    • Popup
    • ContextMenu
    • Context


onHide

fires when window is hidden

void onHide(){ ... };

Example

some.attachEvent("onHide", function(){
    //... some code here ...
});

See also

  • articles
    • Window
    • Popup
    • ContextMenu
    • Context
    • Managing Visibility of Components


onShow

fires when window is shown

void onShow(){ ... };

Example

some.attachEvent("onShow", function(){
    //... some code here ...
});

See also

  • articles
    • Window
    • Popup
    • ContextMenu
    • Context
    • Managing Visibility of Components


onValueSuggest

some item selected in the suggest control

void onValueSuggest(object obj){ ... };

Parameters

obj object data object for the related option

Example

suggest.attachEvent("onValueSuggest", function(obj){
    alert("Suggested "+obj.id);
})

Details

Two main scenarious for event

  • click on item in suggest list
  • keyboard navigation with selection by enter key


ui.datatable

An editable table that can easily display huge data sets.

The component is full of various possibilities: filtering, sorting, pagination, editing, navigation, drag-and-drop, internationalization, export to PDF, Excel etc. It also provides the dynamic mode for handling thousands of records in a fast way. Check datatable documentation for more detailed description.

Constructor

var datatable = webix.ui({
    view:"datatable",
    columns:[
        { id:"rank",    header:"",              width:50},
        { id:"title",   header:"Film title",    width:200},
        { id:"year",    header:"Released",      width:80},
        { id:"votes",   header:"Votes",         width:100}
    ],
    data: [
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790, rank:1},
        { id:2, title:"The Godfather", year:1972, votes:511495, rank:2}
    ]
});

Where to start

  • Overview of the DataTable Widget
  • Samples
Based on: AutoTooltip, Group, DataMarks, DataLoader, DataStore, AtomDataLoader, MouseEvents, MapCollection, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, PagingAbility, TablePaste, DataState, EditAbility, KeysNavigation, DataMove, DragItem, ValidateCollection
Methods
add | adds an item to the store
addCellCss | adds a css class to the cell
addCss | applied CSS class to a component item
addRowCss | adds a css class to the row
addSelectArea | adds a select area
addSpan | adds colspan or rowspan to the datatable
adjust | adjusts the component to the size of the parent HTML container
adjustColumn | adjusts a column to the width of the content
adjustRowHeight | autodetect height of rows in datatable
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearSelection | clears selection
clearValidation | removes all validation marks from the component
closeSub | closes subrow or subview for an item with the given id
collectValues | returns an array of unique values of the specified column
columnId | returns the id of the column at the specified index
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
eachColumn | iterates over all visible columns in the table
eachRow | iterates over all rows in the table
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editCell | enables the edit mode for the specified cell
editColumn | enables the edit mode for the specified column
editNext | closes the current editor and opens one in the next cell of the row
editRow | enables the edit mode for the specified row
editStop | stops the edit mode and closes all opened editors. The component is still editable
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
filterByAll | refilters DataTable by all specified filters
find | returns rows that match the criterion
focusEditor | moves focus to the active editor
getAllSelectAreas | returns an object that contains configuration objects of all select areas in the datatable
getChildViews | returns child views of the calling component
getColumnConfig | returns the configuration object of the specified column
getColumnIndex | returns the index of the column with the specified id
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
getFilter | returns the filter object that the component uses to filter the values of the specified column
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHeaderContent | returns set of helpers for header content manipulation
getHeaderNode | returns HTML element of the column's header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the current position of scrolls
getSelectArea | returns the object of the select area
getSelectedId | returns the selected elements' ids
getSelectedItem | gets an object of the selected data item
getSpan | returns the config array for a span or null, if there are no spans
getState | returns the current state of the view
getSubView | returns subview of the item with the given id
getText | returns text value of a cell
getTopParentView | returns top parent view
getVisibleCount | returns count of visible rows
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideColumn | hides the specified column
hideOverlay | hides previously defined overlay
isColumnVisible | returns true if column is visible
isEnabled | checks whether the view is enabled
isSelected | returns true if related record is selected
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | converts an HTML node or event object to in-table position
mapCells | applies the callback to a range of cells
mapEvent | routes events from one object to another
mapSelection | executes some custom method for all cells in the currently selected block
markSorting | marks the sorted column with a dedicated sign (asc/desc) in the header
move | moves the specified item to a new position
moveBottom | moves the specified item to the last position
moveColumn | moves column to different position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
openSub | opens subrow or subview for an item with the given id
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshColumns | refreshes the structure of DataTable
refreshFilter | rebuilds list of options in select filter
refreshHeaderContent | refreshes the header row of DataTable
registerFilter | registers a filter element
remove | removes the specified item/items from datastore
removeCellCss | remove css class from the cell of datatable
removeCss | removes CSS class from a component item
removeRowCss | remove css class from the row
removeSelectArea | removes a select area
removeSpan | removes a rowspan/colspan from the datatable
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeSubView | adjusts the row's size to the size of a subview
scrollTo | scrolls the view to the defined position
select | selects the specified element
selectAll | selects all cells in the DataTable
selectRange | selects the specified range of elements
serialize | serializes data to a JSON object
setColumnWidth | sets the width of the specified column
setPage | makes the specified page visible (assuming that the pager was defined )
setRowHeight | sets the height of the specified row
setState | restores the specified state
show | makes the component visible
showCell | scrolls the table (if needed) to make the specified cell visible
showColumn | shows the column which was previously hidden by method 'hidecolumn'
showColumnBatch | shows or hides a group of columns
showItem | 'scrolls' the table to make the specified row visible
showItemByIndex | 'scrolls' the table to make the specified row visible
showOverlay | shows the overlay message over the body of DataTable
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | cancels selection of the specified element
unselectAll | unselects all selected cells in a datatble
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
validateEditor | validates data in currently active editor
Events
onAfterAdd | fires after adding item to datastore
onAfterAreaAdd | fires after a select area was added
onAfterAreaRemove | fires after a select area was removed
onAfterBlockSelect | event occurs after block selection
onAfterColumnDrop | fires after the column has been dragged and dropped to the target position
onAfterColumnDropOrder | fires after the column order was changed with the help of drag-and-drop
onAfterColumnHide |
onAfterColumnShow |
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onAfterFilter | occurs after datatable was filtered
onAfterLoad | fires after data loading is complete
onAfterRender | occurs each time after the view is rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after a cell is selected
onAfterSort | fires after sorting dataset
onAfterUnSelect | fires after a cell is unselected
onAreaDrag | fires when area selection is started
onBeforeAdd | fires before adding item to datastore
onBeforeAreaAdd | fires before a select area is added
onBeforeAreaRemove | fires before a select area is removed
onBeforeBlockSelect | event occurs before block selection
onBeforeColumnDrag | fires the monent you start dragging the column from its source potition
onBeforeColumnDrop | fires the moment you drop the column to its target position
onBeforeColumnDropOrder | fires the moment you drop the column over the target area
onBeforeColumnHide |
onBeforeColumnShow |
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onBeforeFilter | called when filtering process is started, but data is not filtered yet
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs each time before the view is rendered
onBeforeSelect | fires before a cell is selected
onBeforeSort | fires before sorting dataset
onBeforeUnSelect | fired before a cell is unselected
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onCheck | fires when a checkbox is checked or unchecked in the datatable item
onCollectValues | fires after datatable has collected options
onColumnResize | fires when width of column was changed
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHeaderClick | occurs after clicking on header
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLiveEdit | occurs when data was changed in the editor
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onResize | fires when the width or height of DataTable was changed
onRowResize | fires when height of row was changed
onScrollX | fires when the user scrolls the table left or right
onScrollY | fires when the user scrolls the table up or down
onSelectChange | fires when selection is changed in a DataTable
onStructureLoad | fires when the structure of DataTable (columns configuration) is initialized
onStructureUpdate | fires when structure of datatable was changed ( column added, hidden or reconfigured )
onSubViewClose | fires after a subview or a subrow is closed
onSubViewCreate | fires after a subview was created
onSubViewOpen | fires after a subview or a subrow is opened
onSubViewRender | fires each time subview is rendered
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
areaselect | enables/disables area selection
autoConfig | datatable adjust configuration to the data
autoheight | adjusts Datatable size to the its content vertically
autowidth | adjusts Datatable size to its content horizontally
blockselect | enables/disables block selection
borderless | used to hide the component borders
checkboxRefresh | controls behavior of checkbox editors in grid
clipboard | enables/disables clipboard support
columnWidth | defines the default width for columns (in pixels)
columns | configures columns of the table
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datafetch | defines the number of records that will be loaded into datatable during the next dynamic loading call
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
delimiter | sets CSV delimiters for clipboard operations
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragColumn | enables drag-and-drop support for columns
dragscroll | enables autoscroll of component during drag-n-drop
editMath | enables formular editing
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
externalData | allows defining custom 'move' logic for the component.
filterMode | defines filtering rules in tree-like components
fixedRowHeight | defines whether the height should be fixed for all rows or can vary
footer | enables/disables the footer in DataTable (disabled, by default)
form | linked form
gravity | sets the view gravity (1 by default)
header | enables/disables the header in DataTable (enabled, by default)
headerRowHeight | sets the heigth of the header row
headermenu | adds a headermenu to control column visibility
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hover | css class for a row-hover in the datatable
id | the component ID
leftSplit | the number of the fixed columns from the left side of the table (actual for the split mode )
liveValidation | validation during cell editing
loadahead | sets the number of items that will be loaded on each scroll movement relative to the last item in the scrolling direction
map | defines data mapping
math | enables math formulas in DataTable
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minColumnHeight | sets the minimum height for a row
minColumnWidth | sets the minimum width for a column
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables the multi selection mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
prerender | invokes the full rendering of DataTable data
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
resizeColumn | enables/disables horizontal resizing of columns
resizeRow | enables/disables vertical resizing of rows
rightSplit | sets the number of the fixed columns from the right side of the table (actual for the split mode )
rowHeight | sets the default height for rows
rowLineHeight | default line height for grid's row
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables or disables scroll for the datatable
scrollAlignY | enables/disables scrolling the table just by whole rows (i.e. you won't be allowed to scroll along the full length of rows)
scrollX | enables/disables horizontal scrolling
scrollY | enables/disables vertical scrolling
select | sets the selection mode in DataTable
spans | array of span configurations for the datatable
subRowHeight | automatically adjusts the subrow's height to the size of the text
subrow | sets a subrow template
subview | adds a subview configuration into datatable
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | used for configuring presentation of items
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
yCount | defines height of datatable in rows
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
headerContent | a hash property containing a collection of active elements which can be placed in the header
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
waitData | eventual result of an asynchronous operation ('promise' object) for the loaded data


Methods

add | adds an item to the store
addCellCss | adds a css class to the cell
addCss | applied CSS class to a component item
addRowCss | adds a css class to the row
addSelectArea | adds a select area
addSpan | adds colspan or rowspan to the datatable
adjust | adjusts the component to the size of the parent HTML container
adjustColumn | adjusts a column to the width of the content
adjustRowHeight | autodetect height of rows in datatable
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearSelection | clears selection
clearValidation | removes all validation marks from the component
closeSub | closes subrow or subview for an item with the given id
collectValues | returns an array of unique values of the specified column
columnId | returns the id of the column at the specified index
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
eachColumn | iterates over all visible columns in the table
eachRow | iterates over all rows in the table
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editCell | enables the edit mode for the specified cell
editColumn | enables the edit mode for the specified column
editNext | closes the current editor and opens one in the next cell of the row
editRow | enables the edit mode for the specified row
editStop | stops the edit mode and closes all opened editors. The component is still editable
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
filterByAll | refilters DataTable by all specified filters
find | returns rows that match the criterion
focusEditor | moves focus to the active editor
getAllSelectAreas | returns an object that contains configuration objects of all select areas in the datatable
getChildViews | returns child views of the calling component
getColumnConfig | returns the configuration object of the specified column
getColumnIndex | returns the index of the column with the specified id
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
getFilter | returns the filter object that the component uses to filter the values of the specified column
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHeaderContent | returns set of helpers for header content manipulation
getHeaderNode | returns HTML element of the column's header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the current position of scrolls
getSelectArea | returns the object of the select area
getSelectedId | returns the selected elements' ids
getSelectedItem | gets an object of the selected data item
getSpan | returns the config array for a span or null, if there are no spans
getState | returns the current state of the view
getSubView | returns subview of the item with the given id
getText | returns text value of a cell
getTopParentView | returns top parent view
getVisibleCount | returns count of visible rows
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideColumn | hides the specified column
hideOverlay | hides previously defined overlay
isColumnVisible | returns true if column is visible
isEnabled | checks whether the view is enabled
isSelected | returns true if related record is selected
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | converts an HTML node or event object to in-table position
mapCells | applies the callback to a range of cells
mapEvent | routes events from one object to another
mapSelection | executes some custom method for all cells in the currently selected block
markSorting | marks the sorted column with a dedicated sign (asc/desc) in the header
move | moves the specified item to a new position
moveBottom | moves the specified item to the last position
moveColumn | moves column to different position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
openSub | opens subrow or subview for an item with the given id
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshColumns | refreshes the structure of DataTable
refreshFilter | rebuilds list of options in select filter
refreshHeaderContent | refreshes the header row of DataTable
registerFilter | registers a filter element
remove | removes the specified item/items from datastore
removeCellCss | remove css class from the cell of datatable
removeCss | removes CSS class from a component item
removeRowCss | remove css class from the row
removeSelectArea | removes a select area
removeSpan | removes a rowspan/colspan from the datatable
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeSubView | adjusts the row's size to the size of a subview
scrollTo | scrolls the view to the defined position
select | selects the specified element
selectAll | selects all cells in the DataTable
selectRange | selects the specified range of elements
serialize | serializes data to a JSON object
setColumnWidth | sets the width of the specified column
setPage | makes the specified page visible (assuming that the pager was defined )
setRowHeight | sets the height of the specified row
setState | restores the specified state
show | makes the component visible
showCell | scrolls the table (if needed) to make the specified cell visible
showColumn | shows the column which was previously hidden by method 'hidecolumn'
showColumnBatch | shows or hides a group of columns
showItem | 'scrolls' the table to make the specified row visible
showItemByIndex | 'scrolls' the table to make the specified row visible
showOverlay | shows the overlay message over the body of DataTable
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | cancels selection of the specified element
unselectAll | unselects all selected cells in a datatble
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
validateEditor | validates data in currently active editor


add

adds an item to the store

id add(object obj, [number index] );

Parameters

obj | object | the item object
index | number | the item position

Returns

id the item id

Example

dtable.add({
    name:"Best film ever"
    rank:1
});

Details

Object can contain any properties:

$$('mygrid').add({
  some:"some string",
  other:123,
  complex:{
    contain:"any",
    content:"inside"
  }
}, 0);

See also

  • api
    • remove
    • clearAll
    • DataStore
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


addCellCss

adds a css class to the cell

void addCellCss(string id,string name,string css);

Parameters

id | string | the row id
name | string | the column name
css | string | the name of a css class

Example

$$("mytable").addCellCss(152, "years", "css_class_name");

See also

  • api
    • removeCellCss
    • addRowCss
    • removeRowCss
  • articles
    • Styling DataTable


addRowCss

adds a css class to the row

void addRowCss(string id,string css);

Parameters

id | string | the row id
css | string | the name of a css class

Example

$$("mytable").addRowCss(152, "some_rule");

Details

Works as a short alias for the addMark command

See also

  • api
    • addCellCss
    • removeCellCss
    • removeRowCss
  • articles
    • Styling DataTable


addSelectArea

adds a select area

void addSelectArea(object start,object end,boolean preserve, [string area_name,string css,boolean handle] );

Parameters

start | object | the id object of the left top cell, contains two properties: the row id and the column id
end | object | the id object of the right cell, contains two properties: the row id and the column id
preserve | boolean | defines, if the previous select area should be saved, false by default
area_name | string | optional, the name used to address to an area to change or to delete it
css | string | optional, the css style for an area
handle | boolean | optional, defines, whether selection will be resized with or without a handle

Example

$$("dtable").addSelectArea(start,end,preserve);

See also

  • api
    • getSelectArea
    • removeSelectArea
    • getAllSelectAreas
  • articles
    • Area Selection in DataTable


addSpan

adds colspan or rowspan to the datatable

void addSpan(number/string/object id,string column,number width,number height, [string value,string css] );

Parameters

id | number/string/object | id of the row that starts colspan/rowspan
column | string | id of the column that starts colspan/rowspan
width | number | how many columns should the span include
height | number | how many rows should the span include
value | string | value that the span area should display
css | string | css class that should be applied to the span area

Available only in PRO Edition

Example

grid.addSpan(1, "country", 1, 3);
grid.refresh();

Details

To enable the rowspans and colspans functionality, you should set the spans parameter with the true value in the datatable configuration:

webix.ui({
    view:"datatable",
    columns:[...],
    spans:true
    ...
});

The method can as well take an array of arrays with the same configuration (id, column, width, height, value, css) to define several spans at a time.

grid.addSpan([
    [1, "country", 1, 3],
    [4, "country", 1, 2],
    [6, "country", 1, 3]
]);

Defaults:

  • default values for span width and height are 1;
  • span value parameter is optional and used if a custom text for the cell is required. If you need to display the initial value, omit this field or pass an empty value ("", null);
  • span css is optional. By default, colspans and rowspans don't feature any special styling.

See also

  • api
    • spans
    • removeSpan
    • getSpan
  • articles
    • Datatable Rowspans and Colspans


adjust

adjusts the component to the size of the parent HTML container

void adjust();

Example

dtable = webix.ui({
    view:"datatable",
    ...
})

dtable.adjust();

Details

The method changes the width and height of the component to fit the parent HTML container.
If you want to resize the component in the layout according to its widht and height settings, you need to use the resize method.

<div id='mybox' style='width:100px; height:200px;'></div>
webix.ui({ view:"tree", id:"mytree", container:"mybox"});
...
document.getElementById('mybox').style.width = "200px"; //after the container box is resized
$$('mytree').adjust();                           //component needs adjusting to the new size

See also

  • api
    • resize
  • samples
    • Dynamical adjusting to the parent container
    • Sizing and events
  • articles
    • Sizing and Resizing


adjustColumn

adjusts a column to the width of the content

void adjustColumn(string| number id, [string header] );

Parameters

id | string| number | columnID
header | string | adjustment mode ("header", "data", "all");

Example

datatable.adjustColumn("title");
datatable.adjustColumn("title", "header");

Details

Adjustment modes:

  • header - adjusts the column to the width of its header;
  • data (default) - adjusts the column to the width of its content;
  • all - combines the above mentioned modes and adjusts the column to the bigger value.

See also

  • api
    • adjust
  • articles
    • Columns Configuration
    • Sizing and Resizing


adjustRowHeight

autodetect height of rows in datatable

void adjustRowHeight(string columnId,boolean silent);

Parameters

columnId | string | id of column
silent | boolean | apply method without repainting

Example

dtable.adjustRowHeight("title");

Details

Height detected only based on the value of one column, defined by the columnId parameter.

If you want to apply auto-sizing just after data loading you can use code like next

grid = new webix.ui({
    container:"testA",
    view:"datatable",
    columns:[
        { id:"rank",    width:40,   header:"", css:"rank"},
        { id:"title",   width:380,  header:"Film title" },
        { id:"year",    width:160,  header:"Released"   },
        { id:"votes",   width:120,  header:"Votes"      }
    ],
    fixedRowHeight:false,  rowLineHeight:25, rowHeight:25,
    on:{
        "onresize":webix.once(function(){
            this.adjustRowHeight("title", true);
        })
    }
});

You must have fixedRowHeight set to false, or call of adjustRowHeight will not have a visible result.

This method will slowdown a component a lot.

See also

  • samples
    • Row auto-height
  • articles
    • Sizing and Resizing


attachEvent

attaches the handler to an inner event of the component (allows behaviour customizations)

id attachEvent(string type,function functor, [string/number id] );

Parameters

type | string | the event name, case-insensitive
functor | function | the function object or name
id | string/number | the event id

Returns

id the id of the attached event handler

Example

dtable.attachEvent("onAfterLoad",function(){
    this.select(2);
})

- ...mixed... function the callback receives different set of parameters for different events. Check the documentation of the related events. - result boolean returning false will block the default behaviour (works not for all events, check the details below).
Details

How the handler is provided

You can use the method with an inline function or provide just the global function reference. In the second case, be sure that the function is visible from the calling point.

function doTask(){ ... };
dtable.attachEvent("onBeforeLoad", doTask); //uses the reference
dtable.attachEvent("onBeforeLoad", "doTask"); //will work as well, but not recommended

The handler id

The last parameter allows you to define the id of the attached handler. If it was not specified, some unique value will be assigned as the id. The only purpose of such id - detaching the handler from an event (in most cases you don't need to care about the handler's id).

Callback

Check the related documentation to get the full list of parameters. The amount and meaning will vary for different events.

The value which is returned by an event can change behavior of component. Returning true or nothing will be considered as the positive signal, while returning false will be considered as a signal to stop the current activity.

dtable.attachEvent("onBeforeSelect", function(id){
    if (id == 123)
        return false; //blocks selection of a specific element
});

Multiple handlers

You can attach multiple handlers to one and the same event and they won't overwrite each other. If some of handlers will return false - the related operation will be blocked.

Event handlers are processed in the same order as they were attached.

See also

  • api
    • EventSystem,
    • detachEvent,
    • hasEvent
    • callEvent
  • samples
    • Events invoked in DataTable
  • articles
    • Events Handling with DataTable
    • Event Handling


bind

binds components

void bind(object target, [function rule,string format] );

Parameters

target | object | an object that binds to the calling component
rule | function | sets the rule according which components will be bound
format | string | the format of bound data

Example

$$('form1').bind($$('list1'));

gridb.bind(grida, function(slave, master){
        if (!master) return false;
    return master.id == slave.movie;
});

Details

Behavior of data binding differs for different components a lot. Basically, it fills component with data based on selection in the master component.

The technique allows you to create complex data updates schemes, but you can ignore it as the same use case can be implemented through events and custom logic.

Binding rule defines a rule according to which records in the slave component are filtered. It can be defined only in case slave component is based on DataStore (all data management components except for tree-like) or TreeStore (tree and treetable).

See also

  • api
    • unbind
  • samples
    • Binding to List
    • Linking tables
    • List Data Bound to Richselect
  • articles
    • Events Handling with DataTable
    • Data Binding and Syncing
    • Working with Bound Components


blockEvent

temporarily blocks triggering of ALL events of the calling object

void blockEvent();

Example

$$('list').blockEvent();
$$('list').add({ text:'abc'}); //will not trigger list events
$$('list').unblockEvent();

Details

Use the command with care, many actions in components are linked through events.

The most common use-case - preventing a component from repainting with each small operation:

//will repaint component 3 times

$$('list').add({ text:'111'});
$$('list').add({ text:'222'});
$$('list').add({ text:'333'});

//will repaint component only once (onStoreUpdated of List DataStore is blocked)
$$('list').data.blockEvent();
$$('list').add({ text:'111'});
$$('list').add({ text:'222'});
$$('list').add({ text:'333'});
$$('list').data.unblockEvent();
$$('list').refresh();

See also

  • api
    • unblockEvent
  • articles
    • Events Handling with DataTable
    • Event Handling


callEvent

calls an inner event

boolean callEvent(string name,array params);

Parameters

name | string | the event name, case-insensitive
params | array | an array of the event related data

Returns

boolean false, if some of the event handlers returns false. Otherwise, true

Example

//invokes triggering handlers of the 'onResize' event
var check = dtable.callEvent("onResize", [...]);

Details

Normally, events are called automatically and you needn't to use this method.

See also

  • api
    • hasEvent
    • attachEvent
    • detachEvent
  • samples
    • Events invoked in DataTable
    • Sizing and events
  • articles
    • Events Handling with DataTable


clearAll

removes all items from the component

void clearAll();

Example

dtable = webix.ui({
          view:"datatable",
          ...
          url:"data.xml"
)}

dtable.clearAll();

See also

  • api
    • remove
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


clearSelection

clears selection

void clearSelection();

Example

dtable = webix.ui({
          view:"datatable",
          ...
)}

dtable.clearSelection();

See also

  • api
    • select
    • unselect
    • getSelectedId
  • articles
    • Selection with Datatable


closeSub

closes subrow or subview for an item with the given id

void closeSub(string/number id);

Parameters

id string/number the id of the item

Example

$$("mydatatable").closeSub(id);

See also

  • api
    • openSub
  • samples
    • Sub-Form in a DataTable
    • SubRows in DataTable - API


collectValues

returns an array of unique values of the specified column

array collectValues(id id);

Parameters

id id the column id

Returns

array an array of unique values


columnId

returns the id of the column at the specified index

id columnId(number index);

Parameters

index number the column index, zero-based numbering

Returns

id the column id

Example

//the id of the first column
var id = datatable.columnId(0);

See also

  • api
    • getColumnIndex
  • articles
    • Columns Configuration


detachEvent

detaches a handler from an event (which was attached before by the attachEvent method)

void detachEvent(id id);

Parameters

id id the event id (the result of the attachEvent operation)

Example

var myEvent = $$("mylist").attachEvent("onItemClick", function (){
    ...//event handler code
});
...
$$("mylist").detachEvent(myEvent);

See also

  • api
    • hasEvent
    • attachEvent
  • samples
    • Events invoked in DataTable
    • Sizing and events
  • articles
    • Events Handling with DataTable


disable

disables the calling view (makes it dimmed and unclickable)

void disable();

Example

dtable.disable();

See also

  • api
    • enable
  • samples
    • Disabling Components
  • articles
    • Disabling/Enabling Components


eachColumn

iterates over all visible columns in the table

void eachColumn(function handler, [boolean all] );

Parameters

handler | function | the handler function
all | boolean | if true, hidden columns are included into a loop

Example

dtable.eachColumn(
    function (columnId){
        console.log( dtable.getColumnIndex(columnId) )
    }
)

Details
  • The handler function takes column ID as parameter;
  • The order of iteration is the current columns order.


eachRow

iterates over all rows in the table

void eachRow(function handler, [boolean all] );

Parameters

handler | function | the handler function
all | boolean | if true, hidden rows are included into a loop

Example

dtable.eachRow(
    function (row){
        console.log( dtable.getItem(row).title )
    }
)

Details
  • The loop variable i is the row id.
  • Basically, the order of iteration is the order that rows were added to the table but not necessarily so.
  • If the table loads data dynamically - just already parsed rows will be iterated.
  • If you apply filtering to the table, all rows will be iterated, doesn't matter they meet filtering criteria or not.


edit

enables the edit mode for the specified item

void edit(object id);

Parameters

id object the object defining the position of a cell

Example

dtable.edit({
        row:2,
        column:"title"
});

Related sample: Using the 'select' editor
Details

The method has been created for components compatibility and isn't handy for direct use.
We strongly encourage you to use editRow, editColumn, editCell instead of this method.

The input object parameter should contain 2 attributes:

  • row - (string) the row id
  • column - (string) the column id

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • editRow
    • editColumn
    • editCell
  • samples
    • Using the 'select' editor
  • articles
    • DataTable Editing
    • Editing Data Items


editCancel

cancels the edit mode and closes all opened editors. The table is still editable

void editCancel();

Example

dtable.editCancel()

Details

The method doesn't save changes before closing the editor(s)

See also

  • api
    • editStop
  • articles
    • DataTable Editing
    • Editing Data Items


editCell

enables the edit mode for the specified cell

void editCell(string row,string col, [boolean preserve,boolean show] );

Parameters

row | string | the row id
col | string | the column id
preserve | boolean | the true value 'says' to keep the previous editor opened
show | boolean | the true value 'says' to scroll DataTable if the specified cell is out of the viewport

Example

dtable.editColumn(1, "title", true, true);

Details

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • editable
    • editaction
    • editRow
    • editColumn
    • editStop
    • editCancel
  • samples
    • Opening multiple editors
  • articles
    • DataTable Editing
    • Editing Data Items


editColumn

enables the edit mode for the specified column

void editColumn(string id);

Parameters

id string the column id

Example

dtable.editColumn("title"); // enables the edit mode for the 'title' column

Details

By default, the method sets the cursor to the first cell of the column.

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • editable
    • editaction
    • editRow
    • editCell
    • editStop
    • editCancel
  • samples
    • Opening multiple editors
  • articles
    • DataTable Editing
    • Editing Data Items


editNext

closes the current editor and opens one in the next cell of the row

boolean editNext();

Returns

boolean false

Example

dtable.editNext();

Details

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • editable
    • editaction
    • editCell
    • editRow
    • editColumn
    • editStop
    • editCancel
    • edit
    • editStop
    • focusEditor
  • articles
    • DataTable Editing
    • Editing Data Items


editRow

enables the edit mode for the specified row

void editRow(string id);

Parameters

id string the row id

Example

dtable.editRow(2); //enables the edit mode for the row with id=2

Details

By default, the method sets the cursor to the first cell of the row.

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • editable
    • editaction
    • editColumn
    • editCell
    • editStop
    • editCancel
  • samples
    • Opening multiple editors
  • articles
    • DataTable Editing
    • Editing Data Items


editStop

stops the edit mode and closes all opened editors. The table is still editable

void editStop();

Example

dtable.editStop();

Details

The method saves changes before closing the editor(s)

See also

  • api
    • editCancel
  • articles
    • DataTable Editing
    • Editing Data Items


enable

enables the calling view that was disabled by the 'disable' method

void enable();

Example

dtable.enable();

See also

  • api
    • disable
  • samples
    • Disabling Components
  • articles
    • Disabling/Enabling Components


filter

filters the component

void filter(template|function text,string value,boolean preserve);

Parameters

text | template|function | a template of filtered value or function
value | string | the filtering mask
preserve | boolean | if set to true, each next filtering criteria will be applied to the already filtered list

Example

//filters all fields with 'abc' in the 'text' property
//using a template
list.filter('#text#',"abc")

//using a function
list.filter(function(obj){
    return obj.text.toString().indexOf("abc") != -1;
});

See also

  • api
    • find
  • samples
    • Chart: Filtering
    • Filtering via a separate input element
    • List: Filtering
  • articles
    • DataTable Filtering
    • Filtering in the Tree
    • Data Filtering and Sorting


filterByAll

refilters DataTable by all specified filters

void filterByAll();

Example

dtable.filterByAll();

See also

  • api
    • filter
  • samples
    • Filtering by multiple criteria
  • articles
    • DataTable Filtering


focusEditor

moves focus to the active editor

void focusEditor();

Example

$$("mylist").focusEditor();

Details

If components has no active editors - command do nothing.

See also

  • samples
    • The 'select' editor
  • articles
    • DataTable Editing
    • Editing Data Items


getAllSelectAreas

returns an object that contains configuration objects of all select areas in the datatable

object getAllSelectAreas();

Returns

object an object with config objects of all select areas

Example

var areas = $$("dtable").getAllSelectAreas();

Details

Each returned object of the select area contains the following parameters:

  • start - (object) the id object of the left top cell, contains two parameters: the row id and the column id
  • end - (object) the id object of the right cell, contains two parameters: the row id and the column id
  • preserve - (boolean) defines, if the previous select area should be saved, false by default
  • area_name - (string) optional, the name used to address to an area to change or to delete it
  • css - (string) optional, the css style for an area
  • handle - (boolean) optional, defines, whether selection will be resized with or without a handle

See also

  • api
    • addSelectArea
    • removeSelectArea
    • getSelectArea
  • articles
    • Area Selection in DataTable


getColumnConfig

returns the configuration object of the specified column

object getColumnConfig(string id);

Parameters

id string the column id

Returns

object the configuration object

Example

dtable.getColumnConfig("title");

Details

The method let's you to know attributes that are specified for a certain column.

For example, if you have the following configuration:

columns:[
    { id:"rank",    editor:"text",      header:"",              width:50},
    { id:"title",   editor:"text",      header:"Film title",    width:200},
    { id:"votes",   editor:"text",      header:"Votes",         width:100}
]

calling getColumnConfig("title") will return the object as in:

{
    id:"title",
    editor:"text",
    header:[{
        text:"Film title"
    }],
    width:200
}

Note that the method works for hidden column as well.

See also

  • api
    • columns
  • articles
    • Columns Configuration


getColumnIndex

returns the index of the column with the specified id

number getColumnIndex(id id);

Parameters

id id the id of the column

Returns

number the index of the column

Example

//gets the index of the 'rank' column
var ind = grid.getColumnIndex("rank");

Details

Index represents the order of columns in the table structure.
Zero-based numbering, i.e. the index of the first column == 0.

See also

  • api
    • columnId
  • articles
    • Columns Configuration


getEditState

returns info about active editor object

object getEditState();

Returns

object object with editors state and info

Example

var editor = view.getEditState();

Details

If there are many active objects - returns info about last opened editor

Editor object

{
    node: html_node_of_editor,
    value: initial_value_of_editor
    config: configuration_of_editor
}

You can access all methods of editor through this object

//get value
var value = some.getEditState().getValue();
//set value
some.getEditState().setValue( new_value );
//set focus
some.getEditState().focus();

See also

  • api
    • getEditorValue
    • getEditor
  • articles
    • Data Editors
    • DataTable Editing


getEditor

returns editor object

object getEditor( [string| number| object row,string| number column] );

Parameters

row | string| number| object | row id
column | string| number | column id

Returns

object object with editor state and info

Example

//return last opened editor
var editor = view.getEditor();

//return specific editor
var editor = view.getEditor(3, "year");
//or
var editor = view.getEditor({row:3, column:"year"});

Details

Editor object

{
    column: column id,
    config: editor configuration object,
    focus: method that sets focus for an editor,
    getInputNode: method that return the input node of an editor,
    getValue: method that return editor value   ,
    node: HTML node of the editor,
    render: method that renders the editor,
    setValue: method that sets value for an editor,
    value: current editor value,
}

You can access all methods of editor through this object

//get value
var value = some.getEditor().getValue();
//set value
some.getEditor().setValue( new_value );
//set focus
some.getEditor().focus();

See also

  • api
    • getEditState
    • getEditorValue
  • articles
    • Data Editors
    • DataTable Editing


getEditorValue

returns the value of the active (currently open) editor

string getEditorValue();

Returns

string the editor value

Example

dtable.getEditorValue();

Details

If no editors or several editors are open, the method returns the value of the last opened editor.

See also

  • api
    • getEditState
    • getEditor
  • articles
    • Data Editors
    • DataTable Editing


getFilter

returns the filter object that the component uses to filter the values of the specified column

object getFilter(id columnID);

Parameters

columnID id the id of a column

Returns

object the filter object

Example

columns:[
    { id:"title",   header:["Film title", {content:"textFilter"}],width:200,    sort:"string"},
    { id:"year",    header:["Released",  {content:"selectFilter"}] , width:80,  sort:"int"},
]
....

//gets to the filter object of each column and retrieves its current value
var title = this.getFilter("title").value;
var year = this.getFilter("year").value;

See also

  • api
    • filter
    • filterByAll
    • registerFilter
  • samples
    • Filtering by several criteria (OR logic)
  • articles
    • DataTable Filtering


getFirstId

gets the ID of the first row

id getFirstId();

Returns

id the id of the first item

Example

var row_id = dtable.getFirstId();

See also

  • api
    • getLastId
  • samples
    • Selection
  • articles
    • Selection
    • Data Object Operations


getHeaderContent

returns set of helpers for header content manipulation

hash getHeaderContent(id id);

Parameters

id id content id

Returns

hash hash of helpers

Example

webix.ui({
    view:"datatable", id:"mytable",
    columns:[
        { header:{ content:"masterCheckbox", contentId:"cm1" } }
    ]
});
$$("mytable").getHeaderContent("cm1").check();

Details

currently it works only with masterCheckbox

masterCheckbox

Available API

var control = $$("mytable").getHeaderContent("cm1");

//check master checkbox
control.check();

//uncheck master checkbox
control.uncheck();

//get master checkbox state
var state = control.isChecked();


getHeaderNode

returns HTML element of the column's header

HTMLElement getHeaderNode(string columnId, [number rowIndex] );

Parameters

columnId | string | id of the column in question
rowIndex | number | index of the header row in case of a multiline header.

Returns

HTMLElement the component HTML element

Example

$$("datatable").getHeaderNode("title");


getIdByIndex

returns the id of the item with the specified index

id getIdByIndex(number index);

Parameters

index number the item index (zero-based numbering)

Returns

id the item id
Details

if item with such index doesn't exists method returns undefined value

See also

  • api
    • getIndexById
  • articles
    • Data Object Operations


getIndexById

returns the index of the item with the specified id

number getIndexById(id id);

Parameters

id id the item id

Returns

number the item's index
Details

if id is not found then method returns -1

With tree-like structures, use the getBranchIndex method.

See also

  • api
    • getIdByIndex
  • articles
    • Data Object Operations


getItem

gets the object of the data item with the specified id

object getItem(id id);

Parameters

id id the item id

Returns

object the object of a data item

Example

//'record' variable will contain an object of the related DataTable row,
var record = dtable.getItem("rowId");

//you can access data members directly
var title = record.title;

See also

  • articles
    • Getting/setting the cell value
    • Data Object Operations


getItemNode

returns HTML element of the item

void getItemNode(id id);

Parameters

id id data item ID

Example

var node = mylist.getItemNode(123);
node.innerHTML = "some text";

Details

Datatable and treetable specificity:

  • item ID as number - the method returns HTML element of the first cell in a row with this ID:
$$("mydatatable").getItemNode(2);
  • item ID as object that contains data item ID and column ID - the method returns HTML element of a cell with these row and column IDs:
$$("mydatatable").getItemNode({ row: 2, column:"title"});


getLastId

returns the id of the last row

id getLastId();

Returns

id the id of the last item

Example

var row_id = dtable.getLastId();

See also

  • api
    • getFirstId
  • samples
    • Selection
  • articles
    • Selection
    • Data Object Operations


getNextId

returns the ID of an item which is positioned the specified step after the specified item

id getNextId(id id,number step);

Parameters

id | id | the item id
step | number | the step (by default, 1)

Returns

id the item id

See also

  • api
    • getPrevId
  • articles
    • Selection
    • Data Object Operations


getPage

returns the currently visible page in case of paged view

number getPage();

Returns

number the index of the currently visible page, zero-based numbering

Example

var page = $$('dtable').getPage();

See also

  • api
    • setPage
  • articles
    • Paging


getParentView

returns the parent object of the calling element. Used while integrating with Webix Touch

object getParentView();

Returns

object the parent object

Example

webix.ui({
  rows:[
    { id:"myview", template:"some" }
  ]
});

var layout = $$('myview').getParentView();

See also

  • api
    • getChildViews
  • samples
    • Colorpicker in Form
  • articles
    • View


getPrevId

returns the ID of an item which is positioned the specified step before the specified item

id getPrevId(id id,number step);

Parameters

id | id | the item id
step | number | the step (by default, 1)

Returns

id the item id

See also

  • api
    • getNextId
  • articles
    • Selection
    • Data Object Operations


getScrollState

returns the current position of scrolls

object getScrollState();

Returns

object the position of scrolls

Example

var state = $$('mytable').getScrollState();
alert(state.x); //position of x-scroll
alert(state.y); //position of y-scroll

See also

  • api
    • scrollTo
    • showItem
    • showItemByIndex
  • articles
    • Scrollview
    • Sizing and Resizing


getSelectArea

returns the object of the select area

object getSelectArea(string area_name);

Parameters

area_name string optional, the name of the select area

Returns

object the object of the select area

Example

var area = $$("dtable").getSelectArea();

Details

if the area_name parameter isn't passed, the method returns the last selected area

The returned object of the select area contains the following parameters:

  • start - (object) the id object of the left top cell, contains two parameters: the row id and the column id
  • end - (object) the id object of the right cell, contains two parameters: the row id and the column id
  • preserve - (boolean) defines, if the previous select area should be saved, false by default
  • area_name - (string) optional, the name used to address to an area to change or to delete it; by default it's generated by webix.uid() method
  • css - (string) the css style (classname) for the border of an area. By default, the border of area selection is black
  • handle - (boolean) optional, enables/disables a handle for selection area resize (enabled by default)

See also

  • api
    • addSelectArea
    • removeSelectArea
    • getAllSelectAreas
  • articles
    • Area Selection in DataTable


getSelectedId

returns the selected elements' ids

object/array/string getSelectedId(boolean asArray,boolean asString);

Parameters

asArray | boolean | optional, specifies whether the returning result should be array
asString | boolean | optional, specifies whether the returning result should be string

Returns

object/array/string cell/row/column id or array of them

Example

//return ids as an array of objects
grid.getSelectedId(true);

//return ids as an array of strings
grid.getSelectedId(true, true);

Details

If no parameters were passed to the method, it returns the id as an object (for one selected element) or as an array of objects (for several elements).

The format of the selection result if the second parameter (asString) is false:

{ column:"votes", row:4, id:4 } // "row" selection

where:

  • column - the column id
  • row - the row id
  • id - string value of the ID (the same as if you pass asString)

If the "asString" parameter was set, the result value depends on the selection mode:

  • "row" or true - 4 (as in dataset)
  • "column" - "votes"
  • "cell" - "4_votes"

See also

  • api
    • getSelectedItem
    • mapSelection
    • select
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


getSelectedItem

gets an object of the selected data item

object getSelectedItem( [boolean as_array ] );

Parameters

as_array boolean if true, returns an array with selected item(s)

Returns

object object of the selected item with all its properties

Example

var item = grid.getSelectedItem();
//item =  {id:1, title:"Title", year:1987}

Details

In case of multiple item selection the method will return array of selected items anyway. If array mode ("as_array") is switched on, even one item will be put put into an array.

See also

  • api
    • getSelectedId
  • articles
    • Selection with Datatable


getSpan

returns the config array for a span or null, if there are no spans

array getSpan();

Returns

array config for a span

Example

var span = $$("dtable").getSpan();

Details

the elements of the returned array are:

  • id - (number/string/object) id of the row that starts colspan/rowspan
  • column - (string) id of the column that starts colspan/rowspan
  • width - (number) how many columns should the span include
  • height - (number) how many rows should the span include
  • value - (string) optional, the value that the span area should display
  • css - (string) optional, css class that should be applied to the span area

See also

  • api
    • addSpan
    • removeSpan
  • articles
    • Datatable Rowspans and Colspans


getState

returns the current state of the table

object getState();

Returns

object the state object

Example

dtable.getState()

See also

  • api
    • setState
  • samples
    • DataTable state object
    • (Re)Storing the state of the filtered table
  • articles
    • Saving and Restoring Component State


getSubView

returns subview of the item with the given id

object getSubView(string/number id);

Parameters

id string/number the id of the item

Returns

object the subview object

Example

$$("mydatatable").getSubView(id);


getText

returns text value of a cell

string getText(id rowid,id colid);

Parameters

rowid | id | id of row
colid | id | name of column

Returns

string value of the cell as it rendered in a datatable

Example

//get value
var val = $$("mytable").getItem(12).price;

//get rendered text
var val = $$("mytable").getText(12, "price");


getVisibleCount

returns count of visible rows

number getVisibleCount();

Returns

number count of visible rows

Example

var count = $$("mytable").getVisibleCount();

Details

It returns not ALL rows, and not actual count of loaded rows - but how many rows can be visible with current datatable height

See also

  • api
    • count
  • articles
    • Data Object Operations


hasEvent

checks whether the component has the specified event

boolean hasEvent(string name);

Parameters

name string the event name, case-insensitive

Returns

boolean true, if at least one handler was attached to the specified event. Otherwise, false

Example

var is_exit = dtable.hasEvent('onBeforeSelect');

Details

The method checks whether some handler was attached to the object, and doesn't check whether that object has such event

See also

  • api
    • EventSystem,
    • detachEvent,
    • attachEvent
    • callEvent
  • articles
    • Event Handling
    • Events Handling with DataTable


hide

hides view. Used while integrating with Webix Touch

void hide();

Example

$$('mylist').hide();

Details

The method doesn't have any sense for standalone DataTable

See also

  • api
    • show
  • samples
    • Popup Menu
  • articles
    • Common Functions to Switch Between Views
    • Managing Visibility of Components


hideColumn

hides the specified column

void hideColumn(id id);

Parameters

id id the column id

Example

dtable.hideColumn("price");

Details

While data of the hidden column still can be accessed, api calls against it will result in error.

See also

  • api
    • showColumn
    • onBeforeColumnHide
    • onAfterColumnHide
  • articles
    • Columns Configuration


hideOverlay

hides previously defined overlay

void hideOverlay();

Example

view:"datatable",
on: {onAfterLoad:function(){
            this.hideOverlay();
        }
}

See also

  • api
    • showOverlay
  • samples
    • Loading screen
  • articles
    • Loading Data into DataTable


isColumnVisible

returns true if column is visible

boolean isColumnVisible(id id);

Parameters

id id column id

Returns

boolean true if column visible

Example

var check = mytable.isColumnVisible("year");


isSelected

returns true if related record is selected

void isSelected(id id);

Parameters

id id id of a row ( column, cell )
Details

If you are using cell-based selection, you can use the next syntax

var check = grid.isSelected(row_id, cell_id);


load

loads data from an external data source.

promise load(string url, [string type,function callback] );

Parameters

url | string | the data url
type | string | (optional) the type of data to load: 'json' (default), 'xml', 'jsarray', 'csv'
callback | function | (optional) the callback function

Returns

promise "promise" object

Example

$$("mylist").load("data.xml", "xml");

Details

Function signatures

The load method can be used with up to three parameters:

  • By default, the data type is set to 'json':
$$("component_id").load("some/path/data.json");
  • You can also pass a callback function:
$$('component_id').load("some/path/data.json", function(text, data, http_request){
  // do something with data.json()
});
  • If you need to specify both the data type and the callback:
$$("component_id").load("some/path/data.xml", "xml", function(text, data, http_request){
  // do something with the data object
});
//or
$$("component_id").load("some/path/data.xml", "xml", {
  error: function(text, data, http_request){
    webix.alert("error");
  },
  success:function(text, data, http_request){
    webix.message("success");
  }
});

Callback

By default, the loading is asynchronous, so you will need to use the callback to trigger some action after loading is finished.

The callback function takes 3 parameters:

  1. The text of the response
  2. The data object of the response
  3. The raw HTTP request object

Return Value

The method returns a Promises/A+ compatible promise object than contains the eventual result of an AJAX request.

Webix uses the Promiz.js library for promises. Learn more at:

  • Data Loading
  • Ajax operations

Error handlers

The callback can be defined as a combination of error and success functions (you can use only one of them if you want to).

Post and synchronous loading

As the load method doesn't provide direct ability to use post and sync, you can use the parse method instead:

// sync data loading
var result = webix.ajax().sync().get("some.json");
$$("component_id").parse(result.responseText);
// using POST for data loading
var result = webix.ajax().post("mydata.php", "some=value", function (text) {
  $$("component_id").parse(text);
});

See also

  • api
    • url
    • datatype
    • parse
  • samples
    • Form: Loading
  • articles
    • Loading Data into DataTable_external_file


locate

converts an HTML node or event object to in-table position

object locate(HTMLElement|Event node);

Parameters

node HTMLElement|Event an HTML node or event object

Returns

object the cell position

Example

var pos = dtable.locate(event);
alert(pos.row); //the row id
alert(pos.col); //the column id
alert(pos.rind); //the row index
alert(pos.cind); //the column index

Details

The method can be used to locate the related cell from some event handler.

The result object contains:

  • pos.row - the row id
  • pos.col - the column id
  • pos.rind - the row index
  • pos.cind - the column index


mapCells

applies the callback to a range of cells

void mapCells(number startrow,string startcol,number numrows,number numcols,function callback);

Parameters

startrow | number | the start row id
startcol | string | the start column id
numrows | number | the amount of rows
numcols | number | the amount of columns
callback | function | the function calling for each cell in the specified range

Example

grid.mapCells(1, "title", 3, 2, function(value, row_id, column_id, row_ind, col_ind) {
    console.log(value, row_id, column_id, row_ind, col_ind);
});

See also

  • api
    • mapSelection
  • samples
    • Mapping cells
  • articles
    • Getting/setting the cell value


mapSelection

executes some custom method for all cells in the currently selected block

void mapSelection(function callback);

Parameters

callback function the callback function

Example

//uppercase selected cells
dtable.mapSelection(function(value){
    return value.toString().toUpperCase();
});

-value string|int the cell value -row_id string|int the row id -column_id string|int the column id -row_ind number the row index of a cell within the selected block -col_ind number the column index of a cell within the selected block

See also

  • api
    • mapCells
  • samples
    • Mapping selection
  • articles
    • Getting/setting the cell value


markSorting

marks the sorted column with a dedicated sign (asc/desc) in the header

void markSorting(string column_id,string dir);

Parameters

column_id | string | column ID
dir | string | sorting direction

Example

dtable = webix.ui({view:"datatable", ...})

dtable.markSorting("title", "asc");

Details

The method is designed for the cases of programmatic sorting to indicated that the data in the datatable has been sorted.

dtable.sort("title", "asc");
dtable.markSorting("title", "asc");

The method can be called with no parameter to remove all sotring signs from the datatable headers.

See also

  • api
    • sort
  • samples
    • Sorting Datatable. Using sorting methods
  • articles
    • DataTable Sorting


move

moves the specified item to a new position

string move(string sid,number tindex, [object tobj,object details] );

Parameters

sid | string | the id of the item to move
tindex | number | the new position of the item (new index)
tobj | object | the object that the item is moved to
details | object | extra parameters for moving

Returns

string new item id

Example

//moving in the same list
$$("list").move("a12", 0);
$$("list").move("a13", -1);
//moves an item to a different list
var id = $$("list").move("a13", 0, $$("list2"), {newId:"b13"});

Details

Details object can contain the next properties:

details = {};
details.newId = "123"; //new id for moved item

Note that in case newId is not defined, the new ID will be the same as the ID of the source item (sid), which is not desirable during copying within one and the same component.

See also

  • api
    • moveBottom
    • moveDown
    • moveTop
    • moveUp
  • articles
    • Data Object Operations


moveBottom

moves the specified item to the last position

void moveBottom(id id);

Parameters

id id the item id

Example

$$('view').moveBottom("a12"); //moves the item with id="a12" 2 to the very end

See also

  • api
    • move
    • moveDown
    • moveTop
    • moveUp
  • articles
    • Data Object Operations


moveColumn

moves column to different position

void moveColumn(string id,number index);

Parameters

id | string | source column id
index | number | target index

Example

//moves column "year" to first position
$$("mytable").moveColumn("year", 0);

See also

  • api
    • hideColumn
    • showColumn
  • articles
    • Columns Configuration


moveDown

increases the item index and moves the item to the new position

void moveDown(id id,number step);

Parameters

id | id | the item id
step | number | the step of moving

Example

$$('view').moveDown("a12", 2); //moves the item with id="a12" 2 items down

See also

  • api
    • move
    • moveBottom
    • moveTop
    • moveUp
  • articles
    • Data Object Operations


moveSelection

moves selection in the specified direction

void moveSelection(string direction);

Parameters

direction string the move direction

Example

$$("list").moveSelection("top");

Details

The method can take only one of a predefined set of values.
The predefined values are:

  • 'up' ( cell and row selection modes)
  • 'down' (cell and row selection modes)
  • 'right' (cell and column selection modes)
  • 'left' (cell and column selection modes)

See also

  • api
    • getSelectedId
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


moveTop

moves the specified item to the first position

void moveTop(id id);

Parameters

id id the item id

Example

$$('view').moveTop("a12"); //moves the item with id="a12" to the very beginning

See also

  • api
    • move
    • moveBottom
    • moveDown
    • moveUp
  • articles
    • Data Object Operations


moveUp

decreases the item index and moves the item to the new position

void moveUp(id id,number step);

Parameters

id | id | the item id
step | number | the step of moving

Example

$$('view').moveUp("a12",2); //moves the item with id="a12" 2 items up

See also

  • api
    • move
    • moveBottom
    • moveDown
    • moveTop
  • articles
    • Data Object Operations


openSub

opens subrow or subview for an item with the given id

void openSub(string/number id);

Parameters

id string/number the id of the item

Example

$$("mydatatable").openSub(id);

See also

  • api
    • closeSub
  • samples
    • SubRows in DataTable - API


parse

loads data to the component from an inline data source

void parse(string| object data,string type);

Parameters

data | string| object | the data to add
type | string | the data type: 'json' (default), 'xml', 'csv', 'jsarray'

Example

webix.ui({
    id:"data",
    view:"dataview",
    ...
});

var str = "<data><item id='1'><title>The Lord of the Rings</title><year>2003</year></item>";
str += "<item id='2'><title>Star Wars: Episode V</title><year>1980</year></item></data>";

$$("data").parse(str,"xml");

Details

If you want to parse data in addition to the existing dataset, specify position of parsing, namely the index from which you insert new data:

$$("datatable").parse({
   pos: $$("datatable").count(), //number of records will be right the last index +1
   data:dataset
});

See also

  • api
    • data
    • datatype
    • load
  • samples
    • Dataview: JSON Dataset
    • Dataview: XML Dataset
  • articles
    • Loading Data into DataTable_inline_dataset


refresh

repaints the whole view or a certain item

void refresh( [id id] );

Parameters

id id the item id. If the parameter is set, just the specified item will be repainted

Example

$$("button1").define("label", "New value");
$$("button1").refresh();

See also

  • api
    • updateItem
  • articles
    • Getting/setting the cell value
    • Changing Properties of Components


refreshColumns

refreshes the structure of DataTable

void refreshColumns( [array config,boolean reset] );

Parameters

config | array | array with new configurations for the columns
reset | boolean | if true, shows columns hidden by user before (false by default)

Example

dtable.refreshColumns();

Details

When used without an argument, the method redraws currect grid structure.

You can use this method to refresh structure of datatable after modifying some properties of columns collection.

dtable.config.columns[2].id = "newPrice";
dtable.config.columns[2].width = 500;
dtable.refreshColumns();

Or, with new config provided, set a completely different columns.

var config = [
    {id:"col1", header:"First Name", width:150},
    {id:"col2", header:"Last Name", width:150}
];

dtable.refreshColumns(config);

See also

  • api
    • refresh
    • refreshHeaderContent
  • articles
    • Sizing and Resizing


refreshFilter

rebuilds list of options in select filter

void refreshFilter(id id);

Parameters

id id id of column, where filter need to be refreshed

Example

dtable.refreshFilter("price");

Details

When called without parameter - refreshes all filters

dtable.refreshFilter(); //all filters


refreshHeaderContent

refreshes the header row of DataTable

void refreshHeaderContent();

See also

  • api
    • refresh
    • refreshColumns
  • articles
    • Sizing and Resizing
    • Columns Configuration


registerFilter

registers a filter element

void registerFilter(HTMLElement node,object config,object obj);

Parameters

node | HTMLElement | the html node of the filter
config | object | the hash of settings
obj | object | the controller object

Example

grid.registerFilter(document.getElementById("myfilter"),
        { columnId:"title" },
        {
            getValue:function(node){
                return node.value;
            },
            setValue:function(node, value){
                node.value = value;
            }
        }
);

Details

In the above mentioned sample:

  • the input with 'myfilter' ID becomes filter for a datatable column with 'title' ID;
  • the getValue method of the newly created filter gets the value from its HTML node and sets it as filtering parameter.

See also

  • api
    • filter
    • filterByAll
    • getFilter
  • samples
    • Filtering by multiple criteria
  • articles
    • DataTable Filtering


remove

removes the specified item/items from datastore

void remove(string/number/array id);

Parameters

id string/number/array the item id or an array of items' ids

Example

$$("my_list").remove(1); //removes the item with ID=1
$$("my_list").remove($$("data").getSelectedId()); //removes the selected item

$$("my_list").remove([1,3,5]); // removes multiple items

See also

  • api
    • clearAll
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


removeCellCss

remove css class from the cell of datatable

void removeCellCss(string id,string name,string css_name);

Parameters

id | string | row id
name | string | column name
css_name | string | name of css class to remove

Example

$$("mytable").removeCellCss(152, "year", "some_style");

See also

  • api
    • addCellCss
    • addRowCss
    • removeRowCss
  • articles
    • Styling DataTable


removeRowCss

remove css class from the row

void removeRowCss(string id,string css_name);

Parameters

id | string | row id
css_name | string | name of css class to remove

Example

$$("mytable").removeRowCss(152, "some_style");

Details

Works as short alias for removeMark command

See also

  • api
    • addCellCss
    • removeCellCss
    • addRowCss
  • articles
    • Styling DataTable


removeSelectArea

removes a select area

void removeSelectArea(string area_name);

Parameters

area_name string optional, the name of the select area that should be removed

Example

$$("dtable").removeSelectArea();

Details

if the area_name parameter isn't passed, the method removes the last unnamed select area

See also

  • api
    • addSelectArea
    • getSelectArea
    • getAllSelectAreas
    • onAfterAreaRemove
    • onBeforeAreaRemove
  • articles
    • Area Selection in DataTable


removeSpan

removes a rowspan/colspan from the datatable

void removeSpan(string/number id,string column);

Parameters

id | string/number | row id that starts a colspan/rowspan
column | string | column id that starts a colspan/rowspan

Available only in PRO Edition

Example

grid.removeSpan(1, "country");
grid.refresh();

See also

  • api
    • addSpan
    • spans
    • getSpan
  • articles
    • Datatable Rowspans and Colspans


render

renders the specified item or the whole component

void render(id id,object data,string operation );

Parameters

id | id | the item id
data | object | the hash of data for the rendered item
operation | string | the type of the operation: 'update', 'add', 'delete', 'move'ype

Example

dtable.render();

Details

When no parameters are specified, the method renders the whole view.

Types of the operation:

  • update - replaces the existing HTML with the new one
  • add - place a new HTML at the required position
  • delete - removes the related HTML
  • move - simulates add-delete sequence

See also

  • api
    • refresh
  • samples
    • Customizing Pager Controls
  • articles
    • Changing Properties of Components


resize

adjusts the view to a new size

void resize();

Example

dtable = new webix.ui({
        view:"datatable",
        ...
})

dtable.define("width", 700);
dtable.resize();

Details

You may need to use this method if you want to change the width or height of the component.

$$('list1').config.width = 200;
$$('list1').config.height = 200;
$$('list1').resize();

If a component is placed into some layout - you need not to call resize for the parent layout, it will adjust automatically.

Performance tip

If you set sizes for multiple components,it makes sense to set sizes for all of them at first and only then call resize().

$$('list1').config.width = 200;
$$('list1').config.height = 200;

$$('list2').config.width = 600;
$$('list2').config.height = 400;

$$('list1').resize();
$$('list2').resize();

See also

  • api
    • adjust
  • samples
    • Dynamical adjusting to the parent container
  • articles
    • Sizing components
    • Sizing and Resizing


resizeSubView

adjusts the row's size to the size of a subview

void resizeSubView(string/number id);

Parameters

id string/number the id of the item

Example

$$("mydatatable").resizeSubView(id);


scrollTo

scrolls the view to the defined position

void scrollTo(number x,number y);

Parameters

x | number | the position of x-scroll
y | number | the position of y-scroll
Details

In case of dynamic loading: if the view is scrolled to the position at which the viewport isn't fully populated with data
- DataTable automatically generates a load request to the server.

See also

  • api
    • showItem
    • showItemByIndex
    • getScrollState
  • articles
    • Scroll Control
    • Sizing and Resizing


select

selects the specified element

void select(id row_id,boolean preserve);

Parameters

row_id | id | the row id
preserve | boolean | sets whether the previous selection should be saved
Details

Alternative syntax

The parameters of the method differ depending on the value the select parameter is set to.

The main description above relates to select: 'row'.

In case select:'cell'

dtable.select(row_id, column_id, preserve);
  • row_id - (string/int) the row id
  • column_id - (string/int) the column id
  • preserve - (bool) sets whether the previous selection should be saved

In case select:'column':

dtable.select(row_id, column_id, preserve);
  • column_id - (string/int) the column id
  • preserve - (bool) sets whether the previous selection should be saved

See also

  • api
    • selectRange
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


selectAll

selects all cells in the DataTable

void selectAll();

Example

dtable.selectAll();

See also

  • api
    • unselectAll


selectRange

selects the specified range of elements

void selectRange( row_id, end_row_id, [boolean preserve] );

Parameters

row_id |  | id the id of the first selected row in the selection range
end_row_id |  | id the id of the last selected row in the selection range
preserve | boolean | preserves the previously made selection (true by default)
Details

Alternative syntax

The parameters of the method differ depending on the value the select parameter is set to.

The main description above relates to select: 'row'.

In case select:'cell'

dtable.selectRange(row_id, column_id, end_row_id, end_column_id);
  • row_id - (string/int) the row id of the first selected cell in the selection range
  • column_id - (string/int) the column id of the first selected cell in the selection range
  • end_row_id - (string/int) the row id of the last selected cell in the selection range
  • end_column_id - (string/int) the column id of the last selected cell in the selection range

In case select:'column':

dtable.selectRange(column_id, end_column_id);
  • column_id - (string/int) the id of the first selected column in the selection range
  • end_column_id - (string/int) the id of the last selected column in the selection range

See also

  • api
    • select
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


setColumnWidth

sets the width of the specified column

void setColumnWidth(id id,number width);

Parameters

id | id | the column id
width | number | the width in pixels

Example

dtable.setColumnWidth("title", 300)

See also

  • articles
    • Columns Configuration
    • Sizing and Resizing


setRowHeight

sets the height of the specified row

void setRowHeight(id id,number height);

Parameters

id | id | the row id
height | number | the height in pixels

Example

dtable.setRowHeight("r1", 300);

See also

  • articles
    • Columns Configuration
    • Sizing and Resizing


setState

restores the specified state

void setState(object state);

Parameters

state object the state object

Example

webix.storage.local.put("state", grid.getState());
...

var state = webix.storage.local.get("state");
if (state)
    grid.setState(state);

See also

  • api
    • getState
  • samples
    • DataTable state object
    • (Re)Storing the state of the filtered table
  • articles
    • Saving and Restoring Component State


showCell

scrolls the table (if needed) to make the specified cell visible

void showCell(string row,string column);

Parameters

row | string | the row id
column | string | the column id

Example

dtable.showCell(15,"title");

See also

  • api
    • showItemByIndex,showItem


showColumn

shows the column which was previously hidden by method 'hidecolumn'

void showColumn(id id);

Parameters

id id the id of a column

Example

dtable.hideColumn("col1");
....
dtable.showColumn("col1");

See also

  • api
    • hideColumn
  • articles
    • Columns Configuration


showColumnBatch

shows or hides a group of columns

void showColumnBatch(string| number batch,boolean preserve );

Parameters

batch | string| number | batch name
preserve | boolean | hides batch; controls behaviour of other batches

Example

var grida = new webix.ui({
    view:"datatable",
    visibleBatch:1,
    columns:[
        { id:"id",  header:"#", css:"rank",  batch:2,   width:50},
        { id:"title", header:"Film title", fillspace:true },
        { id:"year",  batch:1,  header:"Released" , width:80},
        { id:"category", header:"Category", batch:1},
        { id:"votes", batch:3, header:"Votes",  width:100},
        { id:"rating", batch:3, header:"Rating", width:100},
        { id:"rank", batch:2, header:"Rank", css:"rank", width:50}
    ]
});

//show id, rank
grida.showColumnBatch(2);

//show votes, rating
grid.showColumnBatch(3;

Details

Preserve mode offers three possibilities:

  • not defined - the desired group is shown, other groups are hidden. Only one group is visible at a time;
  • true - the desired group is shown, other groups preserve their state (hidden or visible);
  • false - the desired group is hidden, other groups preserve their state (hidden or visible).

See also

  • samples
    • Column Batches
  • articles
    • Columns Configuration


showItem

'scrolls' the table to make the specified row visible

void showItem(id id);

Parameters

id id the row id

Example

dtable.showItem(123)

See also

  • api
    • showItemByIndex
    • scrollTo
    • getScrollState


showItemByIndex

'scrolls' the table to make the specified row visible

void showItemByIndex(number index);

Parameters

index number the row index (zero-based numbering)

Example

dtable.showItemByIndex(4);

See also

  • api
    • showItem
    • scrollTo
    • getScrollState


showOverlay

shows the overlay message over the body of DataTable

void showOverlay(string message);

Parameters

message string the text or html string which will be shown as the overlay message

Example

view:"datatable",
on:{
        onBeforeLoad:function(){
            this.showOverlay("Loading...");
        }
}

Details

Good for "Loading" and "No data" notifications.

Can be styled with the help of the webix_datatable_overlay css class

See also

  • api
    • hideOverlay
  • samples
    • Loading screen
    • Adding overlay text
  • articles
    • Data Loading


sort

sorts rows in DataTable

void sort(string by, [string dir,string as] );

Parameters

by | string | the name(s) of property(s) by which data will be sorted
dir | string | the sorting direction, default is "asc"
as | string | the type of data , default is "string"

Example

data.sort("price", "asc");

Details

Usage examples

The method sort can be used with different count of parameters.

The most common use case of the sort method is using the first parameter as the name of a property:

//sorts by name value; ascedent; sorted values as strings
data.sort("#name#","asc","string");
//sorts by price value; descedant; sorted values as numbers
data.sort("#price#","desc","int");

The property name should be included into sharps.

Instead of default sorting types, you can use your own method ( can be used for complex data types ):

function sort_by_length(data1, data2){
    return data1.length>data2.length ? 1:-1;
}

data.sort("#name#","asc",sort_by_length);

Possible return values of this function are 0,1,-1.

  • 1 means that the first object is greater than the second object;
  • -1 means that the first object is less than the second object;
  • 0 means that 2 objects are equal.

If you need to access multiple properties of an object during sorting or you need to have some complex sorting logic, use a function as the first parameter.

function my_sorting(a,b){
    //a, b - data objects
    return a.Version > b.Version ? 1 : -1;
}
data.sort(my_sorting, "des"); //3rd parameter will be ignored

Alternative syntax

You can use a hash of sorting settings as the first parameter of the sort method:

data.sort({
    as:"string",
    dir:"desc",
    by:"#Package#"
});

Sorting directions

Possible values for the second parameter of the sort method is string which represents sorting direction:

  • "asc" - for ascending sorting
  • "desc" - for decrescent sorting

Sorting types

The third parameter of the sort method may be string which represents the data type:

  • "int" - sorts as interger values
  • "string" - sorts as string
  • "string_strict" - sorts as string, case-sensitive

See also

  • api
    • markSorting
  • samples
    • Sorting Datatable. Using sorting methods
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree


unblockEvent

cancels blocking events that was enabled by the 'blockEvent' command

void unblockEvent();

Example

$$('mylist').blockEvent();
$$('mylist').add({ text:'abc'}); //will not trigger any events
$$('mylist').unblockEvent();

See also

  • api
    • blockEvent
  • articles
    • Events Handling with DataTable


unselect

cancels selection of the specified element

void unselect(id row_id);

Parameters

row_id id the id of the row which should be unselected
Details

Alternative syntax

The parameters of the method differ depending on the value the select parameter is set to.

The main description above relates to select: 'row'.

In case select:'cell'

dtable.unselect(row_id, column_id);
  • row_id - (string/int) the row id of the cell which should be unselected
  • column_id - (string/int) the column id of the cell which should be unselected

In case select:'column':

dtable.unselect(column_id);
  • column_id - (string/int) the id of the column which should be unselected

See also

  • api
    • select
    • selectRange
    • getSelectedId
    • mapSelection
    • clearSelection
  • articles
    • Selection with Datatable


unselectAll

unselects all selected cells in a datatble

void unselectAll();

Example

dtable.unselectAll();

See also

  • api
    • selectAll


updateItem

sets properties of the data item

void updateItem(id id,object data);

Parameters

id | id | the item id
data | object | the hash of properties

Example

var sel = dtable.getSelectedId();
var row = dtable.getItem(sel.row);
row[sel.column] = "some_new_value";

dtable.updateItem(sel.row, row);

See also

  • api
    • refresh
    • edit
  • samples
    • Server-side Integration: Datatable
  • articles
    • Getting/setting the cell value
    • Data Updating


validate

validates one record or all dataset against validation rules

boolean validate( [string id] );

Parameters

id string id of record to validate

Returns

boolean true if record is valid

Example

mygrid = webix.ui({
    view:"list",
    ...
    rules:{
        "text":webix.rules.isNotEmpty
    }
});

/*validate all records*/
var result = mygrid.validate();

/*validate first record*/
var result = mygrid.validate( mygrid.getFirstId() );

Details

If id was not provided - component will validate all records.

Methods uses config.rules for validation

Invalid rows has "webix_invalid" marker on them

See also

  • api
    • clearValidation
    • addCellCss
    • removeCellCss
    • addRowCss
    • removeRowCss
  • samples
    • Datatable Validation
    • Datatable Validation. Complex Rule.
    • Validation with per Cell Marking
  • articles
    • Data Validation


validateEditor

validates data in currently active editor

boolean validateEditor( [id id] );

Parameters

id id id of editor

Returns

boolean true if text in editor confirms to validation rules

Example

var grid = webix.ui({
    view:"datatable",
    rules:{
       price:function(obj){ return obj>0; }
    }
    ...
})
...
grid.validateEditor();

Details

If id not provided - uses last opened editor


Properties

animate | defines or disables view change animation.
areaselect | enables/disables area selection
autoConfig | datatable adjust configuration to the data
autoheight | adjusts Datatable size to the its content vertically
autowidth | adjusts Datatable size to its content horizontally
blockselect | enables/disables block selection
borderless | used to hide the component borders
checkboxRefresh | controls behavior of checkbox editors in grid
clipboard | enables/disables clipboard support
columnWidth | defines the default width for columns (in pixels)
columns | configures columns of the table
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datafetch | defines the number of records that will be loaded into datatable during the next dynamic loading call
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
delimiter | sets CSV delimiters for clipboard operations
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragColumn | enables drag-and-drop support for columns
dragscroll | enables autoscroll of component during drag-n-drop
editMath | enables formular editing
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
externalData | allows defining custom 'move' logic for the component.
filterMode | defines filtering rules in tree-like components
fixedRowHeight | defines whether the height should be fixed for all rows or can vary
footer | enables/disables the footer in DataTable (disabled, by default)
form | linked form
gravity | sets the view gravity (1 by default)
header | enables/disables the header in DataTable (enabled, by default)
headerRowHeight | sets the heigth of the header row
headermenu | adds a headermenu to control column visibility
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hover | css class for a row-hover in the datatable
id | the component ID
leftSplit | the number of the fixed columns from the left side of the table (actual for the split mode )
liveValidation | validation during cell editing
loadahead | sets the number of items that will be loaded on each scroll movement relative to the last item in the scrolling direction
map | defines data mapping
math | enables math formulas in DataTable
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minColumnHeight | sets the minimum height for a row
minColumnWidth | sets the minimum width for a column
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables the multi selection mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
prerender | invokes the full rendering of DataTable data
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
resizeColumn | enables/disables horizontal resizing of columns
resizeRow | enables/disables vertical resizing of rows
rightSplit | sets the number of the fixed columns from the right side of the table (actual for the split mode )
rowHeight | sets the default height for rows
rowLineHeight | default line height for grid's row
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables or disables scroll for the datatable
scrollAlignY | enables/disables scrolling the table just by whole rows (i.e. you won't be allowed to scroll along the full length of rows)
scrollX | enables/disables horizontal scrolling
scrollY | enables/disables vertical scrolling
select | sets the selection mode in DataTable
spans | array of span configurations for the datatable
subRowHeight | automatically adjusts the subrow's height to the size of the text
subrow | sets a subrow template
subview | adds a subview configuration into datatable
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | used for configuring presentation of items
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
yCount | defines height of datatable in rows


areaselect

enables/disables area selection

boolean areaselect;

Example

webix.ui({
    view:"datatable",
    columns:[...],
    areaselect:true
}}

See also

  • samples
    • Area Selection
  • articles
    • Area Selection in DataTable


autoConfig

datatable adjust configuration to the data

boolean autoConfig;

Example

webix.ui({
  view:"datatable",
  autoConfig:true,
  url:"data.php"
});

Details

Configuration of columns will be based on data ( columns will be created for each properties of first object in collection )
Headers of columns are based on property names in dataset


autoheight

adjusts Datatable size to the its content vertically

boolean autoheight;

Example

webix.ui({
    view:"datatable",
    autoheight:true,
    ...
});

See also

  • api
    • autowidth
  • samples
    • Height and width autosizing
  • articles
    • Sizing and Resizing
    • Details

    If a Datatable features 10 rows, the resulting height will be datatable.config.rowHeight*10 plus borders.


autowidth

adjusts Datatable size to its content horizontally

boolean autowidth;

Example

webix.ui({
    view:"datatable",
    autowidth:true,
    ...
});

See also

  • api
    • autoheight
  • samples
    • Height and width autosizing
  • articles
    • Sizing and Resizing
    • Details

    If a Datatable features 5 columns with 100px width each, the resulting width will be 500px plus borders.

    To adjust a component to the size of a parent container omit this property.

    To stretch the Datatable columns within the container, you need to set fillspace to at least one of its columns.

    columns:[
    { id:"title", header:"Title", fillspace:true }
]


blockselect

enables/disables block selection

boolean| string blockselect;

Values

  • true
    overlay box is placed over the grid while dragging to mark potentially selected area
  • box
    overlay box is placed over the potentially selected items while dragging
  • select
    native datatable selection with select related events firing on each cell selection
  • false
    disables block selection

    • Example

    webix.ui({
    view:"datatable",
    blockselect:"box",
    ...
});

    See also

  • api
    • multiselect
    • select
  • samples
    • Row selection
    • Multi-cell selection
    • Block selection
  • articles
    • Selection with Datatable


checkboxRefresh

controls behavior of checkbox editors in grid

boolean checkboxRefresh;

Example

webix.ui({
    view:"datatable",
    checkboxRefresh:true
});

See also

  • api
    • refresh
  • samples
    • Custom radio and checkbox in DataTable
  • articles
    • Changing Properties of Components
    • Details

    If set to true, then after checkbox state changing, row will be repainted.


clipboard

enables/disables clipboard support

boolean|string clipboard;

Values

  • block (true)
  • selection
  • repeat
  • false

    • Example

    webix.ui({
    view:"datatable",
    clipboard:true,
    ...
});

    See also

  • samples
    • Cell copying
    • Copying between grids
  • articles
    • Copy-Pasting DataTable Data


columnWidth

defines the default width for columns (in pixels)

number columnWidth;

Example

webix.ui({
    view:"datatable",
    columnWidth:150,
    ...
});

See also

  • articles
    • Columns Configuration
    • Details

    The default value of the parameter is 100px.


columns

configures columns of the table

array columns;

Example

webix.ui({
    view:"datatable",
    ...
    columns:[
        { id:"rank",    header:{ text:"#", rowspan:2}, width:50, css:"rank"},
        { id:"title",   header:["Film title", {text:"Second line", colspan:3}]},
        { id:"year",    header:["Year",""], width:80},
        { id:"votes",   header:["Votes",""], width:100}
    ]
});

See also

  • samples
    • Multiline header
    • Using number templates
    • Setting the default scheme for data
  • articles
    • Columns Configuration
    • Details

    Each object in the array specifies a single column. An object can take the following attributes:

    adjust (boolean, string) adjusts the width of the column to fit the related content size.
    The following values are possible:
    • "data" - adjusts column width to the content of the widest item in it
    • "header" - adjusts column width to its header content
    • true - searches for the widest item among data and header(s) and adjusts column width to its content
    css | (string) the name of a css class that will be applied to the column
    cssFormat (function) sets a function that takes a data property value as a parameter and returns object with css properties ( or the name of a css class) that will be applied to a cell with the related value.
    The parameters are as follows:
    • cell value
    • row item object( all values for the current row )
    • row id
    • column id
    editor (string) the type of the column editors. The attribute can take only one of a predefined set of values.
    The predefined values are:
    • "text" - a single line text editor
    • "inline-text" - a custom text editor
    • "select" - a dropdown list
    • and 9 more
    editAction (string) the type of an action that would open datatable cell for editing.
    The predefined values are:
    • "click" - (default) a single mouse click
    • "dblclick" - a double mouse click
    • "custom" - allows adding any custom action to open the cell (descibed separately)
    liveEdit | (bool) sets on-the-go updating for the same data property used in different columns and edited in one of them
    fillspace (boolean, number) forces the column to widen for filling the unused table space.

    In case of numeric values other than 1 the columns will distribute the available space proportionally according to the numbers.
    format | (function) the format of data presentation
    footer (string, array) specifies the footer of the column. As an array, the footer can contain both string and object values.

    Object values can have the following attributes:
    • text - (string) the text label of the column footer
    • content - ('textFilter', 'selectFilter' or 'summColumn') the built-in filter or counter
    • colspan - (number) the number of rows a cell should span
    • rowspan - (number) the number of columns a cell should span
    header (string, array) specifies the header of the column. As an array, the header can contain both string and object values.

    Object values can have the following attributes:
    • text - (string) the text label of the column
    • content - ('textFilter', 'selectFilter' or 'summColumn') the built-in filter or counter
    • colspan - (number) the number of rows a cell should span
    • rowspan - (number) the number of columns a cell should span
    id | (string) the id of the column
    math | (string) the math formula that applies to all cells of the column
    sort (string, function) enables sorting for the column (triggered by a single click on the header) and assigns one of predefined sorting types or the name of a sorting function.

    As a string the attribute can take only one of a predefined set of values.
    The predefined values are:
    • "int"
    • "date"
    • "string"
    • "string_strict" (case-sensitive 'string')
    template | (string, function) the data template
    width | (number) the width of the column


container

an html container (or its id) where the component needs initializing

HTMLElement container;

Example

webix.ui({
    container:"view_box",
    view:"datatable",
    ...
})

See also

  • samples
    • Loading from inline datasource
  • articles
    • Start Coding with Webix
    • View


css

the name of a css class that will be applied to the view container

string css;

Example

webix.ui({
    view:"datatable",
    css:"myclass",
    ...
});

See also

  • samples
    • Basic styling
  • articles
    • Styling DataTable
    • Details

    Setting the parameter, for example, to the "myClass" value will produce HTML like this:

    <div class='myClass'>...</div>


data

JavaScript array containing data for the component

string|array data;

Example

var books = [
    [ "War and Peace", "Leo Tolstoy" ],
    [ "Hamlet", "Shakespeare" ],
    [ "Madame Bovary", "Gustave Flaubert" ]
];

webix.ui({
    view: "list",
    data: books,
    datatype: "jsarray",
    template: "#data0# (#data1#)"
});

See also

  • api
    • datatype
    • url
    • parse
    • load
  • samples
    • Loading from inline datasource
  • articles
    • Loading Data into DataTable
    • Details

    For data types other than JSON the property is used in conjunction with the datatype parameter.


datafetch

defines the number of records that will be loaded into datatable during the next dynamic loading call

number datafetch;

Example

webix.ui({
    view:"datatable",
    columns:[],
    datafetch:30,
    ..
});

See also

  • api
    • datathrottle
    • loadahead
  • samples
    • Dynamic loading. Load Ahead
  • articles
    • Loading Data into DataTable
    • Dynamic Loading
    • Details

    The value defaults to 50.


datathrottle

sets the polling interval (the time period between the completion of a network request and the next request for data)

number datathrottle;

Example

new webix.ui({
    view:"datatable",
    ...
    datathrottle:500
});

See also

  • api
    • datafetch
    • loadahead
  • samples
    • Setting polling interval
  • articles
    • Loading Data into DataTable
    • Details
    • The option is used during dynamical loading and allows you to skip unnecessary data requests during fast scrolling the dataset.
    • If a new request for data will be received during the waiting period, the timer will be reset and original loading command will be ignored.


delimiter

sets CSV delimiters for clipboard operations

object delimiter;

Example

webix.ui({
    view:"datatable",
    delimiter:{
        rows:"\n", // the rows delimiter
        cols:","   // the columns delimiter
    },
    ...
});

See also

  • articles
    • Copy-Pasting DataTable Data
    • Details
    • The default rows delimiter - '\n' (new-line character)
    • The default columns delimiter - '\t' (horizontal tab )

    You can change delimiters globally by setting webix.csv.delimiter.rows and webix.csv.delimiter.cols properties.

    webix.csv.delimiter.rows = "\b";
webix.csv.delimiter.cols = "\v";


drag

enables or disables drag-and-drop

boolean|string drag;

Values

  • true
    enables DnD within the component, allows taking items into its other instances and different components on the page;
  • order
    enables DnD in the reorder mode, allows dragging component item within one component thus changing their order;
  • source
    enables dragging items from the component without an ability to drop data from other components;
  • target
    enables dropping data to the component. It can take data from outside, but you cannot drag anything from it;
  • false
    disables DnD within the component.

    • Example

    webix.ui({
        view:"datatable",
        ...
        drag:true
});

    See also

  • api
    • dragColumn
  • samples
    • Drag-and-Drop between tables in DataTable
    • Enabling Drag-and-drop in Tree
    • DnD with List Items
  • articles
    • Drag-and-drop with Datatable


dragColumn

enables drag-and-drop support for columns

boolean|string dragColumn;

Values

  • true
    columns can be dragged
  • false
    columns cannot be gragged
  • order
    columns can be dragged within one datatable only

    • Example

    webix.ui({
    view:"datatable",
    ...
    dragColumn:true
});

    See also

  • api
    • drag
  • samples
    • Drag-and-Drop support for columns
  • articles
    • Drag-and-drop with Datatable
    • Details

    The property allows you to set the mode when users will drag columns instead of rows.

    As a string the parameter can take only one value:

    • 'order'

    With such a value set, items can't be dragged out of the calling object boundaries. Also, while dragging an item the remaining items are automatically rearranged so that when you drop the item to the final destination the remaining items won't need to do any rearrangements.


editMath

enables formular editing

boolean editMath;

Example

webix.ui({
    view:"datatable",
    editable:true,
    editaction:"click",
    editMath:true
});


editValue

defines which data item is editable (in case of several data item in the cell/line)

string editValue;

Example

webix.ui({
    view:"list",
    template:"#id#.#name#",
    editable:true,
    editValue:"name",
    ...
});

See also

  • samples
    • Editing on Mouse Click
  • articles
    • Editing Data Items
    • Data Editors
    • Details

    Editvalue is defined for components containing more than one data item in its cell or record.

    In the list above each record contains item ID and name, but only name is editable.


editable

allows/denies editing in the table

boolean editable;

Example

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • editaction
  • samples
    • Basic use of editors
  • articles
    • DataTable Editing
    • Editing Data Items
    • Details

    To allow only programmatic editing, set the editaction parameter to the none value.

    webix.ui({
    view:"datatable",
    editable:true,
    editaction:"none"
    ...
});


editaction

defines the action on which editors will be opened

string editaction;

Values

  • click
    (default) opens the editor on a single click
  • dblclick
    opens the editor on a double click
  • custom
    allows only programmatic editing (denies opening editors for manual editing)

    • Example

    webix.ui({
    view:"datatable",
    editable:true,
    editaction:"dblclick"
    ...
});

    See also

  • api
    • editable
  • samples
    • Basic use of editors
    • Opening multiple editors
  • articles
    • Editing Data Items


filterMode

defines filtering rules in tree-like components

object filterMode;

Example

$$("grouplist").define("filterMode",{
   level:0,
   showSubItems:1
});

$$("grouplist").define("filterMode",{
   level:1
});

See also

  • api
    • filter
  • samples
    • Filtering in TreeTable
    • Custom filters in TreeTable
  • articles
    • DataTable Filtering
    • Filtering in the Tree
    • Details

    Applicable just to Grouplist, TreeTable

    An input object can take 3 attributes:

    • level - (number) sets the node to filter (one-based numbering). The '0' value says to filter all nodes
    • openParents - (bool) defines whether the tree will expand branches to show the found items (true) or stay as is (false). The default value - true
    • showSubItems - (bool) defines whether the component should display childs of the filtered items


fixedRowHeight

defines whether the height should be fixed for all rows or can vary

boolean fixedRowHeight;

Example

webix.ui({
    view:"datatable",
    fixedRowHeight:false,
    data:[
      {id:1, name:"Row with default height" }
      {id:1, name:"Row with custom height", $height:200 }
    ]
});

See also

  • api
    • headerRowHeight
    • height
  • samples
    • Autosizing custom rows
  • articles
    • Sizing and Resizing
    • Columns Configuration
    • Details

    The default value of the parameter is true - the height of rows is fixed.

    When the parameter is set to false, each row can have the $height property to define a custom height.


footer

enables/disables the footer in DataTable (disabled, by default)

boolean footer;

Example

webix.ui({
    view:"datatable",
    footer:true,
    ...
});

See also

  • api
    • header
  • samples
    • Standard header(footer) implementation
  • articles
    • Headers and Footers


form

linked form

string form;

Example

webix.ui({
  view:"popup", id:"popupform",
  body:{ view:"form", elements:[ /*...*/ ]}
});

webix.ui({
  view:"datatable", editable:true, form:"popupform"
});

See also

  • articles
    • Editing Data Items
    • Data Editors
    • Details

    ID of linked form, which will be used for edit operations


header

enables/disables the header in DataTable (enabled, by default)

boolean header;

Example

webix.ui({
    view:"datatable",
    header:false,
    ...
});

See also

  • api
    • footer
  • samples
    • Standard header(footer) implementation
  • articles
    • Headers and Footers


headerRowHeight

sets the heigth of the header row

number headerRowHeight;

Example

webix.ui({
    view:"datatable",
    headerRowHeight:40,
    ...
});

See also

  • api
    • fixedRowHeight
    • height
  • articles
    • Sizing and Resizing
    • Columns Configuration


headermenu

adds a headermenu to control column visibility

boolean| object headermenu;

Available only in PRO Edition

Example

//simple config
webix.ui({
    view:"datatable",
    headermenu:true
});

//complex config
webix.ui({
    view:"datatable",
    headermenu:{
        width:250,
        autoheight:false,
        scroll:true
    }
});

See also

  • samples
    • Header menu in the DataTable
    • Extended Header menu in the DataTable
  • articles
    • Datatable Header Menu
    • Details

    The whole list of parameters that help configure the header menu can be found in the related article.


height

sets the height of the component

number height;

Example

webix.ui ({
    view:"window",
    height:300,
    width:300,
    ...
});

See also

  • api
    • width
    • headerRowHeight
    • fixedRowHeight
  • samples
    • Sizing through the 'width', 'height' parameters
  • articles
    • Sizing and Resizing
    • Columns Configuration


hover

css class for a row-hover in the datatable

string hover;

Example

<style type="text/css">
    .myhover{
        background: #F0DCB6;
    }
</style>

webix.ui({
    view:"datatable",
    hover:"myhover"
});


leftSplit

the number of the fixed columns from the left side of the table (actual for the split mode )

number leftSplit;

Example

webix.ui({
    view:"datatable",
    leftSplit:2,
    ...
});

See also

  • api
    • rightSplit
  • samples
    • Frozen columns. Basic implementation
  • articles
    • Split Mode or 'Frozen Columns'


liveValidation

validation during cell editing

boolean liveValidation;

Example

webix.ui({
    view:"datatable",
    rules:{
       price:function(obj){ return obj>0; }
    },
    liveValidation:true,
    ...
})

Details

If enabled, validation will run during text typing in editor


loadahead

sets the number of items that will be loaded on each scroll movement relative to the last item in the scrolling direction

number loadahead;

Example

webix.ui({
    view:"datatable",
    loadahead:100,
});

See also

  • api
    • datafetch
    • datathrottle
  • samples
    • Dynamic loading. Load Ahead
  • articles
    • Loading Data into DataTable
    • Dynamic Loading for Plain Structures


map

defines data mapping

object map;

Example

webix.ui({
    view:"datatable",
    map:{
        name:"#firstname# #lastname#",
        birth:"(date)#birthdate#"
    },
    columns:[
        { id:"name", header:"User name" },
        { id:"birth", header:"Date of birth"}
    ],
    data:[
        { id:1, firstname:"Adam", lastname:"Smith", birthdate:new Date(1985, 1, 1) },
        { id:2, firstname:"Tom", lastname:"Brown", birthdate:new Date(1986, 2, 2) },
    ]
});

Details

For details, check Data Mapping


math

enables math formulas in DataTable

boolean math;

Example

webix.ui({
    view:"datatable",
    math:true,
    ...
});

See also

  • samples
    • Using formulas
    • Applying formulas to an entire column
  • articles
    • Math Operations


minColumnHeight

sets the minimum height for a row

number minColumnHeight;

Example

webix.ui({
    view:"datatable",
    minColumnHeight:40,
    ...
});

See also

  • api
    • minColumnWidth
  • articles
    • Sizing and Resizing
    • Columns Configuration
    • Details

    By default, the parameter is 26px.
    Affects while row resizing only. If you need to set the default row height you need to use the rowHeight parameter.


minColumnWidth

sets the minimum width for a column

number minColumnWidth;

Example

webix.ui({
    view:"datatable",
    minColumnWidth:40,
    ...
});

See also

  • api
    • minColumnHeight
  • articles
    • Sizing and Resizing
    • Columns Configuration
    • Details

    By default, the parameter is 20px.


multiselect

enables the multi selection mode

boolean multiselect;

Example

webix.ui({
    view:"datatable",
    select:"cell",
    multiselect:true,
    ...
});

See also

  • api
    • select
    • blockselect
  • samples
    • Multi-cell selection
    • Multi-row selection
    • Multi-column selection
  • articles
    • Selection with Datatable


on

allows attaching custom handlers to inner events of the component

object on;

Example

webix.ui({
         view:"datatable",
         ...
         on:{'onItemClick': function(){alert("you have clicked an item");}}
});

See also

  • api
    • attachEvent
    • detachEvent
    • hasEvent
  • samples
    • Datatable: Custom Handler
    • Block selection
  • articles
    • Events Handling with DataTable
    • Details

    All keys defined in the object will be processed as the names of events, and their values as the related handlers.

    The property can be used as an alternative to the attachEvent method.


pager

defines paging configuration ( creates a 'ui.pager' object)

string| object pager;

Example

webix.ui({
    view:"datatable",
    pager:{
        container:"paging_here",
        size:100,
        group:5
    }
})

See also

  • api
    • getPage
    • setPage
    • getPager
  • samples
    • Static paging. Loading from DB
    • Defining several pagers on a page
    • Pager localization
  • articles
    • Paging with Datatable
    • Details

    The parameter has the following attributes:

    • container - the container where the pager controls will be placed into;
    • size - the number of records per page;
    • group - the number of pages in the pager.


prerender

invokes the full rendering of DataTable data

boolean prerender;

Example

webix.ui({
    view:"datatable",
    prerender:true,
    ...
});

See also

  • api
    • render
  • articles
    • Integration
    • Details
    • The parameter doesn't give advantages for non-touch devices (slower than with a standard data loading).
    • On touch devices it allows you to get a bit more smooth scrolling (anyway, it's not usable with big datasets)
    • Not related to dynamical loading.


resizeColumn

enables/disables horizontal resizing of columns

boolean resizeColumn;

Example

webix.ui({
    view:"datatable",
    resizeColumn:true,
    ...
});

See also

  • api
    • resizeRow
  • articles
    • Columns Configuration
    • Details

    By default, the parameter is disabled.

    When enabled, the method doesn't actually resize the datatable. After page refresh, size returns to the initial one (provided that you haven't saved the table's state).


resizeRow

enables/disables vertical resizing of rows

boolean resizeRow;

Example

webix.ui({
    view:"datatable",
    resizeRow:true,
    ...
});

See also

  • api
    • resizeColumn
  • articles
    • Columns Configuration
    • Details

    By default, the parameter is disabled.

    When enabled, the method doesn't actually resize the datatable. After page refresh, size returns to the initial one (provided that you haven't saved the table's state).


rightSplit

sets the number of the fixed columns from the right side of the table (actual for the split mode )

number rightSplit;

Example

webix.ui({
    view:"datatable",
    rightSplit:2,
    ...
});

See also

  • api
    • leftSplit
  • samples
    • Frozen columns. Basic implementation
  • articles
    • Split Mode or 'Frozen Columns'


rowHeight

sets the default height for rows

number rowHeight;

Example

webix.ui({
    view:"datatable",
    rowHeight:40,
    ...
});

See also

  • api
    • headerRowHeight
    • fixedRowHeight
    • height
  • articles
    • Sizing and Resizing
    • Columns Configuration


rowLineHeight

default line height for grid's row

number rowLineHeight;

Example

webix.ui({
    view:"datatable",
    rowLineHeight:25
});

See also

  • api
    • headerRowHeight
    • fixedRowHeight
    • height
  • articles
    • Sizing and Resizing
    • Columns Configuration


rules

set of validation rules for the component

object rules;

Example

webix.ui({
    view:"datatable",
    rules:{
        "year": webix.rules.isNotEmpty,
        "value": function(value){ return value > 0 }
    }
})

See also

  • api
    • validate
    • rules
  • samples
    • Datatable Validation
    • Datatable Validation. Complex Rule.
  • articles
    • Data Validation
    • Details

    You will not be able to save data to server side if it doesn't conform to validation rules.


scheme

defines schemes for data processing

object scheme;

Example

dtable.data.scheme({
    name:"Default name",
    age:16
});
dtable.add();//will add {name:"Default name", age:16} record

See also

  • api
    • add
  • samples
    • Converting strings to dates
  • articles
    • Defining Data Scheme
    • Cells Templates


scroll

enables or disables scroll for the datatable

booleanboolean|string scroll;

Values

  • y (true)
    enables vertical scroll (the default value)
  • x
    enables horizontal scroll
  • xy
    enables both scrolls
  • false
    disables both scrolls

    • Example

    webix.ui({
    view:"datatable",
    scroll:false
});

    See also

  • api
    • scrollX
    • scrollY
    • scrollAlignY
  • articles
    • Scroll Control
    • Sizing and Resizing
    • Details

    Enabled by default


scrollAlignY

enables/disables scrolling the table just by whole rows (i.e. you won't be allowed to scroll along the full length of rows)

boolean scrollAlignY;

Example

webix.ui({
    view:"datatable",
    scrollAlignY:false,
    ...
});

See also

  • api
    • scrollX
    • scrollY
    • scroll
  • samples
    • Scrolling alignment
  • articles
    • Sizing and Resizing
    • Scroll Control
    • Details

    By default, the parameter is enabled.


scrollX

enables/disables horizontal scrolling

boolean scrollX;

Example

webix.ui({
    view:"datatable",
    scrollX:false,
    ...
})

See also

  • api
    • scrollY
    • scrollAlignY
    • scroll
  • samples
    • Different scrolling behaviours
    • Adjusting columns to the parent container
  • articles
    • Sizing and Resizing
    • Scroll Control
    • Details

    By default, horizontal scrolling is enabled. It will be disabled automatically, if you set the autowidth parameter to true.


scrollY

enables/disables vertical scrolling

boolean scrollY;

Example

webix.ui({
    view:"datatable",
    scrollY:false,
    ...
})

See also

  • api
    • scrollX
    • scrollAlignY
    • scroll
  • samples
    • Different scrolling behaviours
  • articles
    • Sizing and Resizing
    • Scroll Control
    • Details

    By default, vertical scrolling is enabled. It will be disabled automatically, if you set the autoheight parameter to true.


select

sets the selection mode in DataTable

boolean|string select;

Values

  • cell
    sets the cell selection
  • row
    sets the row selection
  • column
    sets the column selection
  • true
    sets the row selection
  • false
    disables selection

    • Example

    webix.ui({
    view:"datatable",
    select:"cell",
    ...
})

    See also

  • api
    • multiselect
    • blockselect
  • samples
    • Row selection
    • Multi-cell selection
    • Block selection
  • articles
    • Selection with Datatable
    • Details

    Multiselection can be enabled the following way:

    webix.ui({
    view:"datatable",
    multiselect:true,
    ..//config
});


spans

array of span configurations for the datatable

array spans;

Available only in PRO Edition

Example

webix.ui({
    view:"datatable",
    data:{
       data:grid data,
       spans:[
            [1, "country", 1, 3],
            [4, "country", 1, 2]
       ]
    }
});

See also

  • api
    • addSpan
  • samples
    • Colspans in the DataTable
  • articles
    • Data Loading
    • Datatable Rowspans and Colspans
    • Details

    The parameter is used within the component's data that is presenTed as an object with two properties:

    • data or url - component data, inline of serverside (file);
    • spans - an array of span configurations, each of which includes:
      • id (number, string, object) - id of the row that starts colspan/rowspan;
      • column (string) - id of the column that starts colspan/rowspan;
      • width (number) - how many columns should the span include;
      • height (number) - how many rows should the span include;
      • value (string) - value that the span area should display;
      • css (string) - css class that should be applied to the span area.


subRowHeight

automatically adjusts the subrow's height to the size of the text

string subRowHeight;

Example

webix.ui({
    view:"datatable",
    subRowHeight:"auto"
    ...
});

See also

  • samples
    • SubRows in DataTable - Size to Data
  • articles
    • Adding Subrows


subrow

sets a subrow template

string subrow;

Example

webix.ui({
    view:"datatable",
    subrow:"Rating: #rating#"
    ...
});

See also

  • api
    • subview
  • samples
    • SubRows in DataTable
  • articles
    • Adding Subrows


subview

adds a subview configuration into datatable

subview;

Example

webix.ui({
    view:"datatable",
    subview:{
        view:"form",
        elements:[
            ...
        ]
    }
})

See also

  • api
    • subrow
  • samples
    • Sub-Grid in a DataTable
    • Sub-Form in a DataTable
  • articles
    • Adding Subviews


tooltip

sets a popup message appearing on pointing a mouse cursor over the dedicated item.

boolean tooltip;

Example

grid = new webix.ui({
    container:"testA",
    view:"datatable",
    columns:[
        { id:"rank",  tooltip:false, width:50, header:"", css:"rank" },
        { id:"title", tooltip:"Title: #title#<br>Rating: #rating#", width:200, header:"Film title" },
        { id:"year",    header:"Year"},
        { id:"votes",   header:"Votes"}
    ],
    tooltip:true,
    autoheight:true,
    autowidth:true,

    data:small_film_set
});

See also

  • samples
    • Tooltips
  • articles
    • Tooltip Implementation
    • Data Templates
    • Details

    Content of tooltip will be defined by tooltip property from column configuration. If column has not tooltip property - content of column will be shown in a tooltip.


type

used for configuring presentation of items

object type;

Example

//colors titles of odd rows in red, even - in green
grid = new webix.ui({
        view:"datatable",
        id:"table1",
        type:{
            title_color:function(obj,type){
                 var odd = $$("table1").getIndexById(obj.id)%2
                 return odd?"red":"green"
            }
        },
        columns:[{ id:"title", header:"Film title",
                template:"<span style='color:{common.title_color()}'>#title#</span>"}],
        ...
});

See also

  • articles
    • Type Implementation
    • Details

    The parameter is intended for defining functions which then can be used while setting the template for a column.

    In the template the defined function can be accessed through {common.[func_name]}.

    grid = new webix.ui({
    container:"testA",
    view:"datatable",
    id:"table1",
    type:{
           title_color:function(obj,type){
                 var odd = $$("table1").getIndexById(obj.id)%2
                 return odd?"red":"green"
           },
           votes_color:function(obj,type){
                        return  (obj.votes > 350000?"green":"red")
           }
    },
    columns:[
           { id:"title", header:"Film title",
           template:"<span style='color:{common.title_color()}'>#title#</span>"},
           { id:"votes", header:"Votes",
           template:function(obj,type){return "<span style='color:"+type.votes_color(obj)+
           "'>"+obj.votes+"</span>"}}
    ]
});


url

the URL which the component will use to load data after its initialization

string url;

Example

webix.ui({
  datatype: "xml",
    url: "data.xml"
    ...
});

See also

  • api
    • load
    • parse
    • data
    • datatype
  • samples
    • Loading from an external data file
    • Loading from DB
  • articles
    • Loading Data into DataTable
    • Details

    Used in conjunction with the datatype parameter. If datatype isn't provided, the component will expect data in JSON format.


width

sets the width of the component

number width;

Example

webix.ui ({
         view:"datatable",
         height:300,
         width:300,
     ...
})

See also

  • api
    • height
  • samples
    • Sizing through the 'width', 'height' parameters
  • articles
    • Sizing and Resizing


yCount

defines height of datatable in rows

number yCount;

Example

//grid will height enough to show 20 rows of data
webix.ui({
   view:"datatable",
   yCount:20
});

See also

  • articles
    • Columns Configuration
    • Details

    Possible values for the property are:

    • desired number;
    • 0 to disable yCount ( calculate the number of item on the base of component size).

    Related sample: Popup Menu


Events

onAfterAdd | fires after adding item to datastore
onAfterAreaAdd | fires after a select area was added
onAfterAreaRemove | fires after a select area was removed
onAfterBlockSelect | event occurs after block selection
onAfterColumnDrop | fires after the column has been dragged and dropped to the target position
onAfterColumnDropOrder | fires after the column order was changed with the help of drag-and-drop
onAfterColumnHide |
onAfterColumnShow |
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onAfterFilter | occurs after datatable was filtered
onAfterLoad | fires after data loading is complete
onAfterRender | occurs each time after the view is rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after a cell is selected
onAfterSort | fires after sorting dataset
onAfterUnSelect | fires after a cell is unselected
onAreaDrag | fires when area selection is started
onBeforeAdd | fires before adding item to datastore
onBeforeAreaAdd | fires before a select area is added
onBeforeAreaRemove | fires before a select area is removed
onBeforeBlockSelect | event occurs before block selection
onBeforeColumnDrag | fires the monent you start dragging the column from its source potition
onBeforeColumnDrop | fires the moment you drop the column to its target position
onBeforeColumnDropOrder | fires the moment you drop the column over the target area
onBeforeColumnHide |
onBeforeColumnShow |
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onBeforeFilter | called when filtering process is started, but data is not filtered yet
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs each time before the view is rendered
onBeforeSelect | fires before a cell is selected
onBeforeSort | fires before sorting dataset
onBeforeUnSelect | fired before a cell is unselected
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onCheck | fires when a checkbox is checked or unchecked in the datatable item
onCollectValues | fires after datatable has collected options
onColumnResize | fires when width of column was changed
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHeaderClick | occurs after clicking on header
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLiveEdit | occurs when data was changed in the editor
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onResize | fires when the width or height of DataTable was changed
onRowResize | fires when height of row was changed
onScrollX | fires when the user scrolls the table left or right
onScrollY | fires when the user scrolls the table up or down
onSelectChange | fires when selection is changed in a DataTable
onStructureLoad | fires when the structure of DataTable (columns configuration) is initialized
onStructureUpdate | fires when structure of datatable was changed ( column added, hidden or reconfigured )
onSubViewClose | fires after a subview or a subrow is closed
onSubViewCreate | fires after a subview was created
onSubViewOpen | fires after a subview or a subrow is opened
onSubViewRender | fires each time subview is rendered
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


onAfterAreaAdd

fires after a select area was added

void onAfterAreaAdd(object area){ ... };

Parameters

area object the area object

Example

$$('dtable').attachEvent("onAfterAreaAdd", function(area){
    // some code here
});

Details

The properties of the area object are:

  • start - (object) the id object of the left top cell, contains two parameters: the row id and the column id
  • end - (object) the id object of the right cell, contains two parameters: the row id and the column id
  • preserve - (boolean) defines, if the previous select area should be saved, false by default
  • area_name - (string) optional, the name used to address to an area to change or to delete it
  • css - (string) optional, the css style for an area
  • handle - (boolean) optional, defines, whether selection will be resized with or without a handle

See also

  • api
    • onBeforeAreaAdd
    • onAfterAreaRemove


onAfterAreaRemove

fires after a select area was removed

void onAfterAreaRemove(string area_name){ ... };

Parameters

area_name string the name used to address a select area to change or delete it

Example

$$('dtable').attachEvent("onAfterAreaRemove", function(area_name){
    // some code here
});

See also

  • api
    • onBeforeAreaRemove
    • removeSelectArea


onAfterBlockSelect

event occurs after block selection

void onAfterBlockSelect(cellId start,cellId end){ ... };

Parameters

start | cellId | id of start cell
end | cellId | id of the end cell

Example

$$("datatable").attachEvent("onAfterBlockSelect", function(start, end){
    // some code
});


onAfterColumnDrop

fires after the column has been dragged and dropped to the target position

void onAfterColumnDrop(){ ... };

Example

$$("datatable1").attachEvent("onAfterColumnDrop", function(context, native_event){...});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeColumnDrop
    • onBeforeColumnDrag
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-drop with Datatable


onAfterColumnDropOrder

fires after the column order was changed with the help of drag-and-drop

void onAfterColumnDropOrder(){ ... };

Example

$$("datatable1").attachEvent("onAfterColumnDrop", function(context, native_event){...});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeColumnDropOrder
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-drop with Datatable


onAfterColumnHide

fires after a column was hidden in datatable

void onAfterColumnHide(string/number id){ ... };

Parameters

id string/number the column id

Example

$$("datatable1").attachEvent("onAfterColumnHide", function(id){
    // some code
});

See also

  • api
    • hideColumn
    • onBeforeColumnHide


onAfterColumnShow

fires when a column is shown in datatable

void onAfterColumnShow(string/number id){ ... };

Parameters

id string/number the column id

Example

$$("datatable1").attachEvent("onAfterColumnShow", function(id){
    // some code
});

See also

  • api
    • onBeforeColumnShow
    • showColumn


onAfterDelete

fires after item deleting

void onAfterDelete(id id){ ... };

Parameters

id id id of item in question

Example

some.attachEvent("onAfterDelete", function(id){
    //... some code here ...
});

See also

  • api
    • onBeforeDelete
    • remove
  • articles
    • Adding/Deleting Data Items


onAfterEditStart

fires after edit operation was initiated, editor opened and ready for input

void onAfterEditStart(id id){ ... };

Parameters

id id the item id

Example

some.attachEvent("onAfterEditStart", function(id){
    //... some code here ...
});

See also

  • api
    • onBeforeEditStart
  • articles
    • DataTable Editing
    • Data Editors


onAfterEditStop

fires after edit operation finished

void onAfterEditStop(object state,object editor,boolean ignoreUpdate){ ... };

Parameters

state | object | an object with 2 properties: 'value' - the new value of the cell, 'old' - the old value of the cell
editor | object | the editor's object
ignoreUpdate | boolean | specifies whether the cell was updated after editing

Example

some.attachEvent("onAfterEditStop", function(state, editor, ignoreUpdate){
    if(state.value != state.old){
        webix.notice("Cell value was changed")
    }
});

See also

  • api
    • onAfterEditStart
  • articles
    • DataTable Editing
    • Data Editors


onAfterFilter

occurs after datatable was filtered

void onAfterFilter(){ ... };

Example

dtable.attachEvent("onAfterFilter", function(){
    webix.message("Table was filtered");
})

See also

  • api
    • filter
    • filterByAll
    • registerFilter
    • getFilter
  • articles
    • DataTable Filtering


onAfterRender

occurs each time after the view is rendered

void onAfterRender(array data){ ... };

Parameters

data array the set of data which was rendered

Example

grid.attachEvent("onAfterRender", function(){
   webix.message("Rendering end");
});

Details

In case of DataTable, data is a datastore object of the component

See also

  • api
    • render
    • onBeforeRender
  • articles
    • Changing Properties of Components


onAfterSelect

fires after a cell is selected

void onAfterSelect(object data,boolean preserve){ ... };

Parameters

data | object | the selected object
preserve | boolean | indicates whether the previous selection state should be saved

Example

some.attachEvent("onAfterSelect", function (data, preserve){
  //... some code here ...
});

Details

If multiselect mode is enabled, the event will fire:

  • Each time you select an item with Ctrl+click;
  • Once for each selected item in the group during Shift+click selection.

In each case, the ID of the newly selected item be passed to the event.

To get the IDs of currently selected items, you can use a combination of onSelectChange and the selectRange method.

See also

  • api
    • onBeforeSelect
    • onSelectChange
    • selectRange
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


onAfterSort

fires after sorting dataset

void onAfterSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Example

some.attachEvent("onAfterSort", function(by, dir, as){
    //... some code here ...
});

See also

  • api
    • onBeforeSort
    • sort
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree


onAfterUnSelect

fires after a cell is unselected

void onAfterUnSelect(object data){ ... };

Parameters

data object the unselected object

Example

some.attachEvent("onAfterUnSelect", function(data){
    //... some code here ...
});

See also

  • api
    • onBeforeUnSelect
    • selectRange
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


onAreaDrag

fires when area selection is started

void onAreaDrag(object start,object end,Event object ev){ ... };

Parameters

start | object | the id object of the left top cell, contains two properties: the row id and the column id
end | object | the id object of the right cell, contains two properties: the row id and the column id
ev | Event object | a native event object

Example

$$('dtable').attachEvent("onAreaDrag", function(start, end, ev){
   // some code here
});


onBeforeAdd

fires before adding item to datastore

boolean onBeforeAdd(string|number id ,object obj,number index){ ... };

Parameters

id | string|number | id of the newly added data item
obj | object | data for new item
index | number | index, at which new item will be added

Returns

boolean false if operation need to be blocked

Example

$$('some').attachEvent("onBeforeAdd", function(obj, index){
    if (obj.text == "")
        return false;
});

See also

  • api
    • onAfterAdd
    • add
    • DataStore
  • articles
    • Adding/Deleting Data Items


onBeforeAreaAdd

fires before a select area is added

void onBeforeAreaAdd(object area){ ... };

Parameters

area object the area object

Example

$$('dtable').attachEvent("onBeforeAreaAdd", function(area){
   // some code here
   return true;
});

Details

The event can be blocked. Return false to block area adding.

The properties of the area object are:

  • start - (object) the id object of the left top cell, contains two parameters: the row id and the column id
  • end - (object) the id object of the right cell, contains two parameters: the row id and the column id
  • preserve - (boolean) defines, if the previous select area should be saved, false by default
  • area_name - (string) optional, the name used to address to an area to change or to delete it
  • css - (string) optional, the css style for an area
  • handle - (boolean) optional, defines, whether selection will be resized with or without a handle

See also

  • api
    • onAfterAreaAdd
    • onBeforeAreaRemove


onBeforeAreaRemove

fires before a select area is removed

void onBeforeAreaRemove(string area_name){ ... };

Parameters

area_name string the name used to address a select area to change or delete it

Example

$$('dtable').attachEvent("onBeforeAreaRemove", function(area_name){
   // some code here
   return true;
});

Details

The event can be blocked. Return false to block area removal.

See also

  • api
    • onAfterAreaRemove
    • removeSelectArea


onBeforeBlockSelect

event occurs before block selection

void onBeforeBlockSelect(cellId start,cellId end,boolean isFinal){ ... };

Parameters

start | cellId | id of start cell
end | cellId | id of the end cell
isFinal | boolean | is selection still in progress or finalized

Example

$$("dt").attachEvent("onBeforeBlockSelect", function(start, end, isFinal){
    return true;
});

Details

return false to block selection

it possible to modify start and end object to modify result of blockselection


onBeforeColumnDrag

fires the monent you start dragging the column from its source potition

void onBeforeColumnDrag(){ ... };

Example

$$("datatable1").attachEvent("onBeforeColumnDrag", function(context, native_event){...});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onBeforeColumnDrop
    • onAfterColumnDrop
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-drop with Datatable


onBeforeColumnDrop

fires the moment you drop the column to its target position

void onBeforeColumnDrop(){ ... };

Example

$$("datatable1").attachEvent("onBeforeColumnDrop", function(context, native_event){...});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onAfterColumnDrop
    • onBeforeColumnDrag
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-drop with Datatable


onBeforeColumnDropOrder

fires the moment you drop the column over the target area

void onBeforeColumnDropOrder(){ ... };

Example

$$("datatable1").attachEvent("onBeforeColumnDropOrder", function(context, native_event){...});

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • api
    • onAfterColumnDropOrder
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-drop with Datatable


onBeforeColumnHide

fires before a column is hidden in datatable

void onBeforeColumnHide(string/number id){ ... };

Parameters

id string/number the column id

Example

$$("datatable1").attachEvent("onBeforeColumnHide", function(id){
    // some code
});

Details

The event is cancellable. If a handler returns false, the column will not be hidden.

See also

  • api
    • onAfterColumnHide
    • hideColumn


onBeforeColumnShow

fires before a column is shown in datatable

void onBeforeColumnShow(string/number id){ ... };

Parameters

id string/number the column id

Example

$$("datatable1").attachEvent("onBeforeColumnShow", function(id){
    // some code
});

Details

The event is cancellable. If a handler returns false, the column will not be shown.

See also

  • api
    • onAfterColumnShow
    • showColumn


onBeforeDelete

fires before item deleting

boolean onBeforeDelete(id id){ ... };

Parameters

id id id of item in question

Returns

boolean returning false will prevent item deleting

Example

some.attachEvent("onBeforeDelete", function(id){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • onAfterDelete
    • remove
  • articles
    • Adding/Deleting Data Items


onBeforeDrag

fires before the mouse button is pressed and the cursor is moved over a draggable item

boolean onBeforeDrag(object context,Event native_event){ ... };

Parameters

context | object | the drag-n-drop context
native_event | Event | an HTML event object

Returns

boolean returning false will prevent dragging of the element

Example

grida.attachEvent("onBeforeDrag", function(context, ev){
        context.html = "<div style='padding:8px;'>";
        for (var i=0; i< context.source.length; i++){
            context.html += context.from.getItem(context.source[i]).title + "<br>" ;
        }
        context.html += "</div>";
});

Details

If you drag multiple items, the event will be called once, for the entire batch of items.

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for dropping on empty space
  • start - the id from which DND was started

See also

  • api
    • onDragOut
    • onBeforeDragIn
  • samples
    • Drag and Drop with Drag Handle
    • Using events for customizing dnd
  • articles
    • Drag-n-Drop within Webix Views
    • Drag-and-Drop Events


onBeforeEditStart

fires before edit operation is initiated

void onBeforeEditStart(id id){ ... };

Parameters

id id the id of the item which will be edited

Example

some.attachEvent("onBeforeEditStart", function(id){
    //... some code here ...
});

See also

  • api
    • edit
    • editRow
    • editColumn
    • onBeforeEditStop
  • articles
    • DataTable Editing


onBeforeEditStop

fires before stop edit command is received

void onBeforeEditStop(object values,object editor){ ... };

Parameters

values | object | an object with two parameters: the new value and the old one
editor | object | the editor object

Example

grid.attachEvent("onBeforeEditStop", function(state, editor){ return false; });

grid.attachEvent("onEditorChange", function(id, value){
    this.getItem(id.row)[id.column] = value;
    this.refresh(id.row);
});;

Details

Events starting from "before" are blockable, which means that if they return false the action is blocked.

In the above sample editing is not finished when the edit stop command is received (it happens when you leave the editor body) and editing continues with setting the new value to the item and refreshing it. It is done to display the new value outside the field where editor opens.

See also

  • api
    • edit
    • editRow
    • editColumn
    • onBeforeEditStart
  • samples
    • Using 'inline' editors
  • articles
    • DataTable Editing


onBeforeFilter

called when filtering process is started, but data is not filtered yet

boolean onBeforeFilter(id id,id value,object config){ ... };

Parameters

id | id | the column id
value | id | the value to be fitlered by
config | object | the filter configuration

Returns

boolean returning false will prevent data filtering

Example

dtable.attachEvent("onBeforeFilter", function(id, value, config){
    //ignores short filter-strings during filtering
    if (value.length < 3) return false;
})

See also

  • api
    • onAfterFilter
    • filter
    • filterByAll
    • registerFilter
    • getFilter
  • articles
    • DataTable Filtering


onBeforeRender

occurs each time before the view is rendered

boolean onBeforeRender(array data){ ... };

Parameters

data array the set of data which will be rendered

Returns

boolean returning false will prevent view rendering

Example

grid.attachEvent("onBeforeRender", function(){
   webix.message("Rendering start");
});

Details

In case of DataTable, data is a datastore object of the component

See also

  • api
    • onAfterRender
    • render
  • articles
    • Changing Properties of Components


onBeforeSelect

fires before a cell is selected

boolean onBeforeSelect(object data,boolean preserve){ ... };

Parameters

data | object | the selected object
preserve | boolean | indicates whether the previous selection will be saved

Returns

boolean returning `false` will prevent item selection

Example

some.attachEvent("onBeforeSelect", function (data, preserve){
  // ... some code here ...
  // return false to block operation
  return true;
});

See also

  • api
    • onAfterSelect
    • selectRange
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


onBeforeSort

fires before sorting dataset

boolean onBeforeSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Returns

boolean returning false will prevent sorting

Example

some.attachEvent("onBeforeSort", function(by, dir, as){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • onAfterSort
    • sort
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree
    • Operations with Chart Data


onBeforeUnSelect

fired before a cell is unselected

void onBeforeUnSelect(object data){ ... };

Parameters

data object the unselected object

Example

some.attachEvent("onBeforeUnSelect", function(data){
    //... some code here ...
});

See also

  • api
    • onAfterUnSelect
    • selectRange
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • articles
    • Selection with Datatable


onCheck

fires when a checkbox is checked or unchecked in the datatable item

void onCheck(number row,string column,number state){ ... };

Parameters

row | number | id of the row
column | string | id of the column
state | number | new checkbox state

Example

datatable.attachEvent("onCheck", function(row, column, state){
    //code
});

Details

Checkbox state is 0 or 1 by default, if other is not stated by the checkValue and uncheckValue properties of the column:

{id:"ch", template:"{common.checkbox()}", checkValue:"On", uncheckValue:"Off"}

See also

  • samples
    • Events invoked in DataTable


onCollectValues

fires after datatable has collected options

void onCollectValues(string id,object data){ ... };

Parameters

id | string | the id of the column
data | object | the object that contains options

Example

datatable.attachEvent("onCollectValues", function(id, data){
    if (data.values[0].value == "")
    data.values[0].value = "Select something";
});

See also

  • samples
    • Customizing automatic options


onColumnResize

fires when width of column was changed

void onColumnResize(string id,number newWidth,number oldWidth){ ... };

Parameters

id | string | id of the column
newWidth | number | the new width set for the column
oldWidth | number | the previous width of the column

Example

$$("table").attachEvent("onColumnResize", function(id, newWidth, oldWidth){
    alert("New column width: " + this.getColumnConfig(id).width );
});


onHeaderClick

occurs after clicking on header

void onHeaderClick(id id,object e,element trg){ ... };

Parameters

id | id | id of column
e | object | native html event
trg | element | html element on which click was catched

Example

grid.attachEvent("onHeaderClick", function(id){
    this.sort({ by:id });
});


onItemClick

fires when a component item was clicked

void onItemClick(object id, [Event e,HTMLElement node] ){ ... };

Parameters

id | object | row/column of the clicked item
e | Event | a native event object
node | HTMLElement | the target HTML element

Example

grid.attachEvent("onItemClick", function(id, e, node){
    var item = this.getItem(id);
    //... some code here ...
});

Details

The id parameter has the following structure:

{ row:3, column:"title"}

It can be passed into a getItem method anyhway.

See also

  • api
    • onItemDblClick
  • samples
    • Datatable: Custom Handler
  • articles
    • Event Handling


onLiveEdit

occurs when data was changed in the editor

void onLiveEdit(object state,object editor){ ... };

Parameters

state | object | an object with 2 properties: 'value' - the new value of the cell, 'old' - the old value of the cell
editor | object | the editor's object

Example

some.attachEvent("onLiveEdit", function(state, editor, ignoreUpdate){
    webix.notice("Current value: " + state.value);
});

Details

Occurs only if liveEdit mode was used for the editor


onResize

fires when the width or height of DataTable was changed

void onResize(number width,number height){ ... };

Parameters

width | number | the current widht
height | number | the current height

Example

dtable.attachEvent("onResize", function(width, height){
    webix.message("Datatable takes "+(width*height)+" square pixels");
});

See also

  • articles
    • Sizing and Resizing


onRowResize

fires when height of row was changed

void onRowResize(id id){ ... };

Parameters

id id id of the row

Example

$$("table").attachEvent("onRowResize", function(id){
    alert("New row height: " + this.getItem(id).$height );
));


onScrollX

fires when the user scrolls the table left or right

void onScrollX(){ ... };

Example

dtable.attachEvent("onScrollX", function(){
    var state = $$('datatable1').getScrollState();
    webix.message("The scroll coordinates: ["+state.x+","+state.y+"]");
});

See also

  • api
    • getScrollState
    • onScrollY
  • articles
    • Sizing and Resizing


onScrollY

fires when the user scrolls the table up or down

void onScrollY(){ ... };

Example

dtable.attachEvent("onScrollY", function(){
            var state = $$('datatable1').getScrollState();
            webix.message("The scroll coordinates: ["+state.x+","+state.y+"]");
})

See also

  • api
    • getScrollState
    • onScrollX
  • articles
    • Sizing and Resizing


onSelectChange

fires when selection is changed in a DataTable

void onSelectChange(){ ... };

Example

webix.ui({
  view: "datatable",
  on: {
     onSelectChange: function () {
       var text = "Selected: " + grid.getSelectedId(true).join();
       document.getElementById('testB').innerHTML = text;
     }
  }
});

Details

The event doesn't provide any details about changes; it just informs that it has occurred.

See also

  • api
    • onAfterSelect
    • onBeforeSelect
    • selectRange
    • getSelectedId
    • mapSelection
    • unselect
    • clearSelection
  • samples
    • Block selection
  • articles
    • Selection with Datatable


onStructureLoad

fires when the structure of DataTable (columns configuration) is initialized

void onStructureLoad(){ ... };

Example

dtable.attachEvent("onStructureLoad", function(){
   webix.message("Structure is ready");
});

See also

  • articles
    • Columns Configuration


onStructureUpdate

fires when structure of datatable was changed ( column added, hidden or reconfigured )

void onStructureUpdate(){ ... };

Example

mydata.attachEvent("onStructureUpdate", function(){
    webix.message("Grid was updated");
})


onSubViewClose

fires after a subview or a subrow is closed

void onSubViewClose(obj id){ ... };

Parameters

id obj ID of the cell that starts a subview

Example

datatable.attachEvent("onSubViewOpen", function(id){
    // code
});

Details

ID of the cell is an object with the following properties:

  • row - ID of the related row;
  • column - ID of the related column.

See also

  • api
    • onSubViewOpen
    • onSubViewCreate
    • onSubViewRender
  • articles
    • Adding Subrows
    • Adding Subviews


onSubViewCreate

fires after a subview was created

void onSubViewCreate(object view,object item){ ... };

Parameters

view | object | the created subview
item | object | the item that a subgrid is created for

Example

$$("$datatable1").attachEvent("onSubViewCreate",function(view, item){
    webix.message("A subview is created");
});

See also

  • samples
    • Sub-Grid in a DataTable - Inline Data
    • Sub-Form in a DataTable
  • articles
    • Adding Subviews


onSubViewOpen

fires after a subview or a subrow is opened

void onSubViewOpen(obj id){ ... };

Parameters

id obj ID of the cell that starts a subview

Example

datatable.attachEvent("onSubViewOpen", function(id){
    // code
});

Details

ID of the cell is an object with the following properties:

  • row - ID of the related row;
  • column - ID of the related column.

See also

  • api
    • onSubViewClose
    • onSubViewCreate
    • onSubViewRender
  • articles
    • Adding Subrows
    • Adding Subviews


onSubViewRender

fires each time subview is rendered

void onSubViewRender(object view,object item){ ... };

Parameters

view | object | the rendered subview
item | object | the item that a subgrid is rendered for

Example

$$("$datatable1").attachEvent("onSubViewRender",function(view, item){
    webix.message("A subview is rendered");
});


onValidationError

fires when newly loaded/added/edited data fails to pass validation

void onValidationError(number| string id,object obj,object details){ ... };

Parameters

id | number| string | id of the data item that is being validated
obj | object | data item object
details | object | validation result for data keys under validation

Example

webix.ui({
    view:"datatable",
    rules:{
        title:webix.rules.isNotEmpty,
        rating:webix.rules.isNumber
    },
    on:{
        onValidationError:function(id, obj, details){
            var index = this.getIndexById(id)+1;
            webix.message({ type:"error", text:"Empty title for row "+index });
        }
     }
});

Details

The last parameter, details, contains invalid markers for each data key that has been validated and looks like:

{
    title:true,//haven't passed validation
    rating:false //have passed validation
}

See also

  • api
    • validate
    • rules
    • onValidationSuccess
  • samples
    • Validation with Message
    • Validation with Complex Message
  • articles
    • Data Validation


onValidationSuccess

fires after the newlyloaded/added/edited data has passes validation successfully

void onValidationSuccess(){ ... };

Example

some.attachEvent("onValidationSuccess", function(){
    //... some code here ...
});

See also

  • api
    • validate
    • rules
    • onValidationError
  • articles
    • Data Validation


Others

$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
headerContent | a hash property containing a collection of active elements which can be placed in the header
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
waitData | eventual result of an asynchronous operation ('promise' object) for the loaded data


headerContent

a hash property containing a collection of active elements which can be placed in the header

object headerContent;


waitData

eventual result of an asynchronous operation ('promise' object) for the loaded data

promise waitData;

Example

var grid = webix.ui({
    view:"datatable", //any data object
    url:"data.php",
});

grid.waitData.then(function(){
    //when we have data - do some actions
});

See also

  • articles
    • Ajax operations
    • Data Loading
    • Details

    The ultimate advantage of Promise objects is that they allow treating the result of asynchronous operations without callbacks.


ui.dataview

A control for displaying data in a tabular format.

The component presents a collection of objects according to a user-defined template. Support for various template forms and the possibility to sort, filter data. Check dataview documentation for more detailed description.

Constructor

var dataview = webix.ui({
    view:"dataview",
    id:"dataview1",
    xCount:3,
    type: {
        height: 60,
    },
    template:"<div class='webix_strong'>#title#</div> Year: #year#, rank: #rank#",
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, rank:1},
        { id:2, title:"The Godfather", year:1972, rank:2},
        { id:3, title:"The Godfather: Part II", year:1974, rank:3},
        { id:4, title:"The Good, the Bad and the Ugly", year:1966, rank:4}
    ]
});

Where to start

  • Overview of the Dataview Widget
  • Samples
Based on: DataMove, DragItem, MouseEvents, KeysNavigation, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, VirtualRenderStack
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | enables autosizing to content
borderless | used to hide the component borders
click | sets an action happening on a button click
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datafetch | defines the number of records that will be loaded during each dynamic loading request
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
loadahead | how the number of records that need to be loaded in addition to mandatory ones during each dynamic loading request
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | adjusts the view width to display the defined number of items in a row
yCount | adjusts the view height to display the defined number of items in a column
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types
waitData | eventual result of an asynchronous operation ('promise' object) for the loaded data


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


filter

filters the component

void filter(template|function text,string value,boolean preserve);

Parameters

text | template|function | a template of filtered value or function
value | string | the filtering mask
preserve | boolean | if set to true, each next filtering criteria will be applied to the already filtered list

Example

//filters all fields with 'abc' in the 'text' property
//using a template
list.filter('#text#',"abc")

//using a function
list.filter(function(obj){
    return obj.text.toString().indexOf("abc") != -1;
});

See also

  • api
    • samples
      • List: Filtering
    • articles
      • Data Filtering and Sorting


refresh

repaints the whole view or a certain item

void refresh( [id id] );

Parameters

id id the item id. If the parameter is set, just the specified item will be repainted

Example

$$("button1").define("label", "New value");
$$("button1").refresh();

See also

  • api
    • render
  • articles
    • Getting/setting the cell value
    • Changing Properties of Components


remove

removes the specified item/items from datastore

void remove(string/number/array id);

Parameters

id string/number/array the item id or an array of items' ids

Example

$$("my_list").remove(1); //removes the item with ID=1
$$("my_list").remove($$("data").getSelectedId()); //removes the selected item

$$("my_list").remove([1,3,5]); // removes multiple items

See also

  • api
    • add
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


render

renders the specified item or the whole component

void render(id id,object data,string type);

Parameters

id | id | the item id
data | object | the hash of data for the rendered item
type | string | the type of the operation: 'update', 'add', 'delete', 'move'

Example

$$('view').render();

Details

When no parameters are specified, the method renders the whole view.

Types of the operation:

  • update - replaces the existing HTML with the new one
  • add - place a new HTML at the required position
  • delete - removes the related HTML
  • move - simulates add-delete sequence

See also

  • api
    • refresh
  • samples
    • Customizing Pager Controls
  • articles
    • Changing Properties of Components


select

selects the specified item(s)

void select(string| array id,boolean preserve);

Parameters

id | string| array | the id of a single item or an array of items ids
preserve | boolean | if it's set to true, the method won't affect the existing selection (will select new items but preserve selection of old items). The default value - false

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').select(2);               //selects an item with the id=2
$$('data').select(3, true);         //selects an extra item, preserving previos selection

$$('data').select([2,3,5]);         //selects a group of items with ids: 2,3,5

Details

If the parameters aren't specified, all items will be selected.

    $$('data').select();                     //selects all items

See also

  • api
    • selectAll
    • isSelected
    • getSelectedId
    • unselect
    • unselectAll
  • samples
    • Selection
  • articles
    • Selection


setPage

makes the specified page visible (assuming that the pager was defined )

void setPage(number page);

Parameters

page number the page number (zero-based numbering)

Example

dtable.setPage(2); // makes the third page visible

See also

  • api
    • getPage
  • samples
    • Static Paging
  • articles
    • Paging


showItem

scrolls the component to make the specified item visible

void showItem(id id);

Parameters

id id the item's id

Example

list = webix.ui({
    view:"list",
    ...
});
list.showItem('item1'); // 'item1' is the item's id

See also

  • samples
    • Horizontal List
  • articles
    • Scroll Control


sort

sorts datastore

void sort(string by, [string dir,string as] );

Parameters

by | string | the name(s) of property(s) by which data will be sorted
dir | string | the sorting direction, default is "asc"
as | string | the type of data , default is "string"

Example

data.sort("price", "asc");

Details

Usage examples

The method sort can be used with different count of parameters.

The most common use case of the sort method is using the first parameter as the name of a property:

//sorts by name value; ascedent; sorted values as strings
data.sort("#name#","asc","string");
//sorts by price value; descedant; sorted values as numbers
data.sort("#price#","desc","int");

The property name should be included into sharps.

Instead of default sorting types, you can use your own method ( can be used for complex data types ):

function sort_by_length(data1, data2){
    return data1.length>data2.length ? 1:-1;
}

data.sort("#name#","asc",sort_by_length);

Possible return values of this function are 0,1,-1.

  • 1 means that the first object is greater than the second object;
  • -1 means that the first object is less than the second object;
  • 0 means that 2 objects are equal.

If you need to access multiple properties of an object during sorting or you need to have some complex sorting logic, use a function as the first parameter.

function my_sorting(a,b){
    //a, b - data objects
    return a.Version > b.Version ? 1 : -1;
}
data.sort(my_sorting, "des"); //3rd parameter will be ignored

Alternative syntax

You can use a hash of sorting settings as the first parameter of the sort method:

data.sort({
    as:"string",
    dir:"desc",
    by:"#Package#"
});

Sorting directions

Possible values for the second parameter of the sort method is string which represents sorting direction:

  • "asc" - for ascending sorting
  • "desc" - for decrescent sorting

Sorting types

The third parameter of the sort method may be string which represents the data type:

  • "int" - sorts as interger values
  • "string" - sorts as string
  • "string_strict" - sorts as string, case-sensitive

See also

  • samples
    • Sorting Datatable. Using sorting methods
  • articles
    • Data Filtering and Sorting


updateItem

sets properties of the data item

void updateItem(id id,object data);

Parameters

id | id | the item id
data | object | the hash of properties

Example

var sel = dtable.getSelectedId();
var row = dtable.getItem(sel.row);
row[sel.column] = "some_new_value";

dtable.updateItem(sel.row, row);

See also

  • samples
    • Server-side Integration: Dataview
  • articles
    • Data Updating
    • Tree Nodes manipulations


Properties

animate | defines or disables view change animation.
autoheight | enables autosizing to content
borderless | used to hide the component borders
click | sets an action happening on a button click
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datafetch | defines the number of records that will be loaded during each dynamic loading request
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
loadahead | how the number of records that need to be loaded in addition to mandatory ones during each dynamic loading request
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | adjusts the view width to display the defined number of items in a row
yCount | adjusts the view height to display the defined number of items in a column


autoheight

enables autosizing to content

boolean autoheight;

Example

webix.ui({
    view:"dataview",
    autoheight:true
});


datafetch

defines the number of records that will be loaded during each dynamic loading request

number datafetch;

Example

webix.ui({
    view:"dataview",
    datafetch:200,
    ..
});

See also

  • api
    • loadahead
  • samples
    • Setting the Number of Items to Load
  • articles
    • Dynamic Loading for Plain Structures
    • Details

    Default value is 500.


datathrottle

sets the polling interval (the time period between the completion of a network request and the next request for data)

number datathrottle;

Example

grid = new webix.ui({
    view:"datatable",
    columns:[{...}, {...}],
    datathrottle:500,
    url:"data/data_dyn.php"
});

See also

  • samples
    • Setting Polling Interval for Loading
  • articles
    • Dynamic Loading
    • Details
    • The option is used during dynamical loading and allows you to skip unnecessary data requests during fast scrolling the dataset.
    • If a new request for data will be received during the waiting period, the timer will be reset and original loading command will be ignored.


loadahead

how the number of records that need to be loaded in addition to mandatory ones during each dynamic loading request

number loadahead;

Example

webix.ui({
    view:"datatable",
    loadahead:100
});

See also

  • api
    • datafetch
  • samples
    • Dynamic loading. Load Ahead
  • articles
    • Dynamic Loading for Plain Structures


type

object that specifies items presentation

object| string type;

Example

list = webix.ui({
    view:"list",
    ...
    type:{
        height:50
    }
})

See also

  • samples
    • Search Field
  • articles
    • Data Templates
    • Type Implementation
    • Details

    Attributes of the type object:

    • css - (string) the name of a css class that will be applied to component's items (the default name of the applied class is 'default').
    • height - (number) the height of an item in the component.
    • template - (function, string) an html template that will define item presentation in the component.
    • width - (number) the width of the items list.


xCount

adjusts the view width to display the defined number of items in a row

number xCount;

Example

webix.ui({
    view:"dataview",
    data:big_film_set,
    xCount:4, yCount:2
        });

See also

  • api
    • yCount
  • samples
    • Controlling a Number of Displayed Items
  • articles
    • Dataview
    • Details

    Possible values for the property are:

    • desired number;
    • 0 to disable xCount ( calculate the number of item on the base of component size).


yCount

adjusts the view height to display the defined number of items in a column

number yCount;

Example

webix.ui({
    view:"dataview",
    data:big_film_set,
    xCount:4, yCount:2
        });

See also

  • api
    • xCount
  • samples
    • Controlling a Number of Displayed Items
  • articles
    • Dataview
    • Details

    Possible values for the property are:

    • desired number;
    • 0 to disable yCount ( calculate the number of item on the base of component size).

    Related sample: Popup Menu


Events

onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


onAfterSort

fires after sorting dataset

void onAfterSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Example

some.attachEvent("onAfterSort", function(by, dir, as){
    //... some code here ...
});

See also

  • api
    • sort
    • onBeforeSort
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree


onBeforeSort

fires before sorting dataset

boolean onBeforeSort(string|function by,string dir,string|function as){ ... };

Parameters

by | string|function | template of sort-by field
dir | string | direction of sorting
as | string|function | type of sorting

Returns

boolean returning false will prevent sorting

Example

some.attachEvent("onBeforeSort", function(by, dir, as){
    //... some code here ...
    //return false to block operation
    return true;
});

See also

  • api
    • sort
    • onAfterSort
  • articles
    • DataTable Sorting
    • Data Filtering and Sorting
    • Sorting in the Tree
    • Operations with Chart Data


Others

$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types
waitData | eventual result of an asynchronous operation ('promise' object) for the loaded data


ui.datepicker

A control that allows the user to select a date.

The control combines an editable text field with a drop-down calendar. Supports all date and time formats. Besides the days of the month, it can display hour and minite selectors. Check datepicker documentation for more detailed description.

Constructor

var datepicker = webix.ui({
    view:"datepicker",
    date:new Date(2012, 6, 8),
    label:'Date',
    timepicker:true,
    width:300
});

Where to start

  • Overview of the Datepicker Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | gets actual text value from the control's input
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
editable | allows entering characters in datepicker input, false by default
format | sets date format in the control
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
icons | shows "Today" and "Clear" icons for calendar and datepicker popup
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
stringResult | if the parameter is set to true, the method getValue returns data as string (otherwise, as object)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
timeIcon | sets an icon for time in the datepicker
timepicker | enables optional timepicker in the calendar
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


getText

gets actual text value from the control's input

string getText();

Returns

string text displayed in the input field

Example

$$("mydatepicker").getText();
$$("mycolorpicker").getText();

Details

To get the control's value you should use the getValue method.

In case you don't have a stringResult property in the control's configuration, the getValue method will return raw unformatted value.

See also

  • api
    • getValue


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
editable | allows entering characters in datepicker input, false by default
format | sets date format in the control
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
icons | shows "Today" and "Clear" icons for calendar and datepicker popup
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
stringResult | if the parameter is set to true, the method getValue returns data as string (otherwise, as object)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
timeIcon | sets an icon for time in the datepicker
timepicker | enables optional timepicker in the calendar
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


editable

allows entering characters in datepicker input, false by default

boolean editable;

Example

webix.ui({
    view:"datepicker",
    editable:true
});


icon

sets an icon into the control

string icon;

Example

webix.ui({
    view:"search",
    icon:"search",
    ...
});


text

visible text in the related input

string text;

Example

var now = $$("dpicker").config.text;


value

sets the initial value for a control

Date| string value;

Example

{ view:"datepicker", value:"2015-03-06"}

See also

  • api
    • getValue
    • setValue
  • samples
    • Editable Combo Box ('combo')
  • articles
    • Controls Guide
    • Details

    All controls fall into:

    • single-value - those containing a string of a number;
    • multiple-value - those containing an array of values;

    In case of multiple controls value property defines the one initially chosen.

    Value of the control may be:

    • text value in the input text and textarea field;
    • selected item like date in calendar and color in the colorboard;
    • state of the two-state control (checkbox, radio, toggle);
    • selected option of integral buttons (tabbar, tabview, segmented;
    • selected option of select, richselect, and combo;
    • string with selected options of a multiselect and multicombo control.


ui.fieldset

A wrapper which renders an HTML fieldset.

The control presents a standard fieldset that combines several sense-connected UI elements inside itself. Check fieldset documentation for more detailed description.

Constructor

var fieldset = webix.ui({
    view:"fieldset",
    label:"Field Set 1",
    body:{
        rows:[
            { view:"text", label:"Email"},
            { view:"text", label:"Password"}
        ]
    }
});

Where to start

  • Overview of the Fieldset Control
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | returns sub-view of fieldset
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
body | config for sub-view of fieldset
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
label | legend of fieldset
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | returns sub-view of fieldset
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link


getBody

returns sub-view of fieldset

object getBody();

Returns

object webiv ui object, which is placed inside fieldset

Example

var set = webix.ui({
    view:"fieldset", label:"Test area",
    body:{
       view:"text", label:"Field B"
    }
});
var text = set.getBody();


Properties

animate | defines or disables view change animation.
body | config for sub-view of fieldset
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
label | legend of fieldset
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
width | sets the width of the component


body

config for sub-view of fieldset

WebixView body;

Example

webix.ui({
    view:"fieldset", label:"Test area",
    body:{
       rows:[
           { view:"text", label:"Field A" },
           { view:"text", label:"Field B" }
       ]
    }
});


label

legend of fieldset

label;

Example

webix.ui({
    view:"fieldset", label:"Test area",
    body:{
       rows:[
           { view:"text", label:"Field A" },
           { view:"text", label:"Field B" }
       ]
    }
});


ui.form

A form that supports an extended set of elements.

The component provides validation and the ability to save user input to the backend database. Check form documentation for more detailed description.

Constructor

var form = webix.ui({
    view:"form",
    elements:[
        { view:"text", label:"Email" },
        { view:"text", type:"password", label:"Password" },
        {cols:[
            { view:"button", value:"Login", type:"form" },
            { view:"button", value:"Cancel" }
        ]}
    ]
});

Where to start

  • Overview of the Form Widget
  • Samples
Based on: ui.toolbar, Scrollable, AtomDataLoader, Values, ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension, ValidateData
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clear | clears all the field in a specified form
clearValidation | removes "data incorrect" highlighting from invalid text fields
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus into the necessary component
getChildViews | returns child views of the calling component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives input values from the form
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isDirty | checks whether changes within form were made
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
markInvalid | marks a form control invalid
parse | loads data to the component from an inline data source
reconstruct | rebuilds the layout
refresh | repaints the component
removeView | removes view from layout-like component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
setDirty | marks the form as the one with changed values and vice versa
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | checks data in the form
Events
onAfterLoad | fires after server side loading is complete
onAfterScroll | fires when to component is scrolled in any direction
onAfterValidation | fires after data has been validated
onBeforeLoad | occurs immediately before data loading has been started
onBeforeValidate | called before running validation
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when data in the input or related form/toolbar is changed
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onSubmit | fires when enter key is pressed for a focused control in the form
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully
onValues | fires after values have been set within toolbar or form
Properties
animate | defines or disables view change animation.
autoheight | sets component height according to its contents
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
elements | collection of subviews
elementsConfig | settings, which will be applied to all nested inputs
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
rules | defines a set of rules for input field(s) of the form(htmlform)
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
type | defines the layout borders
url | the URL which the component will use to load data after its initialization
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clear | clears all the field in a specified form
clearValidation | removes "data incorrect" highlighting from invalid text fields
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus into the necessary component
getChildViews | returns child views of the calling component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives input values from the form
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isDirty | checks whether changes within form were made
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
markInvalid | marks a form control invalid
parse | loads data to the component from an inline data source
reconstruct | rebuilds the layout
refresh | repaints the component
removeView | removes view from layout-like component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
setDirty | marks the form as the one with changed values and vice versa
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | checks data in the form


clear

clears all the field in a specified form

void clear();

Example

function clear_form() {
   $$('myform').clear();
}

See also

  • samples
    • Binding to List
  • articles
    • HTMLForm and Form Treatment


clearValidation

removes "data incorrect" highlighting from invalid text fields

void clearValidation();

Example

{view:"button", value:"Clear Validation", click:"$$('form1').clearValidation();"}

Details

The function removes highlighting from fields with failed validation. This is done for convenience means so that users can continue filling in the form without annoying red. It doesn't cancel validation rules.

See also

  • api
    • validate
  • samples
    • Validation with Predefined Rules
  • articles
    • Data Validation


focus

sets focus into the necessary component

void focus(string item);

Parameters

item string ID or name of the form element

Example

//htmlform
<input type="button" value="Focus author" onclick="focus_form('author');" />
<input type="button" value="Focus genre" onclick="focus_form('genre');" />

            ...
function focus_form(item) {
                if (!item)
                    $$('htmlform1').focus();
                else
                    $$('htmlform1').focus(item);
            }

Details

If applied with no parameter, the function sets focus on the whole component.

See also

  • articles
    • Keyboard Events. Focusing. Navigation


getCleanValues

returns hash of original form values

object getCleanValues();

Returns

object hash of original form values

Example

var original = $$("form").getCleanValues();
alert("Before edit name: "+original.name);


getDirtyValues

returns hash of changed values

object getDirtyValues();

Returns

object hash of changed values

Example

var changed = $$("form").getDirtyValues();
if (change.name)
    alert("New name: "+changed.name);


getValues

derives input values from the form

hash getValues( [object| function details] );

Parameters

details object| function additional parameters (described below)

Returns

hash returns hash of form values: data entered by user or initial data from the value property.

Example

webix.ui({
    view:"form",
    elements:[
         //name is necessary for getting the control's value
         { view:"text", label:'Login', name:"login"},
         { view:"text", label:'Email', name:"email" },
         { view:"button", value:"Sumbit"}
    ]
});

function get_form() {
    var values = $$("myform").getValues();
    //returns { login:"", email:""}
}

Details

Additonal parameters

When the method is called without the arguments, all the values of this form are returned including the values of hidden and disabled fields.

Still, you can alter this behaviour:

//returns values of visible fields only
$$('myform').getValues({hidden:false});

//returns values of enabled fields only
$$('myform').getValues({disabled:false});

//excludes both hidden and disabled fields from the result
$$('myform').getValues({
    hidden:false,
    disabled:false
});

Additionally, you can pass a loop function into the method to iterate through the form controls:

$$('myform').getValues(function(obj){
    //'obj' points to a control object
    console.log(obj.getValue());
});

Getting the value of a specific element

To get value of some specific element within the form, you should specify its name.

webix.ui({
    view:"form",
    elements: [
        {view:"text", name:"title", placeholder:"Enter film title"},
        {...},
        {view:"button", click:"get_title"}
    ]
})

function get_title() {
    var title = $$('myform').getValues().title;
    console.log(title);
}

See also

  • api
    • setValues
    • complexData
  • samples
    • Hidden Inputs
  • articles
    • HTMLForm and Form Treatment


index

returns the cell index in the layout collection

number index(object obj);

Parameters

obj object the cell object

Returns

number the cell index in the collection of the parent layout

Example

$$("mylayout").index($$('cell1'));

See also

  • articles
    • View


isDirty

checks whether changes within form were made

boolean isDirty();

Returns

boolean returns **true** if the data was changed

Example

if(form.isDirty()){
        if(!form.validate())
            return false;
        form.save();
    }
 };

Details

With form, the method is used before data validation and saving it to the component and server.

See also

  • api
    • setDirty
  • samples
    • Binding to List
  • articles
    • HTMLForm and Form Treatment


markInvalid

marks a form control invalid

void markInvalid(string name, [boolean| string state] );

Parameters

name | string | value of "name" parameter of the desired input
state | boolean| string | removes invalid mark; sets invalidMessage

Example

$$("myform").markInvalid("login", "Login must not be empty");

Details

"State" parameter is optional. It may define:

  • (boolean) - whether to apply invalid marking or remove it (if false). True by default;
  • (string) - text of invalidMassage parameter of the input. If such parameter already exists, this method will redefine it.

See also

  • api
    • invalidMessage


setDirty

marks the form as the one with changed values and vice versa

void setDirty( [boolean mark] );

Parameters

mark boolean if true, marks the form dirty

Example

form.setDirty();

Details

When used with a parameter the method marks the form dirty while 'clean' and 'dirty' value remain the same:

  • getCleanValues will return the initial form values;
  • getDirtyValues will return a set of changed values;
  • isDirty will return true.

When used without a parameter the method removed the 'dirty' mark, if any, and maked 'dirty' values 'clean':

  • getCleanValues will return a set of changed values;
  • getDirtyValues will return empty object, as form is consireded unchanged now;
  • isDirty will return false.

See also

  • api
    • isDirty
  • articles
    • HTMLForm and Form Treatment


setValues

sets values into the inputs of a form/toolbar/property sheet control

void setValues(object values, [boolean update] );

Parameters

values | object | hash of property - value pairs
update | boolean | if true adds updates the form with new values while exisitng values remain. False by default

Example

webix.ui({
    view:"form",
    id:"myform",
    elements:[
        { view:"text", name:"field_a" },
        { view:"text", name:"field_b" },
    ]
});

function set_form(){
    $$("myform").setValues({
       field_a: "London",
       field_b: "New York"
    });
};

Details

The methods allows for setting several values at time. Pass the names of the necessary elements and their values into the function.

Complex Data

In the complex data mode the object with values can feature sub items of any complexity level. In this case elements names are concatenated from all the data names in the chain:

webix.ui({
    view:"form",
    id:"sets",
    complexData:true,
    elements:[
        { view:"text", name:"layout.width" },
        { view:"text", name:"layout.height" }
    ]
});

$$("sets").setValues({
    layout:{
        width:250,
        height:480
    }
});

Complex data mode is enabled with the help of a same-name parameter in the form/toolbar/property sheet configuration.

Updating values

The second parameter helps manipulate values separately. By default, it is set to false.

Take that we want to set a new value for a field_b input from the form described above.

$$("my_form").setValues({ field_b:"Paris" });

In this case the value for the field_a is lost.

To avoid this, set the update parameter to true. The form will be updated with a new value for field_b input while field_a value remains unchanged.

$$("my_form").setValues({ field_b:"Paris" }, true);

See also

  • api
    • getValues
    • complexData
  • samples
    • Hidden Inputs
    • Form:Data with complex properties
  • articles
    • HTMLForm and Form Treatment


validate

checks data in the form

boolean validate( [object mode] );

Parameters

mode object validation mode for hidden and disabled fields

Returns

boolean result of validation (success or failure)

Example

webix.ui({
    view:"form",
    elements:[
        { view:"text", label:'Login', name:"login" },
        { view:"text", label:'Email', name:"email" },
    ],
    rules:{
        "email":webix.rules.isEmail,
        "login":webix.rules.isNotEmpty
    }
});

$$("$form1").validate();

Details

Form is validated according to the rules you ought to define for the necessary form fields. See the corresponding chapter of the API reference.

Customising validation logic

By default values of the hidden and disabled fields are not checked. If you want to include them into validation process, you need to provide a validation mode:

//hidden fileds will be validated
$$("$form1").validate({hidden:true});

//both hidden and disabled fields will be validated
$$("$form1").validate({hidden:true , disabled:true});

Note that if the form is hidden itself, hidden and visible fields are not separated.

See also

  • api
    • rules
    • clearValidation
  • samples
    • Basic Validation
  • articles
    • Data Validation


Properties

animate | defines or disables view change animation.
autoheight | sets component height according to its contents
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
elements | collection of subviews
elementsConfig | settings, which will be applied to all nested inputs
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
rules | defines a set of rules for input field(s) of the form(htmlform)
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
type | defines the layout borders
url | the URL which the component will use to load data after its initialization
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


autoheight

sets component height according to its contents

boolean autoheight;

Example

{ template:"html->my_box2", autoheight:true},

See also

  • api
    • height
  • samples
    • Autosizing to Content
  • articles
    • Sizing components
    • Details

    With autoheight enabled, the component takes the minimal spase enough for displaying its contents.


cols

array of views objects arranged horizontally

array cols;

Example

// layout example
webix.ui({
    rows:[
        { view:"toolbar", ... },
        {
            cols:[
                { view:"list", ... },
                { view:"form", ... }
        ]}
    ]
})

See also

  • api
    • rows
  • samples
    • Layout with Headers
  • articles
    • Layout and Resizer


complexData

enables complex data parsing mode

boolean complexData;

Example

var form = webix.ui({
    view:"form", complexData:true, elements:[
      { view:"text", name:"user.firstname"},
      { view:"text", name:"user.lastname"}
    ]
});

form.setValues({
    user:{
        firstname:"Mark",
        lastname:"Varuno"
    }
})

See also

  • api
    • setValues
    • getValues
  • samples
    • Property sheet::Data with complex properties
    • Form:Data with complex properties
    • Details

    In this mode it is possible to use complex data object for getValues and setValues operations.


elements

collection of subviews

array elements;

Example

webix.ui({
    view:"form",
    elements:[
        {view:"text", label:"First Name"},
        {view:"text", label:"Last Name"}
    ]
});


elementsConfig

settings, which will be applied to all nested inputs

hash elementsConfig;

Example

webix.ui({
    view:"form",
    elements:[
        {view:"text", label:"First Name"},
        {view:"text", label:"Last Name"}
    ],
    elementsConfig:{
        labelPosition:"top"
    }
});


rows

array of views objects arranged vertically

array rows;

Example

// layout example
webix.ui({
    rows:[
        { view:"toolbar", ... },
        {
            cols:[
                { view:"list", ... },
                { view:"form", ... }
        ]}
    ]
})

See also

  • api
    • cols
  • samples
    • Layout and Resizer
  • articles
    • Layout and Resizer


rules

defines a set of rules for input field(s) of the form(htmlform)

rules;

Example

webix.ui({
    view:"form",
    elements: [..],
    rules:{
        login: rule1,
        email: rule2
    }
});

See also

  • api
    • rules
  • articles
    • Data Validation
    • Details

    Rules object contains hash of key value pairs where:

    • key - form field name, data key used for component template, datatable colimn ID.
    • value - the rule applied. Can be predefined or custom (any function can be a rule).


type

defines the layout borders

string type;

Values

  • line
    cells with border (default)
  • clean
    cells without border
  • wide
    cells with border and small space between siblings
  • space
    cells with border and wide space between siblings
  • head
    similar to "wide", but there is any border between the first and second cells

    • Example

    webix.ui({
    type: "space",
    rows: [
    ...
    ]
});

    See also

  • samples
    • Complex Accordion
  • articles
    • Setting Borders to the Components


Events

onAfterLoad | fires after server side loading is complete
onAfterScroll | fires when to component is scrolled in any direction
onAfterValidation | fires after data has been validated
onBeforeLoad | occurs immediately before data loading has been started
onBeforeValidate | called before running validation
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when data in the input or related form/toolbar is changed
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onSubmit | fires when enter key is pressed for a focused control in the form
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully
onValues | fires after values have been set within toolbar or form


onAfterLoad

fires after server side loading is complete

void onAfterLoad(){ ... };

Example

some.attachEvent("onAfterLoad", function(){
    //... some code here ...
});

See also

  • api
    • onAfterLoad
  • articles
    • Data Loading
    • Supported Data Types


onAfterScroll

fires when to component is scrolled in any direction

void onAfterScroll(){ ... };

Example

view.attachEvent("onAfterScroll", function(){
    //code
});


onAfterValidation

fires after data has been validated

void onAfterValidation(boolean result,object value){ ... };

Parameters

result | boolean | result of validation (true or false)
value | object | object with data that has been validated

Example

dp.attachEvent("onAfterValidation", function(result, value){
    //code
});

See also

  • api
    • onBeforeValidate
  • samples
    • 'onAfterValidation' Event
  • articles
    • Data Validation
    • Event Handling


onBeforeValidate

called before running validation

void onBeforeValidate(){ ... };

Example

dp.attachEvent("onBeforeValidate", function(){...});

Details

Can be used to finalize changes

See also

  • api
    • onAfterValidation
  • articles
    • Data Validation
    • Event Handling


onChange

fires when data in the input or related form/toolbar is changed

void onChange(string newv,string oldv){ ... };

Parameters

newv | string | the new value typed into the field
oldv | string | the initial value in the field

Example

$$("form1").elements["login"].attachEvent("onChange", function(newv, oldv){
    //"login" is name of related form field
    webix.message("Value changed from: "+oldv+" to: "+newv);
});
//or
$$("form1").attachEvent("onChange", function(newv, oldv){
    webix.message("Value changed from: "+oldv+" to: "+newv);
});

Details

The event fires only in case some value is changed by user in browser. If values are set programmatically (with setValues method) the onValues will fire instead.

See also

  • api
    • validate
    • onValues
  • samples
    • 'onChange' Event
  • articles
    • Form


onSubmit

fires when enter key is pressed for a focused control in the form

void onSubmit(WebixView view,Event ev){ ... };

Parameters

view | WebixView | an object of a control for which "enter" was stroked
ev | Event | keydown event object

See also

  • articles
    • Form
    • HTMLform


onValidationError

fires when the form fails to pass validation

void onValidationError(string key,object obj){ ... };

Parameters

key | string | data key that is being validated
obj | object | data object

Example

view:"form",
on:{
    onValidationError:function(key, obj){
        var text;

        if (key == "login")
            text = "Login can't be empty";
        if (key == "email")
            text = "Invalid Email";

        webix.message({ type:"error", text:text });
    }
}

See also

  • api
    • validate
    • rules
    • onValidationSuccess
  • samples
    • 'onValidationError' Event
  • articles
    • Data Validation


onValidationSuccess

fires after the form has passed validation successfully

void onValidationSuccess(){ ... };

Example

dp.attachEvent("onValidationSuccess", function(){
    //... some code here ...
});

See also

  • api
    • validate
    • onValidationError
    • rules
  • articles
    • Data Validation


onValues

fires after values have been set within toolbar or form

void onValues(){ ... };

Example

$$("myform").attachEvent("onValues", function(){
    //code
});

Details

The event fires when form or toolbar values are set programmatically with the help of a setValues() method.

When values are changed by user in browser, the onChange event is triggered instead.

See also

  • api
    • setValues
    • onValues
  • articles
    • HTMLForm and Form Treatment
    • Form
    • Toolbar


Available only in PRO Edition

ui.gridsuggest

A datatable-based suggest control..

Offers select options in the form of Webix datatable component.

Can be used standalone or as a suggest list for text, combo and richselect controls, as well as component editors.

Constructor

webix.ui({
    view:"richselect",
    value:1,
    options:{
        view:"gridsuggest",
        data:[
            {id:1, name:"One", year:1988, color:"Red"},
            {id:2, name:"Two", year:1996, color:"Blue"},
            {id:3, name:"Three", year:1997, color:"Green"},
            {id:4, name:"Four", year:2011, color:"Orange"},
            {id:5, name:"Five", year:2000, color:"Grey"},
            {id:6, name:"Six", year: 1994, color:"Yellow"}
        ]
    }
});

Where to start

  • Overview of Grid Suggest
  • Samples
Based on: ui.suggest, ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValueSuggest | some item selected in the suggest control
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.grouplist

A vertical list of items grouped into sections by some category.

The component provides navigation within the list and between the sections. Support for various data template formats, sorting and filtering features. Check grouplist documentation for more detailed description.

Constructor

var grouplist = webix.ui({
  view:"grouplist",
  scroll:false,
  data:[
    {id:"root", value:"Films data", open:true, data:[
      { id:"1", open:true, value:"The Shawshank Redemption", data:[
        { id:"1.1", value:"Part 1" },
        { id:"1.2", value:"Part 2"}
      ]}
    ]}
  ]
});

Where to start

  • Overview of the Grouplist Widget
  • Samples
Based on: Group, ui.list, KeysNavigation, DataMove, DragItem, MouseEvents, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, CopyPaste
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getOpenState | gets IDs of items taking part in the current group opening
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
templateBack | an html template that defines data that will be presented in group header in the expanded state
templateCopy | sets the template according to which data will be copied to the clipboard
templateGroup | an html template that defines data that will be presented in group header in the collapsed state
templateItem | an html template that defines data that will be presented in grouplist
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getOpenState | gets IDs of items taking part in the current group opening
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


getOpenState

gets IDs of items taking part in the current group opening

object getOpenState();

Returns

object object containing an array all parents to this level and an array of items from the currently opened group

Example

webix.ui({
    view:"grouplist",
    data:[ //hierarchical JSON dataset
        {id:"root", value:"Films data", open:true, data:[
            { id:"1", open:true, value:"The Shawshank Redemption", data:[
                { id:"1.1", value:"Part 1" },
                { id:"1.2", value:"Part 2", data:[
                    { id:"1.2.1", value:"Page 1" },
                    { id:"1.2.2", value:"Page 1" }
                    ]},
                { id:"1.3", value:"Part 3" }
            ]},
            { id:"2", open:true, value:"The Godfather", data:[
                { id:"2.1", value:"Part 1" }
            ]}
        ]}
});

var state = $$('grouplist1').getOpenState();
if(state){
    result = JSON.stringify(state);
    webix.message(result);
    }
};

/*
If you open the "root" branch, there go to "1" and then open the "1.2"
{
    "parents":["root","1","1.2"],
    "branch":["1.2.1","1.2.2"]
}
*/

Details

The return object contains two properties:

  • parents (array )- ID of the all parents (parents of the currently opened group from lower ot upper level);
  • branch (array)- IDs of the items from the currently opened group.

On the upper level with all the groups closed, "parents" will be empty.

In case you use non-hierarchical data and form groups(parents) on the go during component init, they take automatically generated IDs.

{
    "parents":["1363185715932"], <- auto ID
    "branch":[125,169,184,189]
}

If needed each of the array can be accessed as well as attributes of each data item:

function get_children(){
            var state = $$('group').getOpenState().branch; //gets only children
            titles = [];
            for (var i=0; i<state.length; i++){
                var id = state[i];
                var title = $$('group').getItem(id).title;
                titles.push(title);
            }
            alert(titles.join(",\n")); //get all the titles of the children

        };

See also

  • samples
    • Getting Grouplist State
  • articles
    • Grouplist


refresh

repaints the whole view or a certain item

void refresh( [id id] );

Parameters

id id the item id. If the parameter is set, just the specified item will be repainted

Example

$$("button1").define("label", "New value");
$$("button1").refresh();

See also

  • articles
    • render


Properties

animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
templateBack | an html template that defines data that will be presented in group header in the expanded state
templateCopy | sets the template according to which data will be copied to the clipboard
templateGroup | an html template that defines data that will be presented in group header in the collapsed state
templateItem | an html template that defines data that will be presented in grouplist
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items


templateBack

an html template that defines data that will be presented in group header in the expanded state

string| template templateBack;

Example

webix.ui({
    view:"grouplist",
    id:"mylist",
    url:"data.xml",
    datatype:"xml",
    type:{
        templateItem:"#name# (#author#)",
        templateGroup:"#name#",
        templateBack:"#name#",
    }
});

See also

  • api
    • templateGroup
    • templateItem
    • templateCopy
  • samples
    • List: Grouping
  • articles
    • Grouplist


templateCopy

sets the template according to which data will be copied to the clipboard

function templateCopy;

Example

webix.ui({
    view:"list",
    ...
    clipboard: "custom",
    templateCopy: function(item) {
        return [item.title, item.year, item.votes, item.rating, item.rank].join(" , ")
    }
});

See also

  • api
    • clipboard
    • templateItem
    • templateBack
    • templateGroup
  • samples
    • List: Grouping
  • articles
    • Working with the clipboard
    • Grouplist
    • Details

    As a parameter, the template function takes the data item object.


templateGroup

an html template that defines data that will be presented in group header in the collapsed state

string| function templateGroup;

Example

webix.ui({
    view:"grouplist",
    id:"mylist",
    url:"data.xml",
    datatype:"xml",
    type:{
        templateItem:"#name# (#author#)",
        templateGroup:"#name#",
        templateBack:"#name#",
    }
});

See also

  • api
    • templateBack
    • templateItem
    • templateCopy
  • samples
    • List: Grouping
  • articles
    • Grouplist


templateItem

an html template that defines data that will be presented in grouplist

string| function templateItem;

Example

webix.ui({
    view:"grouplist",
    id:"mylist",
    url:"data.xml",
    datatype:"xml",
    type:{
        templateItem:"#name# (#author#)",
        templateGroup:"#name#",
        templateBack:"#name#",
    }
});

See also

  • api
    • templateGroup
    • templateBack
    • templateCopy
  • samples
    • List: Grouping
  • articles
    • Grouplist


type

object that specifies items presentation

object| string type;

Example

list = webix.ui({
    view:"list",
    ...
    type:{
        height:50
    }
})

See also

  • samples
    • Search Field
  • articles
    • Data Templates
    • Type Implementation
    • Details

    Attributes of the type object:

    • css - (string) the name of a css class that will be applied to component's items (the default name of the applied class is 'default').
    • height - (number) the height of an item in the component.
    • templateItem - (function, string) an html template that defines data that will be presented in the component.
    • templateGroup - (function, string) an html template that defines data that will be presented in the group header in the collapsed state.
    • templateBack - (function, string) an html template that defines data that will be presented in the group header in the expanded state.
    • width - (number) the width of the items list.

    As a function, templateItem, templateGroup and templateBack takes a data item object.


Events

onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


ui.headerlayout

A horizontal or vertical layout with the header(s).

The component consists of cells arranged vertically or horizontally. The header is an optional part of the cell, i.e. in one and the same layout some cells can be with headers, some cells - without. By clicking on the header the user can collapse/expand the related cell. Check layout documentation for more detailed description.

Constructor

var headerlayout = webix.ui({
  cols:[
    { header:"col 1", body:"content 1", width:150},
    { header:"col 2", body:"content 2", width:150},
    { header:"col 3", body:"content 3", width:150}
  ]
});

Where to start

  • Overview of Headerlayout
  • Samples
Based on: ui.accordion, ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterCollapse | fires after an item collapses in the accordion
onAfterExpand | fires after an item expands in the accordion
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
collapsed | 'says' to display initially all accordion cells collapsed
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multi | enables/disables mode when several panels can be visible at once
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
panelClass | returns the name of a css class applied to the accordion panels
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.htmlform

A control for integration with an HTML form.

The component allows you to get an HTML Form as a lib-based view, so that to use it together with the other lib components (common API, techniques, architecture etc.). Check htmlform documentation for more detailed description.

Constructor

HTML.

<div class="myform">
    <div>
      <label for="title">Book title</label><br/>
      <input type="text" name="title" placeholder="Title" />
  </div>
    <div>
      <label for="author">Author</label><br/>
      <input type="text" name="author" placeholder="Author" />
  </div>
</div>

JS.

var htmlform = webix.ui({
  view:"htmlform",
  id:"formView",
  padding:5,
  content:document.body
});

Where to start

  • Overview of the HTMLform Widget
  • Samples
Based on: ui.template, Scrollable, AtomDataLoader, AtomRender, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Values
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes focus from the component
callEvent | calls an inner event
clear | clears all the field in a specified form
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus into the necessary component
getChildViews | returns child views of the calling component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives input values from the form
hasEvent | checks whether the component has the specified event
hide | hides the view
isDirty | checks whether changes within form were made
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
markInvalid | marks a form control invalid
parse | loads data to the component from an inline data source
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
setContent | attaches html container to the template
setDirty | marks the form as the one with changed values and vice versa
setHTML | set hmlt for template
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterLoad | fires after server side loading is complete
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when data in the input or related form/toolbar is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValues | fires after values have been set within toolbar or form
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | lets the component autosize to its contents
borderless | used to hide the component borders
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
content | the id or node, whose content will be moved to the view
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
src | the path to an external template that is loaded by Ajax
template | the component template
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes focus from the component
callEvent | calls an inner event
clear | clears all the field in a specified form
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus into the necessary component
getChildViews | returns child views of the calling component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives input values from the form
hasEvent | checks whether the component has the specified event
hide | hides the view
isDirty | checks whether changes within form were made
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
markInvalid | marks a form control invalid
parse | loads data to the component from an inline data source
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
setContent | attaches html container to the template
setDirty | marks the form as the one with changed values and vice versa
setHTML | set hmlt for template
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


blur

removes focus from the component

void blur();

Example

$$("htmlform1").blur();


clear

restores initial form values

void clear( [boolean all] );

Parameters

all boolean if true, all form fields are completely cleared

Example

function clear_form() {
   $$('myform').clear();
}

See also

  • samples
    • Binding to List
  • articles
    • HTMLForm and Form Treatment


setContent

attaches html container to the template

void setContent(any node);

Parameters

node any HTML node, or ID of html element that need to be attached

Example

//assuming that we have <div id="a12">Content</div>
$$("mytemplate").setContent( document.getElementById("a12") );
//or
$$("mytemplate").setContent( "a12");

Details

Works similar to the content property


setHTML

set hmlt for template

void setHTML(string html);

Parameters

html string html to set in template

Example

$$("view").setHTML("<h2>My app name</h2>");

Details

Data and templating rules will not be applied, method will set provided html as is.


Properties

animate | defines or disables view change animation.
autoheight | lets the component autosize to its contents
borderless | used to hide the component borders
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
content | the id or node, whose content will be moved to the view
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
src | the path to an external template that is loaded by Ajax
template | the component template
url | the URL which the component will use to load data after its initialization
width | sets the width of the component


autoheight

lets the component autosize to its contents

autoheight;

Example

webix.ui({
rows:[
        { template:"html->my_box1", autoheight:true},
        { template:"Area 1"},
        { template:"html->my_box2", autoheight:true}
      ]
})

See also

  • samples
    • Autosizing to Content
  • articles
    • Sizing components


content

the id or node, whose content will be moved to the view

id|HTMLElement content;

Example

<div id="details">...</div>

webix.ui({
    view:"context",
    body:{
        content:"details"
    }
})

See also

  • samples
    • Context Menu: HTML Content
  • articles
    • Context


src

the path to an external template that is loaded by Ajax

string src;

Example

{view:"template", src:"gettext.php"}

Details

When the response is received from server, it is set as value of the view template property.


template

the component template

string|function template;

Example

{ view:"template", type:"header", template:"This is a List Header"}

See also

  • samples
    • Template as a String
    • Template as a Function
    • Template Types
  • articles
    • Template
    • Data Templates
    • Details

    1 . Above is the common text template for template component:

    2 . Data template for data-containing components:

    { view:"list", template:"#id#.#title#" }
 // the list will show ID and title of each data item from the specified datasource

    3 . Function template (takes data object and function parameter):

    { view:"list", template:function(obj){
    return "<div class='overall'><div class='rank'>"
        +obj.rank+"</div>"+
        "<div class='title'>"+obj.title+"</div></div>"
}}
//the list will show rank and title of each item styled with specified CSS

    4 . HTML templates defined within an HTML container:

    { view: "dataview", template:"html->template_container" }

    5 . HTML template defined in the external file:

    { view:"dataview", template:"http->template.html" }

    6 . Template component can load the external template by Ajax:

    { view:"template", src:"loadtext.php" }


Events

onAfterLoad | fires after server side loading is complete
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when data in the input or related form/toolbar is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValues | fires after values have been set within toolbar or form
onViewResize | view size was changed by resizer


ui.icon

A static picture of an icon.

The component provides a collection of popular icons and API for their handling. Check icon documentation for more detailed description.

Constructor

var icon = webix.ui({
   view:"icon",
   icon: "envelope",
   align:"left"
});

Where to start

  • Overview of the Icon Control
  • Samples
Based on: ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | the component's icon
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | the component's icon
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
value | sets the initial value for a control
width | sets the width of the component


icon

the component's icon

string icon;

Example

webix.ui({
    view:"icon",
    icon:"bars",
    ...
});


ui.iframe

A view with the IFRAME element inside it.

If you want to place some IFRAME content, note that the component provides much more flexible way to do this than a usual layout.

Check templates for example. Check iframe documentation for more detailed description.

Constructor

var iframe = webix.ui({
    view:"iframe",
    id:"frame-body",
    src:"//docs.webix.com/samples/80_docs/data/pageA.html"
});

Where to start

  • Overview of the IFrame Widget
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getIframe | returns html element of inner iframe
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getWindow | gets the window object of an iframe
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads a document you'd like to show in the iframe
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterLoad | fires after an HTML page was loaded to the component
onAfterScroll | occurs when some webix view has been scrolled
onBeforeLoad | fires before HTML page starts to load
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
src | the URL of a document you'd like to show in an iframe
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getIframe | returns html element of inner iframe
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getWindow | gets the window object of an iframe
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads a document you'd like to show in the iframe
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getIframe

returns html element of inner iframe

HTMLElement getIframe();

Returns

HTMLElement html element of inner iframe

Example

var frame = $$("myframe").getIframe();


getWindow

gets the window object of an iframe

HTMLElement getWindow();

Returns

HTMLElement the dom element of the window

See also

  • articles
    • IFrame


load

loads a document you'd like to show in the iframe

void load(string value);

Parameters

value string the URL of the document

Example

$$("my_iframe").load("google.com");

Details

The source for iframe content can be defined in its constructor by the src property.

See also

  • api
    • src
  • articles
    • IFrame


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
src | the URL of a document you'd like to show in an iframe
width | sets the width of the component


src

the URL of a document you'd like to show in an iframe

string src;

Example

webix.ui({
    view:"iframe",
    id:"frame-body",
    src:"http://data/pageA.com"
});

See also

  • api
    • load
  • articles
    • IFrame


Events

onAfterLoad | fires after an HTML page was loaded to the component
onAfterScroll | occurs when some webix view has been scrolled
onBeforeLoad | fires before HTML page starts to load
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterLoad

fires after an HTML page was loaded to the component

void onAfterLoad(){ ... };

Example

$$('myIframe').attachEvent("onAfterLoad",function(){
           alert("Loading is finished!");
});

Details

Note, the event will be envoked only if you load page(s) from the same domain the page with the Iframe view resides.

See also

  • api
    • onBeforeLoad
  • articles
    • Data Loading


onBeforeLoad

fires before HTML page starts to load

void onBeforeLoad(){ ... };

Example

$$('myIframe').attachEvent("onBeforeLoad",function(){
           alert("Loading is starting!");
});

See also

  • api
    • onAfterLoad
  • articles
    • Data Loading


ui.label

A non-editable text control.

The component is used to display static text on a page. Check label documentation for more detailed description.

Constructor

var label = webix.ui({
    view:"label",
    label: "Label",
    inputWidth:100,
    align:"left"
});

Where to start

  • Overview of the Label Control
  • Samples
Based on: ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setHTML | set hmlt for template
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
label | the text label of the control
labelPosition | positions label in relation to the control
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setHTML | set hmlt for template
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
label | the text label of the control
labelPosition | positions label in relation to the control
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
value | sets the initial value for a control
width | sets the width of the component


autowidth

adjusts label to its text content

boolean autowidth;

Example

{ view:"label", label:"My label", autowidth:true }


ui.layout

A vertical or horizontal layout without the headers.

The component allows you to programmatically define interface structure by organizing views in a vertical or horizontal layout. By including layouts one by one, it's possible to create the final screen of any complexity. Check layout documentation for more detailed description.

Constructor

var layout = webix.ui({
    rows:[
        {template:"row 1"},
        {template:"row 2"},
        {
            cols:[
                {template:"col 1"},
                {template:"col 2"}
            ]
        }
    ]
});

Where to start

  • Overview of the Layout Widget
  • Samples
Based on: ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


Events

onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed


ui.list

A regular list of items.

The component serves as the base class that defines properties, methods, and events common for all list-type controls. Check list documentation for more detailed description.

Constructor

var list = webix.ui({
  view:"list",
  width:250,
  height:200,
  template:"#title#",
  select:true,
  data:[
    { id:1, title:"Item 1"},
    { id:2, title:"Item 2"},
    { id:3, title:"Item 3"}
  ]
});

Where to start

  • Overview of the List Widget
  • Samples
Based on: KeysNavigation, DataMove, DragItem, MouseEvents, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, CopyPaste
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


Properties

animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items


pager

defines paging configuration ( creates a 'ui.pager' object)

string| object pager;

Example

webix.ui({
    view:"datatable",
    pager:{
        container:"paging_here",
        size:100,
        group:5
    }
})

See also

  • api
    • ui.pager
  • samples
    • List: Pagination
  • articles
    • Paging
    • Details

    The parameter has the following attributes:

    • container - the container where the pager controls will be placed into;
    • size - the number of records per page;
    • group - the number of pages in the pager.


ui.menu

A menu of individually selectable items.

The component can be displayed in 2 modes: static (the menu is fully expanded all the time) and dynamic (only the parent item is static, while its childs are displayed only when the user holds the mouse pointer over the parent). You can configure any nesting level complexity. Check menu documentation for more detailed description.

Constructor

var menu = webix.ui({
    view:"menu",
    data:[
        {id:1, value:"Translate", submenu:["English", "French", "German"]},
        {id:2, value:"Post"},
        {id:3, value:"Info"}
    ],
    type:{
        subsign:true,
    }
});

Where to start

  • Overview of the Menu Widget
  • Samples
Based on: ui.list, KeysNavigation, DataMove, DragItem, MouseEvents, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, CopyPaste
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
disableItem | disables menu item
enable | enables the calling view that was disabled by the 'disable' method
enableItem | enables menu item
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getMenu | gets object of a menu/submenu where an item is located
getMenuItem | search for menu item in submenus
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getSubMenu | gets the submenu object of a menu item (if any)
getTopMenu | returns top menu object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideItem | hides menu item
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sizeToContent | adjusts the size of menu and its submenus to their content
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMenuItemClick | fires when menu item has been clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
openAction | alters the way of submenu opening to "click"
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subMenuPos | aligns submenu towards main menu
submenuConfig | defines submenu configuration
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
disableItem | disables menu item
enable | enables the calling view that was disabled by the 'disable' method
enableItem | enables menu item
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getMenu | gets object of a menu/submenu where an item is located
getMenuItem | search for menu item in submenus
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getSubMenu | gets the submenu object of a menu item (if any)
getTopMenu | returns top menu object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideItem | hides menu item
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sizeToContent | adjusts the size of menu and its submenus to their content
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


filter

filters the component

void filter(template|function text,string value,boolean preserve);

Parameters

text | template|function | a template of filtered value or function
value | string | the filtering mask
preserve | boolean | if set to true, each next filtering criteria will be applied to the already filtered list

Example

//filters all fields with 'abc' in the 'text' property
//using a template
list.filter('#text#',"abc")

//using a function
list.filter(function(obj){
    return obj.text.toString().indexOf("abc") != -1;
});

See also

  • api
    • samples
      • List: Filtering
    • articles
      • DataTable Filtering
      • Filtering in the Tree
      • Data Filtering and Sorting


getSubMenu

gets the submenu object of a menu item (if any)

object getSubMenu(string| number id);

Parameters

id string| number menu item ID

Returns

object object of a child menu (submenu), if any

Example

$$("mymenu").getSubmenu(id);

Details

The method helps retrieve properties of submenu items:

$$("mymenu").attachEvent("onItemClick", function(id){
    var submenu = this.getSubMenu(id);
    if(submenu)
        //returns text value of a clicked menu item
        webix.message("Click: " + submenu.getItem(id).value);
});

See also

  • api
    • getMenu
  • articles
    • Menu


Properties

animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
openAction | alters the way of submenu opening to "click"
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subMenuPos | aligns submenu towards main menu
submenuConfig | defines submenu configuration
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items


autowidth

adjusts the width of Submenus to their labels

boolean autowidth;

Example

webix.ui({
    view:"menu",
    autowidth:true,
    data:[
        { id:"1",value:"Short...",
            submenu:[ "FB", "G+", "TW" ]},
        { id:"2",value:"Medium...",
            submenu:[ "Facebook", "Google+", "Twitter" ]},
        ...
    ]
});

See also

  • samples
    • Autowidth for Submenus
  • articles
    • Menu


type

object that specifies items presentation

object| string type;

Example

webix.ui({
    view:"menu",
    type:{
        subsign:true
    },
    ..//config
});

See also

  • samples
    • Basic Menu
  • articles
    • Data Templates
    • Type Implementation
    • Details

    Attributes of the type as object:

    • css - (string) the name of a css class that will be applied to component's items (the default name of the applied class is 'default').
    • height - (number) the height of an item in the component.
    • template - (function, string) an html template that will define item presentation in the component.
    • width - (number) the width of the items list.
    • subsign - (bool) - for menu: if true shows an array of menu items that feature a submenu.

    Named type

    It is possible to create a type object separately and then refer to it by its name:

    webix.type(webix.ui.dataview,{
    name:"typeA",
    width: 260,
    height: 90
});

webix.ui({
    view:"dataview",
    type:"typeA",
    ..
});

    Related sample: Named Templates

    More information about Type Implementation can be found in a separate article of the main documentation.


Events

onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMenuItemClick | fires when menu item has been clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


Available only in PRO Edition

ui.multicombo

An editable combo box that allows choosing several options from a suggest list at once..

The control combines an editable text field with a suggest list that contains predefined options. Each option has a checkbox which is checked if the option is selected. The list can be supplied with a customizable 'Select' button to enter selected items to the input.

Check multicombo documentation for more detailed description.

Constructor

var multicombo = webix.ui({
    view:"multicombo",
    label:"To",
    value:"1,3",
    options:[
        {"id":1,"value":"Ray M. Parra"},
        {"id":2,"value":"Sabrina N. Hermann"},
        {"id":3,"value":"Lane E. Dion"},
        {"id":4,"value":"Bradly N. Mauro"}
    ]
});

Where to start

  • Overview of the Multicombo Control
  • Samples
Based on: ui.richselect, ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getList | returns list view of the control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | returns text of currently selected option
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
button | defines whether the "Select" button will be displayed in the options list;
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
iconWidth | sets icon width
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
keepText | defines whether the entered text should be kept in the input after an option is selected
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
master |
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
newValues | allows to enter new values into a multicombo field
on | allows attaching custom handlers to inner events of the component
optionWidth | sets the width of the suggest list with options
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | a delimiter for separating options in a multicombo, comma by default
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tagMode | defines presentation mode of input values
tagTemplate | defines template of input values
text | visible text in the related input
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
button | defines whether the "Select" button will be displayed in the options list;
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
iconWidth | sets icon width
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
keepText | defines whether the entered text should be kept in the input after an option is selected
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
master |
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
newValues | allows to enter new values into a multicombo field
on | allows attaching custom handlers to inner events of the component
optionWidth | sets the width of the suggest list with options
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | a delimiter for separating options in a multicombo, comma by default
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tagMode | defines presentation mode of input values
tagTemplate | defines template of input values
text | visible text in the related input
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


button

defines whether the "Select" button will be displayed in the options list

boolean button;

Example

webix.ui({
    view:"multicombo",
    button:true
});


iconWidth

sets icon width

string iconWidth;

Example

{ view:"multitext", iconWidth:50}

See also

  • api
    • icon
  • articles
    • Multitext
    • Icons with UI Components
    • Details

    The default iconWidth is 20px.


keepText

defines whether the entered text should be kept in the input after an option is selected

boolean keepText;

Example

{ view:"multicombo", keepText:true}


master

master;


newValues

allows to enter new values into a multicombo field

boolean newValues;

Example

{ view:"multicombo", newValue:true, options:[...]}

Details

If set, the property allows users to enter new itmes into the input field even if there're no corresponding options in the suggest list.


optionWidth

sets the width of the suggest list with options

number optionWidth;


options

defines data items of the drop-down list

object options;

Example

webix.ui({
    view:"richselect",
    value:1, //the initially selected one
    label: 'Fruit',
    options:[
        { value:1, label:"Banana"},
        { value:2, label:"Papai" },
        { value:3, label:"Apple" }
    ]
});

webix.ui({
    view:"richselect",
    options:["Banana", "Papai", "Apple"]
});

webix.ui({
    view:"richselect", options:"server/options.php"
});

See also

  • api
    • getValue
    • setValue
    • value
  • samples
    • Non-editable Combo Box ('richselect')
  • articles
    • Controls Guide
    • Details

    Each option presents a singular select option in the drop-down list. Options can be set as:

    • a simple array;
    • an associative array of objects with id and value properties;
    • a string with a path to a script that loads options from server.

    The initially selected option is defined by a value property.


separator

a delimiter for separating options in a multicombo, comma by default

string separator;

Example

{
    view:"multicombo",
    label:"Name",
    labelPosition: "top",
    value:"1|7|9|12",
    separator: "|", //data contains commas
    ...
}

See also

  • articles
    • Multicombo


tagMode

defines presentation mode of input values

boolean tagMode;

Example

{ view:"multicombo", tagMode:false}

See also

  • api
    • tagTemplate
  • samples
    • MultiSelect combobox
    • Details

    With tagMode enabled the control shows the titles of all the chosen items in the input field. Otherwise, it shows only their count, e.g. 'Two item(s)', which can be configured by tagTemplate.

    True by default.


tagTemplate

defines template of input values

function tagTemplate;

Example

{ view:"multicombo", tagMode:false, tagTemplate: function(values){
    return (values.length? values.length+" item(s) selected":"");
}}

See also

  • api
    • tagMode
  • samples
    • MultiSelect combobox
    • Details

    The setting should be coupled with tagMode disabled, otherwise the titles of the chosen values will be displayed in the input field.

    By default, tagTemplate shows the count of the chosen values as "Two item(s)".


Others

$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


$cssName

name which will be used as part of css class

string $cssName;
Details

Can be used, to re-use css class from different control


Available only in PRO Edition

ui.multiselect

A non-editable combo box with the possibility to select several items at a time..

The control combines a non-editable text field with a drop-down list of predefined values. The list is supplied with a customizable 'Select' button to enter selected items to the input.

Check multiselect documentation for more detailed description.

Constructor

var multiselect = webix.ui({
    view:"multiselect",
    label:"Participant",
    labelWidth:100,
    options:[
        {id:1, value:"Alex Brown"},
        {id:2, value:"Dan Simons"},
        {id:3, value:"Gron Alanski"},
        {id:4, value:"Dan Alanski"}
    ],
    value:"1,4"
});

Where to start

  • Overview of the Multiselect Control
  • Samples
Based on: ui.richselect, ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getList | returns list view of the control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | returns text of currently selected option
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionWidth | sets width of a popup list with options
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | sets a delimiter for control's values
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionWidth | sets width of a popup list with options
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | sets a delimiter for control's values
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


optionWidth

sets width of a popup list with options

number optionWidth;

Example

{view:"multiselect", options:[], optionWidth:200}

See also

  • api
    • options
  • articles
    • Multiselect
    • Details

    By default, the size of a popup is adjusted to the width of the master control.


options

defines data items of the drop-down list

object options;

Example

webix.ui({
    view:"richselect",
    value:1, //the initially selected one
    label: 'Fruit',
    options:[
        { value:1, label:"Banana"},
        { value:2, label:"Papai" },
        { value:3, label:"Apple" }
    ]
});

webix.ui({
    view:"richselect",
    options:["Banana", "Papai", "Apple"]
});

webix.ui({
    view:"richselect", options:"server/options.php"
});

See also

  • api
    • optionWidth
    • getValue
    • setValue
    • value
  • samples
    • Multi-select input
  • articles
    • Controls Guide
    • Details

    Each option presents a singular select option in the drop-down list. Options can be set as:

    • a simple array;
    • an associative array of objects with id and value properties;
    • a string with a path to a script that loads options from server.

    The initially selected option is defined by a value property.


separator

sets a delimiter for control's values

string separator;

Example

{view:"multitext", separator:"-"}

Details

The delimiter is used in the setValue method and in the result of the getValue method.

By default multitext values are separated by a comma (",").


Available only in PRO Edition

ui.multisuggest

A suggest control with a multiple-choice list..

Offers select options in the form of Webix list component with the ability to select multiple items at a time.

Can be used standalone or as a suggest list for text, combo and richselect controls as well as component editors.

Constructor

webix.ui({
    view:"richselect",
    label:"Data",
    value:1, options:{
        view:"multisuggest",
        data:[
            { id:1, value:"Alex Brown" },
            { id:2, value:"Dan Simons" },
            { id:3, value:"Gron Alanski" },
            { id:4, value:"Dan Alanski" }
        ]
    }
});

Where to start

  • Overview of the Multisuggest Control
  • Samples
Based on: ui.suggest, ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getButton | get button object of a multiselect popup
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValueSuggest | some item selected in the suggest control
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
button | sets a button at the bottom of the suggest
buttonText | defines text for the 'Select' button
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
separator | sets a delimiter for multisuggest values
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
value | sets the initial value for a control
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getButton | get button object of a multiselect popup
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getButton

get button object of a multiselect popup

WebixView getButton();

Returns

WebixView webiv ui object of button

Example

multiselect.getPopup().getButton();

Details

Multisuggest object can be easily accessed from the control:

multiselect.getPopup();

See also

  • articles
    • Multiselect
    • Suggest List


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
button | sets a button at the bottom of the suggest
buttonText | defines text for the 'Select' button
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
separator | sets a delimiter for multisuggest values
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
value | sets the initial value for a control
width | sets the width of the component
zIndex | stack order of the component


button

sets a button at the bottom of the suggest

boolean button;

Example

{
    view:"multicombo",
    label:"Name",
    ...
    button: true
}

See also

  • articles
    • Multiselect


buttonText

defines text for the 'Select' button

string buttonText;

Example

{view:"multiselect", label:"Participant",options:{
     buttonText:"Click options to select/deselect",
     data:[
        { id:1, value:"Alex Brown" },
        { id:2, value:"Dan Simons" }
     ]
}}

See also

  • articles
    • Multiselect


separator

sets a delimiter for multisuggest values

string separator;

Example

{ view:"multisuggest", separator:true }

Details

The property should be used if work with the multisuggest initialized separately and need to redefine the delimiter.

If it's a part of a multiselect control, use the same-name property in multiselect configuration.


Available only in PRO Edition

ui.multitext

An editable text control with dynamically added removable fields..

Check multitext documentation for more detailed description.

Constructor

var multitext = webix.ui({
  rows:[
    {
        view:"multitext",
        id:"multi",
        value:'dummy@email.com, mirror@email.com',
        label:"Email"
    }
  ]
});

Where to start

  • Overview of the Multitext Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
addSection | add new empty field to the collection
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
getValueHere | gets value of the basic field
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
removeSection | removes an additional field from the multitext group
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
setValueHere | sets value for the basic field of a multitext control
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon type
iconWidth | sets icon width
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | sets a delimiter for control's values
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

addSection | add new empty field to the collection
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
getValueHere | gets value of the basic field
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
removeSection | removes an additional field from the multitext group
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
setValueHere | sets value for the basic field of a multitext control
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


addSection

add new empty field to the collection

string| number addSection();

Returns

string| number id of the newly added field

Example

multitext.addSection();

Details

Each field of a multitext element features its own ID.

The method can be applied to any field of a multitext group - the new one will be added to the end of the group.

See also

  • api
    • removeSection
  • articles
    • Multitext


getValue

returns the current value of the control

string getValue();

Returns

string the current value of the control

Example

webix.ui({
    view:"form",
    elements:[
        { view:"button", id:"b1", value:"Edit", type:"form" },
        { view:"button", id:"b2", value:"Back", type:"form" }
    ]
});

$$('b1').getValue(); //returns "b1"

Details

The method collects values from all the fields of a multitext control and aggregates them into a string with a comma separator.

The separator can be redefined with the help of a separator property.

To get the value of the basic field only, use the getValueHere method.

Common info

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
    • getValues
    • getValueHere
    • separator
  • articles
    • Controls Guide


getValueHere

gets value of the basic field

string getValueHere();

Returns

string value in the basic input field

Example

var value = multitext.getValueHere();

Details

The method deals only with the basic (the first) field of a multitext view. To get value of the whole control, use the getValue method.

See also

  • api
    • getValue
    • setValueHere
  • articles
    • Multitext


removeSection

removes an additional field from the multitext group

void removeSection( [string| number id] );

Parameters

id string| number id of the field to remove

Example

multitext.removeSection("$multitext2");

Details

Only additional fields can be removed, even if the ID of the basic field is passed into the function.

If no ID is provided, all the additional fields are removed, only the first (basic) field remains.

See also

  • api
    • addSection
  • articles
    • Multitext


setValue

sets a new value for the component

void setValue(string value);

Parameters

value string a new value for the control

Example

//three-field multitext
miltitext.setValue("valueA, valueB, valueC");

Details

To set values for multiple multitext fields, provide a comma-separated string for this method, if other delimiter is not set by a separator property.

The values are set one after another:

  • If there are fewer values than multitext fields, the unused fields as well as their values are removed;
  • If there are more values than available multitext fields, the additional fields are added.

To set value only for the first (basic) field, use the setValueHere method. It resets only the basic field while other fields together with their values are preserved.

See also

  • api
    • getValue
    • setValueHere
    • separator
  • articles
    • Controls Guide


setValueHere

sets value for the basic field of a multitext control

void setValueHere(string| number value);

Parameters

value string| number value for the field

Example

multiselect.setValue("New value");

Details

The method deals only with the first (basic) field of the control. To set the value for the whole multitext, use the setValue method.

See also

  • api
    • getValueHere
    • setValue
    • getValue
  • articles
    • Multitext


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon type
iconWidth | sets icon width
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | sets a delimiter for control's values
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


icon

sets an icon type

string icon;

Example

{ view:"multitext", icon:"plus-square"}

See also

  • api
    • iconWidth
  • articles
    • Multitext
    • Icons with UI Components
    • Details

    Icon types are taken from FontAwesome. The default icon is a plus-circle one.


separator

sets a delimiter for control's values

string separator;

Example

{view:"multitext", separator:"-"}

See also

  • api
    • setValue
    • getValue
  • articles
    • Multitext
    • Details

    The delimiter is used in the setValue method and in the result of the getValue method.

    By default multitext values are separated by a comma (",").


onItemClick

fires after the control has been clicked

void onItemClick(string| number id,event e){ ... };

Parameters

id | string| number | control ID
e | event | event object

Example

button.attachEvent("onItemClick", function(id, e){
    //code
});

Details

If a control features several input fields, the ID of a clicked field will be passed into the event.

See also

  • api
    • click
  • samples
    • List: Active Content
  • articles
    • Event Handling


ui.multiview

A container control that keeps a set of views and displays one view at a time.

The component allows you to divide the page content into multiple groups and display a specific view based on some criteria. Often used in combination with a clickable control to implement tabbar. Check multiview documentation for more detailed description.

Constructor

webix.ui({
  rows:[
    {
      view:"segmented", id:'tabbar', value: 'View1', multiview:true, options: [
        { value: 'Form',  id: 'View1'},
        { value: 'Info',  id: 'View2'}
      ]
    },
    {   id:"mymultiview",
        cells:[
            {id:"View1",template:"Form Content"},
            {id:"View2", template:"<i>Info about the Form</i>"}
        ]
     }
   ]
});

Where to start

  • Overview of the Multiview Widget
  • Samples
Based on: ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
back | switches multiview to previously active view
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getActiveId | returns the id of the currently visible multiview cell
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns id of curren visible view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setValue | defines which view need to be shown in the multiview
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onBeforeBack | fires the moment back() fucntion is triggered
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
onViewChange | fires when the views are switched in the component (regardless of the switching method)
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cells | the array with views objects
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
fitBiggest | sizing mode of multiview
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
keepViews | specifies the mode in which multiview doesn't remove inactive views when the become hidden
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
back | switches multiview to previously active view
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getActiveId | returns the id of the currently visible multiview cell
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns id of curren visible view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setValue | defines which view need to be shown in the multiview
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


back

switches multiview to previously active view

void back(number step);

Parameters

step number how far in history we will go, 1 by default

Example

webix.ui({
    id:"views",
    cells:[ ...],
});

$$("views").back();

See also

  • api
    • show
  • samples
    • 'Show/Back' Navigation
  • articles
    • Common Functions to Switch Between Views


getActiveId

returns the id of the currently visible multiview cell

void getActiveId();

Example

$$("views").getActiveId();

See also

  • api
    • back
    • show


getValue

returns id of curren visible view

id getValue();

Returns

id id of current visible view

Example

var id = $$("mview").getValue();


setValue

defines which view need to be shown in the multiview

void setValue(id toshow);

Parameters

toshow id id of view to show

Example

$$("mview").setValue("some_view");

Details

Command is equal to view.show

    $$("mview").setValue("some_view");
    //is equal to
    $$("some_view").show();


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cells | the array with views objects
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
fitBiggest | sizing mode of multiview
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
keepViews | specifies the mode in which multiview doesn't remove inactive views when the become hidden
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


cells

the array with views objects

object cells;

Example

webix.ui({
    view:"multiview", //optional
    cells:[
        { view:"list", id:"listview", ... },
        { view:"form", id:"formview", elements:[...] }
    ]
});

See also

  • samples
    • 'Show/Back' Navigation
    • Tabbar
    • Tabview
  • articles
    • Tabview
    • Controls to Switch Between View Cells
    • Common Functions to Switch Between Views
    • Details
    • Multiview cells may contain any ui components and layout elements you like.
    • Each cell features the unique ID to apply methods like show() and back() to it.
    • If you layout features cells property object, it automatically becomes the multiview, so you needs specify view name.
    • switching between cell is implemeted with integral buttons(tabbar and segmented), tabview or dedicated functions.


fitBiggest

sizing mode of multiview

boolean fitBiggest;
Details

When enabled, multiview will size self to biggest view ( biggest tab )
By default multiview sizes self to the active view ( active tab )


keepViews

specifies the mode in which multiview doesn't remove inactive views when the become hidden

keepViews;

Example

webix.ui({
  view: "multiview",
  keepViews:true,
  cells: [
     ...
  ]
});

See also

  • articles
    • Multiview
    • Details

    the mode is actual when dealing with iframe content, e.g. WYSIWYG editors (CKEditor)


Events

onBeforeBack | fires the moment back() fucntion is triggered
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
onViewChange | fires when the views are switched in the component (regardless of the switching method)


onBeforeBack

fires the moment back() fucntion is triggered

void onBeforeBack(){ ... };

Example

some.attachEvent("onBeforeBack", function(){
    //... some code here ...
});

See also

  • api
    • back


onViewChange

fires when the views are switched in the component (regardless of the switching method)

void onViewChange(){ ... };

Example

some.attachEvent("onViewChange", function(){
    //... some code here ...
});

See also

  • articles
    • Multiview


Available only in PRO Edition

ui.organogram

An organizational chart widget for creating hierarchical diagrams.

The component supports data loading from different sources. You can customize the look and feel of Organogram items by using templates, uniting child elements of items into list blocks and redefining the applied css styles. It's also possible to create your own css style for Organogram. Check Organogram documentation for more detailed description.

Constructor

var organogram = new webix.ui({
  view:"organogram",
  data: [
     {id:"1", value:"Item 1", data:[
        { id:"1.1", value:"Item 1.1", data:[
            {id:"1.1.1", value:"Item 1.1.1", data:[]},
        ]},
        { id:"1.2", value:"Item 1.2", data:[]},
        { id:"1.3", value:"Item 1.3", data:[
            { id:"1.3.1", value:"Item 1.3.1", data:[]}
        ]},
    ]}
  ]
});

Where to start

  • Overview of the Organogram Widget
  • Samples
Based on: AutoTooltip, Group, TreeAPI, DataMarks, SelectionModel, MouseEvents, Scrollable, RenderStack, TreeDataLoader, TreeStore, DataStore, DataLoader, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
close | closes the branch with the specified id
closeAll | closes all branches in the tree
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBranchIndex | gets index of the node in a specific branch
getChildViews | returns child views of the calling component
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getState | returns the current state of the view
getTopParentView | returns top parent view
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setState | restores the specified state
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
Events
onAfterAdd | fires after adding item to datastore
onAfterClose | fires after the branch has been closed
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemCheck | called when the checkbox inside the tree item was checked
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | adjusts Organogram to the parent container size vertically
autowidth | adjusts Organogram to the parent container size horizontally
borderless | used to hide the component borders
click | sets an action happening on a button click
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
filterMode | defines the pattern for tree item filtering
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
threeState | enable three-state checkboxes
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
close | closes the branch with the specified id
closeAll | closes all branches in the tree
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBranchIndex | gets index of the node in a specific branch
getChildViews | returns child views of the calling component
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getState | returns the current state of the view
getTopParentView | returns top parent view
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setState | restores the specified state
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item


close

closes the branch with the specified id

void close(id id);

Parameters

id id the node id

Example

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"1.1", value:"Part 1" },
            { id:"1.2", value:"Part 2" }
        ]},
        { id:"branch2", value:"The Godfather", data:[
            { id:"2.1", value:"Part 1" }
        ]}
    ]
});

tree.close('branch1');

See also

  • api
    • open
    • closeAll
    • openAll
    • isBranchOpen
  • articles
    • Tree Nodes manipulations


closeAll

closes all branches in the tree

void closeAll();

Example

tree = new webix.ui({
    view:"tree",
    ...
});

tree.closeAll();

See also

  • api
    • openAll
    • close
    • open
    • closeAll
  • articles
    • Tree Nodes manipulations


getBranchIndex

gets index of the node in a specific branch

number getBranchIndex(id id, [id parent] );

Parameters

id | id | tree node ID;
parent | id | ID of the parent node.

Returns

number index of related tree node

Example

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"1.1", value:"Part 1" },
            { id:"1.2", value:"Part 2" }
        ]}
    ]
});

var index  = tree.getBranchIndex('1.1'); // -> 0
var index1 = tree.getBranchIndex('1.2'); // -> 1

Details

There is also the getIndexById method to get the node index but we don't suggest using it. It's a common method that is inherited by all data-containing components from the DataStore class and not intended for using with tree-like data structures.

For exact node specifying, pass both node ID and parent node ID into the function:

var sel = tree.getSelectedId();
var parent = tree.getParentView(sel);
tree.add({ value:"New item"}, tree.data.getBranchIndex(parent, sel), parent);

See also

  • articles
    • Getting/setting the node


getFirstChildId

gets the ID of the first child of the specified branch

string getFirstChildId(id id );

Parameters

id id the parent (branch) id

Returns

string returns the id of the first child of the specified branch. If there are not any, returns null

Example

tree.data.getFirstChildId(tree.getSelectedId());
    //returns the ID of the first child of selected item

See also

  • api
    • getParentId
  • articles
    • Getting/setting the node


getNextSiblingId

returns the id of the next sibling of the specified node

id getNextSiblingId( id);

Parameters

id id ID of the node in question

Returns

id ID of the next sibling or false if there isn't any

Example

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"part1", value:"Part 1" },
            { id:"part2", value:"Part 2" }
        ]}
    ]
});

$$('tree1').getNextSiblingId("part1"); // returns 'part2'

See also

  • api
    • getPrevSiblingId
  • articles
    • Getting/setting the node


getOpenItems

returns ids of the opened branches

array getOpenItems();

Returns

array an array of ids

Example

tree = new webix.ui({
        view:"tree",
        ...
})
tree.getOpenItems();

Details

For example, for the tree as in:

data: [
    {id:"root", value:"Cars", open:true, data:[
        { id:"1", open:true, value:"Toyota", data:[
            { id:"1.1", value:"Avalon" },
            { id:"1.2", value:"Corolla" },
            { id:"1.3", value:"Camry" }
        ]},
        { id:"2", value:"Skoda", open:true, data:[
            { id:"2.1", value:"Octavia" },
            { id:"2.2", value:"Superb" }
        ]}
    ]}
]

the method returns the following array:

["1", "2", "root"]

See also

  • articles
    • Tree Nodes manipulations


getParentId

get the ID of the parent node of the specified item

id getParentId(id id );

Parameters

id id ID of the child node

Returns

id ID of the parent node

Example

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"part1", value:"Part 1" },
            { id:"part2", value:"Part 2" }
        ]}
    ]
});

var child = tree.getParentId('part1'); // -> 'branch1'

See also

  • api
    • getFirstChildId
  • articles
    • Getting/setting the node


getPrevSiblingId

returns the id of the previous sibling of the specified node

id getPrevSiblingId( id);

Parameters

id id ID of the node in question

Returns

id ID of the previous sibling or false if there isn't any

Example

tree = new webix.ui({
    view:"tree",
    data: [
        { id:"branch1", value:"The Shawshank Redemption", data:[
            { id:"part1", value:"Part 1" },
            { id:"part2", value:"Part 2" }
        ]}
    ]
});

$$('tree1').getPrevSiblingId("part2"); // returns 'part1'

See also

  • api
    • getNextSiblingId
  • articles
    • Getting/setting the node


getState

returns the current state of the view

object getState();

Returns

object the state object

Example

tree.getState();

Details

The state object reflects UI configuration of the view.

For example, for Tree shown below:

the state object will look as in:

{
    open: ["1","root"],
    select:["1.2"],
}

See also

  • api
    • setState
  • articles
    • Tree Nodes manipulations


isBranch

checks whether the node has any children

boolean isBranch(id id );

Parameters

id id ID of the branch in question

Returns

boolean true, if the branch has at least one child, false, if there are no children

Example

tree.isBranch('branch1');


isBranchOpen

checks whether the specified branch is open or closed

boolean isBranchOpen(id id);

Parameters

id id the node id

Returns

boolean true, if the branch is opened, otherwise - false

Example

tree = new webix.ui({
    view: "tree",
    data: [
        { id: "branch1", value: "The Shawshank Redemption", data: [
            { id: "1.1", value: "Part 1" },
            { id: "1.2", value: "Part 2" }
        ]},
        { id: "branch2", value: "The Godfather", data: [
            { id: "2.1", value: "Part 1" }
        ]}
    ]
});

tree.isBranchOpen("branch1");

See also

  • api
    • open
    • close
    • closeAll
    • openAll
  • articles
    • Tree Nodes manipulations


loadBranch

loads data to the specified branch, as direct children of the node with the id provided

void loadBranch(id id ,function callback ,string url);

Parameters

id | id | branch ID
callback | function | callback function
url | string | data URL

See also

  • samples
    • Loading Branch Data
  • articles
    • Dynamic Loading for Hierarchical Data Structures


open

opens the branch with the specified id

void open(string/number id, [boolean show] );

Parameters

id | string/number | the node id
show | boolean | if true, opens all parent of the branch

Example

tree = new webix.ui({
    view: "tree",
    data: [
        { id: "branch1", value: "The Shawshank Redemption", data: [
            { id: "1.1", value: "Part 1" },
            { id: "1.2", value: "Part 2" }
        ]},
        { id: "branch2", value: "The Godfather", data: [
            { id: "2.1", value: "Part 1" }
        ]}
    ]
});

tree.open("branch1");

Details

To learn when the open() call has completed loading dynamic data, you can set a promise in onDataRequest and check for it in onAfterOpen - see this example.

See also

  • api
    • close
    • openAll
    • closeAll
    • isBranchOpen
  • articles
    • Tree Nodes manipulations


openAll

opens all branches in the tree

void openAll();

Example

tree = new webix.ui({
    view:"tree",
    ...
});

tree.openAll();

See also

  • api
    • open
    • closeAll
    • openAll
    • isBranchOpen
  • articles
    • Tree Nodes manipulations


setState

restores the specified state

void setState(object state);

Parameters

state object the state object

Example

webix.storage.local.put("state", tree.getState());
...

var state = webix.storage.local.get("state");
if (state)
    tree.setState(state);

See also

  • api
    • getState
  • articles
    • Tree Nodes manipulations


Properties

animate | defines or disables view change animation.
autoheight | adjusts Organogram to the parent container size vertically
autowidth | adjusts Organogram to the parent container size horizontally
borderless | used to hide the component borders
click | sets an action happening on a button click
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
filterMode | defines the pattern for tree item filtering
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
threeState | enable three-state checkboxes
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component


autoheight

adjusts Organogram to the parent container size vertically

boolean autoheight;

Example

webix.ui({
    view:"organogram",
    autoheight:true,
    ...
});

See also

  • api
    • autoheight
  • samples
    • Height adjustment


autowidth

adjusts Organogram to the parent container size horizontally

boolean autowidth;

Example

webix.ui({
    view:"organogram",
    autowidth:true,
    ...
});

See also

  • api
    • autowidth
  • samples
    • Width adjustment


filterMode

defines the pattern for tree item filtering

object filterMode;

Example

view:"tree",
filterMode:{
    showSubItems:false,
    level:2
}

See also

  • samples
    • Filtering
  • articles
    • Filtering in the Tree
    • Details

    The filterMode property is an object that can contain 3 attributes:

    • showSubItems - (boolean) defines whether the tree should display children of the filtered items (true) (even if they don't match the filtering condition). The default value - true.
    • openParents - (boolean) - defines whether parents of the filtered items should be expanded (even if they don't match the filtering condition) so that user can effortlessly see the result of filtering. True by default.
    • level - (number) sets the nesting level to filter items from (one-based numbering).


threeState

enable three-state checkboxes

boolean threeState;

Example

webix.ui({
    view: "tree",
    threeState: true
})


Events

onAfterAdd | fires after adding item to datastore
onAfterClose | fires after the branch has been closed
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemCheck | called when the checkbox inside the tree item was checked
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterClose

fires after the branch has been closed

void onAfterClose(){ ... };

Example

some.attachEvent("onAfterClose", function(){
    //... some code here ...
});

See also

  • api
    • onAfterOpen
    • close
    • closeAll
  • articles
    • Tree Nodes manipulations


onAfterOpen

fires after the branch has been opened

void onAfterOpen(id id){ ... };

Parameters

id id id of the opened branch

Example

some.attachEvent("onAfterOpen", function(){
    //... some code here ...
});

See also

  • api
    • onAfterClose
    • close
    • closeAll
  • articles
    • Tree Nodes manipulations


onBeforeClose

fires the moment you attempt to close the tree branch

void onBeforeClose(id id){ ... };

Parameters

id id ID of the closed item

Example

some.attachEvent("onBeforeClose", function(){
    //... some code here ...
});

See also

  • api
    • onBeforeOpen
    • closeAll
    • close
  • articles
    • Tree Nodes manipulations


onBeforeOpen

fires the moment you attempt to open the tree branch

void onBeforeOpen(id id){ ... };

Parameters

id id ID of the opened branch

Example

some.attachEvent("onBeforeOpen", function(){
    //... some code here ...
});

See also

  • api
    • onBeforeClose
    • open
    • openAll
  • articles
    • Tree Nodes manipulations


onItemCheck

called when the checkbox inside the tree item was checked

void onItemCheck(id id,boolean state){ ... };

Parameters

id | id | id of related item
state | boolean | state of checkbox

Example

tree.attachEvent("onItemCheck". function(id, state){
    webix.message("Item " + id + " was " + (state? "checked" : "unchecked"));
})


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


ui.pager

Page navigation control.

The component makes little sense on its own, but can be used with other data-based components such as DataTable, DataView, List. Not purposed for direct initialization. Check pager documentation for more detailed description.

Constructor

webix.ui({
  view:"list",
  template:"#id#. #title#",
  pager:{
    size:1,
    group:4
  },
  data:[
     {"id":1,"title":"Item 1"},
     {"id":2,"title":"Item 2"},
     {"id":3,"title":"Item 3"},
     {"id":4,"title":"Item 4"},
     {"id":5,"title":"Item 5"},
     {"id":6,"title":"Item 6"},
  ]
});

Where to start

  • Overview of the Pager Component
  • Samples
Based on: MouseEvents, SingleRender, AtomRender, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clone | creates a copy of the pager
customize | redefines the 'type' property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the whole view or a certain item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
select | switches pager to the necessary page (zero-based numbering)
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterContextMenu | fires after the context menu was called in the item area
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
apiOnly | makes the pager invisible to enable paging with custom buttons
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
count | the total number of records that the pager will process
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
group | the number of visible pages in the pager
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
limit | the total number of pages in the pager
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
page | sets the currently active page (zero-based numbering)
size | sets the number of records per page
template | the component template
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | currently used set of helpers for view rendering


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clone | creates a copy of the pager
customize | redefines the 'type' property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the whole view or a certain item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
select | switches pager to the necessary page (zero-based numbering)
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


clone

creates a copy of the pager

object clone(object config);

Parameters

config object a configuration object, the same as for the pager constructor

Returns

object a new pager object

Example

var pagerB = pagerA.clone({
                container:"paging_here_too",
                size:10,
                group:5
            });

Details

Can be used if you need to have few synced paging controls for the same component.

See also

  • articles
    • Component Copying and Extending


customize

redefines the 'type' property

void customize(object obj);

Parameters

obj object the hash of new 'type' settings

Example

mylist = webix.ui({
    view:"list",
    ...
    type:{
        height:50
    }
});

mylist.customize({ height:30});
mylist.refresh();

Details

Remember, the method doesn't cause repainting of the component. That's why after calling the customize() method you should call method refresh or render to apply the newly-specified value

See also

  • api
    • refresh
    • type
  • articles
    • Changing Properties of Components


define

redefines a single configuration property (or a hash of properties)

void define(string property,any value);

Parameters

property | string | the property name or a hash of properties that need redefining
value | any | the new property value

Example

//redefines the datafeed url
$$('mylist').define("url", "new_data.xml");
$$('mylist').refresh();

//changes the label of the button
$$('button1').define("label", "New value");
$$('button1').refresh();

//change multiple properties at once
$$('text2').define({
    value:"123",
    label:"New label"
});
$$('text2').refresh();

Details

The component should be refreshed to make the changes come into force.

Redefining "config" object

You can use the config property to get the desired configuration option:

var width = $$("myList").config.width;

config is especially useful when a property is presented by an object:

var fieldWidth = $$('myGrid').config.fields['field_1'].width;

Note, in this case after $$("component_id").config you should write the complete dependency property inheritance chain.

See also

  • api
    • config
    • refresh
  • samples
    • Dynamical adjusting to the parent container
    • Named Templates
  • articles
    • Resizing Components


select

switches pager to the necessary page (zero-based numbering)

void select(number page);

Parameters

page number the page number

Example

$$('dtable').getPager().select(2);


Properties

animate | defines or disables view change animation.
apiOnly | makes the pager invisible to enable paging with custom buttons
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
count | the total number of records that the pager will process
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
group | the number of visible pages in the pager
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
limit | the total number of pages in the pager
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
page | sets the currently active page (zero-based numbering)
size | sets the number of records per page
template | the component template
width | sets the width of the component


apiOnly

makes the pager invisible to enable paging with custom buttons

boolean apiOnly;

Example

{ view:pager, id:"pagerA", apiOnly:true, size:50, group:5 }

See also

  • samples
    • Not-visible pager
  • articles
    • Paging
    • Details

    Standard pager won't be displayed yet the paging functionality can still be connected to the necessary component.

    In addition, here you should create JS or HTML button and attach 'paging' functions to them. Here is the 'Next Page' fucntion:

    function next_page(){
  $$("pagerA").select("next");
}


container

an html container (or its id) where the component needs initializing

HTMLElement container;

Example

<div id="box" style="width:320px; height:600px;"></div>
webix.ui ({
    container:"box",
    view:"list",
    ...
});

See also

  • samples
    • Visible pager
  • articles
    • Start Coding with Webix
    • View


count

the total number of records that the pager will process

number count;

Example

var myPager = webix.ui ({
        view:"pager",
        container:"paging_here",
        count:5000
});

See also

  • api
    • count
    • size
    • Details

    The parameter has sense only when ui.pager is used stand-alone.

    The count and limit parameters are interchangeable and used in pair with the size parameter to limit the number of records to process.
    In case of count, the total number of pages is calculated automatically.
    In case of limit, the total number of records is calculated automatically.

    Integration with Webix components

    If ui.pager is integrated with some Webix component, the total number of records to process will be generated automatically and the parameter (if it's set) will be ignored.

    //if you set the 'count' parameter for this pager it will be ignored
var myPager = webix.ui ({
        view:"pager",
        container:"paging_here",
        size:100
});

dtable = new webix.ui({
        view:"datatable",
        pager:myPager,
        ...
})


group

the number of visible pages in the pager

number group;

Example

webix.ui ({
    view:"pager",
    group:5
});

See also

  • samples
    • Static Paging
  • articles
    • Paging


limit

the total number of pages in the pager

number limit;

Example

webix.ui ({
    view:"pager",
    limit:30
});

See also

  • api
    • count, size
    • Details

    The parameter has sense only when ui.pager is used stand-alone.

    The count and limit parameters are interchangeable and used in pair with the size parameter to limit the number of records to process.
    In case of count, the total number of pages is calculated automatically.
    In case of limit, the total number of records is calculated automatically.

    Integration with Webix components

    If ui.pager is integrated with some Webix component, the total number of pages will be generated automatically and the parameter (if it's set) will be ignored.

    //if you set the 'limit' parameter for this pager it will be ignored
var myPager = webix.ui ({
        view:"pager",
        container:"paging_here",
        size:100
});

dtable = new webix.ui({
        view:"datatable",
        pager:myPager,
        ...
})


page

sets the currently active page (zero-based numbering)

number page;

Example

webix.ui ({
    view:"pager",
    page:3
});

See also

  • samples
    • Static Paging
  • articles
    • Paging


size

sets the number of records per page

number size;

Example

webix.ui ({
    view:"pager",
    size:100
});

See also

  • samples
    • Static Paging
  • articles
    • Paging


template

the component template

string|function template;

Example

webix.ui({
    view:"datatable",
    pager:{
        template: "{common.prev()}{common.pages()}{common.next()}"
        size:10,
        group:5
    }
});

See also

  • samples
    • Custom Pager Template
  • articles
    • Paging
    • Data Templates
    • Details

    Pager template may include the same elements as ordinary template:

    • standard text;
    • pager data elements (e.g. '#limit#' to display the total number of pages);
    • common icons:
      • {common.prev()} - 'less-than' sign, directs to previous page;
      • {common.first()} - double 'less-than' sign, directs to the first page;
      • {common.next()} - 'greater-than' sign, directs to the next page;
      • {common.last()} - double 'greater-than' sign, directs to the last page;
      • {common.page()} - displays the number of the current page;
      • {common.pages()} - displays a set of numbered squares.
    template: "{common.prev()}{common.next()}<div class='paging_text1'>
        Page {common.page()} from #limit#</div>"


Events

onAfterContextMenu | fires after the context menu was called in the item area
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | currently used set of helpers for view rendering


type

currently used set of helpers for view rendering

hash type;

Example

some.type.templateStart = function(obj, type){
   return "<div>"
};


ui.popup

A static popup window.

The window can contain any content, be modal or modeless. The main use case - displaying popup content on some action (e.g. click). Check popup documentation for more detailed description.

Constructor

var popup = webix.ui({
    view:"popup",
    id:"my_popup",
    height:250,
    width:300,
    body:{
        template:"Some text"
    }
}).show();

Where to start

  • Overview of the Popup Widget
  • Samples
Based on: ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setPosition | sets window's position
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setPosition | sets window's position
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component


head

sets the view header

object| string head;

See also

  • api
    • samples
      • articles
          • Details

          Not used in the current version of the library.


Available only in PRO Edition

ui.portlet

A movable layout component that can contain other components inside.

Portlet can include any content and be dragged to any position. It allows placing several components on the page at once. Check portlet documentation for more detailed description.

Constructor

var portlet = webix.ui({
    type:"space",
    rows:[
        { view:"portlet", body:{
            template:"row 1"
        . }},
        { view:"portlet", body:{
            template:"row 2"
        . }},
        { view:"portlet", body:{
            template:"row 3"
        . }}
    ]
});

Where to start

  • Overview of the Portlet Widget
  • Samples
Based on: ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
markDropArea | renders marker on the area where a portlet can be dropped during drag-n-drop
movePortlet | moves portlet to the marked area
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
body | defines the portlet content (a view or some HTML)
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
layoutType | defines the borders of layout that will be created after drag-n-drop operation is finished
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$drag | method called when drag operation initiated
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
markDropArea | renders marker on the area where a portlet can be dropped during drag-n-drop
movePortlet | moves portlet to the marked area
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


markDropArea

renders marker on the area where a portlet can be dropped during drag-n-drop

void markDropArea(string target,string mode );

Parameters

target | string | id of the view that should be selected
mode | string | the mode of selection ("top","bottom","left","right")

Example

$$("myportlet").markDropArea(target, mode);


movePortlet

moves portlet to the marked area

void movePortlet(string target,string mode);

Parameters

target | string | id of the view where the dragged portlet will be dropped
mode | string | the mode of dropping ("top","bottom","left","right")

Example

$$("myportlet").movePortlet(target,mode);


Properties

animate | defines or disables view change animation.
body | defines the portlet content (a view or some HTML)
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
layoutType | defines the borders of layout that will be created after drag-n-drop operation is finished
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


body

defines the portlet content (a view or some HTML)

string|WebixView body;

Example

webix.ui({
    container:"divA",
    type:"space",
    view:"portlet", body:{
        template:"Drag and drop portlets"
    }}
});

See also

  • samples
    • Portlet: Move cells
    • Horizontal Accordion
    • Windows: Basic Initialization
  • articles
    • Portlet
    • Accordionitem Configuration
    • Window


layoutType

defines the borders of layout that will be created after drag-n-drop operation is finished

string layoutType;

Values

  • line
    cells with border (default)
  • clean
    cells without border
  • wide
    cells with border and small space between siblings
  • space
    cells with border and wide space between siblings
  • head
    similar to "wide", but there is any border between the first and second cells

    • Example

    webix.ui({
    view:"portlet",
    layoutType: "space",
    rows: [
    ...
    ]
});

    See also

  • articles
    • Setting Borders to the Components


Others

$drag | method called when drag operation initiated
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.property

A structured table of 2 columns that presents 'name:value' pairs for a list of properties.

The component can be used for creating various on-page editors. The value field can be presented by any control - a text field, a checkbox, a drop-down list box etc. Check property documentation for more detailed description.

Constructor

var property = webix.ui({
    view:"property",
    id:"sets",
    width:300,
    elements:[
       { label:"Layout", type:"label"},
       { label:"Data url", type:"text", id:"url"},
       { label:"Data type", type:"select", options:["json","xml","csv"], id:"type"},
       { label:"Use JSONP", type:"checkbox", id:"jsonp"}
    ]
});

Where to start

  • Overview of the Property Sheet Widget
  • Samples
Based on: AutoTooltip, EditAbility, MapCollection, MouseEvents, Scrollable, SingleRender, AtomRender, AtomDataLoader, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
customize | redefines the 'type' property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editNext | closes the current editor and opens one in the next cell of the row
editStop | stops the edit mode and closes all opened editors. The component is still editable
enable | enables the calling view that was disabled by the 'disable' method
focusEditor | moves focus to the active editor
getChildViews | returns child views of the calling component
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
getFormView | returns master form for the input
getItem | gets the data object for related property
getItemNode | returns HTML element of the item
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives values from the property sheet (like with form)
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
registerType | registeres a new type for property sheet elements
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
showItem | 'scrolls' the table to make the specified row visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | alias for refresh, repaints property view
validateEditor | validates data in currently active editor
Events
onAfterContextMenu | fires after the context menu was called in the item area
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLiveEdit | occurs when data was changed in the editor
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | auto height mode for property view
borderless | used to hide the component borders
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
elements | an array of property items
form | linked form
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
map | defines data mapping
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
nameWidth | width of first column ( property names )
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
template | the component template
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_edit | set of flags, defines which types are editable
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
on_render | set of functions, for custom property types
type | currently used set of helpers for view rendering


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
customize | redefines the 'type' property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editNext | closes the current editor and opens one in the next cell of the row
editStop | stops the edit mode and closes all opened editors. The component is still editable
enable | enables the calling view that was disabled by the 'disable' method
focusEditor | moves focus to the active editor
getChildViews | returns child views of the calling component
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
getFormView | returns master form for the input
getItem | gets the data object for related property
getItemNode | returns HTML element of the item
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives values from the property sheet (like with form)
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
registerType | registeres a new type for property sheet elements
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
showItem | 'scrolls' the table to make the specified row visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | alias for refresh, repaints property view
validateEditor | validates data in currently active editor


customize

redefines the 'type' property

void customize(object obj);

Parameters

obj object the hash of new 'type' settings

Example

mylist = webix.ui({
    view:"list",
    ...
    type:{
        height:50
    }
});

mylist.customize({ height:30});
mylist.refresh();

Details

Remember, the method doesn't cause repainting of the component. That's why after calling the customize() method you should call method refresh or render to apply the newly-specified value

See also

  • api
    • type
  • articles
    • Changing Properties of Components


edit

enables the edit mode for the specified item

void edit(object id);

Parameters

id object the object defining the position of a cell

Example

dtable.edit({
        row:2,
        column:"title"
});

Related sample: Using the 'select' editor
Details

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

The input object parameter should contain 2 attributes:

  • row - (string) the row id
  • column - (string) the column id

Still, for datatable it's better to use its editCell, editRow and editColumn methods.

The method is useful when adding a hotkey to open edit state.

webix.UIManager.addHotKey("enter", function(view){
    var pos = view.getSelectedId();
    view.edit(pos); //edit selected item on pressing 'enter'
}, gridc);

Related sample: Using the 'select' editor

See also

  • samples
    • Using the 'select' editor
  • articles
    • DataTable Editing
    • Editing Data Items


editCancel

cancels the edit mode and closes all opened editors. The component is still editable

void editCancel();

Example

$$('mygrid').editCancel()

Details

The method doesn't save changes before closing the editor(s)

See also

  • articles
    • DataTable Editing
    • Editing Data Items


editNext

closes the current editor and opens one in the next cell of the row

boolean editNext();

Returns

boolean false

Example

$$('mylist').editNext();

Details

Note, the method will work only with the enabled editable parameter:

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • api
    • edit
    • editStop
    • focusEditor
  • articles
    • DataTable Editing
    • Editing Data Items


editStop

stops the edit mode and closes all opened editors. The component is still editable

void editStop();

Example

prop.registerType("toggle",{
...,
click:{
            webix_toggle_button_custom:function(e, id){
                var data = this.getItem(id);
                if (data.options[0] == data.value)
                    data.value = data.options[1];
                else
                    data.value = data.options[0];

                this.editStop();
                this.refresh(id);
                this.callEvent("onCheck",[id, data.value]);
            },
..
});

Details

The method saves changes before closing the editor(s)

See also

  • samples
    • Property Sheet: Custom Editors
  • articles
    • DataTable Editing
    • Editing Data Items
    • Property Sheet


focusEditor

moves focus to the active editor

void focusEditor();

Example

$$("mylist").focusEditor();

Details

If components has no active editors - command do nothing.

See also

  • samples
    • The 'select' editor
  • articles
    • Editing Data Items
    • DataTable Editing


getEditor

returns editor object

object getEditor( [string id] );

Parameters

id string record id

Returns

object object with editor state and info

Example

var editor = view.getEditor(row_id);

Details

If id not provided - returns info about last opened editor

Editor object

{
    node: html_node_of_editor,
    value: initial_value_of_editor
    config: configuration_of_editor
}

You can access all methods of editor through this object

//get value
var value = some.getEditor().getValue();
//set value
some.getEditor().setValue( new_value );
//set focus
some.getEditor().focus();

See also

  • api
    • getEditState
    • getEditorValue
  • articles
    • Data Editors
    • DataTable Editing


getEditorValue

returns the value of the active (currently open) editor

string getEditorValue();

Returns

string the editor value

Example

$$('mygrid').getEditorValue();

Details

If no editors or several editors are open, the method returns the value of the last opened editor.

See also

  • api
    • getEditState
    • getEditor
  • articles
    • Data Editors
    • DataTable Editing


getItem

gets the data object for related property

object getItem(string id);

Parameters

id string name of property

Returns

object the data object for the property

Example

var record = property.getItem("width");
var title = record.value;

Details

Each data object has id, value, label attributes, it also will contain all extra data which was defined during configuration.


getValues

derives values from the property sheet (like with form)

hash getValues();

Returns

hash returns hash of form values: data entered by user or initial data from the value property.

Example

function get_form() {
                var values = $$('myform').getValues();
                console.log(values);
            }

Details

To get value of some specific element within the form, you should specify its ID or name.

webix.ui({
    view:"form",
    elements: [
        {view:"text", id:"title", placeholder:"Enter film title"},
        {...},
        {view:"button", click:"get_title"}
    ]
})

function get_title() {
        var title = $$('myform').getValues().title;
        console.log(title);
        }

See also

  • api
    • setValues
  • samples
    • Hidden Inputs
  • articles
    • HTMLForm and Form Treatment


registerType

registeres a new type for property sheet elements

void registerType(string name,object data);

Parameters

name | string | name of the new editor
data | object | data object that includes template, click behaviour and editor

Example

prop.registerType("popup",{
        editor:"popup"
    });

Details

Editors are based on standard Webix editors that can be either taken as they are or with extra functionality added with the help of extend() method.

Study the Property Sheet article for details.

See also

  • samples
    • Property Sheet: Custom Editors
  • articles
    • Property Sheet


setValues

sets values into the inputs of a form/toolbar/property sheet control

void setValues(object values, [boolean update] );

Parameters

values | object | hash of property - value pairs
update | boolean | if true adds updates the form with new values while exisitng values remain. False by default

Example

webix.ui({
    view:"form",
    id:"myform",
    elements:[
        { view:"text", name:"field_a" },
        { view:"text", name:"field_b" },
    ]
});

function set_form(){
    $$("myform").setValues({
       field_a: "London",
       field_b: "New York"
    });
};

Details

The methods allows for setting several values at time. Pass the names of the necessary elements and their values into the function.

Complex Data

In the complex data mode the object with values can feature sub items of any complexity level. In this case elements names are concatenated from all the data names in the chain:

webix.ui({
    view:"form",
    id:"sets",
    complexData:true,
    elements:[
        { view:"text", name:"layout.width" },
        { view:"text", name:"layout.height" }
    ]
});

$$("sets").setValues({
    layout:{
        width:250,
        height:480
    }
});

Complex data mode is enabled with the help of a same-name parameter in the form/toolbar/property sheet configuration.

Updating values

The second parameter helps manipulate values separately. By default, it is set to false.

Take that we want to set a new value for a field_b input from the form described above.

$$("my_form").setValues({ field_b:"Paris" });

In this case the value for the field_a is lost.

To avoid this, set the update parameter to true. The form will be updated with a new value for field_b input while field_a value remains unchanged.

$$("my_form").setValues({ field_b:"Paris" }, true);

See also

  • api
    • getValues
  • samples
    • Property Sheet: Basic Initialization
    • Form:Data with complex properties
  • articles
    • Property Sheet


updateItem

alias for refresh, repaints property view

void updateItem();

Example

var item = property.getItem("width");
item.value = "new one";
property.updateItem("width"); //same  as property.refresh();

Details

Made for API compatibility with data components.


Properties

animate | defines or disables view change animation.
autoheight | auto height mode for property view
borderless | used to hide the component borders
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
elements | an array of property items
form | linked form
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
map | defines data mapping
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
nameWidth | width of first column ( property names )
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
template | the component template
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
url | the URL which the component will use to load data after its initialization
width | sets the width of the component


autoheight

auto height mode for property view

boolean autoheight;

Example

webix.ui({ view:"property", autoheight:true });


editable

allows/denies editing in the view

boolean editable;

Example

webix.ui({
    view:"datatable",
    editable:true,
    ...
});

See also

  • samples
    • Editing on Mouse Click
  • articles
    • Editing Data Items


elements

an array of property items

object elements;

Example

view:"property",
elements:[
    { label:"Layout" },
    { label:"Width", type:"text", id:"width"},
    { label:"Data type", type:"toggle", options:["json","xml"], id:"type"},
    { label:"Color front",  type:"popup",    popup:"myColorF", id:"colorF" },
]

See also

  • api
    • editors
    • registerType
  • samples
    • Property Sheet: Basic Initialization
  • articles
    • Property Sheet
    • Details

    Each property element features

    • label - text label displayed on the left. If there's no other properties, such elements becomes header;
    • type - editor type initiated on clicking the element value;
    • id - ID of the element. Used by setValues() and getValues() methods to place values into dedicated cells;
    • editor controls (depend on the type property). Check editor types for details.

    Possible type values coincide with editor types and are as follows:

    • color - for colors, colorboard appears on editing;
    • text - for text values);
    • select - for selection among several text values;
    • checkbox - for two-state values;
    • toggle (a two-state button) - for two-state values;
    • popup - a popup window;

    When type is not defined, the element turns into header of the property sheet section.


nameWidth

width of first column ( property names )

number nameWidth;

Example

webix.ui({
    view:"property",
    nameWidth:250
});


Events

onAfterContextMenu | fires after the context menu was called in the item area
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLiveEdit | occurs when data was changed in the editor
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterEditStart

fires after edit operation was initiated, editor opened and ready for input

void onAfterEditStart(id id){ ... };

Parameters

id id the item id

Example

some.attachEvent("onAfterEditStart", function(id){
    //... some code here ...
});

See also

  • api
    • onBeforeEditStart
  • articles
    • DataTable Editing
    • Editing Data Items
    • Data Editors


onAfterEditStop

fires after edit operation finished

void onAfterEditStop(object state,object editor,boolean ignoreUpdate){ ... };

Parameters

state | object | an object with 2 properties: 'value' - the new value of the cell, 'old' - the old value of the cell
editor | object | the editor's object
ignoreUpdate | boolean | specifies whether the cell was updated after editing

Example

some.attachEvent("onAfterEditStop", function(state, editor, ignoreUpdate){
    if(state.value != state.old){
        webix.notice("Cell value was changed")
    }
});

See also

  • api
    • onAfterEditStart
  • articles
    • DataTable Editing
    • Editing Data Items
    • Data Editors


onBeforeEditStart

fires before edit operation is initiated

void onBeforeEditStart(id id){ ... };

Parameters

id id the id of the item which will be edited

Example

some.attachEvent("onBeforeEditStart", function(id){
    //... some code here ...
});

See also

  • api
    • onAfterEditStart
  • articles
    • DataTable Editing
    • Editing Data Items


onBeforeEditStop

fires before stop edit command is received

void onBeforeEditStop(object values,object editor){ ... };

Parameters

values | object | an object with two parameters: the new value and the old one
editor | object | the editor object

Example

grid.attachEvent("onBeforeEditStop", function(state, editor){ return false; });

grid.attachEvent("onEditorChange", function(id, value){
    this.getItem(id.row)[id.column] = value;
    this.refresh(id.row);
});;

Details

Events starting from "before" are blockable, which means that if they return false the action is blocked.

In the above sample editing is not finished when the edit stop command is received (it happens when you leave the editor body) and editing continues with setting the new value to the item and refreshing it. It is done to display the new value outside the field where editor opens.

See also

  • api
    • onBeforeEditStop
  • samples
    • Using 'inline' editors
  • articles
    • DataTable Editing
    • Editing Data Items
    • Data Editors


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_edit | set of flags, defines which types are editable
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
on_render | set of functions, for custom property types
type | currently used set of helpers for view rendering


on_edit

set of flags, defines which types are editable

hash on_edit;

Example

property.on_edit["mycheckbox"] = false;

//or

property.on_edit["custombox"] = "text";


on_render

set of functions, for custom property types

hash on_render;

Example

property.on_render["mycheckbox"] = function(value, config){
   var start = "<input type='checkbox' class='webix_property_check' ";
   return  start+(value?"checked":"")+">";
}


ui.radio

A radio button.

You can group multiple component instances together to provide the desired set of choices. Check radio documentation for more detailed description.

Constructor

var radio = webix.ui({
    view:"radio",
    label:"Branch",
    value:1, options:[
    { id:1, value:"Master" },
    { id:2, value:"Branch" }]
});

Where to start

  • Overview of the Radio Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
customRadio | enables/disables custom radio button for some skins
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionHeight | height of radio-option item
options | defines options for a set of radiobuttons
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
vertical | arranges radiobutton vertically (false by default)
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
customRadio | enables/disables custom radio button for some skins
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionHeight | height of radio-option item
options | defines options for a set of radiobuttons
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
vertical | arranges radiobutton vertically (false by default)
width | sets the width of the component


customRadio

enables/disables custom radio button for some skins

boolean customRadio;

Example

{ view:"radio", customRadio:false }

Details

Webix radio control is based on standard HTML radio, but some skins use a FontAwesome icon to render it. Then the value of customRadio parameter is true by default.

To switch to a standard HTML checkbox, use customRadio property.


optionHeight

height of radio-option item

number optionHeight;

Example

webix.ui({
  rows:[{
    view:"radio",
    vertical:true,
    optionHeight:37,
    options:["Some <br> Text", "Other <br> Text " ]
  },{
    type:"header", template:"Bottom Line"
  }]
})

Details

This value is used only to calculate expected height of radio control


options

defines options for a set of radiobuttons

array options;

Example

webix.ui({
    view:"radio",
    label:"Branch",
    value:1,
    options:[
        {  id:1, value:"Master" }, //the initially selected item
        {  id:2, value:"Branch" }
    ]
});

See also

  • api
    • getValue
    • setValue
    • value
  • samples
    • Radio Button ('radio')
  • articles
    • Controls Guide
    • Radio
    • Details

    Options can be as well enumerated in the array of values:

    {view:"radio", options:["Master", "Branch"]}


vertical

arranges radiobutton vertically (false by default)

boolean vertical;

Example

{ view:"radio",
  options:[
    { value:"Master", id:1 },
    { value:"Branch", id:2 }
    ],
  vertical:true
}

See also

  • samples
    • Radio Button ('radio')
  • articles
    • Radio


onItemClick

fires after the control has been clicked

void onItemClick(string| number id,event e){ ... };

Parameters

id | string| number | control ID
e | event | event object

Example

button.attachEvent("onItemClick", function(id, e){
    //code
});

Details

The ID of the whole control is passed (but not a separate option).

See also

  • api
    • click
  • samples
    • List: Active Content
  • articles
    • Event Handling


Available only in PRO Edition

ui.rangechart

A component that allows presenting data of data components in a detailed way.

RangeChart inherits from Chart and gives the possibility to display in detail some data of a data component limited by frame. This component is useful for controlling and visualizing data of other data components.

Check RangeChart documentation for more details

Constructor

var rangechart = webix.ui({
    view:"rangechart",
    height: 80,
    id:"range",
    type:"line",
    value:"#sales#",
    frameId:"time",
    item: { radius :0 },
    range:{ start:30, end:50 },
    data: data
});

Where to start

  • Overview of the RangeChart Widget
  • Samples
Based on: ui.chart, Group, AutoTooltip, DataLoader, DataStore, AtomDataLoader, MouseEvents, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
add | adds an item to the store
addSeries | adds an additional graph to the chart
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCanvas | clears the component canvas
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getFrameData | returns an array of objects that are included into the range
getFrameRange | returns the object of the data range selected in the frame
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getTopParentView | returns top parent view
group | groups data by the specified data property
hasEvent | checks whether the component has the specified event
hide | hides the view
hideSeries | hides the chosen graph in the chart with several graphs
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeAllSeries | removes all series from the chart
render | renders the specified item or the whole component
resize | adjusts the view to a new size
serialize | serializes data to a JSON object
setFrameRange | sets the data range for the frame
show | makes the component visible
showSeries | shows the hidden graph in the chart
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
updateItem | sets properties of the data item
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterRangeChange | fires after the frame range is changed
onAfterRender | called after the rendering of calendar is complete.
onAfterScroll | occurs when some webix view has been scrolled
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
alpha | defines the opacity of chart items
animate | defines or disables view change animation.
barWidth | the width of bars
border | enables/disables the bar borders
borderColor | sets the border color of each item in the graph
borderless | used to hide the component borders
cant | defines the slope angle of 3D pie
color | defines items colors
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disableLines | disapbles graph lines with radar chart
disabled | indicates whether an item is enabled or not
eventRadius | sets the radius (in pixels) of the virtual circle which events will fire for items within
fill | fills the chart area with the specified background color.
fixOverflow | chart max limit mode
frameId | points to the property in data that will be used for the frame
gradient | specifies the chart gradient
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
item | defines markers that present chart's data items
label | sets the template for items' labels
labelOffset | the offset of sector labels from the pie frame
legend | defines the chart legend
line | defines chart lines
lineColor | sets the color for strips dividing the pie sectors
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
offset | defines whether the first item of the scale will be drawn with the offset equal to the half of the scale's step (relative to the origin of the chart) or not.
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
origin | sets the scale origin
padding | sets paddings of the chart content
pieHeight | the height of the 3d pie
pieInnerText | sets the template for the pie inner labels
preset | applies the predefined chart configuration object with the specified name
radius | the radius of the bar's rounding
range | data range that should be selected in the frame
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scale | type of chart scale, logarithic or plain
scheme | defines schemes for data processing
series | defines graphs presented on the chart
shadow | enables/disables the pie shadow
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | sets the chart type
url | the URL which the component will use to load data after its initialization
value | defines values for the vertical axis
width | sets the width of the component
x | the horizontal position of the pie center
xAxis | defines the horizontal axis
xValue | a property of the dataset that defines values for the horizontal axis
y | the vertical position of the pie center
yAxis | defines the vertical axis
yValue | a property of the dataset that defines values for the vertical axis.
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
colormap | collection of coloring strategies
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
presets | collection of styling presets


Methods

add | adds an item to the store
addSeries | adds an additional graph to the chart
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCanvas | clears the component canvas
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getFrameData | returns an array of objects that are included into the range
getFrameRange | returns the object of the data range selected in the frame
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getTopParentView | returns top parent view
group | groups data by the specified data property
hasEvent | checks whether the component has the specified event
hide | hides the view
hideSeries | hides the chosen graph in the chart with several graphs
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeAllSeries | removes all series from the chart
render | renders the specified item or the whole component
resize | adjusts the view to a new size
serialize | serializes data to a JSON object
setFrameRange | sets the data range for the frame
show | makes the component visible
showSeries | shows the hidden graph in the chart
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
updateItem | sets properties of the data item


getFrameData

returns an array of objects that are included into the range

array getFrameData();

Returns

array an array of objects that are included into the range (including the starting and ending ones)

Example

rangechart.getFrameData();


getFrameRange

returns the object of the data range selected in the frame

object getFrameRange();

Returns

object the object of the data range selected in the frame

Example

rangechart.getFrameRange();

Details

the parameters of the returned object are:

  • start - (number) id of the item that starts the range, or value of the property that is defined in the frameId parameter
  • sindex - (number) index of the item that starts the range
  • end - (number) id of the item that ends the range, or value of the property that is defined in the frameId parameter
  • eindex - (number) index of the item that ends the range
{
    start: 30,
    sindex:29,
    end: 40,
    eindex:39
}

See also

  • api
    • setFrameRange


setFrameRange

sets the data range for the frame

void setFrameRange(object range );

Parameters

range object object with range parameters

Example

rangechart.setFrameRange({
    start:30,
    end:40
});

Details

The parameters of the range object are the following:

  • start - (number) id of the item that starts the range, or value of the property that is defined in the frameId parameter
  • sindex - (number) index of the item that starts the range
  • end - (number) id of the item that ends the range, or value of the property that is defined in the frameId parameter
  • eindex - (number) index of the item that ends the range

It is possible to specify in the data range either ids or indexes of the starting and the ending data items of the range.

What is more, you can set the id of the starting item and the index of the ending one and vice versa. The important thing is that there are always should be one starting value and one ending value of the range. Thus, you can set the range as:

rangechart.setFrameRange({
    start:30,
    eindex:39
});

Notice that the priority of ids is higher than that of indexes. It means that in case difference between their values is great, the position of data range will be counted using the ids values.

See also

  • api
    • getFrameRange


Properties

alpha | defines the opacity of chart items
animate | defines or disables view change animation.
barWidth | the width of bars
border | enables/disables the bar borders
borderColor | sets the border color of each item in the graph
borderless | used to hide the component borders
cant | defines the slope angle of 3D pie
color | defines items colors
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disableLines | disapbles graph lines with radar chart
disabled | indicates whether an item is enabled or not
eventRadius | sets the radius (in pixels) of the virtual circle which events will fire for items within
fill | fills the chart area with the specified background color.
fixOverflow | chart max limit mode
frameId | points to the property in data that will be used for the frame
gradient | specifies the chart gradient
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
item | defines markers that present chart's data items
label | sets the template for items' labels
labelOffset | the offset of sector labels from the pie frame
legend | defines the chart legend
line | defines chart lines
lineColor | sets the color for strips dividing the pie sectors
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
offset | defines whether the first item of the scale will be drawn with the offset equal to the half of the scale's step (relative to the origin of the chart) or not.
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
origin | sets the scale origin
padding | sets paddings of the chart content
pieHeight | the height of the 3d pie
pieInnerText | sets the template for the pie inner labels
preset | applies the predefined chart configuration object with the specified name
radius | the radius of the bar's rounding
range | data range that should be selected in the frame
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scale | type of chart scale, logarithic or plain
scheme | defines schemes for data processing
series | defines graphs presented on the chart
shadow | enables/disables the pie shadow
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | sets the chart type
url | the URL which the component will use to load data after its initialization
value | defines values for the vertical axis
width | sets the width of the component
x | the horizontal position of the pie center
xAxis | defines the horizontal axis
xValue | a property of the dataset that defines values for the horizontal axis
y | the vertical position of the pie center
yAxis | defines the vertical axis
yValue | a property of the dataset that defines values for the vertical axis.


frameId

points to the property in data that will be used for the frame

string frameId;

Example

webix.ui({
    view:"rangechart",
    frameId:"time",
    data: data
});


range

data range that should be selected in the frame

object range;

Example

range:{ start:30, end:40 }

Details

It is possible to specify in the data range either ids or indexes of the starting and the ending data items of the range.

range:{ sindex:29, eindex:49 }

What is more, you can set the id of the starting item and the index of the ending one and vice versa. The important thing is that there are always should be one starting value and one ending value of the range. Thus, you can set the range as:

range:{ sindex:29, end:50 }

or like this:

range:{ start:30, eindex:49 }


Events

onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterRangeChange | fires after the frame range is changed
onAfterRender | called after the rendering of calendar is complete.
onAfterScroll | occurs when some webix view has been scrolled
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterRangeChange

fires after the frame range is changed

void onAfterRangeChange(){ ... };

Example

rangechart.attachEvent("onAfterRangeChange", function(){
    // some code here
});


ui.rangeslider

A slider component with two markers for selecting a range of values.

Unlike a standard slider, this control allows choosing a particular range of values due to its two handlers. The part of the value line which corresponds to the selected set of values is highlighted in blue color.

Check rangeslider documentation for more detailed description.

Constructor

var rangeslider = webix.ui({
    view:"rangeslider",
    label:"Level A",
    value:"10,100",
    title: webix.template("#value#")
});

Where to start

  • Overview of the Range Slider Control
  • Samples
Based on: ui.slider, ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSliderDrag | fires when the handle of slider was dragged ( but not released yet )
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
max | max value of slider
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
min | min value of slider
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | a delimiter for separating values in a range, comma by default
step | step of slider
stringResult | if the parameter is set to true, the method getValue returns data as string (otherwise, as object)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
title | text over slider bar
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$touchCapture | allows capturing touch gestures in touch limited mode.
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
max | max value of slider
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
min | min value of slider
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
separator | a delimiter for separating values in a range, comma by default
step | step of slider
stringResult | if the parameter is set to true, the method getValue returns data as string (otherwise, as object)
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
title | text over slider bar
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


max

max value of slider

number max;

Example

//valid values 0,10,20,30,40,50
webix.ui({
     view:"slider",
     min:0, max:50,
     step:10
     ...
});

See also

  • api
    • min
  • samples
    • Slider: Negative Values
  • articles
    • Slider
    • Details

    100 by default


min

min value of slider

number min;

Example

//valid values 0,10,20,30,40,50
webix.ui({
     view:"slider",
     min:0, max:50,
     step:10
     ...
})

See also

  • api
    • max
  • samples
    • Slider: Negative Values
  • articles
    • Slider
    • Details

    0 by default


separator

a delimiter for separating values in a range, comma by default

string separator;


step

step of slider

number step;

Example

//valid values 0,10,20,30,40,50
webix.ui({
     view:"slider",
     min:0, max:50,
     step:10
     ...
})

See also

  • articles
    • Slider
    • Details

    1 by default


stringResult

if the parameter is set to true, the method getValue returns data as string (otherwise, as object)

boolean stringResult;

Example

{ view:"rangeslider", stringResult:true, format:"%d  %M %Y" },

Details

The default value is false.


title

text over slider bar

string|function title;

Example

webix.ui({
    view:"slider",
    title:"Select range from 0 to 100",
    ...
});

See also

  • samples
    • Slider: Labels
  • articles
    • Slider
    • Details

    Can be defined as function

    webix.ui({
    view:"slider",
    title:function(obj){
         return "Value: "+ obj.value;
    }
    ...
});


Events

onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSliderDrag | fires when the handle of slider was dragged ( but not released yet )
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onSliderDrag

fires when the handle of slider was dragged ( but not released yet )

void onSliderDrag(){ ... };

Example

$$("my_slider").attachEvent("onSliderDrag", function(){
    webix.message("Dragged to "+this.getValue());
}

See also

  • samples
    • Slider: Labels
  • articles
    • Form
    • Slider


Others

$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$touchCapture | allows capturing touch gestures in touch limited mode.
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


$touchCapture

allows capturing touch gestures in touch limited mode.

boolean $touchCapture;

See also

  • api
    • limit
    • Details

    For slider the value is true by default.


ui.resizer

A draggable border in a layout.

The component is used to make some view placed into a layout draggable by a specific border. Draggable borders differ visually from the undraggable ones. Check layout documentation for more detailed description.

Constructor

webix.ui({
  id:"layout",
  rows:[
    { template:"row 1" },
    { view:"resizer" },
    { template:"row 2" },
    { view:"resizer" },
    { cols:[
      { template:"column 1" },
      { view:"resizer"},
      { template:"column 2" },
    ]}
  ]
});

Where to start

  • Overview of Resizer
  • Samples
Based on: MouseEvents, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
Events
onAfterContextMenu | fires after the context menu was called in the item area
onAfterScroll | occurs when some webix view has been scrolled
onBeforeContextMenu | fires before the context menu is called in the item area
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.


Methods

adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
width | sets the width of the component


ui.richselect

A non-editable combo box.

The control combines a non-editable text field with a drop-down list of predefined values. Check richselect documentation for more detailed description.

Constructor

var richselect = webix.ui({
    view:"richselect",
    label:"Choose",
    value:1, options:[
        {id:1, value:"One"},
        {id:2, value:"Two"},
        {id:3, value:"Three"}
    ]
});

Where to start

  • Overview of the Richselect Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getList | returns list view of the control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | returns popup element of the input
getText | returns text of currently selected option
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


getInputNode

gets the HTML element related to the component

HTMLElement getInputNode();

Returns

HTMLElement the component HTML element

Example

var unit = $$('unit').getInputNode().value;

Details

The method can be used to get the actual text value of the combo while the getValue() function will return the ID of the chosen option.

The same is true about select and richselect.

See also

  • samples
    • Working with UnitList Items
  • articles
    • View


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupWidth | width of the popup window
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
text | visible text in the related input
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


ui.scrollview

A container with scrolls.

Place it in the layout if you want to have a scroll around few other views (not necessary if you need a scroll in one single view). Check scrollview documentation for more detailed description.

Constructor

var scrollview = webix.ui({
  view:"scrollview",
  id:"scrollview",
  scroll:"y",
  height: 160,
  width: 150, body:{
     rows:[
       {template:"Lorem ipsum", autoheight:true},
       {template:"Lorem ipsum dolor sit amet", autoheight:true},
       {template:"Lorem ipsum dolor", autoheight:true},
       {template:"Lorem ipsum dolor sit amet, mentitum", autoheight:true},
       {template:"Lorem ipsum dolor sit", autoheight:true},
     ]
   }
});

Where to start

  • Overview of the Scrollview Widget
  • Samples
Based on: Scrollable, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the inner view of scrollview
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
show | makes the component visible
showView | places focus on the necessary scrollview item
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
body | the view object that needs scrolling
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the inner view of scrollview
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
show | makes the component visible
showView | places focus on the necessary scrollview item
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getBody

gets the inner view of scrollview

object getBody();

Returns

object the inner view object


showView

places focus on the necessary scrollview item

void showView(id id);

Parameters

id id ID of the view to scroll to

Example

webix.ui({
    view:"scrollview",
    id:"verses",
    body:{
       rows:[
           { id:"verse_1", template:".."},
           { id:"verse_2", template:".."},
           { id:"verse_3", template:".."}
       ]
});

function scroll(id){
            $$("verses").showView("verse_"+id);
        }

See also

  • samples
    • Scrollview
  • articles
    • Scroll Control


Properties

animate | defines or disables view change animation.
body | the view object that needs scrolling
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
width | sets the width of the component


body

the view object that needs scrolling

object body;

Example

webix.ui({
        view:"scrollview",
        container:"box",
        body:{
                view:"datatable",
                columns:[{...}],
                data:film_set
        }
});

See also

  • samples
    • Scrollview
  • articles
    • Scrollview


ui.search

A text edit field with the search icon inside.

The component presents a standard text input but with the "search" icon. Supports regular HTML input's functionality. Check search documentation for more detailed description.

Constructor

var search = webix.ui({
  view:"search",
  placeholder:"Search..",
  width: 300
});

Where to start

  • Overview of the Search Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSearchIconClick | fires after the 'search' icon has been clicked in the input
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


Events

onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSearchIconClick | fires after the 'search' icon has been clicked in the input
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onSearchIconClick

fires after the 'search' icon has been clicked in the input

void onSearchIconClick(Event e){ ... };

Parameters

e Event event object

Example

$$("search_field").attachEvent("onSearchIconClick", function(e){
    var value = this.getvalue();
    //...
});


ui.segmented

A holistic panel that contains multiple buttons (two or more).

The component can be used to build a multi-item menu for navigating between views. Check segmented documentation for more detailed description.

Constructor

var segmented = webix.ui({
    view:"segmented",
    value:1, options:[
        { id:"1", value:"Section A" },
        { id:"2", value:"Section B" },
        { id:"3", value:"Section C" }
    ]
});

Where to start

  • Overview of the Segmented Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
addOption | add a new option (segment) to the button
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
optionIndex | index of the option with specified ID
refresh | repaints the component
removeOption | removes the option of a segmented button
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onAfterTabClick | fires after a segment has been clicked
onBeforeRender | occurs immediately before the component has been rendered
onBeforeTabClick | fires before a segment is clicked
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onOptionRemove | fires after the option (tab, segment) has been removed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multiview | enables switching between multiview cells
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionWidth | sets the width of each view's option
options | defines data items of the drop-down list
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

addOption | add a new option (segment) to the button
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
optionIndex | index of the option with specified ID
refresh | repaints the component
removeOption | removes the option of a segmented button
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


addOption

add a new option (segment) to the button

void addOption(id id,any value, [boolean show ,number index] );

Parameters

id | id | ID of the new option
value | any | value of the new option
show | boolean | makes the newly added option active. 'false' by default
index | number | position to insert to. Last, by default

Example

function open_new_tab(id){
    var item = $$('list1').getItem(id);
    $$('tabs').addOption(item.id, item.title, true);
};

Details

In case of a tabbar, the method can as well take a more extensive option configuration of a tab.

And the parameters are as follows:

  • obj (obj) - tab configuration;
  • show (boolean) - makes the newly added option active;
  • index (number) - position to insert to. Last, by default.
tabbar.addOption({id:1, value:"New", close:true, icon:"cog"}, true);

See also

  • api
    • removeOption
  • samples
    • Dynamic Adding/Deleting of Tabs in Tabbar
  • articles
    • Adding and Deleting Multiview Cells Dynamically


getValue

returns the current value of the control

string getValue();

Returns

string the current value of the control

Example

webix.ui({
    view:"segmented", value:"one", options:[
            { id:"one", value:"One" },
            { id:"two", value:"Two"},
            { id:"three", value:"Three"}
        ]
});
...
$$(segmented1).getValue();
        //returns "one"

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
    • value
  • articles
    • Controls Guide


optionIndex

index of the option with specified ID

number optionIndex(id ID );

Parameters

ID id ID of the needed option

Returns

number index of the option

Example

$$("segmented1").optionIndex(1);

Details

Since options are stored in the array, option indexes are numbered staring from 0.


removeOption

removes the option of a segmented button

void removeOption(id id );

Parameters

id id ID of the option being removed

Example

function del_tab(){
    var tab_id = $$("tabs").getValue();
    $$("tabs").removeOption(tab_id);
}

See also

  • api
    • addOption
    • onOptionRemove
  • samples
    • Dynamic Adding/Deleting of Tabs in Tabbar
  • articles
    • Adding and Deleting Multiview Cells Dynamically


setValue

selects the option by its ID

void setValue(string value);

Parameters

value string a new value for the control

Example

webix.ui({
    view:"segmented", options:[
            { id:"one", value:"One" },
            { id:"two", value:"Two"},
            { id:"three", value:"Three"}
        ]
});
...
$$(segmented1).setValue('two');
    //choose the second option

See also

  • api
    • getValue
    • value
  • articles
    • Controls Guide


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multiview | enables switching between multiview cells
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionWidth | sets the width of each view's option
options | defines data items of the drop-down list
popup | allows to attach pop-up menu to the button
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


multiview

enables switching between multiview cells

boolean multiview;

Example

rows:[
    {view:"tabbar", id:'tabbar', multiview:true, options: [
              { value: 'List', id: 'listView'},
              { value: 'Form', id: 'formView'},
              { value: 'Empty', id: 'emptyView'}
              ]
    },
    {cells:[
        {id:"listView", ....},
        {id:"formView", ....},
        {id:"emptyView", ....},
        ]
    }
]

See also

  • samples
    • Tabbar
  • articles
    • Controls to Switch Between View Cells
    • Details

    Segmented options and multiview cells must have the same IDs.


optionWidth

sets the width of each view's option

number optionWidth;

Example

{
    view:"segmented",
    optionWidth: 80,
    options:[...]
}


options

defines data items of the drop-down list

object options;

Example

webix.ui({
    view:"segmented", value:"one", options:[
            { id:"one", value:"One" },
            { id:"two", value:"Two"},
            { id:"three", value:"Three"}
            ]
})

See also

  • api
    • getValue
    • setValue
  • samples
    • Holistic Panel with Multiple Buttons ('segmented')
  • articles
    • Controls Guide
    • Details

    The property is an array of objects, each of which presents a singular select option on a toolbar.

    The objects in the array have 2 attributes:

    • id - (id) the item id
    • value - (string) the item label

    Nore that the getValue() method returns the ID of selected option.


Events

onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onAfterTabClick | fires after a segment has been clicked
onBeforeRender | occurs immediately before the component has been rendered
onBeforeTabClick | fires before a segment is clicked
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onOptionRemove | fires after the option (tab, segment) has been removed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onAfterTabClick

fires after a segment has been clicked

void onAfterTabClick(){ ... };

Example

segmented.attachEvent("onAfterTabClick", function(id, e){
    //code
});

Details

Unlike the onItemClick event this one watches clicks over separate tabs and passes the ID of a clicked tab into its handler.

See also

  • api
    • onBeforeTabClick
    • onItemClick
    • click
    • on_click


onBeforeTabClick

fires before a segment is clicked

void onBeforeTabClick(){ ... };

Example

segmented.attachEvent("onBeforeTabClick", function(id, e){
    //code
});

Details

Unlike the onItemClick event this one watches clicks over separate tabs and passes the ID of a clicked tab into its handler.

See also

  • api
    • onAfterTabClick
    • onItemClick
    • click
    • on_click


onItemClick

fires after the control has been clicked

void onItemClick(string| number id,event e){ ... };

Parameters

id | string| number | control ID
e | event | event object

Example

button.attachEvent("onItemClick", function(id, e){
    //code
});

Details

The event fires after tab-related click events (onBeforetabClick and onAfterTabClick).

See also

  • api
    • click
    • onBeforeTabClick
    • onAfterTabClick
  • samples
    • List: Active Content
  • articles
    • Event Handling


onOptionRemove

fires after the option (tab, segment) has been removed

void onOptionRemove(string| number id,string value){ ... };

Parameters

id | string| number | option ID
value | string | option value

Example

tabbar.attachEvent("onOptionRemove", function(id, value){
    //code
});

See also

  • api
    • removeOption
  • articles
    • Segmented Button
    • Adding and Deleting Multiview Cells Dynamically


ui.select

A single-selection drop-down list box.

The component can be populated with data from the server side or a file: each item in the list will correspond to an item in the data source. Multi-selection mode isn't supported. Check select documentation for more detailed description.

Constructor

var select = webix.ui({
    view:"select",
    label:"Branch",
    value:1, options:[
        {id:1, value:"Master" },
        {id:2, value:"Release" }
    ]
});

Where to start

  • Overview of the Select Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
options | defines options for a select control
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
options | defines options for a select control
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


options

defines options for a select control

array| string options;

Example

//simple array
{ view:"select", label:"Version", options:["1.0", "1.5", "2.0"]}

//id-value pairs
{ view:"select", value: 2, label:"Branch", options:[
    { value:"Master", id:1 },
    { value:"Release", id:2 }
]},

//serverside options
{ view:"select", label:"Version", options:"server/options.php"}

See also

  • api
    • value
  • samples
    • Select Box ('select')
  • articles
    • Controls Guide
    • Select
    • Details

    Options can be set as:

    • a simple array;
    • an associative array of objects with id and value properties;
    • a string with a path to a script that loads options from server.

    The initially selected options is defined by value property.


ui.sidemenu

A collapsible side menu that allows selecting separate items.

The animated menu component that can be bound to any part of the screen. The size and position of Sidemenu can be customized. It can contain any other views, including complex layouts. Check sidemenu documentation for more detailed description.

Constructor

var sidemenu = webix.ui({
    view: "sidemenu",
    width: 200,
    position: "left",
    body:{
        view:"list",
        borderless:true,
        scroll: false,
        template: "<span class='webix_icon fa-#icon#'></span> #value#",
        data:[
            {id: 1, value: "Users", icon: "user"},
            {id: 2, value: "Products", icon: "cube"},
            {id: 3, value: "Reports", icon: "line-chart"}
        ]
    }
}).show();

Where to start

  • Overview of the Sidemenu Widget
  • Samples
Based on: ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setPosition | sets window's position
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
state | defines the position and size of Sidemenu
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
state | defines the position and size of Sidemenu
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component


state

defines the position and size of Sidemenu

function state;

Values

  • state
    an object that contains the position and size values set as Sidemenu properties

    • Example

    webix.ui({
    view: "sidemenu",
    width: 200,
    position: "left",
    state:function(state){
        // get the toolbar's height
        var toolbarHeight = $$("toolbar").$height;
        // increase the 'top' property
        state.top = toolbarHeight;
        // decrease the 'height' property
        state.height -= toolbarHeight;
    };
});

    See also

  • articles
    • Sidemenu


ui.slider

Horizontal slider for choosing numeric values from a range of predefined ones.

The control allows changing numeric data by dragging a marker over a line, with a defined step (optionally). Check slider documentation for more detailed description.

Constructor

var slider = webix.ui({
    view:"slider",
    label:"Level",
    value:"20",
    min:10,
    max: 120,
    name:"s1"
});

Where to start

  • Overview of the Slider Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSliderDrag | fires when the handle of slider was dragged ( but not released yet )
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
max | max value of slider
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
min | min value of slider
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
step | step of slider
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
title | text over slider bar
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$touchCapture | allows capturing touch gestures in touch limited mode.
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
max | max value of slider
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
min | min value of slider
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
step | step of slider
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
title | text over slider bar
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


Others

$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$touchCapture | allows capturing touch gestures in touch limited mode.
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


ui.spacer

A borderless empty view.

The component has a pure API and only used to fill a layout cell if it's supposed to be empty. Can be initialized by the simple {} construction. Check view documentation for more detailed description.

Constructor

webix.ui({
    view:"toolbar", cols:[
        {view:"button", value:"but1"},
        {},
        {view:"button", value:"but2"}
    ]
});
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
width | sets the width of the component


ui.spreadsheet

A component for organizing, working with and storing data in tabular form.

Webix SpreadSheet allows creating tables online, while keeping data locally. It's possible to import a ready table into an Excel document or export a table from Excel. The tables' appearance can be easily changed: you can customize the styles of colors, fonts and borders, set the necessary vertical and horizontal aligns, merge cells, rows and columns.

The component provides a built-in functionality for mathematical expressions and supports resizing and localization of tables.

Check SpreadSheet documentation for more information.

Constructor

var spreadsheet = webix.ui({
    view:"spreadsheet",
    data: base_data
});

Where to start

  • Overview of the SpreadSheet Widget
  • Samples
Based on: AtomDataLoader, IdSpace, ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
combineCells | merges several adjacent cells
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
eachSelectedCell | iterates over all selected cells in the table
enable | enables the calling view that was disabled by the 'disable' method
getCellValue | returns the value of the cell
getChildViews | returns child views of the calling component
getColumn | returns the configuration object of the specified SpreadSheet column
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getRow | returns the row data by its id
getSelectedId | returns the ids of all cells in the select area
getStyle | returns the style set for the cell
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
innerId | returns the unique inner ID of an item
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
reconstruct | rebuilds the layout
redo | remakes the action that was reverted by the undo action
refresh | repaints spreadsheet
removeView | removes view from layout-like component
reset | resets the SpreadSheet settings to the initial state
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
saveCell | saves changes made in the cell
serialize | serializes SpreadSheet data to a JSON object
setCellValue | sets a value for the cell
setStyle | sets a style for a cell
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
splitCell | splits the cells' span that was made by merging several cells
ui | allows creating new ui, the id of which will be locked in the parent id space
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
undo | undo operation in SpreadSheet
Events
onAfterLoad | fires after data loading is complete
onAfterSelect | fires after a cell has been selected
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSpan | fires before cells' are merged
onBeforeSplit | fires before merged cells are splitted
onBindRequest | fires when the component is ready to receive data from the master component
onCellChange | fires when a cell is changed
onComponentInit | fires when spreadsheet is initialized
onDataParse | fires when data parsing is started
onDataSerialize | fires when serialization of data is started
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onReset | fires when the settings of SpreadSheet are reset to the initial state
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
buttons | contains the names of buttons blocks with arrays of buttons' names
cols | array of views objects arranged horizontally
columnCount | the number of columns in the SpreadSheet
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
liveEditor |
margin | defines the space around elements (applies the specified value to all elements)
math | enables the math functionality in the spreadsheet
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
readonly | sets readonly mode for SpreadSheet
resizeCell | defines whether cells of spreadsheet will be resized
responsive | enables responsive mode for horizontal layout
rowCount | the number of rows in the SpreadSheet
rows | array of views objects arranged vertically
subbar | adds a view between the toolbar and the datatable
type | defines the layout borders
url | the URL which the component will use to load data after its initialization
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$$ | locates sub-item by id
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
combineCells | merges several adjacent cells
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
eachSelectedCell | iterates over all selected cells in the table
enable | enables the calling view that was disabled by the 'disable' method
getCellValue | returns the value of the cell
getChildViews | returns child views of the calling component
getColumn | returns the configuration object of the specified SpreadSheet column
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getRow | returns the row data by its id
getSelectedId | returns the ids of all cells in the select area
getStyle | returns the style set for the cell
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
innerId | returns the unique inner ID of an item
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
reconstruct | rebuilds the layout
redo | remakes the action that was reverted by the undo action
refresh | repaints spreadsheet
removeView | removes view from layout-like component
reset | resets the SpreadSheet settings to the initial state
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
saveCell | saves changes made in the cell
serialize | serializes SpreadSheet data to a JSON object
setCellValue | sets a value for the cell
setStyle | sets a style for a cell
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
splitCell | splits the cells' span that was made by merging several cells
ui | allows creating new ui, the id of which will be locked in the parent id space
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
undo | undo operation in SpreadSheet


combineCells

merges several adjacent cells

void combineCells(object range);

Parameters

range object optional, the range of cells that should be merged

Example

$$("ssheet").combineCells(range);

Details

If the range parameter isn't set, spreadsheet combines selected cells.

The range object includes three properties:

  • cell - (string) the id of the cell that starts the range
  • x - (number) the number of cells that will be merged horizontally
  • y - (number) the number of cells that will be merged vertically


eachSelectedCell

iterates over all selected cells in the table

void eachSelectedCell(function handler);

Parameters

handler function the handler function

Example

$$("ssheet").eachSelectedCell(
    function (cell){
        console.log($$("ssheet").getCellValue(cell.row,cell.column) )
    }
);


getCellValue

returns the value of the cell

string getCellValue(number row,number column);

Parameters

row | number | the row's number
column | number | the column's number

Returns

string the value of the cell

Example

var value = $$("ssheet").getCellValue(2, 3);

See also

  • api
    • setCellValue


getColumn

returns the configuration object of the specified SpreadSheet column

object getColumn(string id);

Parameters

id string the column id

Returns

object the column's configuration object

Example

var config = $$("ssheet").getColumn(id);


getRow

returns the row data by its id

object getRow(string id);

Parameters

id string the row's id

Returns

object the row's data

Example

var data = $$("ssheet").getRow(id);


getSelectedId

returns the ids of all cells in the select area

array getSelectedId();

Returns

array an array of selected cells

Example

var cells = $$("ssheet").getSelectedId();


getStyle

returns the style set for the cell

string getStyle(number row,number column);

Parameters

row | number | the number of the row
column | number | the number of the column

Returns

string the style set for the cell

Example

var style = $$("ssheet").getStyle(row, column);

See also

  • api
    • setStyle


innerId

returns the unique inner ID of an item

id innerId(id id);

Parameters

id id the ID of item

Returns

id the inner ID of item
Details

The method will be to the point when you use the same ID's for several nested components, e.g. you place 2 windows on page and put inside each of them list component. Both lists you are given the same ID: 'mylist'.

webix.ui({
  view:"window",
  id:"win1",
  body:{
        view:"list",
        id:"mylist",
        ...
  }
  ...
});

webix.ui({
  view:"window",
  id:"win2",
  body:{
        view:"list",
        id:"mylist",
        ...
  }
  ...
});

So, when you need to refer to one of this lists, you should use:

// for example, to refresh list from the second window
$$('win2').$$('mylist').refresh();

innerId() allows to shorten this referring:

realID=$$('win2').innerId('mylist');
//
$$('realID').refresh();


redo

remakes the action that was reverted by the undo action

void redo();

Example

$$("ssheet").redo();

See also

  • api
    • undo


refresh

repaints spreadsheet

void refresh();

Example

$$("ssheet").refresh();


reset

resets the SpreadSheet settings to the initial state

void reset();

Example

$$("ss").config.columnCount = 5;
$$("ss").config.rowCount = 10;
$$("ss").reset();


saveCell

saves changes made in the cell

void saveCell(number row,number column);

Parameters

row | number | the row's number
column | number | the column's number

Example

$$("ssheet").saveCell(row, column);


serialize

serializes SpreadSheet data to a JSON object

object serialize();

Returns

object serialized JSON object

Example

var data = $$("ssheet").serialize();


setCellValue

sets a value for the cell

void setCellValue(number row,object column,string value);

Parameters

row | number | the row's number
column | object | the column's number
value | string | the value that should be set for the cell

Example

$$("ssheet").setCellValue(row, column, value);

See also

  • api
    • getCellValue


setStyle

sets a style for a cell

void setStyle(number row,number column,string style);

Parameters

row | number | the row's number
column | number | the column's number
style | string | the style that should be set for the cell

Example

$$("ssheet").setStyle(row, column, style);

See also

  • api
    • getStyle


splitCell

splits the cells' span that was made by merging several cells

void splitCell(number row,number column);

Parameters

row | number | the number of the row that the span starts with
column | number | the number of the column that the span starts with

Example

$$("ssheet").splitCell(row, column);


ui

allows creating new ui, the id of which will be locked in the parent id space

WebixView ui(object view);

Parameters

view object config of view

Returns

WebixView newly created view

Example

some.ui({ view:"popup", id:"myid" });
...
//will NOT locate view
var view = $$("myid"); //null
//will locate view
var view = some.$$("myid"); //popup

Details

Arguments of the method are the same as for the webix.ui command


undo

undo operation in SpreadSheet

void undo(string id);

Parameters

id string optional, the id of an item

Example

$$("ssheet").undo();

See also

  • api
    • redo
  • articles
    • Undo for Data Components


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
buttons | contains the names of buttons blocks with arrays of buttons' names
cols | array of views objects arranged horizontally
columnCount | the number of columns in the SpreadSheet
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
liveEditor |
margin | defines the space around elements (applies the specified value to all elements)
math | enables the math functionality in the spreadsheet
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
readonly | sets readonly mode for SpreadSheet
resizeCell | defines whether cells of spreadsheet will be resized
responsive | enables responsive mode for horizontal layout
rowCount | the number of rows in the SpreadSheet
rows | array of views objects arranged vertically
subbar | adds a view between the toolbar and the datatable
type | defines the layout borders
url | the URL which the component will use to load data after its initialization
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


buttons

contains the names of buttons blocks with arrays of buttons' names

object buttons;

Example

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

See also

  • samples
    • Custom configuration of the toolbar
  • articles
    • Customizing SpreadSheet


columnCount

the number of columns in the SpreadSheet

number columnCount;

Example

webix.ui({
    view:"spreadsheet",
    data: base_data,
    columnCount:10
});

See also

  • api
    • rowCount
  • articles
    • Configuring Spreadsheet


liveEditor

enables the formula editor in spreadsheet

boolean liveEditor;

Example

webix.ui({
    view: "spreadsheet",
    data: base_data,
    liveEditor: true
});


math

enables the math functionality in the spreadsheet

boolean math;

Example

webix.ui({
    view:"spreadsheet",
    data: base_data,
    math:true
});


readonly

sets readonly mode for SpreadSheet

boolean readonly;

Example

webix.ui({
    view:"spreadsheet",
    data: base_data,
    readonly:true
});


resizeCell

defines whether cells of spreadsheet will be resized

boolean resizeCell;

Example

webix.ui({
    view:"spreadsheet",
    data: base_data,
    resizeCell:true
});


rowCount

the number of rows in the SpreadSheet

number rowCount;

Example

webix.ui({
    view:"spreadsheet",
    data: base_data,
    rowCount:20
});

See also

  • api
    • columnCount
  • articles
    • Configuring Spreadsheet


subbar

adds a view between the toolbar and the datatable

object subbar;

Example

webix.ui({
    view:"spreadsheet",
    data: base_data,
    subbar:{
        view:"toolbar",
        elements:[
            { view:'label', template:"Custom cell editor: ", width:190},
            { view:'text', id:'text', width:250 }
        ]
    },
});


Events

onAfterLoad | fires after data loading is complete
onAfterSelect | fires after a cell has been selected
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSpan | fires before cells' are merged
onBeforeSplit | fires before merged cells are splitted
onBindRequest | fires when the component is ready to receive data from the master component
onCellChange | fires when a cell is changed
onComponentInit | fires when spreadsheet is initialized
onDataParse | fires when data parsing is started
onDataSerialize | fires when serialization of data is started
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onReset | fires when the settings of SpreadSheet are reset to the initial state


onAfterSelect

fires after a cell has been selected

void onAfterSelect(string id){ ... };

Parameters

id string the cell's id

Example

$$("ssheet").attachEvent("onAfterSelect", function(id){
    // some code here
});


onBeforeSpan

fires before cells' are merged

void onBeforeSpan(number row,number column,array size){ ... };

Parameters

row | number | the number of the row that the span starts with
column | number | the number of the column that the span starts with
size | array | the number of cells in col and row spans

Example

$$("ssheet").attachEvent("onBeforeSpan", function(row, column, size){
    // some code here
    return true;
});

Details

return false to block cell's merging


onBeforeSplit

fires before merged cells are splitted

void onBeforeSplit(number row,number column,array value ){ ... };

Parameters

row | number | the number of the row that the span starts with
column | number | the number of the column that the span starts with
value | array | the array with values of the deleted span

Example

$$("ssheet").attachEvent("onBeforeSplit", function(row, column, value){
    // some code here
    return true;
});

Details

return false to block cell's splitting


onCellChange

fires when a cell is changed

void onCellChange(number row,number column,string value){ ... };

Parameters

row | number | the number of the row
column | number | the number of the column
value | string | the value of the cell

Example

$$("ssheet").attachEvent("onCellChange", function(row, column, value){
    // some code here
});


onComponentInit

fires when spreadsheet is initialized

void onComponentInit(){ ... };

Example

$$("ssheet").attachEvent("onComponentInit", function(){
    // some code here
});


onDataParse

fires when data parsing is started

void onDataParse(object data){ ... };

Parameters

data object data that should be parsed

Example

$$("ssheet").attachEvent("onDataParse", function(data){
    // some code here
});


onDataSerialize

fires when serialization of data is started

void onDataSerialize(object data){ ... };

Parameters

data object the data that should be serialized

Example

$$("ssheet").attachEvent("onDataSerialize", function(data){
    // some code here
});


onReset

fires when the settings of SpreadSheet are reset to the initial state

void onReset(){ ... };

Example

$$("ssheet").attachEvent("onReset", function(){
    // some code here
});


Others

$$ | locates sub-item by id
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


$$

locates sub-item by id

object $$;

Example

var view  = some.$$('list1');


ui.submenu

A sub-menu.

The component is a compliment to the menu component and isn't intended for direct initialization. Check menu documentation for more detailed description.

Constructor

webix.ui({
    view:"menu",
    subMenuPos:"right",
    data:[
        { value:"Translate...", submenu:["English", "Slavic...", "German"]},
        { value:"Post...", submenu:[ "Facebook", "Google+", "Twitter" ]}
    ],
    type:{
        subsign:true,
        height:50
    }
});
Based on: ui.menu, ui.list, KeysNavigation, DataMove, DragItem, MouseEvents, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, CopyPaste, ui.popup, ui.window, Movable, Modality
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | removes a window
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
disableItem | disables menu item
enable | enables the calling view that was disabled by the 'disable' method
enableItem | enables menu item
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getMenu | gets object of a menu/submenu where an item is located
getMenuItem | search for menu item in submenus
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getSubMenu | gets the submenu object of a menu item (if any)
getTopMenu | returns top menu object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideItem | hides menu item
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
setPosition | sets window's position
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sizeToContent | adjusts the size of menu and its submenus to their content
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMenuItemClick | fires when menu item has been clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
body | the content of window body: template or view
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
mouseEventDelay | the delay between a real mouse action and invoking the related events
move | makes view movable
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
openAction | alters the way of submenu opening to "click"
padding | sets paddings of the chart content
pager | defines paging configuration ( creates a 'ui.pager' object)
position | sets position of the window relative to the the screen
ready | event handler called just after the component has been completely initialized
relative | positions a popup window relative to the component it's connected with
removeMissed | defines how to treat items in case of reloading
resize | enables/disables window resizing
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subMenuPos | aligns submenu towards main menu
submenuConfig | defines submenu configuration
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
toFront | places window above other windows on clicking it
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
top | the top offset of a window
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
zIndex | stack order of the component
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | removes a window
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
disableItem | disables menu item
enable | enables the calling view that was disabled by the 'disable' method
enableItem | enables menu item
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getMenu | gets object of a menu/submenu where an item is located
getMenuItem | search for menu item in submenus
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getSubMenu | gets the submenu object of a menu item (if any)
getTopMenu | returns top menu object
getTopParentView | returns top parent view
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideItem | hides menu item
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
setPosition | sets window's position
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sizeToContent | adjusts the size of menu and its submenus to their content
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
body | the content of window body: template or view
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
mouseEventDelay | the delay between a real mouse action and invoking the related events
move | makes view movable
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
openAction | alters the way of submenu opening to "click"
padding | sets paddings of the chart content
pager | defines paging configuration ( creates a 'ui.pager' object)
position | sets position of the window relative to the the screen
ready | event handler called just after the component has been completely initialized
relative | positions a popup window relative to the component it's connected with
removeMissed | defines how to treat items in case of reloading
resize | enables/disables window resizing
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subMenuPos | aligns submenu towards main menu
submenuConfig | defines submenu configuration
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
toFront | places window above other windows on clicking it
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
top | the top offset of a window
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
zIndex | stack order of the component


ui.suggest

A suggest control.

Can be used standalone or as an editor for other components. Check suggest documentation for more detailed description.

Constructor

webix.ui({
    view:"text",
    width: 300,
    name:"country",
    label:"Country",
    value:"Belarus", suggest:[
        {id:1, value: "Albania"},
        {id:2, value: "Bhutan"},
        {id:3, value: "Colombia"},
        {id:4, value: "Denmark"},
        {id:5, value: "Germany"},
        {id:6, value: "Moldova"}
    ]
});

Where to start

  • Overview of Suggest List
  • Samples
Based on: ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValueSuggest | some item selected in the suggest control
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.tabbar

A panel that contains multiple clickable items.

Items of the component combine icons with text labels. The component can be used to build a multi-item menu for navigating between views. Check tabbar documentation for more detailed description.

Constructor

webix.ui({
    rows:[
        {view:"tabbar", id:'tabbar', value:'formView', multiview:true, options: [
            { value: 'Form', id: 'formView'},
            { value: 'Empty', id: 'emptyView'}
        ]},
        {
          cells:[
             {id:"formView",template:"Form Content"},
             {id:"emptyView", template:"Some content"}
        ]}
    ]
});

Where to start

  • Overview of the Tabbar Control
  • Samples
Based on: ui.segmented, ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
addOption | add a new option (segment) to the button
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | return the optional popup with extra tabs
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
optionIndex | index of the option with specified ID
refresh | repaints the component
removeOption | removes the option of a segmented button
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onAfterTabClick | fires after a segment has been clicked
onBeforeRender | occurs immediately before the component has been rendered
onBeforeTabClick | fires before a segment is clicked
onBeforeTabClose | fires before the tab is closed
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onOptionRemove | fires after the option (tab, segment) has been removed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomOffset | bottom offset of tabbar
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
moreTemplate | template for "more" button for responsive tabbar
multiview | enables switching between multiview cells
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionWidth | sets the width of each view's option
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupTemplate | template for items in popup for responsive tabbar
popupWidth | width of popup for extra tabs
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tabMargin | space between tabs
tabMinWidth | minimum width for responsive tabs
tabMoreWidth | width of "more" button in tabbar
tabOffset | left padding of first tab
tabbarPopup | custom popup for responsive tabbar
tooltip | tooltip for the input
topOffset | top offset of tabbar
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
yCount | count of items in popup for responsive tabbar
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

addOption | add a new option (segment) to the button
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getPopup | return the optional popup with extra tabs
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
optionIndex | index of the option with specified ID
refresh | repaints the component
removeOption | removes the option of a segmented button
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input


addOption

add a new option (tab) to the tabbar

void addOption(id id,any value, [boolean show ,number index] );

Parameters

id | id | ID of the new option
value | any | value of the new option
show | boolean | makes the newly added option active. 'false' by default
index | number | position to insert to. Last, by default

Example

function open_new_tab(id){
    var item = $$('list1').getItem(id);
    $$('tabs').addOption(item.id, item.title, true);
};

Details

In case of a tabbar, the method can as well take a more extensive option configuration of a tab.

And the parameters are as follows:

  • obj (obj) - tab configuration;
  • show (boolean) - makes the newly added option active;
  • index (number) - position to insert to. Last, by default.
tabbar.addOption({id:1, value:"New", close:true, icon:"cog"}, true);

See also

  • api
    • removeOption
  • samples
    • Dynamic Adding/Deleting of Tabs in Tabbar
  • articles
    • Adding and Deleting Multiview Cells Dynamically


getPopup

return the optional popup with extra tabs

WebixView getPopup();

Returns

WebixView popup with extra tabs


getValue

returns the current value of the control

string getValue();

Returns

string the current value of the control

Example

{ view:"tabbar", type:"bottom", value:"one", options:[
                { id:"one", value:"One" },
                { id:"two", value:"Two"},
                { id:"three", value:"Three"}
            ]}
...
$$("tabbar1").getValue(); // returns "one"

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
    • value
  • articles
    • Controls Guide


optionIndex

index of the option with specified ID

number optionIndex(id ID );

Parameters

ID id ID of the needed option

Returns

number index of the option

Example

$$("tabbar").optionIndex(1);

Details

Since options are stored in the array, option indexes are numbered staring from 0.


removeOption

removes the option of a tabbar

void removeOption(id id );

Parameters

id id ID of the option being removed

Example

function del_tab(){
    var tab_id = $$("tabs").getValue();
    $$("tabs").removeOption(tab_id);
}

See also

  • api
    • addOption
    • onOptionRemove
  • samples
    • Dynamic Adding/Deleting of Tabs in Tabbar
  • articles
    • Adding and Deleting Multiview Cells Dynamically


setValue

sets a new value for the component

void setValue(string value);

Parameters

value string a new value for the control

Example

{ view:"tabbar", id:"tabs", type:"bottom",  options:[
                { id:"one", value:"One" },
                { id:"two", value:"Two"},
                { id:"three", value:"Three"}
            ]}
...

$$("tabs").setValue("two");
        //the second option will be selected

See also

  • api
    • getValue
    • value
  • articles
    • Controls Guide


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomOffset | bottom offset of tabbar
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
moreTemplate | template for "more" button for responsive tabbar
multiview | enables switching between multiview cells
name | name of the control
on | allows attaching custom handlers to inner events of the component
optionWidth | sets the width of each view's option
options | defines data items of the drop-down list
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
popupTemplate | template for items in popup for responsive tabbar
popupWidth | width of popup for extra tabs
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tabMargin | space between tabs
tabMinWidth | minimum width for responsive tabs
tabMoreWidth | width of "more" button in tabbar
tabOffset | left padding of first tab
tabbarPopup | custom popup for responsive tabbar
tooltip | tooltip for the input
topOffset | top offset of tabbar
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
yCount | count of items in popup for responsive tabbar


bottomOffset

bottom offset of tabbar

number bottomOffset;

Example

webix.ui({
    view:"tabbar",
    bottomOffset:10
})


moreTemplate

template for "more" button for responsive tabbar

function moreTemplate;


options

defines tabs in a tabbar

object options;

Example

webix.ui({
    view:"tabbar",
    id:'tabbar',
    value: 'listView', // the initially selected tab
    multiview:true,
    options: [
          { value: 'List', id: 'listView'},
          { value: 'Form', id: 'formView'},
          { value: 'Empty', id: 'emptyView'}
          ]
});

See also

  • api
    • getValue
    • setValue
  • samples
    • Holistic Panel with Multiple Buttons ('segmented')
  • articles
    • Controls Guide
    • Details

    The property is an array of objects, each of which presents a singular select option on a toolbar.

    The objects in the array have 2 attributes:

    • id - (id) the item id
    • value - (string) the item label

    Nore that the getValue() method returns the ID of selected option.


popupTemplate

template for items in popup for responsive tabbar

function popupTemplate;


popupWidth

width of popup for extra tabs

number popupWidth;


tabMargin

space between tabs

number tabMargin;

Example

webix.ui({
    view:"tabbar",
    tabMargin:10
})


tabMinWidth

minimum width for responsive tabs

number tabMinWidth;


tabMoreWidth

width of "more" button in tabbar

number tabMoreWidth;


tabOffset

left padding of first tab

number tabOffset;

Example

webix.ui({
    view:"tabbar",
    tabOffset:10
})


tabbarPopup

custom popup for responsive tabbar

WebixView tabbarPopup;


topOffset

top offset of tabbar

number topOffset;

Example

webix.ui({
    view:"tabbar",
    topOffset:10
})


type

the type of the control

string type;

Values

  • bottom
    styles tabbar to match bottom position

    • Example

    rows:[
    { cells:[..] },//multiview cells..
    { view:"tabbar", type:"bottom", options:[..] }
]

    See also

  • articles
    • Tabbar


yCount

count of items in popup for responsive tabbar

number yCount;


Events

onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onAfterTabClick | fires after a segment has been clicked
onBeforeRender | occurs immediately before the component has been rendered
onBeforeTabClick | fires before a segment is clicked
onBeforeTabClose | fires before the tab is closed
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onOptionRemove | fires after the option (tab, segment) has been removed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


onBeforeTabClose

fires before the tab is closed

void onBeforeTabClose(string| number id,event e){ ... };

Parameters

id | string| number | tab ID
e | event | event object

Example

tabbar.attachEvent("onBeforeTabClose", function(id, e){
    //code
});

Details

The event fires when user clicks on the "close" button of the tab, but before it is really removed.

The event is cancellable, which means that if an event handler return false, the tab won't be removed.

tabbar.attachEvent("onBeforeTabClose", function(id, e){
    //code
    return false;
});

See also

  • api
    • onOptionRemove
  • samples
    • Tabview: Close tab button
  • articles
    • Tabbar


onItemClick

fires after the control has been clicked

void onItemClick(string| number id,event e){ ... };

Parameters

id | string| number | control ID
e | event | event object

Example

button.attachEvent("onItemClick", function(id, e){
    //code
});

Details

The event fires after tab-related click events (onBeforetabClick and onAfterTabClick).

See also

  • api
    • onAfterTabClick
    • onBeforeTabClick
    • click
  • samples
    • List: Active Content
  • articles
    • Event Handling


onOptionRemove

fires after the option (tab, segment) has been removed

void onOptionRemove(string| number id,string value){ ... };

Parameters

id | string| number | option ID
value | string | option value

Example

tabbar.attachEvent("onOptionRemove", function(id, value){
    //code
});

See also

  • api
    • onBeforeTabClose
    • removeOption
  • articles
    • Tabbar


ui.tabview

A container control with a navigation tab panel that keeps a set of views and displays one view at a time.

The component optimizes the process of creating tabbed structures on the page - elements that present multiple groups of content switched by tabs. Check tabview documentation for more detailed description.

Constructor

var tabview = webix.ui({
    view:"tabview",
    cells:[
      {
        header:"Form",
        body:{
            template:"Form Content"
        }
      },
      { header:"Empty",
        body:{
          template:"Some content"
        }
      }
    ]
});

Where to start

  • Overview of the Tabview Widget
  • Samples
Based on: ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getMultiview | returns webix ui for multiview in tabbar
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTabbar | returns webix ui for Tabbar in tabview
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setValue | sets a new value for the component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cells | defines content of tabview
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multiview | allows to configure multiview part of tabview
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
tabbar | allows to configure tabbar part of tabview
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getMultiview | returns webix ui for multiview in tabbar
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTabbar | returns webix ui for Tabbar in tabview
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setValue | sets a new value for the component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


addView

add new view to layout-like component

WebixView addView(object view);

Parameters

view object configuration of new view

Returns

WebixView new view object

Example

$$("tabview1").addView({
    header:"New Tab",
    body:{
        template:"New content "+webix.uid()
    }
});

Details

The method works for layout rows and cols, multiview cells, accordion and carousel panels, toolbar and form controls.

See also

  • api
    • removeView
    • ui
  • samples
    • Tabview: Adding and Removing tabs
  • articles
    • Dynamic UI Modifications


getMultiview

returns webix ui for multiview in tabbar

object getMultiview();

Returns

object webix ui for multiview in tabbar

Example

// view - instance of webix.ui.multiview
var view = $$("mytabs").getMultiview();


getTabbar

returns webix ui for Tabbar in tabview

object getTabbar();

Returns

object webix ui for Tabbar in tabview

Example

// view - instance of webix.ui.tabbar
var view = $$("mytabs").getTabbar();


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cells | defines content of tabview
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multiview | allows to configure multiview part of tabview
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
tabbar | allows to configure tabbar part of tabview
type | defines the layout borders
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


cells

defines content of tabview

array cells;

Example

webix.ui({
    view:"tabview",
    cells:[
      { header:"A", template:"My Tab 1 "},
      { header:"B", template:"My Tab 2 "}
    ]
})


multiview

allows to configure multiview part of tabview

object multiview;

Example

webix.ui({
    view:"tabview",
    multiview:{
      animate:{ type:"slide" }
    },
    cells:[
      { header:"A", template:"My Tab 1 "},
      { header:"B", template:"My Tab 2 "}
    ]
})


tabbar

allows to configure tabbar part of tabview

object tabbar;

Example

webix.ui({
    view:"tabview",
    tabbar:{
        optionWidth:100
    },
    cells:[
      { header:"A", template:"My Tab 1 "}
    ]
})


ui.template

A view with some HTML content inside.

The component is a simple container (but with rich API support) where you can put any HTML content. Check template documentation for more detailed description.

Constructor

var template = webix.ui({
  view: "template",
  template: "Default template with some text inside"
});

Where to start

  • Overview of the Template Widget
  • Samples
Based on: Scrollable, AtomDataLoader, AtomRender, EventSystem, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | gets data hash
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
setContent | attaches html container to the template
setHTML | set hmlt for template
setValues | sets data hash
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | lets the component autosize to its contents
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
content | the id or node, whose content will be moved to the view
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
src | the path to an external template that is loaded by Ajax
template | the component template
type | name of predefined styling type
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | gets data hash
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
setContent | attaches html container to the template
setHTML | set hmlt for template
setValues | sets data hash
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getValues

gets data hash

void getValues();

Example

webix.ui({
    view:"template",
    id:"template1",
    data:{
        src:"imgs/image002.jpg"
    }
});

var values = $$("template1").getValues(); //{src:"imgs/image002.jpg"}

See also

  • api
    • setValues
  • articles
    • Template


setValues

sets data hash

void setValues(object obj, [boolean update] );

Parameters

obj | object | data object
update | boolean | if true, updates only changed values while the unchanged ones remain

Example

$$("template1").setValues({src:"imgs/image002.jpg"});

Details

Working with template data object

The method only make sence if you use a template with a single data element defined for it.

For instance, you have a template object with the following configuration:

{
    view:"template", //optional
    id:"template1",
    data:{
        src:"imgs/image001.jpg",
        desrc:"mytown"
    },
    template:function(obj){
        return '<img src="'+obj.src+'"/>';
    }
}

Then data from both initially defined and modified data object will be correctly displayed.

Manipulating values

The second parameter helps manipulate values set separately. By default, it is false.

Take that we set new value for a src property from the template described above.

$$("template1").setValues({src:"imgs/image002.jpg"});

In this case, the value for the descr property is lost. To avoid this, set the update parameter to true. Template data will be updated with a new value for src property while descr value remains unchanged.

$$('template1').setValues({src:"imgs/image002.jpg"}, true);

See also

  • api
    • getValues
  • samples
    • Carousel Initialization
  • articles
    • Template
    • Data Templates


Properties

animate | defines or disables view change animation.
autoheight | lets the component autosize to its contents
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
content | the id or node, whose content will be moved to the view
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
src | the path to an external template that is loaded by Ajax
template | the component template
type | name of predefined styling type
url | the URL which the component will use to load data after its initialization
width | sets the width of the component


template

the component template

string|function template;

Example

{ view:"template", type:"header", template:"This is a List Header"}

See also

  • api
    • src
  • samples
    • Autosizing to Content
    • Scrollview
  • articles
    • Template
    • Data Templates
    • Details

    1 . Above is the common text template for template component:

    2 . Data template for data-containing components:

    { view:"list", template:"#id#.#title#" }
 // the list will show ID and title of each data item from the specified datasource

    3 . Function template (takes data object and function parameter):

    { view:"list", template:function(obj){
    return "<div class='overall'><div class='rank'>"
        +obj.rank+"</div>"+
        "<div class='title'>"+obj.title+"</div></div>"
}}
//the list will show rank and title of each item styled with specified CSS

    4 . HTML templates defined within an HTML container:

    { view: "dataview", template:"html->template_container" }

    5 . HTML template defined in the external file:

    { view:"dataview", template:"http->template.html" }

    6 . Template component can load the external template by Ajax:

    { view:"template", src:"loadtext.php" }


type

name of predefined styling type

string type;

Example

webix.ui({
  view:"template",
  type:"header",
  template:"My header text" });

Details

There are two predefined types:

  • header
  • section


Events

onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


ui.text

A one-line, editable text field with the label inside it.

A label inside the control distinguishes it from the input component. Check text documentation for more detailed description.

Constructor

var text = webix.ui({
   view:"text",
   value:'dummy@email.com',
   label:"Email"
});

Where to start

  • Overview of the Text Control
  • Samples
Based on: ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | sets an icon into the control
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


type

the type of the control

string type;

Values

  • text
    set by default
  • password
  • email
  • url

    • Example

    { view:"button", id:"button1", type:"form", label: "Button"}
//
{view:"text", label:"text", type:"password", align:"left"}

    See also

  • articles
    • Button
    • Details

    The parameter can take only one of a predefined set of values.

    'Password' type ensures that input symbols are displayed as asterisks while 'email' and 'url' are vidal for HTML5 input data validation.


ui.textarea

A multiline, editable text field.

Check textarea documentation for more detailed description.

Constructor

var textarea = webix.ui({
   view:"textarea",
   label:"Note",
   labelAlign:"right",
   height:150,
   value: "type here"
});

Where to start

  • Overview of the Textarea Control
  • Samples
Based on: ui.text, ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | validates value of input
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$render | code called after rending control
$renderIcon | renders icon for the control
$renderInput | called each time when component need to paint control's input
$renderLabel | renders html for the label
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
attributes | sets a hash of HTML input attributes that will be parsed for the Webix input control
autowidth | adjusts button to its text content
borderless | used to hide the component borders
bottomLabel | sets a label under a control
bottomPadding | sets the bottom offset of the control input
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputPadding | padding of text in the input
inputWidth | the width of the input area, or a button's text value area.
invalidMessage | sets the text of a validation message
label | the text label of the control
labelPosition | positions label in relation to the control
labelWidth | the width of the label
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
on | allows attaching custom handlers to inner events of the component
placeholder | placeholder text for the input area
popup | allows to attach pop-up menu to the button
readonly | configures readonly mode for the input
relatedAction | action to call when value of cell changes
relatedView | id of view, that will be affected by relatedAction operation
required | marks field as required
suggest | links suggest list to the input
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
validate | adds validation to the field
validateEvent | on which event validation fires
value | sets the initial value for a control
width | sets the width of the component


onKeyPress

occurs when keyboard key is pressed for the control in focus

void onKeyPress(number code,event e){ ... };

Parameters

code | number | key code
e | event | event object

Example

text.attachEvent("onKeyPress", function(code, e){
    //code
});

See also

  • api
    • onTimedKeyPress
  • articles
    • Event Handling
    • Keyboard Events. Focusing. Navigation


ui.toggle

A two-state button.

The component is fully customizable and can be used both as a stand-alone view and as a part of a form or a toolbar. Check toggle documentation for more detailed description.

Constructor

var toggle = webix.ui({
    view:"toggle",
    type:"iconButton",
    name:"s4",
    offIcon:"pause",
    onIcon:"play",
    offLabel:"Disabled",
    onLabel:"Enabled"
});

Where to start

  • Overview of the Toggle Control
  • Samples
Based on: ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
toggle | changes the state of the two-state control
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | an icon for pressed and unpressed toggle states
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
offIcon | an icon for an unpressed toggle
offLabel | a text label on the button in the unpressed state
on | allows attaching custom handlers to inner events of the component
onIcon | an icon for a pressed toggle
onLabel | a text label on the button in the pressed state
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
value | sets the initial value for a control
width | sets the width of the component
Other
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
setValue | sets a new value for the component
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
toggle | changes the state of the two-state control
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


toggle

changes the state of the two-state control

void toggle();

Example

$$('toggle1').toggle();

Details

If the toggle button was pressed - it becomes unpressed and vice versa.

See also

  • articles
    • Controls Guide


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
icon | an icon for pressed and unpressed toggle states
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputWidth | the width of the input area, or a button's text value area.
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
name | name of the control
offIcon | an icon for an unpressed toggle
offLabel | a text label on the button in the unpressed state
on | allows attaching custom handlers to inner events of the component
onIcon | an icon for a pressed toggle
onLabel | a text label on the button in the pressed state
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
value | sets the initial value for a control
width | sets the width of the component


icon

an icon for pressed and unpressed toggle states

string icon;

Example

{
    view:"toggle",
    type:"iconButton",
    name:"s4",
    icon:"pressed"
}


offIcon

an icon for an unpressed toggle

string offIcon;

Example

{ view:"toggle", type:"iconButton", name:"s4", offIcon:"pause"}


offLabel

a text label on the button in the unpressed state

string offLabel;

Example

{ view:"toggle", type:"iconButton", name:"s4", offLabel:"Disabled"}


onIcon

an icon for a pressed toggle

string onIcon;

Example

{ view:"toggle", type:"iconButton", name:"s4", onIcon:"play"}


onLabel

a text label on the button in the pressed state

onLabel;

Example

{ view:"toggle", type:"iconButton", name:"s4", onLabel:"Enabled"}


ui.toolbar

A horizontal toolbar.

The component can contain various elements inside it (actually, the same elements that the form can contain): an icon, a button, a label, an input box etc. Check toolbar documentation for more detailed description.

Constructor

var toolbar = webix.ui({
    view:"toolbar",
    id:"myToolbar",
    cols:[
        { view:"button", id:"LoadBut", value:"Load", width:100, align:"left" },
        { view:"button", value:"Save", width:100, align:"center" },
        { view:"button", value:"Info", width:100, align:"right" }
    ]
});

Where to start

  • Overview of the Toolbar Widget
  • Samples
Based on: Scrollable, AtomDataLoader, Values, ui.layout, ui.baselayout, EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension, ValidateData
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clear | clears all the field in a specified form
clearValidation | removes "data incorrect" highlighting from invalid text fields
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
focus | sets focus into the necessary component
getChildViews | returns child views of the calling component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getScrollState | returns the scroll position
getTopParentView | returns top parent view
getValues | derives input values from the form
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isDirty | checks whether changes within form were made
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
markInvalid | marks a form control invalid
parse | loads data to the component from an inline data source
reconstruct | rebuilds the layout
refresh | repaints the component
removeView | removes view from layout-like component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
scrollTo | scrolls the data container to a certain position
setDirty | marks the form as the one with changed values and vice versa
setValues | sets values into the inputs of a form/toolbar/property sheet control
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | checks data in the form
Events
onAfterLoad | fires after server side loading is complete
onAfterScroll | fires when to component is scrolled in any direction
onAfterValidation | fires after data has been validated
onBeforeLoad | occurs immediately before data loading has been started
onBeforeValidate | called before running validation
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when data in the input or related form/toolbar is changed
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully
onValues | fires after values have been set within toolbar or form
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
elements | collection of subviews
elementsConfig | settings, which will be applied to all nested inputs
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
rules | defines a set of rules for input field(s) of the form(htmlform)
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
type | defines the layout borders
url | the URL which the component will use to load data after its initialization
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


clearValidation

removes "data incorrect" highlighting from invalid text fields

void clearValidation();

Example

$$(datatable1).clearValidation();"}

Details

The function removes highlighting from fields with failed validation. This is done for convenience means so that users can continue filling in the form without annoying red. It doesn't cancel validation rules.

See also

  • api
    • validate
    • rules
  • samples
    • Validation with Predefined Rules
  • articles
    • Data Validation


index

returns the cell index in the layout collection

number index(object obj);

Parameters

obj object the cell object

Returns

number the cell index in the collection of the parent layout

Example

$$("mytoolbar").index($$('button1'));

See also

  • articles
    • View


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
complexData | enables complex data parsing mode
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
elements | collection of subviews
elementsConfig | settings, which will be applied to all nested inputs
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
isolate | masks IDs of all inner element
margin | defines the space around elements (applies the specified value to all elements)
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
padding | defines the space between the element borders and content (applies the specified value to all sides).
paddingX | sets the right and left padding (applies the specified value to both sides)
paddingY | sets the top and bottom padding (applies the specified value to both sides)
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
rules | defines a set of rules for input field(s) of the form(htmlform)
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
type | defines the layout borders
url | the URL which the component will use to load data after its initialization
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


cols

array of views objects arranged horizontally

array cols;

Example

// layout example
webix.ui({
    rows:[
        { view:"toolbar", ... },
        {
            cols:[
                { view:"list", ... },
                { view:"form", ... }
        ]}
    ]
})

See also

  • api
    • rows
  • samples
    • Toolbar: Multiple Rows
  • articles
    • Layout and Resizer


rows

array of views objects arranged vertically

array rows;

Example

// layout example
webix.ui({
    rows:[
        { view:"toolbar", ... },
        {
            cols:[
                { view:"list", ... },
                { view:"form", ... }
        ]}
    ]
})

See also

  • api
    • cols
  • samples
    • Toolbar: Multiple Rows
  • articles
    • Layout and Resizer


Events

onAfterLoad | fires after server side loading is complete
onAfterScroll | fires when to component is scrolled in any direction
onAfterValidation | fires after data has been validated
onBeforeLoad | occurs immediately before data loading has been started
onBeforeValidate | called before running validation
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when data in the input or related form/toolbar is changed
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully
onValues | fires after values have been set within toolbar or form


ui.tooltip

A static text that is rendered in the absolutely positioned container.

Generally, the component isn't intended for direct initialization. But if you decide to use it, use mouse events (onMouseOut, onMouseIn, onMouseMove etc.) to show/hide the tooltip box in the specified position. Check tooltip documentation for more detailed description.

Constructor

webix.ui({
    view:"datatable",
    tooltip:true,
    columns:[
        {id:"name", header:"Name"},
        {id:"age", header:"Age"}
    ],
    data:[
        {id:1, name:"Ann", age:25},
        {id:2, name:"Tom", age:27}
    ]
});

Where to start

  • Overview of Tooltip
  • Samples
Based on: SingleRender, AtomRender, Settings, EventSystem, ui.view, ui.baseview, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
customize | redefines the 'type' property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
render | renders the specified item or the whole component
resize | adjusts the view to a new size
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
dx | the left offset of the tooltip from the mouse pointer
dy | the top offset of the tooltip from the mouse pointer
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
template | the component template
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
type | currently used set of helpers for view rendering


Methods

adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
customize | redefines the 'type' property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
render | renders the specified item or the whole component
resize | adjusts the view to a new size
show | makes the component visible
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


disable

disables the tooltip (tooltips won't appear anymore)

void disable();

Example

myView = webix.ui({
    view:"dataview",
    ...
    tooltip:{
        template:" Rating: #rating# <br> Votes: #votes#"
    }
});

$$('dataview1').config.tooltip.disable();

See also

  • api
    • enable
  • samples
    • articles
      • Tooltip Implementation


enable

enables the tooltip (after it has beed disabled)

void enable();

Example

myView = webix.ui({
    view:"dataview",
    ...
    tooltip:{
        template:" Rating: #rating# <br> Votes: #votes#"
    }
});

$$('dataview1').config.tooltip.enable();

See also

  • api
    • disable
  • samples
    • articles
      • Tooltip Implementation


hide

hides the tooltip

void hide();

Example

myView = webix.ui({
    view:"dataview",
    ...
    tooltip:{
        template:" Rating: #rating# <br> Votes: #votes#"
    }
});

myView.config.tooltip.hide();

See also

  • api
    • samples
      • articles
        • Tooltip Implementation


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
dx | the left offset of the tooltip from the mouse pointer
dy | the top offset of the tooltip from the mouse pointer
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
template | the component template
width | sets the width of the component


dx

the left offset of the tooltip from the mouse pointer

number dx;

Example

tooltip:{
    template:"#title# - #year#",
    dx: 30,
    dy: 5
}

See also

  • api
    • dy
  • articles
    • Tooltip Implementation
    • Details

    By default the parameter is equal to 20px.

    A negative value places the tooltip to the left of the mouse pointer.


dy

the top offset of the tooltip from the mouse pointer

number dy;

Example

tooltip:{
    template:"#title# - #year#",
    dx: 30,
    dy: 5
}

See also

  • api
    • dx
  • articles
    • Tooltip Implementation
    • Details

    By default the parameter is equal to 0px.

    A negative value places the tooltip above the mouse pointer.


Events

onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
type | currently used set of helpers for view rendering


ui.tree

A hierarchical structure of nodes..

Each node in the tree might contain any number of nodes. Nodes that contain child nodes can be expanded or collapsed.

The component supports in-line node editing, advanced drag-and-drop, three-state checkboxes, etc. Check tree documentation for more detailed description.

Constructor

var tree = webix.ui({
    view:"tree",
    select:true,
    data: [
        {id:"root", value:"Cars", open:true, data:[
            { id:"1", open:true, value:"Toyota", data:[
                { id:"1.1", value:"Avalon" },
                { id:"1.2", value:"Corolla" },
                { id:"1.3", value:"Camry" }
            ]},
            { id:"2", value:"Skoda", open:true, data:[
                { id:"2.1", value:"Octavia" },
                { id:"2.2", value:"Superb" }
            ]}
        ]}
    ]
});

Where to start

  • Overview of the Tree Widget
  • Samples
Based on: AutoTooltip, Group, TreeAPI, DragItem, TreeDataMove, SelectionModel, KeysNavigation, MouseEvents, Scrollable, TreeDataLoader, TreeStore, DataStore, ui.proto, PagingAbility, DataMarks, ValidateCollection, RenderStack, DataLoader, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, TreeRenderStack, CopyPaste, TreeStateCheckbox
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
checkAll | check all items in tree
checkItem | checks the checkbox it the tree item
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | closes the branch with the specified id
closeAll | closes all branches in the tree
copy | makes a copy of item
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBranchIndex | gets index of the node in a specific branch
getChecked | returns ids of the checked items
getChildViews | returns child views of the calling component
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getState | returns the current state of the view
getTopParentView | returns top parent view
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isChecked | checks whether the specified node is checked
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveSelection | moves selection in the specified direction
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setState | restores the specified state
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
uncheckAll | uncheck all items in the tree
uncheckItem | unchecks the checkbox in the tree item
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterClose | fires after the branch has been closed
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemCheck | fires when you check an item in tree and treetable
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPartialRender | called when part of tree is repainted
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
filterMode | defines the pattern for tree item filtering
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
threeState | defines three-state checkboxes for the tree. Flase by default.
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
checkAll | check all items in tree
checkItem | checks the checkbox it the tree item
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | closes the branch with the specified id
closeAll | closes all branches in the tree
copy | makes a copy of item
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBranchIndex | gets index of the node in a specific branch
getChecked | returns ids of the checked items
getChildViews | returns child views of the calling component
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getState | returns the current state of the view
getTopParentView | returns top parent view
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isChecked | checks whether the specified node is checked
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveSelection | moves selection in the specified direction
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setState | restores the specified state
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
uncheckAll | uncheck all items in the tree
uncheckItem | unchecks the checkbox in the tree item
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


add

adds a new item to the tree

string add(object obj, [number index,string parentId] );

Parameters

obj | object | the item object
index | number | the position that the item will be added to (zero-based numbering)
parentId | string | the parent id

Returns

string ID of the newly added item

Example

//inserts a new item into the branch with id='root'
tree.data.add({id:"item10", value:"NewItem"}, 0, "root" );

See also

  • samples
    • Adding and deleting Nodes
  • articles
    • Tree Nodes manipulations


checkAll

check all items in tree

void checkAll( [id id] );

Parameters

id id id of the branch

Example

tree.checkAll();

Details

If id provided - only item in the target branch will be checked, else - all items in the tree


checkItem

checks the checkbox it the tree item

void checkItem(string id);

Parameters

id string the id of an item to check

Example

tree = new webix.ui({
    view:"tree",
    template:"{common.icon()} {common.folder()} {common.checkbox()} #value#",
    ...
});
tree.checkItem('node1'); //'node1' is the item id

Details

The method checks/unchecks the checkbox by turn.

See also

  • api
    • uncheckItem
  • samples
    • 3-state Checkboxes
  • articles
    • Checkboxes in the tree


copy

makes a copy of item

id copy(id sid,number tindex, [WebixView tobj,object details] );

Parameters

sid | id | id of source item
tindex | number | index at which copy will be created
tobj | WebixView | target view
details | object | extra parameters for moving

Returns

id id of created copy
Details

Details object can contain the next properties:

details = {};
details.newId = "123"; //new id for moved item
details.parent = "a2"; //id of new parent element

If parent is defined - tindex will be the child index inside the target branch.

If parent is not defined - the value will be set to 0 (will be added to tree root).

In case newId is not defined, the new ID will be the same as the ID of the source item (sid), which is not desirable during copying within one and the same component.


count

returns the number of currently visible items (counts both parent and child nodes)

number count();

Returns

number the number of visible (opened) items

Example

tree = new webix.ui({
    view:"tree",
    ...
});

tree.count();

See also

  • samples
    • Empty list
  • articles
    • Data Object Operations


getChecked

returns ids of the checked items

array getChecked();

Returns

array an array of ids

Example

tree = new webix.ui({
        view:"tree",
        ...
})
tree.getChecked();

See also

  • api
    • isChecked
  • articles
    • Checkboxes in the tree


isChecked

checks whether the specified node is checked

boolean isChecked(id id );

Parameters

id id ID of the node in question

Returns

boolean *true* if the node is checked; *false* if not

Example

tree.isChecked('part1');

See also

  • api
    • getChecked
  • articles
    • Checkboxes in the tree


isSelected

checks whether the specified item is selected or not

boolean isSelected(id id);

Parameters

id id the id of the item in question

Returns

boolean true if the specified item is selected, otherwise - false

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').select(2);     //selects an item with the id=2
$$('data').isSelected(2); //-> 'true'

See also

  • api
    • getSelectedId
    • select
    • selectAll
    • unselect
    • unselectAll
  • articles
    • Items Selection


move

moves the specified item to the new position

string move(string sid,number tindex, [object tobj,object details] );

Parameters

sid | string | the id of the item to move
tindex | number | the new position of the item (new index)
tobj | object | the object that the item is moved to
details | object | extra parameters for moving

Returns

string the item id

Example

//moving in the same list
$$('list').move("a12", 0);
$$('list').move("a13", -1);
//moves an item to a different list
var id = $$('list').move("a13", 0, $$("list2"));

Details

Details object can contain the following properties:

details = {};
details.newId = "123"; //new id for moved item
details.parent = "a2"; //id of new parent element

If parent is defined - index will be child index inside the target branch.

See also

  • api
    • moveBottom
    • moveDown
    • moveUp
    • moveTop
  • articles
    • Data Object Operations


moveSelection

moves selection in the specified direction

void moveSelection(string direction);

Parameters

direction string the move direction

Example

$$("list").moveSelection("top");

Details

The method can take only one of a predefined set of values.
The predefined values are:

  • 'top' - the selection is moved to the first item of the tree
  • 'bottom' - the selection is moved to the last item of the tree
  • 'up' - the selection is moved one item up
  • 'down' - the selection is moved one item down
  • 'pgup' - the selection is moved to the first item of the previous page (a page is the currently visible tree)
  • 'pgdown' - the selection is moved to the first item of the next page (a page is the currently visible tree)

See also

  • api
    • getSelectedId
    • select
    • unselect
  • articles
    • Items Selection


parse

loads data to the component from an inline data source

void parse(string| object data,string type);

Parameters

data | string| object | the data to add
type | string | the data type: 'json' (default), 'xml', 'csv', 'jsarray'
Details

If you want to parse data in addition to the existing dataset, specify position of parsing, namely the index from which you insert new data:

$$("datatable").parse({
   pos: $$("datatable").count(), //number of records will be right the last index +1
   data:dataset
});

See also

  • api
    • load
    • data
    • url
    • datatype
  • samples
    • Dataview: JSON Dataset
    • Dataview: XML Dataset
  • articles
    • Loading Data into Tree


remove

removes the specified item/items from datastore

void remove(string/number/array id);

Parameters

id string/number/array the item id or an array of items' ids

Example

tree.remove(tree.getSelectedId()); // removes selected
    tree.remove(1); //removes the item with id="1"

See also

  • api
    • add
    • clearAll
  • samples
    • Adding/Removing Items
  • articles
    • Adding/Deleting Data Items


uncheckAll

uncheck all items in the tree

void uncheckAll( [id id] );

Parameters

id id top level id

Example

tree.uncheckAll();

Details

If top level id not provided - uncheck all items, else - only items in the target branch


uncheckItem

unchecks the checkbox in the tree item

void uncheckItem(string id);

Parameters

id string the id of an item to uncheck

Example

tree = new webix.ui({
    view:"tree",
    template:"{common.icon()} {common.folder()} {common.checkbox()} #value#",
    ...
});
tree.uncheckItem('node1'); //'node1' is the item id

See also

  • api
    • checkItem
  • articles
    • Checkboxes in the tree


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
filterMode | defines the pattern for tree item filtering
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
threeState | defines three-state checkboxes for the tree. Flase by default.
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component


data

JavaScript array containing data for the component

string|array data;

Example

var data = [
    { id:"1", open:true, value:"The Shawshank Redemption", data:[
        { id:"1.1", value:"Part 1" },
        { id:"1.2", value:"Part 2" },
        { id:"1.3", value:"Part 3" }
    ]},
    { id:"2", value:"The Godfather", open:true, data:[
        { id:"2.1", value:"Part 1" },
        { id:"2.2", value:"Part 2" }
    ]}
];

webix.ui({
    view:"tree", data:data
});

See also

  • api
    • datatype
  • samples
    • Tree: JSON Dataset
  • articles
    • Data Loading
    • Node templates
    • Details

    After the data is parsed, each data item will be supplied with the following properties to form the hierarchy:

    • $level - (number) the level of nesting (one-based numbering);
    • parent - (string) the id of thr item's parent;
    • $count - (number) the number of childs


drag

enables or disables drag-and-drop

boolean drag;

Values

  • true
    enables DnD within the component, allows taking items into its other instances and different components on the page;
  • order
    enables DnD in the reorder mode, allows dragging component item within one component thus changing their order;
  • source
    enables dragging items from the component without an ability to drop data from other components;
  • target
    enables dropping data to the component. It can take data from outside, but you cannot drag anything from it;
  • false
    disables DnD within the component.

    • Example

    tree = new webix.ui({
        view:"tree",
        ...
        drag:true
});

    See also

  • samples
    • Drag-and-Drop between tables in DataTable
    • Enabling Drag-and-drop in Tree
    • DnD with List Items
  • articles
    • Drag-and-drop support


multiselect

enables multiselect mode

boolean| string multiselect;

Example

{
  view:"list",
  select:true,
  multiselect:true
}

See also

  • samples
    • Multiline Selection
    • Details

    In the multiselect mode api allows marking multiple elements as selected at the same time.

    If a component supports direct selection, it may be possible to use Ctrl-click and Shift-click to select multiple elements at once.

    Possible values are:

    • state - (true/false) enables/disables multiselection
    • "level" - (string) allows selection only on the same level
    • "touch" - (string) sets the "touch" mode of multiselection (the first click on an element selects it, the second one removes selection)


select

enables selection in the tree

boolean select;

Values

  • true
    allows single selection
  • false
    denies selection
  • "multiselect"
    allows multiselection

    • Example

    tree = new webix.ui({
    view:"tree",
    ...
    select:true
});

    See also

  • api
    • multiselect
  • samples
    • Selection
  • articles
    • Items Selection
    • Details

    By default, selection in Tree is disabled.


template

the component template

string|function template;

Example

{view:"list", template:"#id#.#title#"}

See also

  • samples
    • 3-state Checkboxes
  • articles
    • Node templates
    • Details

    1 . Above is the common text template for template component:

    2 . Data template for data-containing components:

    { view:"list", template:"#id#.#title#" }
 // the list will show ID and title of each data item from the specified datasource

    3 . Function template (takes data object and function parameter):

    { view:"list", template:function(obj){
    return "<div class='overall'><div class='rank'>"
        +obj.rank+"</div>"+
        "<div class='title'>"+obj.title+"</div></div>"
}}
//the list will show rank and title of each item styled with specified CSS

    4 . HTML templates defined within an HTML container:

    { view: "dataview", template:"html->template_container" }

    5 . HTML template defined in the external file:

    { view:"dataview", template:"http->template.html" }

    6 . Template component can load the external template by Ajax:

    { view:"template", src:"loadtext.php" }


threeState

defines three-state checkboxes for the tree. Flase by default.

boolean threeState;

Example

webix.ui({
    view:"tree",
    template:"{common.icon()} {common.checkbox()} {common.folder()} #value#",
    threeState: true,
    ...
});

See also

  • samples
    • 3-state Checkboxes
  • articles
    • Checkboxes in the tree
    • Details

    Three state checkboxes define the peculiar behaviour of a checkbox tree, namely:

    • When the user checks/unchecks a parent node - this parent node and all its child nodes (of each nesting level) are checked/unchecked;
    • When the user checks/unchecks a child node - this only node is checked/unchecked.


type

object that specifies items presentation

object| string type;

Example

list = webix.ui({
    view:"tree",
    ...
    type:{
        template:"{common.icon()} {common.folder()}<span>#value#</span>",
    }
})

See also

  • samples
    • Search Field
  • articles
    • Data Templates
    • Type Implementation
    • Details

    Attributes of the type as object:

    • css - (string) the name of a css class that will be applied to component's items (the default name of the applied class is 'default').
    • template - (function, string) an html template that will define item presentation in the component.

    Built-in named types:

    • lineTree - adds vertical lines to the tree presentation.
    webix.ui({
    view:"tree",
    type:"lineTree"
});

    Related sample: Lines

    Built-in type methods

    The following methods are used in the tree template:

    • space
    • icon
    • checkbox
    • folder
    webix.ui({
   view:"tree",
   template:"{common.icon()} {common.checkbox()} {common.folder()}"+
        "<span>#value#</span>",
});

    Related sample: 2-state Checkboxes

    More information on this topic can be found in the dedicated documentation article.


Events

onAfterAdd | fires after adding item to datastore
onAfterClose | fires after the branch has been closed
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemCheck | fires when you check an item in tree and treetable
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPartialRender | called when part of tree is repainted
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


onDataRequest

fires when dynamically-loaded data is requested

void onDataRequest(string/number id, [function callback,string url] ){ ... };

Parameters

id | string/number | id of the parent node whose the children should be loaded
callback | function | callback function, if any
url | string | server API endpoint, if any

Example

tree.attachEvent("onDataRequest", function (id, callback, url) {
    // code
});

Details

Dynamic loading for tree-like structures is triggered for nodes with the webix_kids flag set. When those nodes are expanded, the loadBranch method is automatically called. The component will use the data source specified either by its url property or in the url parameter passed to the load method.

When looking at the related samples, note that during the initial loading, data is returned with the webix_kids property set:

{ id: 1, value: "Branch 1", webix_kids: true }

This event can be used to change the default data loading logic:

tree.attachEvent("onDataRequest", function (id, callback, url) {
  this.parse(
    webix.ajax().get("data/data_dyn_json.php?parent=" + id).then(function (data) {
      return data.json();
    })
  );
  // cancels default behaviour
  return false;
});

See also

  • api
    • loadBranch
  • samples
    • Dynamic Loading
    • Modifying onDataRequest event
  • articles
    • Server-side Integration
    • Dynamic Loading for Hierarchical Data Structures


onItemCheck

fires when you check an item in tree and treetable

void onItemCheck(id id ){ ... };

Parameters

id id ID of the checked item

Example

some.attachEvent("onItemCheck", function(){
    //... some code here ...
});

See also

  • api
    • uncheckItem
    • checkItem
  • samples
    • Hiding Menu Items
  • articles
    • Checkboxes in the tree


onPartialRender

called when part of tree is repainted

void onPartialRender(id id,object data,string type){ ... };

Parameters

id | id | id of item which initiated repainting
data | object | extra data realted to repainting
type | string | type of repainting operaton

Example

some.attachEvent("onPartialRender", function(id, data, type){
    //... some code here ...
});

Details

most common case - opening | closing of branches


Available only in PRO Edition

ui.treemap

A control used for visualization of complex hierarchical data in a compact way.

The component is used for space-saving presentation of big tree-like data. Relations between tree elements are reflected using the correlation of rectangles' sizes or graduation of their colors. One-level rendering of tree data is also possible with Treemap. Check treemap documentation for more detailed description.

Constructor

var treemap = webix.ui({
    view:"treemap",
    select: true,
    template: function(item){
        return item.label||"";
    },
    value: "#value#",
    data: [
        { id:"1", label: "Technology", data:[
            { id:"1.1", value:"50" },
            { id:"1.2", value:"30" },
            { id:"1.3", value:"20" }
        ]},
        { id:"2", label: "Healthcare", data:[
            { id:"2.1", value:"80" },
            { id:"2.2", value:"10" },
            { id:"2.3", value:"60" }
        ]}
    ]
});

Where to start

  • Overview of the Treemap Widget
  • Samples
Based on: AutoTooltip, Group, TreeAPI, SelectionModel, KeysNavigation, MouseEvents, Scrollable, TreeDataLoader, TreeStore, DataStore, ui.proto, PagingAbility, DataMarks, ValidateCollection, RenderStack, DataLoader, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, TreeRenderStack, CopyPaste
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | closes the branch with the specified id
closeAll | closes all branches in the tree
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBranchIndex | gets index of the node in a specific branch
getChildViews | returns child views of the calling component
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getState | returns the current state of the view
getTopParentView | returns top parent view
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
moveSelection | moves selection in the specified direction
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
setState | restores the specified state
show | makes the component visible
showBranch | shows the leaves of the branch by its id
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterClose | fires after the branch has been closed
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemCheck | called when the checkbox inside the tree item was checked
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPartialRender | called when part of tree is repainted
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
activeItem | specifies if childs of the branches will be rendered in the TreeMap
animate | defines or disables view change animation.
borderless | used to hide the component borders
branch | specifies the Treemap branch that should be displayed
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
filterMode | defines the pattern for tree item filtering
gravity | sets the view gravity (1 by default)
header | defines whether the header of Treemap will be shown or hidden
headerHeight | sets the height of the Treemap header
headerTemplate | sets the template for the header label
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subRender | defines if the sub-elements should be rendered for the first-level branches
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
threeState | enable three-state checkboxes
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
value | a template that specifies the area of an item rectangle
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | closes the branch with the specified id
closeAll | closes all branches in the tree
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBranchIndex | gets index of the node in a specific branch
getChildViews | returns child views of the calling component
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getState | returns the current state of the view
getTopParentView | returns top parent view
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
moveSelection | moves selection in the specified direction
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
setState | restores the specified state
show | makes the component visible
showBranch | shows the leaves of the branch by its id
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
ungroup | ungroups data
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


showBranch

shows the leaves of the branch by its id

void showBranch(string/number branchId);

Parameters

branchId string/number the id of the branch

Example

treemap.showBranch("2");


Properties

activeItem | specifies if childs of the branches will be rendered in the TreeMap
animate | defines or disables view change animation.
borderless | used to hide the component borders
branch | specifies the Treemap branch that should be displayed
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
filterMode | defines the pattern for tree item filtering
gravity | sets the view gravity (1 by default)
header | defines whether the header of Treemap will be shown or hidden
headerHeight | sets the height of the Treemap header
headerTemplate | sets the template for the header label
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
subRender | defines if the sub-elements should be rendered for the first-level branches
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
threeState | enable three-state checkboxes
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
value | a template that specifies the area of an item rectangle
width | sets the width of the component


activeItem

specifies if childs of the branches will be rendered in the TreeMap

boolean activeItem;

Example

webix.ui({
    view:"treemap",
    activeItem: true,
    url: "data/data.json"
});

Default value:

false


branch

specifies the Treemap branch that should be displayed

string branch;

Example

webix.ui({
    view:"treemap",
    branch:"2.1"
});


header

defines whether the header of Treemap will be shown or hidden

boolean header;

Example

webix.ui({
    view:"treemap",
    header:true
});


headerHeight

sets the height of the Treemap header

number headerHeight;

Example

webix.ui({
    view:"treemap",
    headerHeight:35
});


headerTemplate

sets the template for the header label

string headerTemplate;

Example

webix.ui({
    view:"treemap",
    headerTemplate:"#category#"
});


subRender

defines if the sub-elements should be rendered for the first-level branches

boolean subRender;

Example

webix.ui({
    view:"treemap",
    subRender: false,
    url: "data/data.json"
});

Default value:

true


value

a template that specifies the area of an item rectangle

string/function value;

Example

webix.ui({
    view:"treemap",
    value: "#value#",
    data:[...]
});


Events

onAfterAdd | fires after adding item to datastore
onAfterClose | fires after the branch has been closed
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemCheck | called when the checkbox inside the tree item was checked
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPartialRender | called when part of tree is repainted
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


ui.treetable

A control for presenting tree in a grid cell.

The component is used to integrate a tree into an editable grid. There is a support for in-line node editing, drag-and-drop, filtering, checkboxes etc. Check treetable documentation for more detailed description.

Constructor

var treetable = webix.ui({
    view:"treetable",
    columns:[
      { id:"id", header:"", width:50},
      { id:"value", header:"Film title", width:250,
       template:"{common.treetable()} #value#" },
      { id:"chapter", header:"Mode", width:200}
    ],
    data: [
      { "id":"1", "value":"The Shawshank Redemption", "open":true, "data":[
        { "id":"1.1", "value":"Part 1", "chapter":"alpha"},
        { "id":"1.2", "value":"Part 2", "chapter":"beta", "open":true, "data":[
          { "id":"1.2.1", "value":"Part 1", "chapter":"beta-twin"}
        ]}
      ]}
    ]
});

Where to start

  • Overview of the Treetable Widget
  • Samples
Based on: TreeAPI, TreeStateCheckbox, TreeDataLoader, TreeStore, DataStore, ui.datatable, AutoTooltip, Group, DataMarks, DataLoader, AtomDataLoader, MouseEvents, MapCollection, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, PagingAbility, TablePaste, DataState, EditAbility, KeysNavigation, DataMove, DragItem, ValidateCollection
Methods
add | adds an item to the store
addCellCss | adds a css class to the cell
addCss | applied CSS class to a component item
addRowCss | adds a css class to the row
adjust | adjusts the component to the size of the parent HTML container
adjustColumn | adjusts a column to the width of the content
adjustRowHeight | autodetect height of rows in datatable
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
checkAll | check all items in tree
checkItem | checks the checkbox it the tree item
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | closes the branch with the specified id
closeAll | closes all branches in the tree
collectValues | returns an array of unique values of the specified column
columnId | returns the id of the column at the specified index
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
eachColumn | iterates over all visible columns in the table
eachRow | iterates over all rows in the table
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editCell | enables the edit mode for the specified cell
editColumn | enables the edit mode for the specified column
editNext | closes the current editor and opens one in the next cell of the row
editRow | enables the edit mode for the specified row
editStop | stops the edit mode and closes all opened editors. The component is still editable
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
filterByAll | refilters DataTable by all specified filters
find | returns rows that match the criterion
focusEditor | moves focus to the active editor
getBranchIndex | gets index of the node in a specific branch
getChecked | returns ids of the checked items
getChildViews | returns child views of the calling component
getColumnConfig | returns the configuration object of the specified column
getColumnIndex | returns the index of the column with the specified id
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
getFilter | returns the filter object that the component uses to filter the values of the specified column
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHeaderContent | returns set of helpers for header content manipulation
getHeaderNode | returns HTML element of the column's header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the current position of scrolls
getSelectedId | returns the selected elements' ids
getSelectedItem | gets an object of the selected data item
getState | returns the current state of the view
getText | returns text value of a cell
getTopParentView | returns top parent view
getVisibleCount | returns count of visible rows
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideColumn | hides the specified column
hideOverlay | hides previously defined overlay
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isChecked | checks whether the specified node is checked
isColumnVisible | returns true if column is visible
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | converts an HTML node or event object to in-table position
mapCells | applies the callback to a range of cells
mapEvent | routes events from one object to another
markSorting | marks the sorted column with a dedicated sign (asc/desc) in the header
move | moves the specified item to a new position
moveBottom | moves the specified item to the last position
moveColumn | moves column to different position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshColumns | refreshes the structure of DataTable
refreshFilter | rebuilds list of options in select filter
refreshHeaderContent | refreshes the header row of DataTable
registerFilter | registers a filter element
remove | removes the specified item/items from datastore
removeCellCss | remove css class from the cell of datatable
removeCss | removes CSS class from a component item
removeRowCss | remove css class from the row
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the view to the defined position
serialize | serializes data to a JSON object
setColumnWidth | sets the width of the specified column
setPage | makes the specified page visible (assuming that the pager was defined )
setRowHeight | sets the height of the specified row
setState | restores the specified state
show | makes the component visible
showCell | scrolls the table (if needed) to make the specified cell visible
showColumn | shows the column which was previously hidden by method 'hidecolumn'
showColumnBatch | shows or hides a group of columns
showItem | 'scrolls' the table to make the specified row visible
showItemByIndex | 'scrolls' the table to make the specified row visible
showOverlay | shows the overlay message over the body of DataTable
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
uncheckAll | uncheck all items in the tree
uncheckItem | unchecks the checkbox in the tree item
ungroup | ungroups data
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
validateEditor | validates data in currently active editor
Events
onAfterAdd | fires after adding item to datastore
onAfterAreaAdd | fires after a select area was added
onAfterAreaRemove | fires after a select area was removed
onAfterBlockSelect | event occurs after block selection
onAfterClose | fires after the branch has been closed
onAfterColumnDrop | fires after the column has been dragged and dropped to the target position
onAfterColumnDropOrder | fires after the column order was changed with the help of drag-and-drop
onAfterColumnHide |
onAfterColumnShow |
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onAfterFilter | occurs after datatable was filtered
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs each time after the view is rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after a cell is selected
onAfterSort | fires after sorting dataset
onAfterUnSelect | fires after a cell is unselected
onAreaDrag | fires when area selection is started
onBeforeAdd | fires before adding item to datastore
onBeforeAreaAdd | fires before a select area is added
onBeforeAreaRemove | fires before a select area is removed
onBeforeBlockSelect | event occurs before block selection
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeColumnDrag | fires the monent you start dragging the column from its source potition
onBeforeColumnDrop | fires the moment you drop the column to its target position
onBeforeColumnDropOrder | fires the moment you drop the column over the target area
onBeforeColumnHide |
onBeforeColumnShow |
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onBeforeFilter | called when filtering process is started, but data is not filtered yet
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs each time before the view is rendered
onBeforeSelect | fires before a cell is selected
onBeforeSort | fires before sorting dataset
onBeforeUnSelect | fired before a cell is unselected
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onCheck | fires when a checkbox is checked or unchecked in the datatable item
onCollectValues | fires after datatable has collected options
onColumnResize | fires when width of column was changed
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHeaderClick | occurs after clicking on header
onItemCheck | fires when you check an item in tree and treetable
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLiveEdit | occurs when data was changed in the editor
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onResize | fires when the width or height of DataTable was changed
onRowResize | fires when height of row was changed
onScrollX | fires when the user scrolls the table left or right
onScrollY | fires when the user scrolls the table up or down
onSelectChange | fires when selection is changed in a DataTable
onStructureLoad | fires when the structure of DataTable (columns configuration) is initialized
onStructureUpdate | fires when structure of datatable was changed ( column added, hidden or reconfigured )
onSubViewClose | fires after a subview or a subrow is closed
onSubViewCreate | fires after a subview was created
onSubViewOpen | fires after a subview or a subrow is opened
onSubViewRender | fires each time subview is rendered
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
areaselect | enables/disables area selection
autoConfig | datatable adjust configuration to the data
autoheight | adjusts Datatable size to the its content vertically
autowidth | adjusts Datatable size to its content horizontally
blockselect | enables/disables block selection
borderless | used to hide the component borders
checkboxRefresh | controls behavior of checkbox editors in grid
clipboard | enables/disables clipboard support
columnWidth | defines the default width for columns (in pixels)
columns | configures columns of the table
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datafetch | defines the number of records that will be loaded into datatable during the next dynamic loading call
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
delimiter | sets CSV delimiters for clipboard operations
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragColumn | enables drag-and-drop support for columns
dragscroll | enables autoscroll of component during drag-n-drop
editMath | enables formular editing
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
externalData | allows defining custom 'move' logic for the component.
filterMode | defines filtering rules in tree-like components
fixedRowHeight | defines whether the height should be fixed for all rows or can vary
footer | enables/disables the footer in DataTable (disabled, by default)
form | linked form
gravity | sets the view gravity (1 by default)
header | enables/disables the header in DataTable (enabled, by default)
headerRowHeight | sets the heigth of the header row
headermenu | adds a headermenu to control column visibility
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hover | css class for a row-hover in the datatable
id | the component ID
leftSplit | the number of the fixed columns from the left side of the table (actual for the split mode )
liveValidation | validation during cell editing
loadahead | sets the number of items that will be loaded on each scroll movement relative to the last item in the scrolling direction
map | defines data mapping
math | enables math formulas in DataTable
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minColumnHeight | sets the minimum height for a row
minColumnWidth | sets the minimum width for a column
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables the multi selection mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
prerender | invokes the full rendering of DataTable data
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
resizeColumn | enables/disables horizontal resizing of columns
resizeRow | enables/disables vertical resizing of rows
rightSplit | sets the number of the fixed columns from the right side of the table (actual for the split mode )
rowHeight | sets the default height for rows
rowLineHeight | default line height for grid's row
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables or disables scroll for the datatable
scrollAlignY | enables/disables scrolling the table just by whole rows (i.e. you won't be allowed to scroll along the full length of rows)
scrollX | enables/disables horizontal scrolling
scrollY | enables/disables vertical scrolling
select | sets the selection mode in DataTable
spans | array of span configurations for the datatable
subRowHeight | automatically adjusts the subrow's height to the size of the text
subrow | sets a subrow template
subview | adds a subview configuration into datatable
threeState | defines three-state checkboxes for the tree. Flase by default.
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | used for configuring presentation of items
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
yCount | defines height of datatable in rows
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
headerContent | a hash property containing a collection of active elements which can be placed in the header
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
waitData | eventual result of an asynchronous operation ('promise' object) for the loaded data


Methods

add | adds an item to the store
addCellCss | adds a css class to the cell
addCss | applied CSS class to a component item
addRowCss | adds a css class to the row
adjust | adjusts the component to the size of the parent HTML container
adjustColumn | adjusts a column to the width of the content
adjustRowHeight | autodetect height of rows in datatable
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
checkAll | check all items in tree
checkItem | checks the checkbox it the tree item
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
close | closes the branch with the specified id
closeAll | closes all branches in the tree
collectValues | returns an array of unique values of the specified column
columnId | returns the id of the column at the specified index
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
eachColumn | iterates over all visible columns in the table
eachRow | iterates over all rows in the table
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editCell | enables the edit mode for the specified cell
editColumn | enables the edit mode for the specified column
editNext | closes the current editor and opens one in the next cell of the row
editRow | enables the edit mode for the specified row
editStop | stops the edit mode and closes all opened editors. The component is still editable
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
filterByAll | refilters DataTable by all specified filters
find | returns rows that match the criterion
focusEditor | moves focus to the active editor
getBranchIndex | gets index of the node in a specific branch
getChecked | returns ids of the checked items
getChildViews | returns child views of the calling component
getColumnConfig | returns the configuration object of the specified column
getColumnIndex | returns the index of the column with the specified id
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
getFilter | returns the filter object that the component uses to filter the values of the specified column
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getHeaderContent | returns set of helpers for header content manipulation
getHeaderNode | returns HTML element of the column's header
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getNode | returns the main HTML container for the calling object
getOpenItems | returns ids of the opened branches
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentId | get the ID of the parent node of the specified item
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getScrollState | returns the current position of scrolls
getSelectedId | returns the selected elements' ids
getSelectedItem | gets an object of the selected data item
getState | returns the current state of the view
getText | returns text value of a cell
getTopParentView | returns top parent view
getVisibleCount | returns count of visible rows
group | groups data by the specified data property
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
hideColumn | hides the specified column
hideOverlay | hides previously defined overlay
isBranch | checks whether the node has any children
isBranchOpen | checks whether the specified branch is open or closed
isChecked | checks whether the specified node is checked
isColumnVisible | returns true if column is visible
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | converts an HTML node or event object to in-table position
mapCells | applies the callback to a range of cells
mapEvent | routes events from one object to another
markSorting | marks the sorted column with a dedicated sign (asc/desc) in the header
move | moves the specified item to a new position
moveBottom | moves the specified item to the last position
moveColumn | moves column to different position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
open | opens the branch with the specified id
openAll | opens all branches in the tree
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshColumns | refreshes the structure of DataTable
refreshFilter | rebuilds list of options in select filter
refreshHeaderContent | refreshes the header row of DataTable
registerFilter | registers a filter element
remove | removes the specified item/items from datastore
removeCellCss | remove css class from the cell of datatable
removeCss | removes CSS class from a component item
removeRowCss | remove css class from the row
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the view to the defined position
serialize | serializes data to a JSON object
setColumnWidth | sets the width of the specified column
setPage | makes the specified page visible (assuming that the pager was defined )
setRowHeight | sets the height of the specified row
setState | restores the specified state
show | makes the component visible
showCell | scrolls the table (if needed) to make the specified cell visible
showColumn | shows the column which was previously hidden by method 'hidecolumn'
showColumnBatch | shows or hides a group of columns
showItem | 'scrolls' the table to make the specified row visible
showItemByIndex | 'scrolls' the table to make the specified row visible
showOverlay | shows the overlay message over the body of DataTable
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
uncheckAll | uncheck all items in the tree
uncheckItem | unchecks the checkbox in the tree item
ungroup | ungroups data
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
validateEditor | validates data in currently active editor


editStop

stops the edit mode and closes all opened editors. The component is still editable

void editStop();

Example

$$('mygrid').editStop();

Details

The method saves changes before closing the editor(s)

See also

  • articles
    • DataTable Editing
    • Editing Data Items


getState

returns the current state of the view

object getState();

Returns

object the state object

Example

grid.getState();

See also

  • api
    • setState
  • samples
    • Tree State Object
  • articles
    • Saving and Restoring Component State


move

move item to new position

id move(id sid,number tindex, [WebixView tobj,object details] );

Parameters

sid | id | id of source item
tindex | number | new item index
tobj | WebixView | target view
details | object | extra parameters for moving

Returns

id id of moved item ( new id, if it was changed )
Details

Details object can contain the next properties

details = {};
details.newId = "123"; //new id for moved item
details.parent = "a2"; //id of new parent element

If parent is defined - tindex will be the child index inside the target branch.

If parent is not defined - the value will be set to 0 (will be added to tree root).

In case newId is not defined, the new ID will be the same as the ID of the source item (sid), which is not desirable during moving within one and the same component.


setState

restores the specified state

void setState(object state);

Parameters

state object the state object

Example

webix.storage.local.put("state", grid.getState());
...

var state = webix.storage.local.get("state");
if (state)
    grid.setState(state);

See also

  • api
    • getState
  • samples
    • Tree State Object
  • articles
    • Tree Nodes manipulations.md


Properties

animate | defines or disables view change animation.
areaselect | enables/disables area selection
autoConfig | datatable adjust configuration to the data
autoheight | adjusts Datatable size to the its content vertically
autowidth | adjusts Datatable size to its content horizontally
blockselect | enables/disables block selection
borderless | used to hide the component borders
checkboxRefresh | controls behavior of checkbox editors in grid
clipboard | enables/disables clipboard support
columnWidth | defines the default width for columns (in pixels)
columns | configures columns of the table
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datafetch | defines the number of records that will be loaded into datatable during the next dynamic loading call
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
delimiter | sets CSV delimiters for clipboard operations
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragColumn | enables drag-and-drop support for columns
dragscroll | enables autoscroll of component during drag-n-drop
editMath | enables formular editing
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
externalData | allows defining custom 'move' logic for the component.
filterMode | defines filtering rules in tree-like components
fixedRowHeight | defines whether the height should be fixed for all rows or can vary
footer | enables/disables the footer in DataTable (disabled, by default)
form | linked form
gravity | sets the view gravity (1 by default)
header | enables/disables the header in DataTable (enabled, by default)
headerRowHeight | sets the heigth of the header row
headermenu | adds a headermenu to control column visibility
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hover | css class for a row-hover in the datatable
id | the component ID
leftSplit | the number of the fixed columns from the left side of the table (actual for the split mode )
liveValidation | validation during cell editing
loadahead | sets the number of items that will be loaded on each scroll movement relative to the last item in the scrolling direction
map | defines data mapping
math | enables math formulas in DataTable
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minColumnHeight | sets the minimum height for a row
minColumnWidth | sets the minimum width for a column
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables the multi selection mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
prerender | invokes the full rendering of DataTable data
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
resizeColumn | enables/disables horizontal resizing of columns
resizeRow | enables/disables vertical resizing of rows
rightSplit | sets the number of the fixed columns from the right side of the table (actual for the split mode )
rowHeight | sets the default height for rows
rowLineHeight | default line height for grid's row
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables or disables scroll for the datatable
scrollAlignY | enables/disables scrolling the table just by whole rows (i.e. you won't be allowed to scroll along the full length of rows)
scrollX | enables/disables horizontal scrolling
scrollY | enables/disables vertical scrolling
select | sets the selection mode in DataTable
spans | array of span configurations for the datatable
subRowHeight | automatically adjusts the subrow's height to the size of the text
subrow | sets a subrow template
subview | adds a subview configuration into datatable
threeState | defines three-state checkboxes for the tree. Flase by default.
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | used for configuring presentation of items
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
yCount | defines height of datatable in rows


clipboard

enables/disables clipboard support

boolean|string clipboard;

Example

webix.ui({
    view:"datatable",
    clipboard:true,
    ...
});

See also

  • samples
    • Copying between grids
  • articles
    • Copy-Pasting DataTable Data


data

JavaScript array containing data for the component

string|array data;

Example

var data: [
    { "id":"1",
      "value":"The Shawshank Redemption",
      "open":true,
      "data":[
        { "id":"1.1", "value":"Part 1", "chapter":"alpha"},
        { "id":"1.2", "value":"Part 2", "chapter":"beta", "open":true,
           "data":[
            { "id":"1.2.1", "value":"Part 1", "chapter":"beta-twin"},
            { "id":"1.2.2", "value":"Part 1", "chapter":"beta-twin"}
            ]
        }
     }
];

webix.ui({
    view:"treetable",
    data:data,
    columns:[
        { id:"id", header:""},
        { id:"value", header:"Film title",
                        template:"{common.treetable()} #value#" },
        { id:"chapter", header:"Mode",  width:200}
    ]
});

See also

  • api
    • datatype
  • samples
    • Basic initialization
  • articles
    • Data Loading
    • Node templates
    • Details

    After the data is parsed, each data item will be supplied with the following properties to form the hierarchy:

    • $level - (number) the level of nesting (one-based numbering);
    • parent - (string) the id of thr item's parent;
    • $count - (number) the number of childs


navigation

activates the selection keyboard navigation

boolean navigation;

Example

webix.ui({
    view:"datatable",
    navigation:true,
    ...
});

See also

  • api
    • select
  • samples
    • Navigation in a wide table
    • Navigation in a long table
  • articles
    • Keyboard navigation
    • Details
    Table 1 Keyboard commands
Command | Description
Up arrow key | moves one cell (row) to the up
Down arrow key | moves one cell (row) to the down
Left arrow key | moves one cell (column) to the left
Right arrow key | moves one cell (column) to the right
Home | moves to the top left cell(row, column) in the grid
End | moves to the bottom right cell(row, column) in the grid
PGUP | scrolls the table up
PGDN | scrolls the table down


scroll

enables or disables scroll for the datatable

boolean scroll;

Values

  • y (true)
    enables vertical scroll (the default value)
  • x
    enables horizontal scroll
  • xy
    enables both scrolls
  • false
    disables both scrolls

    • Example

    webix.ui({
    view:"datatable",
    scroll:false
});

    See also

  • api
    • scrollX
    • scrollY
    • scrollAlignY
  • articles
    • Scroll Control
    • Sizing and Resizing
    • Details

    Enabled by default


Events

onAfterAdd | fires after adding item to datastore
onAfterAreaAdd | fires after a select area was added
onAfterAreaRemove | fires after a select area was removed
onAfterBlockSelect | event occurs after block selection
onAfterClose | fires after the branch has been closed
onAfterColumnDrop | fires after the column has been dragged and dropped to the target position
onAfterColumnDropOrder | fires after the column order was changed with the help of drag-and-drop
onAfterColumnHide |
onAfterColumnShow |
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onAfterFilter | occurs after datatable was filtered
onAfterLoad | fires after data loading is complete
onAfterOpen | fires after the branch has been opened
onAfterRender | occurs each time after the view is rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after a cell is selected
onAfterSort | fires after sorting dataset
onAfterUnSelect | fires after a cell is unselected
onAreaDrag | fires when area selection is started
onBeforeAdd | fires before adding item to datastore
onBeforeAreaAdd | fires before a select area is added
onBeforeAreaRemove | fires before a select area is removed
onBeforeBlockSelect | event occurs before block selection
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeColumnDrag | fires the monent you start dragging the column from its source potition
onBeforeColumnDrop | fires the moment you drop the column to its target position
onBeforeColumnDropOrder | fires the moment you drop the column over the target area
onBeforeColumnHide |
onBeforeColumnShow |
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onBeforeFilter | called when filtering process is started, but data is not filtered yet
onBeforeLoad | occurs immediately before data loading has been started
onBeforeOpen | fires the moment you attempt to open the tree branch
onBeforeRender | occurs each time before the view is rendered
onBeforeSelect | fires before a cell is selected
onBeforeSort | fires before sorting dataset
onBeforeUnSelect | fired before a cell is unselected
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onCheck | fires when a checkbox is checked or unchecked in the datatable item
onCollectValues | fires after datatable has collected options
onColumnResize | fires when width of column was changed
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onHeaderClick | occurs after clicking on header
onItemCheck | fires when you check an item in tree and treetable
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLiveEdit | occurs when data was changed in the editor
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onResize | fires when the width or height of DataTable was changed
onRowResize | fires when height of row was changed
onScrollX | fires when the user scrolls the table left or right
onScrollY | fires when the user scrolls the table up or down
onSelectChange | fires when selection is changed in a DataTable
onStructureLoad | fires when the structure of DataTable (columns configuration) is initialized
onStructureUpdate | fires when structure of datatable was changed ( column added, hidden or reconfigured )
onSubViewClose | fires after a subview or a subrow is closed
onSubViewCreate | fires after a subview was created
onSubViewOpen | fires after a subview or a subrow is opened
onSubViewRender | fires each time subview is rendered
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


onBeforeRender

occurs each time before the view is rendered

boolean onBeforeRender(array data){ ... };

Parameters

data array the set of data which will be rendered

Returns

boolean returning false will prevent view rendering

Example

grid.attachEvent("onBeforeRender", function(){
   webix.message("Rendering start");
});

See also

  • api
    • onAfterRender
    • render
  • articles
    • Changing Properties of Components


ui.unitlist

A vertical list of items united into groups according to a template.

Support for various data template formats, sorting and filtering features. Check unitlist documentation for more detailed description.

Constructor

var unitlist = webix.ui({
    view:"unitlist",
    height: 200,
    uniteBy:function(obj){
        return obj.title.substr(0,1);
    },
    type:{
        height:40,
    },
    template:"#title#",
    data: [{ id:1, title:"The Shawshank Redemption", year:1994},
    { id:2, title:"The Godfather", year:1972},
    { id:3, title:"12 Angry Men", year:1974},
    { id:4, title:"The Good, the Bad and the Ugly", year:1966},
    { id:5, title:"My Fair Lady", year:1964},
    { id:6, title:"Collector", year: 1987}]
});

Where to start

  • Overview of the Unitlist Widget
  • Samples
Based on: ui.list, KeysNavigation, DataMove, DragItem, MouseEvents, SelectionModel, Scrollable, ui.proto, PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem, CopyPaste
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
getUnitList | gets ID-s of the data records united by the specified unit value
getUnits | returns unit values
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterContextMenu | fires after the context menu was called in the item area
onAfterDelete | fires after item deleting
onAfterDrop | fires after drag-n-drop was finished
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSelect | fires after item was selected
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeContextMenu | fires before the context menu is called in the item area
onBeforeDelete | fires before item deleting
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSelect | fires before item selection is started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onDragOut | fires when a dragged element is moved outside of the droppable area
onFocus | fires when a view gets focus
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
onPaste | fires when the user presses CTRL+V keys combination
onSelectChange | fires after selection state was changed
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
sort | sets sorting rule(s) according which items will be sorted within units
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
uniteBy | sets the template according which items will be grouped in units.
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getScrollState | returns the scroll position
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
getTopParentView | returns top parent view
getUnitList | gets ID-s of the data records united by the specified unit value
getUnits | returns unit values
getVisibleCount | returns the number of items that can be seen with the current view height
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isSelected | checks whether the specified item is selected or not
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveSelection | moves selection in the specified direction
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
scrollTo | scrolls the data container to a certain position
select | selects the specified item(s)
selectAll | selects all items or the specified range
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unselect | removes selection from the specified item
unselectAll | removes selection from all items
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


getUnitList

gets ID-s of the data records united by the specified unit value

array getUnitList(string name);

Parameters

name string name of unit, for which records need to be collected

Returns

array array of data objects for the unit in question

Example

var datas = $$("mylist").getUnitList("A");


getUnits

returns unit values

array getUnits();

Returns

array JS array of unit values arranged in alphabetical order

Example

var units = $$('list').getUnits(); // ->[1, C, M, T]

Details

The method returns the unit criterion you set by the uniteBy property:

uniteBy:function(obj){
            return obj.title.substr(0,1); //first letters of item titles
        }

See also

  • api
    • uniteBy
    • getUnitList
  • samples
    • Working with UnitList Items
  • articles
    • Unitlist


Properties

animate | defines or disables view change animation.
autoheight | height of view will be adjusted to show all items
autowidth | width of view will be adjusted to show all items
borderless | used to hide the component borders
click | sets an action happening on a button click
clipboard | enables/disables clipboard support
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
externalData | allows defining custom 'move' logic for the component.
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
layout | defines x or y orientation of layout
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
mouseEventDelay | the delay between a real mouse action and invoking the related events
multiselect | enables multiselect mode
navigation | activates the selection keyboard navigation
on | allows attaching custom handlers to inner events of the component
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)
select | enables/disables item selection or multiselection in grouplist
sort | sets sorting rule(s) according which items will be sorted within units
template | the component template
templateCopy | sets the template according to which data will be copied to the clipboard
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
uniteBy | sets the template according which items will be grouped in units.
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
xCount | defines width of view in items
yCount | defines height of view in items


sort

sets sorting rule(s) according which items will be sorted within units

function sort;

Example

webix.ui({
      view:"unitlist",
      sort:{
          by:"#name#"
      }
});

Details

The parameter is an object that can contain the following attributes:

  • by - (template, function, hash of parameters) the template for sorted value
  • dir - (asc or des) the sorting direction (optional)
  • as - (function or one of the next values:'string', 'string_strict', 'integer') the type of data sorting (optional)


uniteBy

sets the template according which items will be grouped in units.

function uniteBy;

Example

webix.ui({
      view:"unitlist",
      ...
      uniteBy:function(obj){
             return obj.name.substr(0,1);
      }
});

Details

As a parameter the property function takes the item object.


ui.uploader

A control for uploading multiple files.

The component allows tracking the whole progress of individual file upload. Fully customizable. Check uploader documentation for more detailed description.

Constructor

var uploader = webix.ui({
    view:"uploader",
    id: "uploader_1",
    width:200,
    value:"Upload file",
    link:"mylist",
    upload:"//docs.webix.com/samples/21_upload/php/upload.php"
});

Where to start

  • Overview of the Uploader Widget
  • Samples
Based on: ui.button, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, AtomRender, EventSystem
Methods
addDropZone | adds uploader drop zone to any HTML element of the page
addFile | adds files to the uploader using browser fileApi
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
fileDialog | opens a file browsing dialog on a client machine
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isUploaded | checks whether all sent files have been uploaded to server
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
send | sends files from uploader body to server
setValue | sets a new value for the component
show | makes the component visible
stopUpload | cancel current upload
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterFileAdd | fires after file has been added to the uploader body
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeFileAdd | fires the moment you try to add file to uploader
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFileUpload | fires the moment file uploading ends
onFileUploadError | fires in case of serverside error during uploading
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onUploadComplete | fires when all files have been successfully uploaded to server
onViewResize | view size was changed by resizer
Properties
align | the alignment of the control within the parent container
animate | defines or disables view change animation.
apiOnly | sets the uploader to "invisible" mode. *False* by default.
autosend | enable seding files to server immediately after they have been added to uploader. *True* by default.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
formData | extra data that will be sent to server side along with the file uploading
getValue | returns the current value of the control
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputName | name of the uploader input
inputWidth | the width of the input area, or a button's text value area.
label | the text label of the control
link | sets the component to display values of the files chosen for upload;
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multiple | enables uploading of several files at a time. *True* by default.
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
value | sets the initial value for a control
width | sets the width of the component
Other
$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$onUploadComplete | completes uploading for flash uploader
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$updateProgress | method for updating progress state
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


Methods

addDropZone | adds uploader drop zone to any HTML element of the page
addFile | adds files to the uploader using browser fileApi
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
blur | removes the focus from the control
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
fileDialog | opens a file browsing dialog on a client machine
focus | sets focus to the control
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getInputNode | gets the HTML element related to the component
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getValue | returns the current value of the control
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isUploaded | checks whether all sent files have been uploaded to server
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
render | renders the specified item or the whole component
resize | adjusts the view to a new size
send | sends files from uploader body to server
setValue | sets a new value for the component
show | makes the component visible
stopUpload | cancel current upload
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


addDropZone

adds uploader drop zone to any HTML element of the page

void addDropZone(HTMLElement element);

Parameters

element HTMLElement HTML element

Example

$$("uploadAPI").addDropZone($$("mylist").$view);

Details

By default, you can drop files over the upload button.

This method allows defining any area as uploader drop zone while the uploader itself is set to apiOnly.

See also

  • api
    • apiOnly
  • samples
    • Dnd with Invisible Uploader
  • articles
    • Binding Uploader to Any Page Element


addFile

adds files to the uploader using browser fileApi

void addFile(string name,number size, [string type ] );

Parameters

name | string | file name and (optionally) its extension
size | number | file size
type | string | file extension

Example

$$("uploader_1").addFile("my_picture," 214, "jpg");

Details

If you pass file name as with tis extension, like "my_picture.jpg", uploader will automatically define its extension and store it as file type.

If you specify only file title "my_pictire", type becomes an obligatory parameter.


fileDialog

opens a file browsing dialog on a client machine

void fileDialog( [object content] );

Parameters

content object file upload context

Example

$$("uploadAPI").fileDialog();
//or
$$("uploadAPI").fileDialog({ rowid : id.row });

Details

File upload context is an optional object with any properties that you would like to see within an uploaded item data.

For instance, context can be used in an onFileUpload event:

webix.ui({
    view:"uploader",
    id:"uploadAPI",
    on:{
        onFileUpload:function(item){
            var id = item.context.rowid;
            var row = $$("people").getItem(id);

            row.photo = item.sname;
            $$("people").updateItem(id, row);
        }
    }
});

See also

  • samples
    • Invisible Uploader for Datatable
  • articles
    • Binding Uploader to Any Page Element


getInputNode

gets the HTML element related to the component

HTMLElement getInputNode();

Returns

HTMLElement the component HTML element

Example

webix.ui({
    container:"box",
    view:"form",
    elements:[
        { view:"text",   id:"f1", label:"Email"},
        { view:"text",   id:"f2", label:"Password", type:'password' },
        { view:"button", id:"b1", value:"Login",  type:"form" }
    ]
});

$$("b1").getInputNode();//-> <input type="button" style="height:27px; width:149px" value="Login">

Details

Dimension you get equal to library defauls defined for a standard button. They can be as well set in JS object:

{ view:"button", id:"b1", value:"Login",  type:"form", width: 300, height: 50 }

Uploader is a JS button in its essence.

See also

  • articles
    • View


isUploaded

checks whether all sent files have been uploaded to server

boolean isUploaded();

Returns

boolean *true* if all files are uploaded

Example

$$("uploader_1").isUploaded();

Details

The function goes through all the uploaded files and checks their state. If at least one of the files has status different from "server", the method returns false.


send

sends files from uploader body to server

void send(number| string| function id,object details);

Parameters

id | number| string| function | file ID or callback function
details | object | additional data

Example

$$("upl1").send(function(response){
    if(response)
        webix.message(response.status);
});
//response contains serverside response

Details

The method allows sending all the pre-added files at a time as well one file specified by ID::

$$("upl1").send();
$$("upl1").send(id);

Additionally, extra data can be send to server:

//any file specified by ID
$$("uploader").send(id, { param1:"value1", param2:"value2"});

$$("uploader").send(function(res){
        /*callback function*/
    },
    { param1:"value1",
      param2:"value2"
    }
);

In case of autosend enabled, the additional data can be defined in the uploader configuration:

webix.ui({
    view:"uploader",
    formData:{
        param1:value1,
        param2:value2
    },
    ...
});

See also

  • samples
    • Sending on custom action
  • articles
    • Configuring Uploader


stopUpload

cancel current upload

void stopUpload(id id);

Parameters

id id id of file, which upload need to be stopped

Example

$$(uploader"").stopUpload();


Properties

align | the alignment of the control within the parent container
animate | defines or disables view change animation.
apiOnly | sets the uploader to "invisible" mode. *False* by default.
autosend | enable seding files to server immediately after they have been added to uploader. *True* by default.
autowidth | adjusts button to its text content
borderless | used to hide the component borders
click | click action handler
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
formData | extra data that will be sent to server side along with the file uploading
getValue | returns the current value of the control
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
hotkey | sets a hotkey that triggers button clicking
id | the component ID
inputHeight | the height of the input area, or a button's text value area.
inputName | name of the uploader input
inputWidth | the width of the input area, or a button's text value area.
label | the text label of the control
link | sets the component to display values of the files chosen for upload;
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
multiple | enables uploading of several files at a time. *True* by default.
name | name of the control
on | allows attaching custom handlers to inner events of the component
popup | allows to attach pop-up menu to the button
tabFocus | defines whether the control will be included in the tab navigation order
tooltip | tooltip for the input
type | the type of the control
value | sets the initial value for a control
width | sets the width of the component


apiOnly

sets the uploader to "invisible" mode. False by default.

boolean apiOnly;

Example

webix.ui({
    view:"uploader",
    apionly:true,
    ...//uploader config
});

See also

  • samples
    • Invisible Uploader for Datatable
  • articles
    • Binding Uploader to Any Page Element
    • Details

    ApiOnly "invisible" uploader is initialized for situations when you need to integrate the uploader with a UI component to upload files (picture, first and furemost) and display them in the component.


autosend

enable seding files to server immediately after they have been added to uploader. True by default.

boolean autosend;

Example

webix.ui({
    view:"uploader",
    autosend:false,
    ...//uploader config
});

See also

  • samples
    • Sending on custom action
  • articles
    • Uploader and Form Integration
    • Details

    The default autosend mode is not recommended for forms where attached files should be saved together with other form values.

    Cancelling autosending allows users to looks through the files ready for uploading before sending them to server to avoid human errors.


formData

extra data that will be sent to server side along with the file uploading

hash formData;

Example

webix.ui({
    view:"uploader",
    formData:{
        userid:123,
        document:"attachment"
    }
});


inputName

name of the uploader input

string inputName;

Example

{ view:"uploader", inputName:"myFile" }

Details

The value is "upload" by default.


link

sets the component to display values of the files chosen for upload;

string link;

Example

webix.ui({
    view:"form",
    rows:[
        {
            view:"uploader",
            value:"Upload file",
            link:"mylist", //ID of the linked list
            upload:"php/upload.php"
        },
        {
            view:"list",
            id:"mylist",
            type:"uploader" //defines config of each list item
        }
    ]
});

See also

  • samples
    • Basic List Uploader
  • articles
    • Uploading Files
    • Progress Bar for Uploader
    • Details

    The component should have appropriate configuration to display file properties. In case of list, just define a built-in "uploader" type for it, which includes the needed template, upload state vizualization, remove icon and click behavior.

    You can as well create a custom type by extending any component that can display data with necessary properties:

    A custom type includes:

    • template (string) - set elements to display - file properties: (name, id, size, sizetext, type, status); - icons;
    • percent (function) - function to display different icons for different upload statuses;
    • removeIcon (function) - fucntion that sets a removeIcon as CSS class;
    • on_click - click behavior of the list item;
    • status (object ) - hash of properties to define messages for upload statuses:
    webix.type(webix.ui.list, {
    name:"custom_name",
    template:"#name#  {common.removeIcon()}{common.percent()}<div style='float:right'>#sizetext#</div>",
    percent:function(obj){...},
    removeIcon:function(obj){...},
    on_click:{...}
    status:function(f){
        var messages = {
            server: "Done",
            error: "Error",
            client: "Ready",
            transfer:  f.percent+"%"
        };
        return messages[f.status]

    }
});

    Don't forget to set your custom type for the linked list.

    webix.ui({
    view:"list",
    type:"custom type"
    ...
});

    Related sample: Progress bar

    More about type implementation.


multiple

enables uploading of several files at a time. True by default.

boolean multiple;

Example

webix.ui({
    view:"uploader",
    multiple:false,
    ...//uploader config
});

See also

  • samples
    • Single Upload
    • Details

    Is this property is set to false value, any newly added file will replace the one in the uploader body. Only one file at a time can be addaed for upload.

    Single file upload is useful in combination with cancelled autosend.


Events

onAfterFileAdd | fires after file has been added to the uploader body
onAfterRender | occurs immediately after the component has been rendered.
onAfterScroll | occurs when some webix view has been scrolled
onBeforeFileAdd | fires the moment you try to add file to uploader
onBeforeRender | occurs immediately before the component has been rendered
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onChange | fires when the value of the control is changed
onDestruct | occurs when component destroyed
onFileUpload | fires the moment file uploading ends
onFileUploadError | fires in case of serverside error during uploading
onFocus | fires when a view gets focus
onItemClick | fires after the control has been clicked
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onUploadComplete | fires when all files have been successfully uploaded to server
onViewResize | view size was changed by resizer


onAfterFileAdd

fires after file has been added to the uploader body

void onAfterFileAdd(){ ... };

Example

$$("uploader_1").attachEvent("onAfterFileAdd", function(){
    //... some code here ...
});

See also

  • articles
    • onBeforeFileAdd


onBeforeFileAdd

fires the moment you try to add file to uploader

void onBeforeFileAdd(){ ... };

Example

$$("uploader_1").attachEvent("onBeforeFileAdd", function(item){
                var type = item.type.toLowerCase();
                if (type != "jpg" && type != "png"){
                    webix.message("Only PNG or JPG images are supported");
                    return false;
                    }
                });

See also

  • api
    • onAfterFileAdd
  • samples
    • Invisible Uploader for Datatable
  • articles
    • Binding Uploader to Any Page Element


onFileUpload

fires the moment file uploading ends

void onFileUpload(object item ,object response){ ... };

Parameters

item | object | file data
response | object | serverside response (if any)

Example

$$("uploader1").attachEvent("onFileUpload", function(item, response){
    //code
});

See also

  • api
    • onUploadComplete
    • onFileUploadError
  • samples
    • Invisible Uploader for Datatable
  • articles
    • Uploading Files
    • Binding Uploader to Any Page Element


onFileUploadError

fires in case of serverside error during uploading

void onFileUploadError(object item ,object response){ ... };

Parameters

item | object | file data
response | object | serverside response (if any)

Example

$$("uploader1").attachEvent("onFileUploadError", function(item, response){
    //code
});

Details

The events fires only when serverside response contains error status, like:

echo "{ status:'error' }";

See also

  • api
    • onUploadComplete
    • onFileUpload
  • samples
    • Invisible Uploader for Datatable
  • articles
    • Uploading Files
    • Binding Uploader to Any Page Element


onUploadComplete

fires when all files have been successfully uploaded to server

void onUploadComplete(object response ){ ... };

Parameters

response object serverside response (if any)

Example

$$("upl1").attachEvent("onUploadComplete", function(response){
    webix.message("done");
});

Details

The event takes serverside response as parameter.

If you tune you uploading script to return a response like

PHP response

//$sname - file save name
echo "{ status: 'server', sname:'$sname'}";

you can get it on the client side:

$$("upl1").attachEvent("onUploadComplete", function(response){
    webix.message(response.status);
});

See also

  • api
    • onFileUpload
  • samples
    • Sending on custom action
  • articles
    • Uploading Files


Others

$cssName | name which will be used as part of css class
$getSize | returns the current size of the component
$getValue | called each time when component need to get value from related html input
$height | current height of the view
$onUploadComplete | completes uploading for flash uploader
$renderInput | called each time when component need to paint control's input
$scope | scope for resolving event and method names
$setSize | sets the component size
$setValue | called each time when component need to set value in related html input
$skin | the method which will be called when skin is defined
$updateProgress | method for updating progress state
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
on_click | attaches a click behavior for component items with the specified CSS class.
touchable | flag, which force touch reaction on touch screen devices


$onUploadComplete

completes uploading for flash uploader

function $onUploadComplete;
Details

The method is used in the inner logic and not intended for direct use.


$updateProgress

method for updating progress state

function $updateProgress;
Details

You can redefine the method if you want a custom reaction on progress update


ui.video

Video player view.

Constructor

HTML.

<div id="video_div" style="width:300px; height:200px;"></div>

JS.

var video = webix.ui({
    view:"video",
    container:"video_div",
    id:"video1",
    src: [
        "http://cdn.webix.io/demodata/movie.ogv",
        "http://cdn.webix.io/demodata/movie.mp4"
    ]
});

Where to start

  • Overview of the Video Widget
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getVideo | gets html5 video object
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
controls | enables video controls
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
src | path to video
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
getVideo | gets html5 video object
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link


getVideo

gets html5 video object

getVideo()

Example

var videoObj = $$('myvideo').getVideo();
videoObj.play();

See also

  • samples
    • Video API


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
controls | enables video controls
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
src | path to video
width | sets the width of the component


controls

enables video controls

boolean controls;

Example

webix.ui({
    view: "video",
    controls: false
});


src

path to video

string src;

Example

webix.ui({
   view:"video",
   src:"some.mp4"
});

webix.ui({
   view:"video",
   src: ["some.mp4", "some.ogv"]
});


ui.window

A movable popup window.

The window consists of the header and the body, can be modal or modaless. The window body can contain any content. The header is set by a template. Check window documentation for more detailed description.

Constructor

var window = webix.ui({
    view:"window",
    id:"my_win",
    head:"My Window",
    width: 200,
    height: 200,
    body:{
        template:"Some text"
    }
}).show();

Where to start

  • Overview of the Window Widget
  • Samples
Based on: ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setPosition | sets window's position
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
fullscreen | renders window in fullscreen mode
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Properties

animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
fullscreen | renders window in fullscreen mode
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
left | the left offset of the window
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
toFront | places window above other windows on clicking it
top | the top offset of a window
width | sets the width of the component
zIndex | stack order of the component


fullscreen

renders window in fullscreen mode

boolean fullscreen;

Example

webix.ui({
   view:"window",
   fullscreen:true,

   head:"Some content here",
   body:"Some content here"
})


Mixins

  • ActiveContent - allows placing active element in other views
  • AtomDataLoader - primitive data loader
  • AtomRender - primitive render for views
  • AutoTooltip - allows for setting a prompting message for data items
  • BaseBind - core of all bind operations
  • BindSource - logic for source of data in bind operations
  • Canvas - wrapper for html canvas tag
  • CodeParser - parsing rules for complex values
  • CollectionBind - binding rules for collections of objects
  • ContextHelper - provides for subviews seen by right mouse click
  • CopyPaste - provides support for copy-paste operations (integration with clipboard)
  • CustomScroll - renders custom scrollbars to webix views
  • DataCollection - view-less component that stores a collection of non-hierarchical data
  • DataDriver - data parsing for different format
  • DataLoader - loads and processes data into a component.
  • DataMarks - implements extra data storage
  • DataMove - transfer data between different components
  • DataProcessor - handles client-server data saving operations
  • DataRecord - data view-less component that stores a single data record
  • DataState - enables saving application state
  • DataStore - core of all operations for data-collection based components
  • DataValue - view-less object that stores a single value
  • Date - date formatting | processing logic
  • Destruction - clean object references during object destruction
  • DragControl - handlers drag-n-drop events
  • DragItem - interface which adds ability to drag items for components with datastore inside
  • DragOrder - implements dnd for data collections
  • EditAbility - implement common edit interactions
  • EventSystem - inner event system
  • Group - data grouping and sorting logic
  • GroupMethods - a collection of functors for grouping
  • GroupStore - implements grouping of data
  • HtmlMap - wrapper for image maps
  • IdSpace - separate layer of ids
  • KeysNavigation - implements keyboard navigation
  • MapCollection - holds logic for collection mapping. used in property-sheet's and datatable's editors
  • Modality - sets modality to popup views
  • MouseEvents - adds inner events for all mouse actions
  • Movable - adds ability to move data in component or between components
  • NavigationButtons - navigationbuttons for carousel view
  • Number - number formating|processing logic
  • OverlayBox - show a temporary layer other view
  • PagingAbility - interface which adds support for pager
  • PowerArray - extension for arrays
  • ProgressBar - draws a progress bar (icon) for a view or application part
  • RecordBind - binding logic for view which have single data object
  • RenderStack - render strategy for plain datasets
  • Scrollable - adds scroll for the view
  • SelectionModel - implements basic selection api
  • Settings - allows configuration of component
  • SingleRender - render for single-value views
  • Sparklines -
  • TablePaste - implements copy-paste for datatable
  • Touch - touch events and touch scroll
  • TreeAPI - implements common apis for tree-like components.
  • TreeClick - implements click handler for tree like components
  • TreeCollection - view-less component that stores a collection of hierarchical data
  • TreeDataLoader - loads hierarchical data
  • TreeDataMove - implement copy and move for tree like components
  • TreeRenderStack - implements rendering strategy for tree like components
  • TreeStateCheckbox - implements tree-state checkbox functionality
  • TreeStore - hierarchical store.
  • TreeTableClick - contains tree specific click handlers
  • TreeTablePaste - implements copy-paste for treetable
  • TreeType - contains elements of tree template
  • UIExtension - can be used to extend base views with custom methods
  • UIManager - controls focus and hotkeys for webix.ui
  • Undo - allows reverting changes in data for datastore-based components
  • UploadDriver - implements file uploader driver
  • ValidateCollection - implements validation for data collections
  • ValidateData - data validation logic
  • ValueBind - binding logic for single value components
  • Values - manupilates values of the form and form fields
  • VirtualRenderStack - allows on-demand rendering for plain datasets
  • ui.baselayout - a base class for layout-based ui components
  • ui.baseview - the very base object for all components
  • ui.checksuggest - a suggest control with a multiple-choice list
  • ui.proto - the very base class for ui components
  • ui.resizearea - visualization and handling resize movements
  • ui.view - a pure view with borders but without any content inside it
  • ui.vscroll - virtual scrolls


ActiveContent

Allows placing active element in other views.

Properties
activeContent sets controls that will be use in view template


Properties

activeContent sets controls that will be use in view template


activeContent

sets controls that will be use in view template

object activeContent;

Example

webix.protoUI({
    name:"activeList"
},webix.ui.list,webix.ActiveContent);

webix.ui({
    view: "activeList",
    id:"mylist",
    data: dataset,
    activeContent:{
        deleteButton:{
            id:"deleteButtonId",
            view:"button",
            label:"Delete",
            width:120,
            earlyInit:true
        }
    },
    template: "#title#<div style='float:right'>{common.deleteButton()}</div>",
    type: {
        height:45
    }
});

See also

  • samples
    • List: Active Content


AtomDataLoader

Primitive data loader.

Methods
load | loads data from an external data source.
parse | loads data to the component from an inline data source
Events
onAfterLoad | fires after data loading is complete
onBeforeLoad | occurs immediately before data loading has been started
onLoadError | fires when an error occurs during data loading ( invalid server side response )
Properties
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
url | the URL which the component will use to load data after its initialization


Methods

load | loads data from an external data source.
parse | loads data to the component from an inline data source


Properties

data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
url | the URL which the component will use to load data after its initialization


Events

onAfterLoad | fires after data loading is complete
onBeforeLoad | occurs immediately before data loading has been started
onLoadError | fires when an error occurs during data loading ( invalid server side response )


AtomRender

Primitive render for views.

Methods
render | renders the specified item or the whole component
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
Events
onAfterRender | occurs immediately after the component has been rendered.
onBeforeRender | occurs immediately before the component has been rendered
Properties
template the component template


Methods

render | renders the specified item or the whole component
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another


Properties

template the component template


Events

onAfterRender | occurs immediately after the component has been rendered.
onBeforeRender | occurs immediately before the component has been rendered


AutoTooltip

Allows for setting a prompting message for data items.

Properties
tooltip sets a popup message appearing on pointing a mouse cursor over the dedicated item.


Properties

tooltip sets a popup message appearing on pointing a mouse cursor over the dedicated item.


BaseBind

Core of all bind operations.

Methods
bind | binds components
unbind | breaks "bind" link
Events
onBindRequest fires when the component is ready to receive data from the master component


Methods

bind | binds components
unbind | breaks "bind" link


Events

onBindRequest fires when the component is ready to receive data from the master component


BindSource

Logic for source of data in bind operations.

Methods
addBind | adds one more bound target
getBindData | fills the target object with data
removeBind | disables data binding
saveBatch | makes simultaneous saving several components
setBindData | moves data from master to child
Events
onBindUpdate fires when data is changed in the child and 'save()' is called to update the master.


Methods

addBind | adds one more bound target
getBindData | fills the target object with data
removeBind | disables data binding
saveBatch | makes simultaneous saving several components
setBindData | moves data from master to child


addBind

adds one more bound target

void addBind(object source,string rule,string format);

Parameters

source | object | the object that method is assigned to
rule | string | sets the rule according which components will be bound
format | string | the format of bound data


getBindData

fills the target object with data

void getBindData(id key,boolean update);

Parameters

key | id | the id of master record
update | boolean | forces the target to refresh after data update


removeBind

disables data binding

void removeBind(object source);

Parameters

source object the component which was used as the source of data binding


saveBatch

makes simultaneous saving several components

void saveBatch(function func);

Parameters

func function user-defined handler function

Example

$$('myform1').bind('myStore');
$$('myform2').bind('myStore');

$$('myStore').saveBatch(function(){
        $$('myform1').save();
        $$('myform2').save();
});

Details

The code snippet above shows the most popular use case - saving changes made in 2 bound forms.\ Sequential saving provokes data loss: when we save data in one form, the second form is updated by old data. The method helps to prevent losses and save data simultaneously.


setBindData

moves data from master to child

void setBindData(object data,id key);

Parameters

data | object | the data hash
key | id | the id of the child component


Events

onBindUpdate fires when data is changed in the child and 'save()' is called to update the master.


onBindUpdate

fires when data is changed in the child and 'save()' is called to update the master.

void onBindUpdate(object data,id key){ ... };

Parameters

data | object | the updated data
key | id | the id of the child component

Example

some.attachEvent("onBindUpdate", function(data, key){
    //... some code here ...
});

Details

Part of bind API. Makes no sense if used alone

See also

  • api
    • save


Canvas

Wrapper for HTML Canvas tag.

Methods
clearCanvas | clears the component canvas
getCanvas | gets the canvas context
hideCanvas | hides canvas object
renderText | creates absolutely positioned container
renderTextAt | creates absolutely positioned container and then align it according to the 1st and 2nd parameters
showCanvas | shows canvas object
toggleCanvas | toggle visibility of canvas


Methods

clearCanvas | clears the component canvas
getCanvas | gets the canvas context
hideCanvas | hides canvas object
renderText | creates absolutely positioned container
renderTextAt | creates absolutely positioned container and then align it according to the 1st and 2nd parameters
showCanvas | shows canvas object
toggleCanvas | toggle visibility of canvas


clearCanvas

clears the component canvas

void clearCanvas();

Example

var mychart = webix.ui({
    view:"chart",
    ...
});

mychart.clearCanvas();

See also

  • api
    • getCanvas


getCanvas

gets the canvas context

object getCanvas(string context);

Parameters

context string the context type (by default, 2d)

Returns

object the canvas object

Example

myChart.getCanvas();

See also

  • api
    • clearCanvas


hideCanvas

hides canvas object

void hideCanvas();

Example

some.hideCanvas();


renderText

creates absolutely positioned container

void renderText(number x,number y,string text,string css,number w);

Parameters

x | number | left position
y | number | top position
text | string | the content of the div
css | string | css class name
w | number | container width


renderTextAt

creates absolutely positioned container and then align it according to the 1st and 2nd parameters

void renderTextAt(string valign,string align,number x,number y,string t,string c,number w);

Parameters

valign | string | vertical align
align | string | horizontal align
x | number | left position
y | number | top position
t | string | the content of the div
c | string | css class name
w | number | container width


showCanvas

shows canvas object

void showCanvas();

Example

some.showCanvas();


toggleCanvas

toggle visibility of canvas

void toggleCanvas();

Example

some.toggleCanvas();

Details

Will hide visible canvas, and will show the hidden one.


CodeParser

Parsing rules for complex values.}

Is used by toolbar, form and property sheet components in a complexData mode.

Methods
collapseNames | convert complex object to simple hash
expandNames | converts string names to objects


Methods

collapseNames | convert complex object to simple hash
expandNames | converts string names to objects


collapseNames

convert complex object to simple hash

hash collapseNames(any obj);

Parameters

obj any some complex object

Returns

hash hash of key-value pairs

Example

var obj = { user: { some: { key: 123 } } };
var res = webix.CodeParser.collapseNames(obj);
// res = { "user.some.key" : 123 };


expandNames

converts string names to objects

obj expandNames(hash obj);

Parameters

obj hash hash of key-value pairs

Returns

obj some complex data object

Example

var obj = { "user.some.key" : 123 };
var res = webix.CodeParser.expandNames(obj);
// res = { user: { some: { key: 123 } } };


CollectionBind

Binding rules for collections of objects.

Methods
getCursor | returns the current cursor position.
refreshCursor | force repainting of all bound components with current cursor value
setCursor | sets the position of the cursor
Events
onAfterCursorChange | fires after the cursor changes its position.
onBeforeCursorChange | fires before the cursor changes its position.
Properties
defaultData the property stores data which is displayed in the child when no records are selected in the master.


Methods

getCursor | returns the current cursor position.
refreshCursor | force repainting of all bound components with current cursor value
setCursor | sets the position of the cursor


getCursor

returns the current cursor position.

number getCursor();

Returns

number the cursor position

Example

data.getCursor();

Details

The cursor position is the ID of an item that the cursor is set on, not the item index.

See also

  • api
    • setCursor


refreshCursor

force repainting of all bound components with current cursor value

void refreshCursor();

Example

store.setCursor(10);
/* after some time */
store.refreshCursor();

Details

You need not call refreshCursor after changing cursor by setCursor or other api.

The only case when refreshCursor has sense - you need to refresh bound component without changing cursor.


setCursor

sets the position of the cursor

void setCursor(id cursor);

Parameters

cursor id the cursor position

Example

var data = new webix.DataCollection({
  ...  // collection config
});

$$('list').attachEvent("onAfterSelect", function (id) {
  data.setCursor(id);
});

Details

The cursor position is the ID of an item that the cursor is set on, not the item index.

See also

  • api
    • getCursor
  • samples
    • DataCollection Syncing
  • articles
    • Data Binding and Syncing with Non-UI Objects


Properties

defaultData the property stores data which is displayed in the child when no records are selected in the master.


defaultData

the property stores data which is displayed in the child when no records are selected in the master.

object defaultData;

Example

$$('mylist').define ("defaultData",{name:"New contact", gender:"Male", age:"18"});

See also

  • api
    • bind
    • define
  • samples
    • Default Data
  • articles
    • Working with Bound Components
    • Details

    The property can be used to prevent the child from 'undefined' values.

    For example, you have the following structure on the page:

    webix.ui({
    container:"box",
    cols:[
    {
        view:"list",
        id:"myList",
        url:"data.json",
        select:true,
        template:"#rank#. #title# </div>"
    },
    {
        view:"template",
        id:"myTemplate",
        template:"Title #title#<hr> Year #year#<hr> Votes #votes#"
    }]
});

$$('myTemplate').bind($$('myList'));

    Initially, when no items are selected in the list, it looks like this:

    But once you add the following command:

    $$('myList').define ("defaultData",{title:"", year:"", votes:""});

    You must call define before calling the bind method. Otherwise, the provided default values won't be applied.

    The app will start look like this:


Events

onAfterCursorChange | fires after the cursor changes its position.
onBeforeCursorChange | fires before the cursor changes its position.


onAfterCursorChange

fires after the cursor changes its position.

void onAfterCursorChange(id){ ... };

Parameters

id string the id of an item that the cursor is set on (the new cursor position)

Example

some.attachEvent("onAfterCursorChange", function(id){
    //... some code here ...
});

See also

  • api
    • onBeforeCursorChange


onBeforeCursorChange

fires before the cursor changes its position.

void onBeforeCursorChange(id){ ... };

Parameters

id string the id of an item that the cursor is set on (the old cursor position).

Example

some.attachEvent("onBeforeCursorChange", function(id){
    //... some code here ...
});

See also

  • api
    • onAfterCursorChange


ContextHelper

Provides for subviews seen by right mouse click.

Methods
attachTo | attaches a context menu to a Webix component
getContext | gets the master area for contextmenu
setContext | allows customizing target context properties: view object and item id
Events
onBeforeShow fires the moment context menu is called
Properties
body | the contents of the context popup window
hidden | sets the initial visibility of the context object. *True* by default.
master | the area for which context object in initialized
padding | spacing between context border and int contents


Methods

attachTo | attaches a context menu to a Webix component
getContext | gets the master area for contextmenu
setContext | allows customizing target context properties: view object and item id


Properties

body | the contents of the context popup window
hidden | sets the initial visibility of the context object. *True* by default.
master | the area for which context object in initialized
padding | spacing between context border and int contents


body

the contents of the context popup window

object body;

Example

webix.ui({
  view: "context",
  body: {  },
  ...  // context config
});

See also

  • samples
    • Context Menu: HTML Content
    • Context Menu: UI Components Inside
  • articles
    • Context
    • Details

    The body property of a context popup menu may contain HTML code as well as Webix components.

    1. Context with HTML object:
    webix.ui({
  view: "context",
  body: {
    content: "details"  // points to the ID of the div container with content
  },
  master: "areaA"
});
    1. Context with Webix component:
    webix.ui({
  view: "context",
  body: {
    view: "toolbar", cols: [
      { view: "button", value: "Button1", width: 100 },
      { view: "button", value: "Button2", width: 100 },
    ]
  }
});


hidden

sets the initial visibility of the context object. True by default.

boolean hidden;
Details

The property is initially true and setting it to false doesn't make much matter since the meaning of the context object is its visibility only on right mouse clicking.


padding

spacing between context border and int contents

number padding;

Example

webix.ui({
    view:"context",
    body:"...",
    master:"...",
    padding: 10
})

See also

  • samples
    • Context Menu: HTML Content
  • articles
    • Context
    • Details

    The default value here is 4px.


Events

onBeforeShow fires the moment context menu is called


CopyPaste

Provides support for copy-paste operations (integration with clipboard).

Events
onPaste fires when the user presses CTRL+V keys combination
Properties
clipboard | enables/disables clipboard support
templateCopy | sets the template according to which data will be copied to the clipboard


Properties

clipboard | enables/disables clipboard support
templateCopy | sets the template according to which data will be copied to the clipboard


Events

onPaste fires when the user presses CTRL+V keys combination


CustomScroll

Renders custom scrollbars to Webix views.

Methods
enable | enables custom scroll
init | initialize custom scroll mode
resize | adjust size of custom scroll
Other
scrollStep defines a scroll step for custom scrollbars


Methods

enable | enables custom scroll
init | initialize custom scroll mode
resize | adjust size of custom scroll


enable

enables custom scroll

void enable(HTMLElement|WebixView html_node);

Parameters

html_node HTMLElement|WebixView html element or view for which custom scroll need to be enabled

Example

webix.CustomScroll.enable(html_node);


init

initialize custom scroll mode

void init();

Example

webix.CustomScroll.init();

Details

All views created after custom mode initialization will have custom scrolls


resize

adjust size of custom scroll

void resize();

Example

webix.CustomScroll.resize();

Details

Normally scroll will adjust self automatically, but in some cases it may be necessary to force scroll resizing.


Others

scrollStep defines a scroll step for custom scrollbars


scrollStep

defines a scroll step for custom scrollbars

number scrollStep;

Example

webix.CustomScroll.scrollStep = 100;

Details

By default, scrollStep is 40px.


DataCollection

View-less component that stores a collection of non-hierarchical data.

var store = new webix.DataCollection({ url:"data.php" });
Methods
add | adds an item to the store
addBind | adds one more bound target
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBindData | fills the target object with data
getCursor | returns the current cursor position.
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
hasEvent | checks whether the component has the specified event
isVisible | returns true if current view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshCursor | force repainting of all bound components with current cursor value
remove | removes the specified item/items from datastore
removeBind | disables data binding
saveBatch | makes simultaneous saving several components
serialize | serializes data to a JSON object
setBindData | moves data from master to child
setCursor | sets the position of the cursor
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterCursorChange | fires after the cursor changes its position.
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeCursorChange | fires before the cursor changes its position.
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBindUpdate | fires when data is changed in the child and 'save()' is called to update the master.
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
Properties
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
defaultData | the property stores data which is displayed in the child when no records are selected in the master.
externalData | allows defining custom 'move' logic for the component.
id | the component ID
map | defines data mapping
on | allows attaching custom handlers to inner events of the component
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
url | the URL which the component will use to load data after its initialization
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

add | adds an item to the store
addBind | adds one more bound target
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBindData | fills the target object with data
getCursor | returns the current cursor position.
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
hasEvent | checks whether the component has the specified event
isVisible | returns true if current view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshCursor | force repainting of all bound components with current cursor value
remove | removes the specified item/items from datastore
removeBind | disables data binding
saveBatch | makes simultaneous saving several components
serialize | serializes data to a JSON object
setBindData | moves data from master to child
setCursor | sets the position of the cursor
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


getCursor

returns the current cursor position.

number getCursor();

Returns

number the cursor position

Example

data.getCursor();

Details

The cursor position is the ID of an item that the cursor is set on, not the item index.

See also

  • api
    • getCursor


isVisible

returns true if current view is visible

boolean isVisible();

Returns

boolean returns true if item is visible

See also

  • articles
    • Managing Visibility of Components


Properties

data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
defaultData | the property stores data which is displayed in the child when no records are selected in the master.
externalData | allows defining custom 'move' logic for the component.
id | the component ID
map | defines data mapping
on | allows attaching custom handlers to inner events of the component
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
url | the URL which the component will use to load data after its initialization


Events

onAfterAdd | fires after adding item to datastore
onAfterCursorChange | fires after the cursor changes its position.
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeCursorChange | fires before the cursor changes its position.
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBindUpdate | fires when data is changed in the child and 'save()' is called to update the master.
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully


Others

config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


DataDriver

Data parsing for different format.

Collection of data parsing objects. Good place for adding custom data loading format.

Other
csv | the parser for data of the CSV format.
excel | parser for uploaded Excel files or loaded as ArrayBuffer
html | the parser for data of the HTML format.
htmltable | the parser for HTML tables.
jsarray | the parser for data of the JSArray format.
json | the parser for data of the JSON format.
xml | the parser for data of the XML format.


Others

csv | the parser for data of the CSV format.
excel | parser for uploaded Excel files or loaded as ArrayBuffer
html | the parser for data of the HTML format.
htmltable | the parser for HTML tables.
jsarray | the parser for data of the JSArray format.
json | the parser for data of the JSON format.
xml | the parser for data of the XML format.


csv

the parser for data of the CSV format.

object csv;

Example

$$('mylist').define("datatype", "csv");
$$('mylist').load("data.csv");
// it is the same as
$$('mylist').load("data.csv","csv");

See also

  • api
    • delimiter
  • samples
    • Loading from inline datasource
    • Chart: CSV Dataset
  • articles
    • Supported Data Types
    • Data Drivers
    • Details

    The object contains methods and properties for correct processing CSV data. The default logic can be customized globally:

    webix.DataDriver.csv.cell = "\t";
webix.DataDriver.csv.row = "|";

    or, to use the altered delimiters locally, whithin one or several components, a custom datatype can be created:

    webix.DataDriver.mycsv = webix.extend({
    row:"|",
    cell:"-"
}, webix.DataDriver.csv);

    and used:

    var grid = webix.ui({
    view:"datatype",
    datatype:"mycsv",
    data:'1-The Shawshank Redemption|2-The Godfather'
});

//or for loading data in that format
$$('mylist').load("data.csv","mycsv");

    Component data can be loaded during initialization with datasource specified by the data property:

    var csv_data = '1,The Shawshank Redemption,1994,678790,9.2,1\n
                2,The Godfather,1972,511495,9.2,2';

webix.ui({
    view:"datatable",
    columns:[..],
    datatype:"csv",
    data:csv_data
});


excel

parser for uploaded Excel files or loaded as ArrayBuffer

string excel;

Example

$$('mylist').data.driver = webix.DataDriver.excel;
$$('mylist').load("binary->files/data.xlsx");
// it is the same as
$$('mylist').load("binary->files/data.xlsx", "excel");

See also

  • samples
    • Excel Viewer
    • Excel Proxy
    • Excel file Uploading and Downloading
    • Import from Excel
  • articles
    • Excel Viewer
    • Excel File Import
    • Details

    The object contains methods and properties for correct processing Excel file. Basically, it parses Excel file data into a plain jsarray.

    webix.ui({
    view:"list",
    id:"mylist",
    url:"binary->files/data.xlsx",
    datatype:"excel"
});

    Excel file should be loaded with the help of binary proxy or the uploaded File contents should be parsed:

     { view:"uploader", value:"Select Excel File", width:200,
    on:{
        onBeforeFileAdd:function(upload){
            $$("excel").clearAll();
            $$("excel").parse(upload.file, "excel");
            return false;
        }
    }
 }


html

the parser for data of the HTML format.

object html;

Example

$$('mylist').data.driver = webix.DataDriver.html;
$$('mylist').load("data.html");
// it is the same as
$$('mylist').load("data.html","html");

Details

The object contains methods and properties for correct processing HTML data.


htmltable

the parser for HTML tables.

object htmltable;

Example

//..body part
<table id="films">
...
</table>

..//script part
dtable.data.driver = webix.DataDriver.htmltable;
dtable.parse("films");
// it is the same as
dtable.parse("films", "htmltable");

See also

  • samples
    • Loading from HTML table
  • articles
    • Supported Data Types
    • Details

    The object contains methods and properties for correct processing HTML tables.


jsarray

the parser for data of the JSArray format.

object jsarray;

Example

$$('mylist').data.driver = webix.DataDriver.jsarray;
$$('mylist').load("data.js");
// it is the same as
$$('mylist').load("data.js","jsarray");

See also

  • samples
    • Loading from inline datasource
  • articles
    • Supported Data Types
    • Details

    The object contains methods and properties for correct processing JSArray data.

    Component data can be loaded during initialization with datasource specified by the data property:

    var jsarray_data = [
    [1,"The Shawshank Redemption",1994,678790,9.2,1],
    [2,"The Godfather",1972,511495,9.2,2]
];

webix.ui({
    view:"datatable",
    columns:[..],
    datatype:"jsarray",
    data: jsarray_data
});


json

the parser for data of the JSON format.

object json;

Example

$$('mylist').data.driver = webix.DataDriver.json;
$$('mylist').load("data.json");
// it is the same as
$$('mylist').load("data.json","json");

See also

  • samples
    • Tree: JSON Dataset
  • articles
    • Supported Data Types
    • Customizing Data Types
    • Details

    The object contains methods and properties for correct processing JSON data. Processing logic can be changed, which allows using custom tags for hierarchical data.

    Since json is the default data type for Webix components, the datatype parameter is optional.

    Component data can be loaded during initialization with datasource specified by the data property:

    var json_data = [
        { id:1, title:"The Shawshank Redemption", year:1994, votes:678790 },
        { id:2, title:"The Godfather", year:1972, votes:511495 }
];

webix.ui({
    view:"datatable",
    columns:[..],
    data: json_data
});


xml

the parser for data of the XML format.

object xml;

Example

$$('mylist').data.driver = webix.DataDriver.xml;
$$('mylist').load("data.xml");
// it is the same as
$$('mylist').load("data.xml","xml");

See also

  • samples
    • Tree: XML Dataset
  • articles
    • Supported Data Types
    • Customizing Data Types
    • Details

    The object contains methods and properties for correct processing XML data. Processing logic can be changed, which allows using custom tags for hierarchical data.

    Component data can be loaded during initialization with datasource specified by the data property:

    var xml_data =
    '<data>
        <item id="1" title="The Shawshank Redemption" year="1994"  />
        <item id="2" title="The Godfather" year="1972"  />
    </data>';

webix.ui({
    view:"datatable",
    columns:[..],
    datatype:"xml",
    data: xml_data
});


DataLoader

Loads and processes data into a component..

Methods
add | adds an item to the store
clearAll | removes all items from the component
count | returns the number of currently visible items
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
serialize | serializes data to a JSON object
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
updateItem | sets properties of the data item
Events
onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSort | fires before sorting dataset
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onLoadError | fires when an error occurs during data loading ( invalid server side response )
Properties
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scheme | defines schemes for data processing
url | the URL which the component will use to load data after its initialization


Methods

add | adds an item to the store
clearAll | removes all items from the component
count | returns the number of currently visible items
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
serialize | serializes data to a JSON object
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
updateItem | sets properties of the data item


Properties

data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
save | defines URLs for data saving
scheme | defines schemes for data processing
url | the URL which the component will use to load data after its initialization


Events

onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSort | fires before sorting dataset
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onLoadError | fires when an error occurs during data loading ( invalid server side response )


DataMarks

Implements extra data storage.

Methods
addCss | applied CSS class to a component item
clearCss | removes css class from all items
hasCss | checks if item has specific css class
removeCss | removes CSS class from a component item


Methods

addCss | applied CSS class to a component item
clearCss | removes css class from all items
hasCss | checks if item has specific css class
removeCss | removes CSS class from a component item


DataMove

Transfer data between different components.

Implements interface for data moving and transformation.

Required for dnd between components.

Methods
copy | copies an item to the same or another object
move | moves the specified item to a new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
Properties
externalData allows defining custom 'move' logic for the component.


Methods

copy | copies an item to the same or another object
move | moves the specified item to a new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position


move

moves the specified item to a new position

string move(string sid,number tindex, [object tobj,object details] );

Parameters

sid | string | the id of the item to move
tindex | number | the new position of the item (new index)
tobj | object | the object that the item is moved to
details | object | extra parameters for moving

Returns

string new item id

Example

//moving in the same list
$$("list").move("a12", 0);
$$("list").move("a13", -1);
//moves an item to a different list
var id = $$("list").move("a13", 0, $$("list2"), {newId:"b13"});

Details

Details object can contain the next properties:

details = {};
details.newId = "123"; //new id for moved item

Note that in case newId is not defined, the new ID will be the same as the ID of the source item (sid), which is not desirable during copying within one and the same component.

See also

  • api
    • moveBottom
    • moveDown
    • moveUp
    • moveTop
  • articles
    • Data Object Operations


Properties

externalData allows defining custom 'move' logic for the component.


DataProcessor

Handles client-server data saving operations.

Methods
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
attachProgress | assigns handler for data saving actions
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearValidation | removes "data incorrect" highlighting from invalid text fields
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
escape | escapes data
getItemState | return update state for the item in question
getState | gets the current DataProcessor state
hasEvent | checks whether the component has the specified event
ignore | the code that you pass here as the parameter will not react on any data changes (will not be affected by 'onStoreUpdated' event handler)
mapEvent | routes events from one object to another
off | disables dataProcessor
on | enables dataProcessor
processResult | process data saving results
reset | reset updated state for all items
save | mark data record as changed and initiates data saving
send | sends a request to server. Allows to save data changes on server.
setItemState | set update state for the item
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | checks data in the form
Events
onAfterDataSend | fires the moment data has gone to server
onAfterDelete | fires after successful data deletion
onAfterInsert | fires after successful data insertion
onAfterSave | fires after serverside response has been received and processed
onAfterSaveError | fires for data saving errors
onAfterSync | called when server side response received and processed
onAfterUpdate | fires after successful data insertion
onAfterValidation | fires after data has been validated
onBeforeDataSend | called before sending data to server side
onBeforeDelete | fires before sending data for item insertion
onBeforeInsert | fires before sending data for item insertion
onBeforeSaveError | fires for data saving errors
onBeforeSync | called when server side response received, but not processed yet
onBeforeUpdate | fires before sending data for item insertion
onBeforeValidate | called before running validation
onLoadError | occurs when server side response is invalid and can't be procesed
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully
Properties
autoupdate | enables automatic data updating on server while any changes on client-side are done
escape | custom escaping function
id | the component ID
master | the linked data source. It can be both some independent data source and one of components operated on data (e.g. grid)
mode | type of request
on | allows attaching custom handlers to inner events of the component
operationName | name of parameter which will hold operation type
rules | defines a set of rules for input field(s) of the form(htmlform)
store | allows to define datastore which will be monitored for changes
trackMove | enables data moving tracking
undoOnError | defines whether undo will be made if server returns error response
updateFromResponse | server data update mode
url | server side data saving script
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
attachProgress | assigns handler for data saving actions
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearValidation | removes "data incorrect" highlighting from invalid text fields
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
escape | escapes data
getItemState | return update state for the item in question
getState | gets the current DataProcessor state
hasEvent | checks whether the component has the specified event
ignore | the code that you pass here as the parameter will not react on any data changes (will not be affected by 'onStoreUpdated' event handler)
mapEvent | routes events from one object to another
off | disables dataProcessor
on | enables dataProcessor
processResult | process data saving results
reset | reset updated state for all items
save | mark data record as changed and initiates data saving
send | sends a request to server. Allows to save data changes on server.
setItemState | set update state for the item
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
validate | checks data in the form


attachProgress

assigns handler for data saving actions

void attachProgress(function start,function end,function error);

Parameters

start | function | handler will be called for data saving start
end | function | handler will be called for data saving end
error | function | handler will be called for data saving error

Example

webix.dp("myview").attachProgress(function(){
    webix.message("Saving...");
}, function(){
    webix.message("Saved!");
}, function(response){
    webix.message("Error!");
});

Details

API is experimental and can be removed in next versions


escape

escapes data

string escape(string value);

Parameters

value string initial value

Returns

string escaped value

Example

var text = dp.escape("some <?> data");

Details

By default the function uses UTF-8 escaping. If a custom escaping function is defined for the dataprocessor, it will be called instead.

See also

  • api
    • escape


getItemState

return update state for the item in question

object getItemState(id itemId);

Parameters

itemId id id of the item

Returns

object update state for the item in question

Example

var details = webix.dp($$("myview")).getItemState(id);


getState

gets the current DataProcessor state

string| boolean getState();

Returns

string| boolean dataprocessor state

Example

//dp is a dataprocessor object
dp.getState();

Details

Possible states are as follows:

  • true - the DataProcessor is in action
  • saving - the request has come from server, DataProcessor performs saving operation
  • false - the DataProcessor is not active

See also

  • articles
    • DataProcessor


ignore

the code that you pass here as the parameter will not react on any data changes (will not be affected by 'onStoreUpdated' event handler)

void ignore(function code,object master);

Parameters

code | function | the code that the method is assigned to
master | object | holder object. Inside function you can refer to this object through 'this'
Details

The alternative to this method is silent Datastore property.

See also

  • api
    • silent


off

disables dataProcessor

void off();


on

enables dataProcessor

void on();


processResult

process data saving results

void processResult(object data);

Parameters

data object response data objects

Example

webix.ajax("save.php", data, function(text, data, loader){
     ...
     dp.processResult({
         id:"123",
         status:"update"
     });
});

Details

Can be used for custom data saving logic. After applying custom saving logic, it possible to call processResult to finish updating process.

The data object can have next parameters:

  • id - ID of item;
  • newId - new ID ( in case of insert operation it is expected that server side will generate new ID );
  • status - result of operation ("update", "insert", "delete", "error", "invalid").


reset

reset updated state for all items

void reset();

Example

dp.reset();

Details

After command call, updates which was not saved yet will be ignored ( also, error and invalid states will be forgotten as well )


save

mark data record as changed and initiates data saving

void save(id id,string operation);

Parameters

id | id | item id
operation | string | 'update', 'add', 'delete', 'move' or null


send

sends a request to server. Allows to save data changes on server.

void send();


setItemState

set update state for the item

void setItemState(id itemId,boolean state);

Parameters

itemId | id | id of the item
state | boolean | update state

Example

//mark as updated
webix.dp($$("myview")).setItemState(id, "update");
//unmark
webix.dp($$("myview")).setItemState(id, false);

Details

State values are : "update", "insert", "delete"


Properties

autoupdate | enables automatic data updating on server while any changes on client-side are done
escape | custom escaping function
id | the component ID
master | the linked data source. It can be both some independent data source and one of components operated on data (e.g. grid)
mode | type of request
on | allows attaching custom handlers to inner events of the component
operationName | name of parameter which will hold operation type
rules | defines a set of rules for input field(s) of the form(htmlform)
store | allows to define datastore which will be monitored for changes
trackMove | enables data moving tracking
undoOnError | defines whether undo will be made if server returns error response
updateFromResponse | server data update mode
url | server side data saving script


autoupdate

enables automatic data updating on server while any changes on client-side are done

boolean autoupdate;

See also

  • articles
    • DataProcessor
    • Details

    The default value for autoupdate is true.


escape

custom escaping function

boolean escape;

Example

var dp = new webix.DataProcessor({
    master:$$("list"),
    escape:function(value){
         return window.escape(value); //non-utf escaping
    }
})

Details

By default dataprocessor uses utf-8 escaping ( encodeURIComponents ).


master

the linked data source. It can be both some independent data source and one of components operated on data (e.g. grid)

object master;

Example

var dp = new webix.DataProcessor({
    master: $$('mydatatree'),
    url: ""
});

See also

  • api
    • store
  • articles
    • DataProcessor


mode

type of request

string mode;

Values

  • post
  • get

    • See also

  • articles
    • DataProcessor
    • Details

    The parameter can take only one of a predefined set of values. The default value id "post".


operationName

name of parameter which will hold operation type

operationName;

Example

var dp = new webix.DataProcessor({
    master:$$("list"),
    operationName:"operation"
})

//on server you will have $_POST["operation"]

See also

  • articles
    • DataProcessor
    • Details

    Default value - "webix_operation"


store

allows to define datastore which will be monitored for changes

object store;

Example

var dp = new webix.DataProcessor({
    store:$$("list").data
});

See also

  • api
    • master
    • Details

    You need to either define "store" or "master".


trackMove

enables data moving tracking

boolean trackMove;

Example

var dp = new webix.DataProcessor({
   master:$$("mytable"),
   url:"some.php",
   trackMove:true
})

See also

  • articles
    • DataProcessor
    • Details

    When option enabled, dataprocessor will react on drag-n-drop and move commands.


undoOnError

defines whether undo will be made if server returns error response

boolean undoOnError;

Example

var dp = new webix.DataProcessor({
    master:$$("list"),
    url:"some.php",
    undoOnError:true
});

Details

Pay attention that the undo property should be enabled for the data component


updateFromResponse

server data update mode

boolean updateFromResponse;

Example

webix.ui({
   view:"list",
   save:{
     url: "my.php",
     updateFromResponse:true
   }
})

See also

  • articles
    • DataProcessor
    • Details

    In this mode, dataprocessor will expect to receive a json object as response for update and insert command. All data from such json object will be applied to the inserted|updated item.

    In other words, server side can update the saved item on client side.


url

server side data saving script

string url;

Example

var dp = new webix.DataProcessor({
    master:$$("list"),
    url:"some.php"
});

See also

  • articles
    • DataProcessor
    • Details

    If you are using connector on server side you can switch to related protocol by using

    var dp = new webix.DataProcessor({
    master:$$("list"),
    url:"connector->some.php"
});


Events

onAfterDataSend | fires the moment data has gone to server
onAfterDelete | fires after successful data deletion
onAfterInsert | fires after successful data insertion
onAfterSave | fires after serverside response has been received and processed
onAfterSaveError | fires for data saving errors
onAfterSync | called when server side response received and processed
onAfterUpdate | fires after successful data insertion
onAfterValidation | fires after data has been validated
onBeforeDataSend | called before sending data to server side
onBeforeDelete | fires before sending data for item insertion
onBeforeInsert | fires before sending data for item insertion
onBeforeSaveError | fires for data saving errors
onBeforeSync | called when server side response received, but not processed yet
onBeforeUpdate | fires before sending data for item insertion
onBeforeValidate | called before running validation
onLoadError | occurs when server side response is invalid and can't be procesed
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully


onAfterDataSend

fires the moment data has gone to server

void onAfterDataSend(object details){ ... };

Parameters

details object object with data details (see below)

Example

//dp is a dataprocessor object
dp.attachEvent("onAfterDataSend", function(details){
    //code
});

Details

The event parameter, details, consists of:

  • data (object) - data object;
  • id (string, number) - ID of a data item on client side;
  • operation (string) - operation name ("update, "insert", "delete");

and looks like:

{
    id:5,
    operation:"update",
    data:{
        id:5,
        title:"The Godfather",
        rating:"9.2"
    }

}

See also

  • api
    • onBeforeDataSend
  • articles
    • DataProcessor


onAfterDelete

fires after successful data deletion

void onAfterDelete(object response,id id,object details){ ... };

Parameters

response | object | json object with details of server side response
id | id | old id of related item
details | object | object which holds state of data saving

Example

dp.attachEvent("onAfterDelete", function(response, id, object){
    //... some code here ...
});

Details

1 . The response parameter contains the following info about saved data item:

  • id - old ID (clientside);
  • newid - new ID (serverside);
  • sid - old ID (clientside);
  • tid - new ID (serverside);
  • status - status of the operation ("delete");
  • type - operation type ("delete");
  • value - saved data value.

2 . The id parameter contains old (clientside) item ID.

3 . The details parameter contains data saving details, namely:

  • data - object with the information about the action performed;
  • loader - Ajax loader object;
  • text - full text of serverside response.

Will not fire for "error" or "invalid" responses.

If server side response with custom type - custom event will be called.

//for such response
{ id:"123", status:"custom" }
//the onAfterCustom event will be called

See also

  • articles
    • onBeforeDelete


onAfterInsert

fires after successful data insertion

void onAfterInsert(object response,id id,object details){ ... };

Parameters

response | object | json object with details of server side response
id | id | old id of related item
details | object | object which holds state of data saving

Example

dp.attachEvent("onAfter", function(response, id, object){
    //... some code here ...
});

Details

1 . The response parameter contains the following info about saved data item:

  • id - old ID (clientside);
  • newid - new ID (serverside);
  • sid - old ID (clientside);
  • tid - new ID (serverside);
  • status - status of the operation ("insert");
  • type - operation type ("insert");
  • value - saved data value.

2 . The id parameter contains old (clientside) item ID. It will differ from the serverside, as a rule.

3 . The details parameter contains data saving details, namely:

  • data - object with the information about the action performed;
  • loader - Ajax loader object;
  • text - full text of serverside response.

Will not fire for "error" or "invalid" responses.

If server side response with custom type - custom event will be called.

//for such response
{ id:"123", status:"custom" }
//the onAfterCustom event will be called


onAfterSave

fires after serverside response has been received and processed

void onAfterSave(object response,id id,object details){ ... };

Parameters

response | object | json object with details of server side response
id | id | id of related item
details | object | object which holds details of data saving

Example

dp.attachEvent("onAfterSave", function(response, id, details){
    //code
});

Details

1 . The response parameter contains the following info about saved data item:

  • id - old ID (clientside);
  • newid - new ID (serverside);
  • sid - old ID (clientside);
  • tid - new ID (serverside);
  • status - status of the operation ("insert", "update", "delete");
  • type - operation type ("insert", "update", "delete");
  • value - saved data value.

2 . The id parameter contains old (clientside) item ID. It will differ from the serverside one in case of insertion.

3 . The details parameter contains data saving details, namely:

  • data - object with the information about the action performed;
  • loader - Ajax loader object;
  • text - full text of serverside response.

In case of an error during saving, the onAfterSaveError fires instead.

See also

  • api
    • onAfterSave
  • articles
    • DataProcessor


onAfterSaveError

fires for data saving errors

void onAfterSaveError(id id,object status,object response,object details){ ... };

Parameters

id | id | id of updated item
status | object | update status
response | object | server side response parsed as json object
details | object | error details

Example

dp.attachEvent("onBeforeSaveError", function(id){
    //...
});

Details

Structure of status

{
   id:"id of item",
   status:"update status",
   newid:"new id after operation"
}

Structure of details

{
   text:"full text of server side response",
   data:"webix ajax data related to the error",
   loader:"xmlHttpRequest object related to the error"
}


onAfterSync

called when server side response received and processed

void onAfterSync(object obj,string text,object data,object loader){ ... };

Parameters

obj | object | object with item ID and operation status
text | string | full text of server side response
data | object | ajax response object
loader | object | ajax loader object

Example

dp.attachEvent("onAfterSync", function(id, text, data, loader){
    //... some code here ...
});

Details

The first parameter, object looks like:

{
    id:1,
    status:"insert" //or "update", "delete"
}

See also

  • api
    • onBeforeSync


onAfterUpdate

fires after successful data insertion

void onAfterUpdate(object response,id id,object details){ ... };

Parameters

response | object | json object with details of server side response
id | id | old id of related item
details | object | object which holds state of data saving

Example

dp.attachEvent("onAfterUpdate", function(response, id, object){
    //... some code here ...
});

Details

1 . The response parameter contains the following info about saved data item:

  • id - old ID (clientside);
  • newid - new ID (serverside);
  • sid - old ID (clientside);
  • tid - new ID (serverside);
  • status - status of the operation ("update");
  • type - operation type ("update");
  • value - saved data value.

2 . The id parameter contains old (clientside) item ID.

3 . The details parameter contains data saving details, namely:

  • data - object with the information about the action performed;
  • loader - Ajax loader object;
  • text - full text of serverside response.

Will not fire for "error" or "invalid" responses.

If server side response with custom type - custom event will be called.

//for such response
{ id:"123", status:"custom" }
//the onAfterCustom event will be called


onBeforeDataSend

called before sending data to server side

void onBeforeDataSend(object details){ ... };

Parameters

details object object with data details (see below)

Example

dp.attachEvent("onBeforeDataSend", function(details){
    //... some code here ...
});

Details

The event parameter, details, consists of:

  • data (object) - data object;
  • id (string, number) - ID of a data item on client side;
  • operation (string) - operation name ("update, "insert", "delete"););

and looks like:

{
    id:5,
    operation:"update",
    data:{
        id:5,
        title:"The Godfather",
        rating:"9.2"
    }

}

See also

  • api
    • onAfterDataSend
    • DataProcessor


onBeforeDelete

fires before sending data for item insertion

void onBeforeDelete(id id,object details){ ... };

Parameters

id | id | old id of related item
details | object | object which holds state of data saving

Example

dp.attachEvent("onBeforeDelete", function(id, details){
    //... some code here ...
});

Details

1 . The id parameter contains old (clientside) item ID.

2 . The details parameter contains data saving details, namely:

  • data - data item object;
  • id - old (clientside) ID;
  • operation - the type of operation ("delete").

See also

  • api
    • onAfterDelete


onBeforeInsert

fires before sending data for item insertion

void onBeforeInsert(id id,object details){ ... };

Parameters

id | id | old id of related item
details | object | object which holds state of data saving

Example

dp.attachEvent("onBeforeInsert", function(id, details){
    //... some code here ...
});

Details

1 . The id parameter contains old (clientside) item ID.

2 . The details parameter contains data saving details, namely:

  • data - data item object;
  • id - old (clientside) ID;
  • operation - the type of operation ("insert").

See also

  • api
    • onAfterInsert


onBeforeSaveError

fires for data saving errors

boolean onBeforeSaveError(id id,object status,object response,object details){ ... };

Parameters

id | id | id of updated item
status | object | update status
response | object | server side response parsed as json object
details | object | error details

Returns

boolean return true to ignore the error and mark item as saved

Example

dp.attachEvent("onBeforeSaveError", function(id){
    return true;
});

Details

Structure of status

{
   id:"id of item",
   status:"update status",
   newid:"new id after operation"
}

Structure of details

{
   text:"full text of server side response",
   data:"webix ajax data related to the error",
   loader:"xmlHttpRequest object related to the error"
}


onBeforeSync

called when server side response received, but not processed yet

void onBeforeSync(object obj,string text,object data,object loader){ ... };

Parameters

obj | object | object with item ID and operation status
text | string | full text of server side response
data | object | ajax response object
loader | object | ajax loader object

Example

dp.attachEvent("onBeforeSync", function(id, text, data, loader){
    //... some code here ...
});

See also

  • api
    • onAfterSync


onBeforeUpdate

fires before sending data for item insertion

void onBeforeUpdate(id id,object details){ ... };

Parameters

id | id | old id of related item
details | object | object which holds state of data saving

Example

dp.attachEvent("onBeforeUpdate", function(id, details){
    //... some code here ...
});

Details

1 . The id parameter contains old (clientside) item ID.

2 . The details parameter contains data saving details, namely:

  • data - data item object;
  • id - old (clientside) ID;
  • operation - the type of operation ("update").

See also

  • api
    • onAfterUpdate


onLoadError

occurs when server side response is invalid and can't be procesed

void onLoadError(string text,object data,object loader){ ... };

Parameters

text | string | full text of server side response
data | object | ajax response object
loader | object | ajax loader object

Example

some.attachEvent("onLoadError", function(text, data, loader){
    //... some code here ...
});

Details

It will not fire for valid responses, which informs about data saving problem, but only for non-parsable responses


onValidationError

fires when newly loaded/added/edited data fails to pass validation

void onValidationError(number| string id,object obj,object details){ ... };

Parameters

id | number| string | id of the data item that is being validated
obj | object | data item object
details | object | validation result for data keys under validation

Example

webix.ui({
    view:"datatable",
    rules:{
        title:webix.rules.isNotEmpty,
        rating:webix.rules.isNumber
    },
    on:{
        onValidationError:function(id, obj, details){
            var index = this.getIndexById(id)+1;
            webix.message({ type:"error", text:"Empty title for row "+index });
        }
     }
});

Details

The above pattern of validation goes for collections (used for validating data in datatable, list, dataview, etc.)

Since forms are validated differently, the event changes slightly and has different parametes, namely:

  • key (string) - data key that is being validated
  • obj (object) - data object
on:{
    onValidationError:function(key, value ){
        var index = this.getIndexById(id)+1;
        webix.message({ type:"error", text:"Empty title for row "+index });
    }
}

Related sample: 'onValidationError' Event

See also

  • api
    • validate
    • rules
    • onValidationSuccess
  • samples
    • Validation with Message
    • Validation with Complex Message
  • articles
    • Data Validation


DataRecord

Data View-less component that stores a single data record.

Methods
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
getValues | gets hash of data values
hasEvent | checks whether the component has the specified event
isVisible | returns true if current view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
setValues | sets values for all inputs in the component
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterLoad | fires after data loading is complete
onBeforeLoad | occurs immediately before data loading has been started
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when the user changes the value of the DataRecord object
onLoadError | fires when an error occurs during data loading ( invalid server side response )
Properties
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
id | the component ID
on | allows attaching custom handlers to inner events of the component
url | the URL which the component will use to load data after its initialization
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
getValues | gets hash of data values
hasEvent | checks whether the component has the specified event
isVisible | returns true if current view is visible
load | loads data from an external data source.
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
setValues | sets values for all inputs in the component
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getValues

gets hash of data values

object getValues();

Returns

object hash of values


isVisible

returns true if current view is visible

boolean isVisible();

Returns

boolean true, when current view is visible


setValues

sets values for all inputs in the component

void setValues(object values, [boolean update] );

Parameters

values | object | hash of property - value pairs
update | boolean | if true adds updates the form with new values while exisitng values remain. **False by default**

Example

function set_form(){
    $$('myform').setValues({
            field_a: "London",
            field_b: "New York"
            });
    };

Details

The methods allows for setting several values at at time. Pass the IDs of the necessary form elements and their values into the function.

The second parameter helps manipulate values set separately. By delaut, it is false.

Take that we set new value for a field_b input from the form described above.

$$('my_form').setValues({ field_b:"Paris" });

In this case, the value for the field_a is lost. To avoid this, set the update parameter to true. The form will be updated with a new value for field_b input while field_a value remains unchanged.

$$('my_form').setValues({ field_b:"Paris" }, true);

See also

  • api
    • getValues
  • samples
    • Hidden Inputs
  • articles
    • HTMLForm and Form Treatment


Properties

data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datatype | the type of loaded data
id | the component ID
on | allows attaching custom handlers to inner events of the component
url | the URL which the component will use to load data after its initialization


Events

onAfterLoad | fires after data loading is complete
onBeforeLoad | occurs immediately before data loading has been started
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when the user changes the value of the DataRecord object
onLoadError | fires when an error occurs during data loading ( invalid server side response )


onChange

fires when the user changes the value of the DataRecord object

void onChange(data){ ... };

Parameters

data object the data object

Example

var data = new webix.DataRecord({
        id:"data",
        name:"Anna Gretim",
        title:"Ms."
});
$$("myForm").bind(data);
...

data.attachEvent("onChange", function(obj){
        alert("Your new object is: "+ obj.title + obj.name);
});


DataState

Enables saving application state.

Methods
getState | returns the current state of the view
setState | restores the specified state


Methods

getState | returns the current state of the view
setState | restores the specified state


getState

returns the current state of the view

object getState();

Returns

object the state object

Example

grid.getState();

Details

The state object reflects inner UI configuration of the view.

For example, for DataTable shown below:

the state object will look as in:

{
    filter:{
        title:"Go"
    },
    ids: ["rank","title","year","votes"],
    select:[{
        column:"title",
        id:3,
        row:3
    }],
    size:[50,200,80,100],
    sort:{
        dir: "desc"
        id: "title"
    }
}

See also

  • api
    • setState
  • samples
    • Tree State Object
  • articles
    • Saving and Restoring Component State


setState

restores the specified state

void setState(object state);

Parameters

state object the state object

Example

webix.storage.local.put("state", grid.getState());
...

var state = webix.storage.local.get("state");
if (state)
    grid.setState(state);

See also

  • api
    • getState
  • samples
    • Tree State Object
  • articles
    • Saving and Restoring Component State


DataStore

Core of all operations for data-collection based components.

Methods
add | adds an item to the store
addMark | allows setting custom flag for a data item.
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
changeId | changes the id of a data item
clearAll | removes all items from the component
clearMark | removes mark from all items in store
count | returns the number of currently visible items
destructor | destroy datastore
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
each | iterates through the collection of data items
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getIndexRange | gets ids of items in the specified index range
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getMark | returns mark value by record id and mark name
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getRange | gets ids of items in the specified range
hasEvent | checks whether the component has the specified event
id | gets the id of a data item
importData | import data from different datastore
mapEvent | routes events from one object to another
move | moves the specified item to the new position
provideApi | assigns methods (and events) of DataStore to an object
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeMark | removes a flag set for the specified item
scheme | sets hash of default values for properties
serialize | serializes data to a JSON object
setDriver | defines type of used data driver
silent | code that you pass here as the parameter will not be affected by 'onStoreUpdated' event handler
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unsync | breaks "sync" link
updateItem | sets properties of the data item
Events
onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterFilter | fires after DataStore was filtered
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeFilter | fires before datatable filtering
onBeforeSort | fires before sorting dataset
onClearAll | fires after datastore was cleared
onDataUpdate | fires when data item is in update process
onIdChange | event fires when id of record changed
onParse | fires when data is ready to be processed by component
onServerConfig | fires when the component loads data containing the config tag (key) inside.
onServerOptions | fires when client side api loads sub-collection from server side
onStoreLoad | fires after data is loaded from external resource
onStoreUpdated | fires after data is changed in datastore
onSyncApply | fires the moment sync() method is applied
Properties
on allows attaching custom handlers to inner events of the component
Other
driver | defines data driver - methods and properties for data parsing
name | indicates the name of the component (a read-only property)
order | returns an array of IDs of the displayable items
pull | returns the hash of data items (where the key is the item id).


Methods

add | adds an item to the store
addMark | allows setting custom flag for a data item.
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
changeId | changes the id of a data item
clearAll | removes all items from the component
clearMark | removes mark from all items in store
count | returns the number of currently visible items
destructor | destroy datastore
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
each | iterates through the collection of data items
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getIndexRange | gets ids of items in the specified index range
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getMark | returns mark value by record id and mark name
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getRange | gets ids of items in the specified range
hasEvent | checks whether the component has the specified event
id | gets the id of a data item
importData | import data from different datastore
mapEvent | routes events from one object to another
move | moves the specified item to the new position
provideApi | assigns methods (and events) of DataStore to an object
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeMark | removes a flag set for the specified item
scheme | sets hash of default values for properties
serialize | serializes data to a JSON object
setDriver | defines type of used data driver
silent | code that you pass here as the parameter will not be affected by 'onStoreUpdated' event handler
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
unsync | breaks "sync" link
updateItem | sets properties of the data item


addMark

allows setting custom flag for a data item.

any addMark(string id,string name, [boolean css,any value] );

Parameters

id | string | the id of a data item to mark
name | string | the flag name
css | boolean | if set to true than the css style with the name equal to the name parameter value will be applied to the marked item
value | any | the value of the flag

Returns

any the flag value

Example

//adds flag 'invaid = true' for the item with 'id=2'.
//applies to this item css style ".invalid"

$$("dtable").addMark(2, "invalid", true, true); // returns 'true'

Details

The method adds some info (as a key/value pair) related to a data item, marking the item thereby. The added information is stored separately from main data. So if you, for example, load data from one data store to multiple components, the mark will exist just for a data item of the calling component.

The method can be called in 3 ways:

  1. addMark(id, name) //-> 'css' is set to false, 'value' - to true
  2. addMark(id, name, css) //-> 'value' is set to true
  3. addMark(id, name, css, value)

See also

  • api
    • removeMark
    • clearMark
    • getMark


changeId

changes the id of a data item

void changeId(id old,id newid);

Parameters

old | id | the old id
newid | id | the new id

See also

  • api
    • id
  • articles
    • Data Object Operations


clearMark

removes mark from all items in store

void clearMark(string name);

Parameters

name string name of mark to be removed

Example

list.data.clearMark("webix_invalid");

See also

  • api
    • addMark
    • removeMark
    • getMark


destructor

destroy datastore

void destructor();

Example

store.destroy();

Details

Called automatically during master component destruction or during page unload.


each

iterates through the collection of data items

void each(function method, [object master,boolean all] );

Parameters

method | function | a method that needs calling for each data item
master | object | an object that the method is applied to ("this" by default)
all | boolean | if true, hidden (as well as hidden by filtering) items are iterated

Example

template:function(data){
        var names = [];
        if (data.each)
            data.each(function(obj){  names.push(obj.name);});
        return names.join(", ");
}

See also

  • samples
    • Template Uploader
  • articles
    • Data Object Operations


getIndexRange

gets ids of items in the specified index range

array getIndexRange(id from,id to);

Parameters

from | id | the start index of a range
to | id | the end index of a range

Returns

array an array of ids in the specified index range

See also

  • articles
    • Data Object Operations


getMark

returns mark value by record id and mark name

any getMark(string id,string mark_name);

Parameters

id | string | record id
mark_name | string | mark name

Returns

any mark value

Example

var value = view.getMark(152, "extra_info");

Details

If marks is not set - returns false
If mark set but value was not specified - returns true

See also

  • api
    • addMark
    • removeMark
    • clearMark


getRange

gets ids of items in the specified range

array getRange(id from,id to);

Parameters

from | id | the id of the first object in a range
to | id | the id of the last object in a range

Returns

array an array of ids in the specified range

See also

  • articles
    • Data Object Operations


id

gets the id of a data item

id id(object item);

Parameters

item object a data object

Returns

id the data item id

See also

  • api
    • changeId
  • articles
    • Start Coding with Webix
    • View
    • Data Object Operations


importData

import data from different datastore

void importData(WebixView source);

Parameters

source WebixView view from which data need to be taken

Example

$$("listB").data.importData($$("listA"));

Details

Similar to "sync" command, but makes one time import only. Changes in the listA data after command call will not be reflected in the listB


move

moves the specified item to the new position

string move(string sid,number tindex, [object tobj,object details] );

Parameters

sid | string | the id of the item to move
tindex | number | the new position of the item (new index)
tobj | object | the object that the item is moved to
details | object | extra parameters for moving

Returns

string the item id

Example

//moving in the same list
$$('list').move("a12", 0);
$$('list').move("a13", -1);
//moves an item to a different list
var id = $$('list').move("a13", 0, $$("list2"));

Details

Details object can contain the following properties

details = {};
details.newId = "123"; //new id for moved item

See also

  • api
    • moveBottom
    • moveDown
    • moveUp
    • moveTop
  • articles
    • Data Object Operations


provideApi

assigns methods (and events) of DataStore to an object

void provideApi(object target,boolean eventable);

Parameters

target | object | the object that methods are assigned to
eventable | boolean | defines if DataStore events needs being assigned


removeMark

removes a flag set for the specified item

void removeMark(string id,string name,boolean css);

Parameters

id | string | the id of a data item to mark
name | string | the flag name
css | boolean | defines whether the css style with the name equal to the flag name (if such class was applied) should be removed as well

Example

$$("dtable").addMark(2, "invalid", true, "incorrect format");
...
// removes the flag but keeps the css style ".invalid" applied to the item with 'id=2'
$$("dtable").getMark(2, "invalid", false);

Details

The method removes only flags set by the addMark method.

See also

  • api
    • addMark
    • getMark
    • clearMark


scheme

sets hash of default values for properties

void scheme(object config);

Parameters

config object hash of default values

Example

$$('list').data.scheme({
    name:"unknown",
    sex:"male",
    age:"30"
});

$$('list').add({
    id:1,
    name:"Alex"
});

// will add a record: name:Alex, sex:male, age:30

See also

  • samples
    • Grouping
    • List: Grouping
  • articles
    • Defining Data Scheme


setDriver

defines type of used data driver

void setDriver(string type);

Parameters

type string driver type: xml, json, csv, html or jsarray

See also

  • api
    • DataDriver
  • articles
    • Supported Data Types
    • Data Drivers


silent

code that you pass here as the parameter will not be affected by 'onStoreUpdated' event handler

void silent(function code);

Parameters

code function the code that the method will be assigned to
Details

If you use Dataprocessor, the alternative to this is its ignore method.

See also

  • api
    • onStoreUpdated
    • ignore


unsync

breaks "sync" link

void unsync();

Example

$$("table").data.unsync();

Details

Contrpart for the "sync" command. Can be used if source of data need to be changed.

See also

  • api
    • sync


Properties

on allows attaching custom handlers to inner events of the component


Events

onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterFilter | fires after DataStore was filtered
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeFilter | fires before datatable filtering
onBeforeSort | fires before sorting dataset
onClearAll | fires after datastore was cleared
onDataUpdate | fires when data item is in update process
onIdChange | event fires when id of record changed
onParse | fires when data is ready to be processed by component
onServerConfig | fires when the component loads data containing the config tag (key) inside.
onServerOptions | fires when client side api loads sub-collection from server side
onStoreLoad | fires after data is loaded from external resource
onStoreUpdated | fires after data is changed in datastore
onSyncApply | fires the moment sync() method is applied


onAfterFilter

fires after DataStore was filtered

void onAfterFilter(){ ... };

Example

some.attachEvent("onAfterFilter", function(){
    //... some code here ...
});

See also

  • api
    • filter
    • onBeforeFilter
  • articles
    • DataTable Filtering
    • Filtering in the Tree
    • Data Filtering and Sorting


onBeforeFilter

fires before datatable filtering

boolean onBeforeFilter(id columnId,string value, [function compare] ){ ... };

Parameters

columnId | id | id of column for filtering
value | string | filter string
compare | function | custom comparation function

Returns

boolean returning false will prevent filtering

Example

dtable.attachEvent("onBeforeFilter", function(column, value){
    if (value == 0) return false;

    webix.message("Filtering...");
    return true;
});

Details

If you have multiple filters assigned - event will fire for all of them

See also

  • api
    • filter
    • onAfterFilter
  • articles
    • DataTable Filtering
    • Filtering in the Tree
    • Data Filtering and Sorting


onClearAll

fires after datastore was cleared

void onClearAll(){ ... };

Example

some.attachEvent("onClearAll", function(){
    //... some code here ...
});

See also

  • api
    • clearAll
  • articles
    • Adding/Deleting Data Items


onIdChange

event fires when id of record changed

void onIdChange(id oldid,id newid){ ... };

Parameters

oldid | id | old record id
newid | id | new record id

Example

dtable.attachEvent("onIdChange", function(oldid,newid){
    webix.message("Id was changed");
));

See also

  • api
    • id
    • changeId


onParse

fires when data is ready to be processed by component

void onParse(object driver,object data){ ... };

Parameters

driver | object | data driver (some from webix.DataDriver collection)
data | object | data object, for json - raw json object, for xml - xml document object

Example

dtable.attachEvent("onParse", function(driver, data){
    //for json data
    webix.message("Count of records "+data.length);
});

Details

event can be used to preprocess data ( but usage of scheme is the better way )
also, this is good place to read some extra attributes from incoming data

See also

  • api
    • parse
  • articles
    • Data Loading


onServerConfig

fires when the component loads data containing the config tag (key) inside.

void onServerConfig(config){ ... };

Parameters

config object the config object

Example

some.attachEvent("onServerConfig", function(config){
    //... some code here ...
});

Details

When the parser processes data and 'sees' the tag (key) named as "config" it invokes the onServerConfig event (before onAfterLoad).

Applicable only to data in the XML, JSON formats

You might want to change the name of tag(key) the parser should look for. In this case, use the DataDriver class and the next command:

webix.DataDriver.[format].config = "/*/[keyword]";

For example, to make the parser search for the "conf" tag instead of "config" in the XML data, you should call the command as in:

webix.DataDriver.xml.config = "/*/conf";


onServerOptions

fires when client side api loads sub-collection from server side

void onServerOptions(hash options){ ... };

Parameters

options hash hash of options collections

Example

mytable.data.attachEvent("onSeverOptions", function(cols){
    for (var key in cols)
           webix.message("Collection: "+key);
});


onStoreLoad

fires after data is loaded from external resource

void onStoreLoad(object driver,array data){ ... };

Parameters

driver | object | data driver
data | array | raw external data

Example

some.attachEvent("onStoreLoad", function(driver, data){
    //... some code here ...
});

See also

  • articles
    • Data Loading
    • load


onStoreUpdated

fires after data is changed in datastore

void onStoreUpdated(id id,object obj,string mode){ ... };

Parameters

id | id | the id of updated object
obj | object | updated object
mode | string | updating mode('inserted','deleted','updated')

Example

some.attachEvent("onStoreUpdated", function(id, obj, mode){
    //... some code here ...
});

See also

  • api
    • onDataUpdate
    • updateItem
  • articles
    • Data Updating
    • Tree Nodes manipulations


onSyncApply

fires the moment sync() method is applied

void onSyncApply(){ ... };

Example

some.attachEvent("onSyncApply", function(){
    //... some code here ...
});

See also

  • api
    • sync
  • articles
    • Data Binding and Syncing
    • Data Binding and Syncing with Non-UI Objects


Others

driver | defines data driver - methods and properties for data parsing
name | indicates the name of the component (a read-only property)
order | returns an array of IDs of the displayable items
pull | returns the hash of data items (where the key is the item id).


driver

defines data driver - methods and properties for data parsing

object driver;

Example

$$('mylist').data.driver = webix.DataDriver.xml;
$$('mylist').load("data.xml");
// it is the same as
$$('mylist').load("data.xml","xml");

See also

  • api
    • DataDriver
  • articles
    • Data Loading
    • Supported Data Types
    • Details

    The property can take one of a predefined set of values.
    The predefined values are:

    1. xml (default)
    2. json
    3. csv
    4. jsarray
    5. html
    6. htmltable

    Or the name of a custom-defined data type:

    webix.DataDriver.customType={ //customType - the name of the new data type
   ...
}
    $$('mylist1').data.driver = webix.DataDriver.customType;


name

indicates the name of the component (a read-only property)

string name;

Example

var name = $$('myList').data.name //-> "DataStore"

Details

The hardcoded value of the property is "DataStore".


order

returns an array of IDs of the displayable items

array order;

Example

var items = $$("myList").data.order

See also

  • api
    • pull
    • Details

    Beware, that the property returns only displayable items not the entire DataStore collection.

    var listData = [
        {id: "1", name: "Emma",     age: 62},
        {id: "2", name: "Emily",    age: 43},
        {id: "3", name: "Madison",  age: 33},
        {id: "4", name: "Mia",      age: 52},
        {id: "5", name: "Olivia",   age: 40}
];

webix.ui({
        view:"list",
        id:"myList",
        template:"#name#"
});
$$("myList").parse(listData,"json");
    $$("myList").data.order; //-> [1, 2, 3, 4, 5]

$$("myList").filter(function(obj){ return obj.age > 50;});
$$("myList").data.order; //-> [1, 4]


pull

returns the hash of data items (where the key is the item id).

object pull;

Example

var items = $$("myList").data.pull;

See also

  • api
    • order
    • Details

    To get a certain item, call the property as in:

    var item = $$("myList").data.pull[id]

    The property returns the entire collection of data items regardless of the number of currently displayable ones.

    var listData = [
        {id: "1", name: "Emma",     age: 62},
        {id: "2", name: "Emily",    age: 43}
];

webix.ui({
        view:"list",
        id:"myList",
        template:"#name#"
});
$$("myList").parse(listData,"json");
    $$("myList").data.pull; //-> { {id:"1", name:"Emma", age:62},{id:"2", name:"Emily", age:43} }

$$("myList").filter(function(obj){ return obj.age > 50;});
$$("myList").data.pull; //-> { {id:"1", name:"Emma", age:62},{id:"2", name:"Emily", age:43} }


DataValue

View-less object that stores a single value.

Methods
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
getValue | returns the current value of the component
hasEvent | checks whether the component has the specified event
isVisible | returns true if current view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
setValue | sets a new value for the component
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when the user changes the value of the DataValue object
Properties
id | the component ID
on | allows attaching custom handlers to inner events of the component
value | sets the initial value for a control
Other
name indicates the name of the component (a read-only property)


Methods

attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
getValue | returns the current value of the component
hasEvent | checks whether the component has the specified event
isVisible | returns true if current view is visible
mapEvent | routes events from one object to another
refresh | repaints the component
setValue | sets a new value for the component
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


getValue

returns the current value of the component

string getValue();

Returns

string a color in the hex format

Example

webix.ui({
    view:"colorboard",
    id:"color",
    cols    :30,
    rows    :30,
    width   :400,
    height  :400
});
$$('color').setValue("#2626FF")

$$('color').getValue();// -> "#2626FF"

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • setValue
    • value
  • articles
    • Controls Guide


isVisible

returns true if current view is visible

boolean isVisible();

Returns

boolean true when current view is visible


setValue

sets a new value for the component

void setValue(string value);

Parameters

value string a new value for the button

Example

webix.ui({
    container:"box",
    view:"form",
    elements:[
        { view:"button", id:"b1", value:"Edit", type:"form" },
        { view:"button", id:"b2", value:"Back", type:"form" }
    ]
});
...
$$('b1').setValue("Save");
$$('b2').setValue("Cancel");

Details

Value of the control may be:

  • text value in the input text and textarea field;
  • selected item like date in calendar and color in the colorboard;
  • state of the two-state control (checkbox, radio, toggle);
  • selected option of integral buttons (tabbar, tabview, segmented;
  • selected option of select, richselect, and combo;
  • string with selected options of a multiselect and multicombo control.

See also

  • api
    • getValue
  • articles
    • Controls Guide


Properties

id | the component ID
on | allows attaching custom handlers to inner events of the component
value | sets the initial value for a control


id

the component ID

id id;

Example

webix.ui({
    view:"radio",
    id:"rad",
    click:"change_batch",
    options:[
        "1","2", "3"
    ]
});

function change_batch(){
    var mode = $$("rad").getValue(); // "1" or "2"
    $$("mybar").showBatch(mode); //the value is passed into the function
}

See also

  • samples
    • Hiding and Showing Groups of Controls
  • articles
    • Start Coding with Webix
    • View
    • Details

    The parameter can contain any string or numeric value and doesn't have a limit on length.

    It is used when referring to the component to apply and methods to it, attach events and getting to its properties.


value

sets the initial value for a control

id value;

Example

rows:[
    { view:"text", name:"country", label:"Country", value:"Belarus" },
    {
        view:"combo", value:1, options:[
            { id:1, value:"Banana" },
            { id:2, value:"Papaya" },
            { id:3, value:"Apple" }
        ]
    },
    { view:"button", type:"form", value:"Submit data"}
]

See also

  • api
    • getValue
    • setValue
  • samples
    • Editable Combo Box ('combo')
  • articles
    • Controls Guide
    • Details

    All controls fall into:

    • single-value - those containing a string of a number;
    • multiple-value - those containing an array of values;

    In case of multiple controls value property defines the one initially chosen.

    Value of the control may be:

    • text value in the input text and textarea field;
    • selected item like date in calendar and color in the colorboard;
    • state of the two-state control (checkbox, radio, toggle);
    • selected option of integral buttons (tabbar, tabview, segmented;
    • selected option of select, richselect, and combo;
    • string with selected options of a multiselect and multicombo control.


Events

onBindRequest | fires when the component is ready to receive data from the master component
onChange | fires when the user changes the value of the DataValue object


onChange

fires when the user changes the value of the DataValue object

void onChange(data){ ... };

Parameters

data object the data object

Example

var data = new webix.DataValue({});
data.setValue("Anna");

$$("myForm").bind(data);
...

data.attachEvent("onChange", function(obj){
        alert("Your new name is: "+ obj.name);
});


Others

name indicates the name of the component (a read-only property)


name

indicates the name of the component (a read-only property)

string name;

Example

var data = new webix.DataValue({});
data.setValue("someValue");

var name = data.name; // returns 'DataValue'

Details

The hardcoded value of the property is "DataValue".


Date

Date formatting | processing logic.

Methods
add | adds the number of date units to date
copy | creates date copy
datePart | gets the date part of date object
dateToStr | creates new date formatting method
dayStart | gets day start
equal | compare two dates
getISOWeek | gets the number of week by ISO (local time zone)
getUTCISOWeek | gets number of week by ISO (UTC time)
isHoliday | returns true if date is a holiday
monthStart | gets the start of the month
strToDate | creates new date parsing method
timePart | gets time part of a date in seconds
toFixed | adds a leading zero to a number if it's less than 10
weekStart | gets the week start
yearStart | gets the year start
Other
startOnMonday defines whether weeks start on Monday.


Methods

add | adds the number of date units to date
copy | creates date copy
datePart | gets the date part of date object
dateToStr | creates new date formatting method
dayStart | gets day start
equal | compare two dates
getISOWeek | gets the number of week by ISO (local time zone)
getUTCISOWeek | gets number of week by ISO (UTC time)
isHoliday | returns true if date is a holiday
monthStart | gets the start of the month
strToDate | creates new date parsing method
timePart | gets time part of a date in seconds
toFixed | adds a leading zero to a number if it's less than 10
weekStart | gets the week start
yearStart | gets the year start


add

adds the number of date units to date

object add(object date,number inc,string mode);

Parameters

date | object | date object
inc | number | positive or negative number of units
mode | string | unit name: day, week, month, year, hour or minute

Returns

object date object


copy

creates date copy

object copy(object date);

Parameters

date object date object

Returns

object copy of date object


datePart

gets the date part of date object

object datePart(object date);

Parameters

date object date object

Returns

object date part of initial date object


dateToStr

creates new date formatting method

function dateToStr(string format,boolean utc);

Parameters

format | string | date format
utc | boolean | convert local time to UTC during conversion

Returns

function formatting function

Example

var myformat = webix.date.dataToStr("%m - %d");
var text = myformat(new Date());

//or directly
{view:"datepicker",
 format: webix.Date.dateToStr("%d/%m/%y")
 }

See also

  • samples
    • Using date templates
    • Date picker in Calendar
  • articles
    • Working with Dates
    • Date formatting methods


dayStart

gets day start

object dayStart(object date);

Parameters

date object date object

Returns

object date object adjusted to the start of the day


equal

compare two dates

boolean equal(object datea,object dateb);

Parameters

datea | object | first date to compare
dateb | object | second date to compare

Returns

boolean true if both dates point to the same value


getISOWeek

gets the number of week by ISO (local time zone)

number getISOWeek(object date);

Parameters

date object date object

Returns

number the number of week


getUTCISOWeek

gets number of week by ISO (UTC time)

number getUTCISOWeek(object data);

Parameters

data object date object

Returns

number the number of week
Details

Actually - this is alias to getISOWeek, we need two methods with different names for correct formatting processing.


isHoliday

returns true if date is a holiday

boolean isHoliday(object date);

Parameters

date object date object

Returns

boolean true if date is a holiday

Example

webix.ui({
    view:"calendar",
    date:new Date(2012,3,16),
    events:webix.Date.isHoliday
});

Related sample: Custom Holidays in Calendar
Details

If true, the method sets webix_cal_event CSS class to the calendar item (red highlighting).

By default returns true for all Sundays and Saturdays (0 and 6). Redefine it if you wish your own sets of holidays.

The following code helps apply holiday highlighting to Fridays, Saturdays and Sundays.

webix.Date.isHoliday = function(day){
        day = day.getDay();
        if (day === 0 || day==5 || day == 6) return "webix_cal_event";
    }

Related sample: Custom Holidays in Calendar

See also

  • samples
    • Calendar
  • articles
    • Calendar


monthStart

gets the start of the month

object monthStart(object date);

Parameters

date object date object

Returns

object date object adjusted to the start of the month


strToDate

creates new date parsing method

function strToDate(string format,boolean utc);

Parameters

format | string | date format
utc | boolean | convert string in UTC time to date in local time

Returns

function formatting function

Example

var myparse = webix.Date.strToDate("%m - %d");
var date = myparse("04 - 22");

See also

  • samples
    • Converting strings to dates
  • articles
    • Date formatting methods
    • Working with Dates


timePart

gets time part of a date in seconds

number timePart(object date);

Parameters

date object date object

Returns

number number of seconds from the start of day


toFixed

adds a leading zero to a number if it's less than 10

number toFixed(number num);

Parameters

num number a number that the method is applied to

Returns

number the formatted number

Example

webix.Date.toFixed(7);//-> 07


weekStart

gets the week start

object weekStart(object date);

Parameters

date object date object

Returns

object date object adjusted to the start of the week


yearStart

gets the year start

object yearStart(object date);

Parameters

date object date object

Returns

object date object adjusted to the start of the year


Others

startOnMonday defines whether weeks start on Monday.


startOnMonday

defines whether weeks start on Monday.

boolean startOnMonday;

Example

var isMonday = webix.Date.startOnMonday;

if (isMonday){
    webix.Date.startOnMonday = false;
}

See also

  • samples
    • Calendar: Start on Monday
  • articles
    • Calendar
    • Details

    The default value is 'false' (weeks start on Sunday).


Destruction

Clean object references during object destruction.

Works automatically

Methods
destructor destructs the calling object
Events
onDestruct occurs when component destroyed


Methods

destructor destructs the calling object


Events

onDestruct occurs when component destroyed


DragControl

Handlers drag-n-drop events.

Methods
addDrag | registers drag area
addDrop | registers drop area
createDrag | called when drag-n-drop is initiated, creates drag representation
destroyDrag | called after drag-n-drop, removes all traces and html elements
getContext | gets drag-n-drop context object
getMaster | returns object which controls dnd
getNode | gets HTML node of drag marker
sendSignal | sets drag-n-drop active state for drag-n-drop context object
Other
$drag | called when drag-n-drop was started and defines dragging behavior
$dragIn | called when mouse was moved in drop area and defines marker behavior within the drop area
$dragOut | called when mouse was moved out drop area and defines marker behavior out of the drop area
$dragPos | defines position of dragged item
$drop | called when mouse was released over drop area and defines dropping behavior
left | position of drag marker relative to mouse cursor
top | position of drag marker relative to cursor


Methods

addDrag | registers drag area
addDrop | registers drop area
createDrag | called when drag-n-drop is initiated, creates drag representation
destroyDrag | called after drag-n-drop, removes all traces and html elements
getContext | gets drag-n-drop context object
getMaster | returns object which controls dnd
getNode | gets HTML node of drag marker
sendSignal | sets drag-n-drop active state for drag-n-drop context object


addDrag

registers drag area

void addDrag(id|HTMLElement node,object ctrl);

Parameters

node | id|HTMLElement | html node or ID
ctrl | object | hash code of the drag control methods

Example

<div id="myDrag"><div>

webix.DragControl.addDrag("myDrag",{
        move:function(source, target, obj){
            var index = -1;
            if (target)
                //defining position of the target item
                index = obj.getIndexById(target);
                obj.add({
                    title:"new item",
                    rank: "0"
                }, index);
        }
});

Details

When a draggable div with myDrag ID is dropped over the datatable item, it takes its place (defined by index). If index cannot be retrieved, the item takes the last position and is added to the end of the datatable.

See also

  • api
    • addDrop
  • samples
    • DataTable. Custom drag-and-drop behaviour
  • articles
    • Advanced Drag-and-Drop


addDrop

registers drop area

void addDrop(id|HTMLElement node,object ctrl,boolean master_mode);

Parameters

node | id|HTMLElement | html node or ID
ctrl | object | hash code of the drag control methods
master_mode | boolean | flag which can be used if node in question has multiple inner areas, some of them can be used in DND and some not

Example

webix.DragControl.addDrop("myDrop",{
                $drop:function(source, target){
                    var dnd = webix.DragControl.getContext();
                    if (dnd.from.name){ //ignoring non-ui dnd
                        // setting which value to drop if case of multiselect
                        var value = dnd.from.getItem(dnd.source[0]).title;
                        target.innerHTML=value;
                    }
                }
});

Details

In the code above, only UI components can be dragged (non-ui and DataValue, DataRecord and DataCollection).In addition, if several items from the source datatable are dragged, only the first one reached the taget textarea.

See also

  • api
    • addDrag
  • samples
    • DataTable. Custom drag-and-drop behaviour
  • articles
    • Advanced Drag-and-Drop


createDrag

called when drag-n-drop is initiated, creates drag representation

void createDrag(Event event);

Parameters

event Event event object


destroyDrag

called after drag-n-drop, removes all traces and html elements

void destroyDrag();


getContext

gets drag-n-drop context object

object getContext();

Returns

object dnd context

Example

var dnd = webix.DragControl.getContext();
            if (dnd.from.name){ //ignoring non-ui dnd
                var value = dnd.from.getItem(dnd.source[0]).title;
                target.innerHTML=value;

Details

The drag-and-drop context can have the next properties:

  • from - the source object
  • to - the target object
  • source - the id of the dragged item(s)
  • target - the id of the drop target, null for drop on empty space
  • start - the id from which DND was started

See also

  • samples
    • DataTable. Custom drag-and-drop behaviour
  • articles
    • Advanced Drag-and-Drop


getMaster

returns object which controls dnd

object getMaster(object target);

Parameters

target object dragged object or dropped object

Returns

object dnd master


getNode

gets HTML node of drag marker

HTMLElement getNode();

Returns

HTMLElement html object


sendSignal

sets drag-n-drop active state for drag-n-drop context object

void sendSignal(string signal);

Parameters

signal string 'start' or 'stop'


Others

$drag | called when drag-n-drop was started and defines dragging behavior
$dragIn | called when mouse was moved in drop area and defines marker behavior within the drop area
$dragOut | called when mouse was moved out drop area and defines marker behavior out of the drop area
$dragPos | defines position of dragged item
$drop | called when mouse was released over drop area and defines dropping behavior
left | position of drag marker relative to mouse cursor
top | position of drag marker relative to cursor


$drag

called when drag-n-drop was started and defines dragging behavior

HTMLElement $drag(object s,Event e);

Parameters

s | object | source html object
e | Event | event object

Returns

HTMLElement html node


$dragIn

called when mouse was moved in drop area and defines marker behavior within the drop area

void $dragIn(object s,object t,Event e);

Parameters

s | object | source html object
t | object | target html object
e | Event | event object


$dragOut

called when mouse was moved out drop area and defines marker behavior out of the drop area

void $dragOut(object s,object t,object n,Event e);

Parameters

s | object | source html object
t | object | target html object
n | object | dragged object
e | Event | event object


$dragPos

defines position of dragged item

function $dragPos;

Example

list.$dragPos = function(pos, e, node){
    pos.y = 10; //fix y position, so only horizontal drag will be possible
};

Details

Can be redefined for custom dnd behavior

There are 3 parameters: - pos object ( has x and y properties ) - event object - html node of drag marker

You can modify pos.x and pos.y - updated values will be applied to drag marker


$drop

called when mouse was released over drop area and defines dropping behavior

void $drop(object s,object t,object d,Event e);

Parameters

s | object | source html object
t | object | target html object
d | object | dropped html object
e | Event | event object

Example

webix.DragControl.addDrop("myDrop",{
        $drop:function(source, target){
            var dnd = webix.DragControl.getContext();
            if (dnd.from.name){ //ignoring non-ui dnd
                var value = dnd.from.getItem(dnd.source[0]).title;
                target.innerHTML=value;
            }
        }
});

See also

  • api
    • $drop
    • addDrop
    • getContext
  • samples
    • DataTable. Custom drag-and-drop behaviour
  • articles
    • Advanced Drag-and-Drop


left

position of drag marker relative to mouse cursor

number left;


top

position of drag marker relative to cursor

number top;


DragItem

Interface which adds ability to drag items for components with datastore inside.

Events
onAfterDrop | fires after drag-n-drop was finished
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onDragOut | fires when a dragged element is moved outside of the droppable area
Properties
drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop
Other
$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules


Properties

drag | enables or disables drag-and-drop
dragscroll | enables autoscroll of component during drag-n-drop


Events

onAfterDrop | fires after drag-n-drop was finished
onBeforeDrag | fires before the mouse button is pressed and the cursor is moved over a draggable item
onBeforeDragIn | fires before a dragged element is moved over the droppable area
onBeforeDrop | fires before a dragged element is released over the droppable area
onBeforeDropOut | fires before a dragged element is released over the droppable area
onDragOut | fires when a dragged element is moved outside of the droppable area


Others

$drag | method called when drag operation initiated
$dragHTML | defines how dragged item will look
$dragIn | method called when item moved on possible drop landing during dnd
$dragMark | method called during dnd when some item in the component need to be marked as active drop target
$dragOut | method called when item moved out of possible drop landing during dnd
$drop | method called when item dragged and dropped on valid target
$dropAllow | can be redefine if you need custom drop rules


DragOrder

Implements DND for data collections.

Events
onAfterDropOrder | called when dnd reording fully finished
onBeforeDropOrder | called when dnd reording was made, but not applied yet
Other
$drag | method called when drag operation initiated
$dragIn | method called when item moved on possible drop landing during dnd
$dragPos | defines position of dragged item
$drop | method called when item dragged and dropped on valid target


Events

onAfterDropOrder | called when dnd reording fully finished
onBeforeDropOrder | called when dnd reording was made, but not applied yet


onAfterDropOrder

called when dnd reording fully finished

void onAfterDropOrder(id source,id target,object e){ ... };

Parameters

source | id | id of dragged item
target | id | id of item, on which position it was dropped
e | object | native html event

Example

$$("myform").attachEvent("onAfterDropOrder", function(source, target, e){
    ...
});


onBeforeDropOrder

called when dnd reording was made, but not applied yet

void onBeforeDropOrder(id source,id target,object e){ ... };

Parameters

source | id | id of dragged item
target | id | id of item, on which position it was dropped
e | object | native html event

Example

$$("myform").attachEvent("onBeforeDropOrder", function(source, target, e){
    ...
});

Details

Can be blocked


Others

$drag | method called when drag operation initiated
$dragIn | method called when item moved on possible drop landing during dnd
$dragPos | defines position of dragged item
$drop | method called when item dragged and dropped on valid target


EditAbility

Implement common edit interactions.

Methods
edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editNext | closes the current editor and opens one in the next cell of the row
editStop | stops the edit mode and closes all opened editors. The component is still editable
focusEditor | moves focus to the active editor
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
validateEditor | validates data in currently active editor
Events
onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onLiveEdit | occurs when data was changed in the editor
Properties
editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
editor | sets editor types for component items
form | linked form


Methods

edit | enables the edit mode for the specified item
editCancel | cancels the edit mode and closes all opened editors. The component is still editable
editNext | closes the current editor and opens one in the next cell of the row
editStop | stops the edit mode and closes all opened editors. The component is still editable
focusEditor | moves focus to the active editor
getEditState | returns info about active editor object
getEditor | returns editor object
getEditorValue | returns the value of the active (currently open) editor
validateEditor | validates data in currently active editor


Properties

editValue | defines which data item is editable (in case of several data item in the cell/line)
editable | allows/denies editing in the view
editaction | defines the action on which editors will be opened
editor | sets editor types for component items
form | linked form


editor

sets editor types for component items

string editor;

Example

{view:"list", editor:"text"}

See also

  • api
    • editors
  • samples
    • Editor Collection
  • articles
    • Data Editors
    • Details

    There're nine editor types:

    • text;
    • inline-text;
    • checkbox;
    • inline-checkbox;
    • combo;
    • popup;
    • select;
    • color;
    • date;

    They are described in detail in related API reference section as well as in the attached related article.


Events

onAfterEditStart | fires after edit operation was initiated, editor opened and ready for input
onAfterEditStop | fires after edit operation finished
onBeforeEditStart | fires before edit operation is initiated
onBeforeEditStop | fires before stop edit command is received
onLiveEdit | occurs when data was changed in the editor


EventSystem

Inner event system.

Methods
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
hasEvent | checks whether the component has the specified event
mapEvent | routes events from one object to another
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Properties
on allows attaching custom handlers to inner events of the component


Methods

attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
hasEvent | checks whether the component has the specified event
mapEvent | routes events from one object to another
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


Group

Data grouping and sorting logic.

Methods
group | groups data by the specified data property
ungroup | ungroups data


Methods

group | groups data by the specified data property
ungroup | ungroups data


GroupMethods

A collection of functors for grouping.

Methods
any | gets a random property value from a group
count | gets the number of items in a group
max | gets the maximum value of a property
min | gets the minimum value of a property
string | adds a custom property to data items
sum | gets the sum of property values


Methods

any | gets a random property value from a group
count | gets the number of items in a group
max | gets the maximum value of a property
min | gets the minimum value of a property
string | adds a custom property to data items
sum | gets the sum of property values


any

gets a random property value from a group

void any(string property,object data);

Parameters

property | string | a data property
data | object | a dataset with items of a group

Example

$$("mychart").group({
        by:"year",
        map:{
            sales:["sales","any"]
        }
});
//or with the same result
$$("mychart").group({
        by:"year",
        map:{
            sales:["sales"]
        }
});

Details

Generally, the functor gets the value of the first item but it's not mandatory.

Note, the same effect of grouping will be achieved if you omit the functor at all.

Let's assume, you have the following data set initially:

initial_data = [
    {id:1, sales:262, year:2003, company:"Company 3"},
    {id:2, sales:527, year:1998, company:"Company 1"},
    {id:3, sales:629, year:2006, company:"Company 3"},
    {id:4, sales:403, year:2008, company:"Company 2"},
    {id:5, sales:377, year:2006, company:"Company 2"}
]

You group the data like this:

$$("mychart").group({
    by:"company",
    map:{
        sales:["sales", "sum"],
        year:["year", "any"]
    }
});

And get a new data set:

new_data= [
    {id: "Company 1", sales: 527,  year: 1998}
    {id: "Company 2", sales: 780,  year: 2008}
    {id: "Company 3", sales: 891,  year: 2003}
];

See also

  • samples
    • Grouping
  • articles
    • Grouping Data Items
    • Custom Functor for Data Grouping


count

gets the number of items in a group

void count(string property,object data);

Parameters

property | string | a data property
data | object | a dataset with items of a group

Example

$$("mychart").group({
        by:"year",
        map:{
            sales:["sales","sum"]
        }
});
//displays the total sales for each year

See also

  • samples
    • Grouping
  • articles
    • Grouping Data Items
    • Custom Functor for Data Grouping


max

gets the maximum value of a property

void max(string property,object data);

Parameters

property | string | a data property
data | object | a dataset with items of a group

Example

$$("mychart").group({
        by:"year",
        map:{
            sales:["sales","max"]
        }
});
//displays the maximum "sales" value for each year

See also

  • samples
    • Grouping
  • articles
    • Grouping Data Items
    • Custom Functor for Data Grouping


min

gets the minimum value of a property

void min(string property,object data);

Parameters

property | string | a data property
data | object | a dataset with items of a group

Example

$$("mychart").group({
        by:"year",
        map:{
            sales:["sales","min"]
        }
});
//displays the minimum "sales" value for each year

See also

  • samples
    • Grouping
  • articles
    • Grouping Data Items
    • Custom Functor for Data Grouping


string

adds a custom property to data items

void string(string property,object data);

Parameters

property | string | a data property
data | object | a dataset with items of the group

Example

$$("mychart").group({
    by:"company",
    map:{
        sales:["sales", "sum"],
        state:["grouped", "string"]
    }
});

Details

Let's assume, we have the following data set initially:

initial_data = [
    {id:1, sales:262, year:2003, company:"Company 3"},
    {id:2, sales:527, year:1998, company:"Company 1"},
    {id:3, sales:629, year:2006, company:"Company 3"},
    {id:4, sales:403, year:2008, company:"Company 2"},
    {id:5, sales:377, year:2006, company:"Company 2"}
]

We group the data like this:

$$("mychart").group({
    by:"company",
    map:{
        sales:["sales", "sum"],
        state:["grouped", "string"]
    }
});

And get a new data set:

new_data= [
    {id: "Company 1", sales: 527,  state: "grouped"}
    {id: "Company 2", sales: 780,  state: "grouped"}
    {id: "Company 3", sales: 891,  state: "grouped"}
];

See also

  • samples
    • Grouping
  • articles
    • Grouping Data Items
    • Custom Functor for Data Grouping


sum

gets the sum of property values

void sum(string property,object data);

Parameters

property | string | a data property
data | object | a dataset with items of a group

Example

$$("mychart").group({
        by:"year",
        map:{
            sales:["sales","sum"]
        }
});
//displays the total sales for each year

See also

  • samples
    • Grouping
  • articles
    • Grouping Data Items
    • Custom Functor for Data Grouping


GroupStore

Implements grouping of data.

Methods
group | groups data
ungroup | ungroups data
Events
onGroupCreated | fires when grouping is applied to the component
onGroupFooter | called during grouping, when group footer element created
onStoreUpdated | fires after data is changed in datastore


Methods

group | groups data
ungroup | ungroups data


group

groups data

void group(object stats);

Parameters

stats object object with group settings: 'by' and 'map' parameters

Example

$$("mychart").group({
                by:"year",
                map:{
                    sales:["sales","max"]
                }
            });

See also

  • api
    • ungroup
  • samples
    • Grouping
  • articles
    • Grouping Data Items


ungroup

ungroups data

void ungroup();

Example

$$('mychart').ungroup();

See also

  • api
    • group
  • articles
    • Grouping Data Items


Events

onGroupCreated | fires when grouping is applied to the component
onGroupFooter | called during grouping, when group footer element created
onStoreUpdated | fires after data is changed in datastore


onGroupCreated

fires when grouping is applied to the component

void onGroupCreated(number id,string value,object data){ ... };

Parameters

id | number | ID of the group header (parent branch);
value | string | value of the grouping criterion;
data | object | component data object;

Example

webix.ui({
    view:"treetable",
    on:{
        "data->onGroupCreated":function(id, value, data){
            this.item(id).value = "Year "+value;
        }
    }
});

grida.group({
    by:"year" //obj.value = year
});

See also

  • samples
    • Handling events while data grouping
  • articles
    • Grouping Data Items


onGroupFooter

called during grouping, when group footer element created

void onGroupFooter(id id,string value,array collection){ ... };

Parameters

id | id | id of group
value | string | group by value
collection | array | array of objects in the group

Example

$$("grid").attachEvent("onGroupFooter", function(){
    //do something
})


HtmlMap

Wrapper for image maps.

Methods
addPoly | renders html map tag
addRect | renders html map tag
addSector | renders html map tag
render | renders html map tag


Methods

addPoly | renders html map tag
addRect | renders html map tag
addSector | renders html map tag
render | renders html map tag


addPoly

renders html map tag

void addPoly(id id,array points);

Parameters

id | id | id which will be assigned to related html section
points | array | array of points

Example

map.addPoly("11", [10,10,  10,100,  100,100,  100,10]);


addRect

renders html map tag

void addRect(id id,array points, [string userdata] );

Parameters

id | id | id which will be assigned to related html section
points | array | array of points
userdata | string | extra data string ( used by series )

Example

map.addRect("11", [10,10,  10,100,  100,100,  100,10], "serie1");


addSector

renders html map tag

void addSector(id id,number aplha0,number aplha1,number x,number y ,number R,number ky);

Parameters

id | id | id which will be assigned to related html section
aplha0 | number | starting angle
aplha1 | number | ending angle
x | number | x position of center
y | number | y position of center
R | number | radius
ky | number | y-scaling factor

Example

map.addSector("12", 0, Math.PI/2, 100,100, 50, 1);


render

renders html map tag

void render(HTMLElement html);

Parameters

html HTMLElement html element in which map need to be rendered

Example

map.render(document.getElementById("mydiv"));


IdSpace

Separate layer of ids.

If component has such mixin, all their child-elements will store id in separate storage ( so there is no need to make them absolutly unique ). Sub-views will not be accessible by global $$ operator, instead of it you will need to use

    //bad, will not work!
    //var comp = $$('sub_view');

    //good
    var comp = $$('myview').$$("sub_view")

Since it change behavior or child element, it has sense to use it only with container element

Practical example

Mixin was used in top-layout of scheduler-touch, as result it possible to add custom views with any ids, without warryng if they conflict with inner ID's of scheduler or not, and in same time it possible to access all controls in the scheduler with simple ids.

Methods
innerId | returns the unique inner ID of an item
ui | allows creating new ui, the id of which will be locked in the parent id space
Other
$$ locates sub-item by id


Methods

innerId | returns the unique inner ID of an item
ui | allows creating new ui, the id of which will be locked in the parent id space


Others

$$ locates sub-item by id


KeysNavigation

Implements keyboard navigation.

Methods
moveSelection moves selection in the specified direction
Properties
navigation activates the selection keyboard navigation


Methods

moveSelection moves selection in the specified direction


Properties

navigation activates the selection keyboard navigation


MapCollection

Holds logic for collection mapping. Used in property-sheet's and datatable's editors.

Properties
map defines data mapping


Properties

map defines data mapping


Modality

Sets modality to popup views.

Properties
zIndex stack order of the component


Properties

zIndex stack order of the component


MouseEvents

Adds inner events for all mouse actions.

Events
onAfterContextMenu | fires after the context menu was called in the item area
onBeforeContextMenu | fires before the context menu is called in the item area
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item
Properties
mouseEventDelay | the delay between a real mouse action and invoking the related events
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.
Other
on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.


Properties

mouseEventDelay | the delay between a real mouse action and invoking the related events
onClick | attaches a click behavior for component items with the specified CSS class.
onContext | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
onDblClick | attaches a dblclick behavior for component items with the specified CSS class.
onMouseMove | attaches a mousemove behaviour for component items with the specified CSS class.


onClick

attaches a click behavior for component items with the specified CSS class.

hash onClick;

Example

webix.ui({
    view:"list",
    template:"#value# <div class='webix_remove_upload'>Del</div>"
    onClick:{
        "webix_remove_upload":function(ev, id){
              this.remove(id);
        }
    }
});

See also

  • api
    • onItemClick
    • onClick
    • click
  • samples
    • Progress bar
  • articles
    • Event Handling
    • Details
    • "onClick" behavior is defined for component items rather than for the whole component
    • Use the 'onItemClick' handler to attach function to item clicking regardless of the CSS class;
    • For standard Webix buttons you'd better use the click property to attach a function;
    • on_click handler can override the default onclick event:

grid = new webix.ui({
view:"datatable",
columns:[
        { id:"rank",    header:"", css:"rank",          width:50},
        { id:"title",   header:"Film title",width:200},
        {   id:"", template:"<input class='delbtn' type='button' value='Delete'>",
            css:"padding_less",width:100 }],
on:{
    "onItemClick":function(id, e, trg){
        webix.message("Click on row: " + id.row+", column: " + id.column);}
    } //default click behavior that is true for any datatable cell
},
// click behavior for the cell with a button styled with 'delbtn' class
onClick:{
    "delbtn":function(e, id, trg){
        webix.message("Delete row: "+id);
        return false; //here it blocks default behavior
    }
});


Events

onAfterContextMenu | fires after the context menu was called in the item area
onBeforeContextMenu | fires before the context menu is called in the item area
onItemClick | fires when a component item was clicked
onItemDblClick | fires when a component item was double-clicked
onMouseMove | fires when the mouse was moved over the specified component
onMouseMoving | fires when the mouse was moved over the component
onMouseOut | fires when the mouse was moved out from the specified item


Others

on_click | redefines default click behavior for component items.
on_context | a property used to define custom context-click (right click) handlers for elements in the DataTable cells
on_dblclick | attaches a dblclick behavior for component items with the specified CSS class.
on_mouse_move | attaches a dblclick behavior for component items with the specified CSS class.


Movable

Adds ability to move data in component or between components.

Events
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
Properties
move makes view movable


Properties

move makes view movable


Events

onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving


NavigationButtons

NavigationButtons for carousel view.

Properties
navigation defines navigation parameters


Properties

navigation defines navigation parameters


Number

Number formating|processing logic.

Methods
format | returns the formatted number as a string
numToStr | returns formatting function


Methods

format | returns the formatted number as a string
numToStr | returns formatting function


format

returns the formatted number as a string

string format(number value,object config);

Parameters

value | number | the number which needs formatting
config | object | an object of formatting configuration options

Returns

string the formatted number in the string format
Details

The config object can contain the following attributes:

  • decimalSize - the number of decimal digits in the float number. By default, 2;
  • groupSize - the number of digits in a group. By default, 3;
  • groupDelimiter - a char which separates groups of digits. By default, '”,'”;
  • decimalDelimiter - a char which separates the decimal part in the float number. By default, '”.'”.
var str1 = webix.Number.format( 10008.999, {decimalSize:3, groupDelimiter:" "});

See also

  • articles
    • Number formatting methods


numToStr

returns formatting function

function numToStr(object config);

Parameters

config object an object of formatting configuration options

Returns

function the formatting function

Example

//a single datatable column
columns:[
    { id:"votes",
      format:webix.Number.numToStr({
            groupDelimiter:" ",
            groupSize:3,
            decimalDelimiter:",",
            decimalSize:2
    })}
]

Details

The config object can contain the following attributes:

  • decimalSize - the number of decimal digits in the float number. By default, 2;
  • groupSize - the number of digits in a group. By default, 3;
  • groupDelimiter - a char which separates groups of digits. By default, ”,”;
  • decimalDelimiter - a char which separates the decimal part in the float number. By default, ”.”.
var formatFunc = webix.Number.numToStr({ decimalSize:2, decimalDelimiter:","});

formatFunc(10000.9990);

The method doesn't format number, but returns a function which can be used for formatting

See also

  • samples
    • Using number templates
  • articles
    • Number formatting methods


OverlayBox

Show a temporary layer other view.

By default will react on onBeforeLoad and onAfterLoad events.

Methods
hideOverlay | hides the overlay box
showOverlay | shows overlay box over the component


Methods

hideOverlay | hides the overlay box
showOverlay | shows overlay box over the component


hideOverlay

hides the overlay box

void hideOverlay();

Example

webix.ui({
    view:"datatable",
    on:{
        onXLE:function(){
            this.hideOverlay();
        }
    }
});

See also

  • api
    • hideOverlay
  • samples
    • Loading screen
  • articles
    • Data Loading
    • Loading Data into DataTable


showOverlay

shows overlay box over the component

void showOverlay();

Example

webix.ui({
    view:"datatable",
    on:{
        onXLS:function(){
            this.showOverlay("Loading...");
        }
    }
});

See also

  • api
    • showOverlay
  • samples
    • Loading screen
    • Adding overlay text
  • articles
    • Data Loading
    • Loading Data into DataTable


PagingAbility

Interface which adds support for pager.

Methods
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
setPage | makes the specified page visible (assuming that the pager was defined )
Properties
pager defines paging configuration ( creates a 'ui.pager' object)


Methods

getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
setPage | makes the specified page visible (assuming that the pager was defined )


Properties

pager defines paging configuration ( creates a 'ui.pager' object)


PowerArray

Extension for arrays.

Methods
each | executes a method for each element of an array
filter | filters the array
find | gets the index of an element in the array
insertAt | adds an element to a collection at the specific position
map | transforms the initial calling array according to the functor
remove | removes an element from the array
removeAt | removes one or more elements from the specified position


Methods

each | executes a method for each element of an array
filter | filters the array
find | gets the index of an element in the array
insertAt | adds an element to a collection at the specific position
map | transforms the initial calling array according to the functor
remove | removes an element from the array
removeAt | removes one or more elements from the specified position


each

executes a method for each element of an array

void each(function functor,object master);

Parameters

functor | function | the method that needs executing
master | object | the object that the method should be applied to

Example

data.each(function(obj){
    if (obj.status == "server")
        //statement 1
    else
        //statement 2

Details

In sample above method is applied to data array of data objects, each of which has status property and checks the value of this property.

See also

  • samples
    • Attached Files
  • articles
    • Data Object Operations


filter

filters the array

array filter(function functor,object master);

Parameters

functor | function | the filtering function
master | object | the object that the function should be applied to

Returns

array the initial but filtered array
Details

Note, the method filters and rebuilds the initial calling array and not create a new one with filtered values.


find

gets the index of an element in the array

number find(any data);

Parameters

data any the element value

Returns

number the index of the element, -1 if it doesn't exist


insertAt

adds an element to a collection at the specific position

void insertAt(any data,number pos);

Parameters

data | any | the element to add
pos | number | the element position in the array


map

transforms the initial calling array according to the functor

array map(function functor,object master);

Parameters

functor | function | the method which needs executing
master | object | the object that the method should be applied to

Returns

array the transformed initial array

Example

view:"datatable",
scheme:{
    $group:{
        by:"year",
        map:{
            votes:["votes", "sum"]
        }
    }
}

See also

  • api
    • GroupMethods
  • samples
    • Aggregating data while grouping
  • articles
    • Grouping Data Items


remove

removes an element from the array

void remove(any value);

Parameters

value any the element value


removeAt

removes one or more elements from the specified position

void removeAt(number pos,number len);

Parameters

pos | number | the element(s) position
len | number | the number of elements to remove


ProgressBar

Draws a progress bar (icon) for a view or application part.

Methods
hideProgress | hides a progress bar/icon
showProgress | displays a progress bar/ progress icon


Methods

hideProgress | hides a progress bar/icon
showProgress | displays a progress bar/ progress icon


hideProgress

hides a progress bar/icon

void hideProgress();

Example

$$("app").hideProgress();

Details

Instead of calling the method, one can tune a progress bar to hide after a certain period of time:

//this progress icon will be hidden after 3 seconds
$$("app").showProgress({
    delay:3000, //ms
    hide:true
});

This progress icon will be hidden after 3 seconds.

See also

  • api
    • showProgress
  • samples
    • Progress Bars::Layout
  • articles
    • Setting Progress Bar and Overlay Messages


showProgress

displays a progress bar/ progress icon

void showProgress( [object config] );

Parameters

config object configuration of a progress bar (icon)

Example

$$("data").showProgress({
    type:"bottom",
    delay:delay,
    hide:true
});

Details

Progress Types

Possible type values are:

  • top - draw a bar above the view/application
  • bottom - draws a bar below a view/application
  • icon - draw an icon in the middle of a view/application

Icon types are taken from FontAwesome collection.

Defaults

If configuration is not passed, the default one will be used, namely:

{
    position:0,
    delay: 2000,
    type:"icon",
    icon:"refresh",
    hide:false
}

If the above mentioned values are not redefined by a custom configuration, they will be applied.

See also

  • api
    • hideProgress
  • samples
    • Progress Bar::Data
    • Progress Bars::Layout
  • articles
    • Setting Progress Bar and Overlay Messages


RecordBind

Binding logic for view which have single data object.


RenderStack

Render strategy for plain datasets.

Methods
customize | redefines the "type" property
getItemNode | returns HTML element of the item
locate | gets the id of an item from the specified HTML event
render | renders the specified item or the whole component
showItem | scrolls the component to make the specified item visible
Events
onAfterRender | occurs immediately after the component has been rendered
onBeforeRender | occurs immediately before the component has been rendered
onItemRender | for each item rendering, occurs only for items with custom templates
Properties
click | sets an action happening on a button click
template | the component template
type | object that specifies items presentation
Other
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

customize | redefines the "type" property
getItemNode | returns HTML element of the item
locate | gets the id of an item from the specified HTML event
render | renders the specified item or the whole component
showItem | scrolls the component to make the specified item visible


Properties

click | sets an action happening on a button click
template | the component template
type | object that specifies items presentation


Events

onAfterRender | occurs immediately after the component has been rendered
onBeforeRender | occurs immediately before the component has been rendered
onItemRender | for each item rendering, occurs only for items with custom templates


Others

type | set of properties and helpers for item rendering
types | collection of possible types


Scrollable

Adds scroll for the view.

Methods
getScrollState | returns the scroll position
scrollTo | scrolls the data container to a certain position
Events
onAfterScroll fires when to component is scrolled in any direction
Properties
scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)


Methods

getScrollState | returns the scroll position
scrollTo | scrolls the data container to a certain position


Properties

scroll | enables/disables the scroll bar
scrollSpeed | the time during which the component is scrolled to the specified position (in milliseconds)


Events

onAfterScroll fires when to component is scrolled in any direction


SelectionModel

Implements basic selection API.

Methods
getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
isSelected | checks whether the specified item is selected or not
select | selects the specified item(s)
selectAll | selects all items or the specified range
unselect | removes selection from the specified item
unselectAll | removes selection from all items
Events
onAfterSelect | fires after item was selected
onBeforeSelect | fires before item selection is started
onSelectChange | fires after selection state was changed
Properties
multiselect | enables multiselect mode
select | enables/disables item selection or multiselection in grouplist


Methods

getSelectedId | returns the id(s) of the selected item(s)
getSelectedItem | returns selected object
isSelected | checks whether the specified item is selected or not
select | selects the specified item(s)
selectAll | selects all items or the specified range
unselect | removes selection from the specified item
unselectAll | removes selection from all items


unselect

removes selection from the specified item

void unselect( [string id] );

Parameters

id string the item id

Example

webix.ui({
    view:"dataview",
    id:"data",
    ...
});
$$('data').unselect($$('data').getFirstId()); //removes selection from the first item

Details

The input parameter is optional. If no item is specified, selection will be removed from all currently selected items

See also

  • api
    • unselectAll
    • isSelected
    • getSelectedId
    • select
    • selectAll
  • articles
    • Selection


Properties

multiselect | enables multiselect mode
select | enables/disables item selection or multiselection in grouplist


Events

onAfterSelect | fires after item was selected
onBeforeSelect | fires before item selection is started
onSelectChange | fires after selection state was changed


Settings

Allows configuration of component.

Methods
define redefines a single configuration property (or a hash of properties)
Properties
id the component ID
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

define redefines a single configuration property (or a hash of properties)


Properties

id the component ID


SingleRender

Render for single-value views.

Methods
customize | redefines the 'type' property
render | renders the specified item or the whole component
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another
Events
onAfterRender | occurs immediately after the component has been rendered.
onBeforeRender | occurs immediately before the component has been rendered
Properties
template the component template
Other
type currently used set of helpers for view rendering


Methods

customize | redefines the 'type' property
render | renders the specified item or the whole component
sync | allows you to sync two copy of data (all or just a part of it) from one DataCollection to another


Others

type currently used set of helpers for view rendering


Sparklines

visual representation of data values in datatable

Methods
template
Other
paddingX
paddingY
radius


Methods

template


template

returns HTML string for sparklines in a cell

HTML string template(object item,string common,array data,object column,number index);

Parameters

item | object | the data item
common | string | the datatable type
data | array | an array with sparklines data
column | object | the column configuration
index | number | the item index

Returns

HTML string HTML string for sparklines in a cell

Example

var html = webix.Sparklines.template(item,common,data,column,index);

See also

  • samples
    • Broken link: 15_datatable/20_templates/09_sparklines.html
  • articles
    • Using Sparklines in Datatable


Others

paddingX
paddingY
radius


paddingX

horizontal padding in pixels

number paddingX;

Example

webix.Sparklines.paddingX = 6;

See also

  • samples
    • Broken link: 15_datatable/20_templates/09_sparklines.html
  • articles
    • Using Sparklines in Datatable
    • Details

    The property is set globally for all sparklines in the application. The default value is 6.


paddingY

vertical padding in pixels

number paddingY;

Example

webix.Sparklines.paddingY = 6,

See also

  • samples
    • Broken link: 15_datatable/20_templates/09_sparklines.html
  • articles
    • Using Sparklines in Datatable
    • Details

    The property is set globally for all sparklines in the application. The default value is 6.


radius

defines the radius of a point in the sparkline

number radius;

Example

webix.Sparklines.radius = 2;

See also

  • samples
    • Broken link: 15_datatable/20_templates/09_sparklines.html
  • articles
    • Using Sparklines in Datatable
    • Details

    The property is set globally for all sparklines in the application. The default value is 2.


TablePaste

Implements copy-paste for datatable.

Properties
clipboard | enables/disables clipboard support
delimiter | sets CSV delimiters for clipboard operations


Properties

clipboard | enables/disables clipboard support
delimiter | sets CSV delimiters for clipboard operations


Touch

Touch events and touch scroll.

Module enables self only on touch devices.

Methods
disable | fully disables Webix touch handlers, only normal touch scrolling for html content works
enable | enables Webix touch handlers
limit | switch touch support to limited mode
scrollTo | scrolls content of html node to the specific position
Other
config the property stores general touch settings. Used to set up touch behaviour.


Methods

disable | fully disables Webix touch handlers, only normal touch scrolling for html content works
enable | enables Webix touch handlers
limit | switch touch support to limited mode
scrollTo | scrolls content of html node to the specific position


disable

fully disables Webix touch handlers, only normal touch scrolling for html content works

void disable();

Example

webix.Touch.disable();

See also

  • articles
    • enable


enable

enables Webix touch handlers

void enable();

Example

webix.Touch.enable();

Details

The method works with Webix touch handlers that were previously disabled by disable method.

See also

  • articles
    • disable


limit

switch touch support to limited mode

void limit(boolean mode);

Parameters

mode boolean limit functionality or not
Details

In limited mode custom touch events is supported only inside components, while global touch events are not affected.


scrollTo

scrolls content of html node to the specific position

void scrollTo(HTMLElement node,number x,number y,string speed);

Parameters

node | HTMLElement | html node
x | number | scroll x position
y | number | scroll y position
speed | string | time for scroling
Details

speed can be defined like "100ms" or "50s" - similar to speed of css animation


Others

config the property stores general touch settings. Used to set up touch behaviour.


config

the property stores general touch settings. Used to set up touch behaviour.

object config;

Example

webix.Touch.config.scrollDelay = 180;

Details

By default, the config object looks as in:

config:{
    longTouchDelay:1000,
    scrollDelay:150,
    gravity:500,
    deltaStep:30,
    speed:"0ms",
    finish:1500,
    ellastic:true
}

where

  • longTouchDelay - (number) the number of milliseconds to wait before firing the longTouch event.
  • scrollDelay - (number) the time in milliseconds between each drawing of the content. The greater you set the delay, the slower the text will appear to scroll.
  • gravity - (number) the coefficient which affects the speed of scrolling. The greater the coefficient, the slower scrolling.
  • deltaStep - (number) the minimum length of the finger movement in pixels to detect this movement as scrolling.
  • speed - (string) the time in milliseconds during which the component is scrolled to the specified position.
  • finish - (number) the time in milliseconds during which the component will proceed scrolling after getting the finger off the screen.
  • ellastic - (bool) defines whether the view will be scrolled up/down when the scroll knob achieves the top/bottom point of the bar and the finger is still on the screen.


TreeAPI

Implements common APIs for tree-like components..

Methods
close | closes the branch with the specified id
closeAll | closes all branches in the tree
getOpenItems | returns ids of the opened branches
getState | returns the current state of the view
isBranchOpen | checks whether the specified branch is open or closed
open | opens the branch with the specified id
openAll | opens all branches in the tree
setState | restores the specified state
Events
onAfterClose | fires after the branch has been closed
onAfterOpen | fires after the branch has been opened
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeOpen | fires the moment you attempt to open the tree branch
onItemCheck | called when the checkbox inside the tree item was checked
Properties
threeState enable three-state checkboxes


Methods

close | closes the branch with the specified id
closeAll | closes all branches in the tree
getOpenItems | returns ids of the opened branches
getState | returns the current state of the view
isBranchOpen | checks whether the specified branch is open or closed
open | opens the branch with the specified id
openAll | opens all branches in the tree
setState | restores the specified state


Properties

threeState enable three-state checkboxes


Events

onAfterClose | fires after the branch has been closed
onAfterOpen | fires after the branch has been opened
onBeforeClose | fires the moment you attempt to close the tree branch
onBeforeOpen | fires the moment you attempt to open the tree branch
onItemCheck | called when the checkbox inside the tree item was checked


TreeClick

Implements click handler for tree like components.

Methods
webix_tree_checkbox
webix_tree_close
webix_tree_open


Methods

webix_tree_checkbox
webix_tree_close
webix_tree_open


webix_tree_checkbox

helper method for rendering checkbox in tree structure

string webix_tree_checkbox(object obj,hash common);

Parameters

obj | object | data object
common | hash | set of helpers

Returns

string html for checkbox rendering


webix_tree_close

helper method for rendering close button in tree structure

string webix_tree_close(object obj,hash common);

Parameters

obj | object | data object
common | hash | set of helpers

Returns

string html for close button rendering


webix_tree_open

helper method for rendering open button in tree structure

string webix_tree_open(object obj,hash common);

Parameters

obj | object | data object
common | hash | set of helpers

Returns

string html for open button rendering


TreeCollection

View-less component that stores a collection of hierarchical data.

var store = new webix.TreeCollection({ url:"tree.php" });
Methods
add | adds an item to the store
addBind | adds one more bound target
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBindData | fills the target object with data
getBranchIndex | gets index of the node in a specific branch
getCursor | returns the current cursor position.
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getParentId | get the ID of the parent node of the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
hasEvent | checks whether the component has the specified event
isBranch | checks whether the node has any children
isVisible | returns true if current view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshCursor | force repainting of all bound components with current cursor value
remove | removes the specified item/items from datastore
removeBind | disables data binding
saveBatch | makes simultaneous saving several components
serialize | serializes data to a JSON object
setBindData | moves data from master to child
setCursor | sets the position of the cursor
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterCursorChange | fires after the cursor changes its position.
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeCursorChange | fires before the cursor changes its position.
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBindUpdate | fires when data is changed in the child and 'save()' is called to update the master.
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
Properties
data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
defaultData | the property stores data which is displayed in the child when no records are selected in the master.
externalData | allows defining custom 'move' logic for the component.
filterMode | defines the pattern for tree item filtering
id | the component ID
map | defines data mapping
on | allows attaching custom handlers to inner events of the component
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
url | the URL which the component will use to load data after its initialization
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

add | adds an item to the store
addBind | adds one more bound target
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearValidation | removes all validation marks from the component
copy | copies an item to the same or another object
count | returns the number of currently visible items
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getBindData | fills the target object with data
getBranchIndex | gets index of the node in a specific branch
getCursor | returns the current cursor position.
getFirstChildId | gets the ID of the first child of the specified branch
getFirstId | returns the ID of the first item
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNextSiblingId | returns the id of the next sibling of the specified node
getParentId | get the ID of the parent node of the specified item
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
hasEvent | checks whether the component has the specified event
isBranch | checks whether the node has any children
isVisible | returns true if current view is visible
load | loads data from an external data source.
loadBranch | loads data to the specified branch, as direct children of the node with the id provided
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
mapEvent | routes events from one object to another
move | moves the specified item to the new position
moveBottom | moves the specified item to the last position
moveDown | increases the item index and moves the item to the new position
moveTop | moves the specified item to the first position
moveUp | decreases the item index and moves the item to the new position
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
refreshCursor | force repainting of all bound components with current cursor value
remove | removes the specified item/items from datastore
removeBind | disables data binding
saveBatch | makes simultaneous saving several components
serialize | serializes data to a JSON object
setBindData | moves data from master to child
setCursor | sets the position of the cursor
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


Properties

data | JavaScript array containing data for the component
dataFeed | the URL that the component will use to reload data during binding
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
defaultData | the property stores data which is displayed in the child when no records are selected in the master.
externalData | allows defining custom 'move' logic for the component.
filterMode | defines the pattern for tree item filtering
id | the component ID
map | defines data mapping
on | allows attaching custom handlers to inner events of the component
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
url | the URL which the component will use to load data after its initialization


TreeDataLoader

Loads hierarchical data.

Methods
loadBranch loads data to the specified branch, as direct children of the node with the id provided
Events
onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeSort | fires before sorting dataset
onDataRequest | fires when dynamically-loaded data is requested
onDataUpdate | fires when data item is in update process
Properties
filterMode defines the pattern for tree item filtering


Methods

loadBranch loads data to the specified branch, as direct children of the node with the id provided


Properties

filterMode defines the pattern for tree item filtering


Events

onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeSort | fires before sorting dataset
onDataRequest | fires when dynamically-loaded data is requested
onDataUpdate | fires when data item is in update process


TreeDataMove

Implement copy and move for tree like components.

Methods
copy | makes a copy of item
move | move item to new position
Other
$dropAllow can be redefine if you need custom drop rules


Methods

copy | makes a copy of item
move | move item to new position


Others

$dropAllow can be redefine if you need custom drop rules


TreeRenderStack

Implements rendering strategy for tree like components.

Methods
getItemNode | returns HTML element of the item
render | renders the specified item or the whole component
Events
onAfterRender | occurs immediately after the component has been rendered
onBeforeRender | occurs immediately before the component has been rendered
onItemRender | for each item rendering, occurs only for items with custom templates
onPartialRender | called when part of tree is repainted


Methods

getItemNode | returns HTML element of the item
render | renders the specified item or the whole component


Events

onAfterRender | occurs immediately after the component has been rendered
onBeforeRender | occurs immediately before the component has been rendered
onItemRender | for each item rendering, occurs only for items with custom templates
onPartialRender | called when part of tree is repainted


TreeStateCheckbox

Implements tree-state checkbox functionality.

Methods
checkAll | check all items in tree
checkItem | checks the checkbox it the tree item
getChecked | returns ids of the checked items
isChecked | checks whether the specified node is checked
uncheckAll | uncheck all items in the tree
uncheckItem | unchecks the checkbox in the tree item
Events
onItemCheck fires when you check an item in tree and treetable
Properties
threeState defines three-state checkboxes for the tree. Flase by default.


Methods

checkAll | check all items in tree
checkItem | checks the checkbox it the tree item
getChecked | returns ids of the checked items
isChecked | checks whether the specified node is checked
uncheckAll | uncheck all items in the tree
uncheckItem | unchecks the checkbox in the tree item


Properties

threeState defines three-state checkboxes for the tree. Flase by default.


Events

onItemCheck fires when you check an item in tree and treetable


TreeStore

Hierarchical store..

Can't be initialized directly; must be extended from DataStore.

var store = new webix.DataStore();
webix.extend(store, webix.TreeStore, true);
Methods
add | adds a new item to the tree
changeId | changes the id of a data item
clearAll | removes all items from the component
count | returns the number of currently visible items (counts both parent and child nodes)
each | iterates through the collection of tree data items
eachChild | iterates through the first-level childs of the specified branch
eachLeaf | iterates through the leaves (items with no sub-items) of the specified branch
eachOpen | iterates through opened nodes of the tree (both parent and child)
eachSubItem | iterates through all childs (of any level) of the specified branch
getBranch | returns dataset from some branch in the tree-like component
getBranchIndex | gets index of the node in a specific branch
getFirstChildId | gets the ID of the first child of the specified branch
getNextSiblingId | returns the id of the next sibling of the specified node
getParentId | get the ID of the parent node of the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getTopRange | returns an array of the top tree nodes
isBranch | checks whether the node has any children
provideApi | assigns methods (and events) of DataStore to an object
remove | removes the specified item/items from datastore
serialize | serializes data to a JSON object
Events
onAfterDelete | fires after item deleting
onBeforeDelete | fires before item deleting
onStoreUpdated | fires after data is changed in datastore
Properties
filterMode defines the pattern for tree item filtering
Other
name indicates the name of the component (a read-only property)


Methods

add | adds a new item to the tree
changeId | changes the id of a data item
clearAll | removes all items from the component
count | returns the number of currently visible items (counts both parent and child nodes)
each | iterates through the collection of tree data items
eachChild | iterates through the first-level childs of the specified branch
eachLeaf | iterates through the leaves (items with no sub-items) of the specified branch
eachOpen | iterates through opened nodes of the tree (both parent and child)
eachSubItem | iterates through all childs (of any level) of the specified branch
getBranch | returns dataset from some branch in the tree-like component
getBranchIndex | gets index of the node in a specific branch
getFirstChildId | gets the ID of the first child of the specified branch
getNextSiblingId | returns the id of the next sibling of the specified node
getParentId | get the ID of the parent node of the specified item
getPrevSiblingId | returns the id of the previous sibling of the specified node
getTopRange | returns an array of the top tree nodes
isBranch | checks whether the node has any children
provideApi | assigns methods (and events) of DataStore to an object
remove | removes the specified item/items from datastore
serialize | serializes data to a JSON object


count

returns the number of currently visible items (counts both parent and child nodes)

number count();

Returns

number the number of visible (opened) items

Example

tree = new webix.ui({
    view:"tree",
    ...
});

tree.data.count();//-> 8
//or simply
tree.count();//-> 8

Details


each

iterates through the collection of tree data items

void each(function code,object master,boolean all,string pid);

Parameters

code | function | a function that needs calling for each data item
master | object | an object that the function is applied to (this by default)
all | boolean | if true, hidden (as well as hidden by filtering) items are iterated
pid | string | the parent node id. Used to iterate through a specific branch

Example

//iterates through all items of the tree
tree.data.each(
    function(obj){
        console.log(obj.value)
    }
);

//iterates through items with $parent="1.2"
tree.data.each(
    function(obj){
        console.log(obj.value)
    }, this, true, "1.2");

Details

Note,

  • each iterates through both parent and child nodes.
  • The each's function takes the data item object as a parameter.
  • If you specify the 3rd parameter (pid), each will iterate only through child nodes of the branch (without iterating through the specified parent node).

See also

  • api
    • eachChild
    • eachOpen
    • eachSubItem
  • articles
    • Getting/setting the node


eachChild

iterates through the first-level childs of the specified branch

void eachChild(string pid,function code, [object master,boolean all] );

Parameters

pid | string | the parent (branch) id
code | function | a function that needs calling for each data item
master | object | an object that the function is applied to (this by default)
all | boolean | if true, hidden (as well as hidden by filtering) items are iterated

Example

tree.data.eachChild("1.2",function(obj){ console.log(obj.id)});

Details

Note,

  • eachChild iterates through the first-level child nodes of the branch (without the specified parent node).
  • The eachChild's function takes the data object as a parameter.
  • If you want to iterate through all childs of a branch - use the eachSubItem method.

See also

  • api
    • each
    • eachOpen
    • eachSubItem
  • articles
    • Getting/setting the node


eachLeaf

iterates through the leaves (items with no sub-items) of the specified branch

void eachLeaf(string pid,function code);

Parameters

pid | string | the parent (branch) id
code | function | a function that needs calling for each data item

Example

tree.data.eachlLeaf("1.2",function(obj){ console.log(obj.id)});


eachOpen

iterates through opened nodes of the tree (both parent and child)

void eachOpen(function code, [object master,string pid] );

Parameters

code | function | a function that needs calling for each data item
master | object | an object that the function is applied to (this by default)
pid | string | the parent node id. Used to iterate through a specific branch

Example

//iterates through all items of the tree
tree.data.eachOpen(function(obj){
   console.log(obj.value)
});

//iterates through items with $parent="2"
tree.data.eachOpen(function(obj){
   console.log(obj.value)
}, this, "2");

Details

Be aware of the following issues:

  • eachOpen iterates through both parent and child nodes.
  • The eachOpen's function takes the data item object as a parameter.
  • If you specify the 3rd parameter (pid), eachOpen will iterate only through child nodes of the branch (without iterating through the specified parent node).

See also

  • api
    • each
    • eachChild
    • eachSubItem
  • articles
    • Getting/setting the node


eachSubItem

iterates through all childs (of any level) of the specified branch

void eachSubItem(string pid,function code);

Parameters

pid | string | the parent (branch) id
code | function | a function that needs calling for each data item

Example

tree.data.eachSubItem("2", function(obj){ console.log(obj.id); });

Details

Note,

  • eachSubItem iterates through all child nodes of the branch (without the specified parent node).
  • The eachSubItem's function takes the data object as a parameter.
  • If you want to iterate only through the first-level childs of a branch - use the eachChild method.

See also

  • api
    • each
    • eachOpen
    • eachChild
  • articles
    • Getting/setting the node


getBranch

returns dataset from some branch in the tree-like component

array getBranch(string id);

Parameters

id string id of root item

Returns

array array of data objects for the branch in question

Example

var data = $$("tree").data.getBranch("1");


getTopRange

returns an array of the top tree nodes

array getTopRange();

Returns

array an array of nodes objects

Example

tree.data.getTopRange();
//e.g. [{$count:2, $level:1, $parent:0, id:"root", open:true, value:"Films data"}]


Events

onAfterDelete | fires after item deleting
onBeforeDelete | fires before item deleting
onStoreUpdated | fires after data is changed in datastore


onAfterDelete

fires after item deleting

void onAfterDelete(id id){ ... };

Parameters

id id id of item in question

Example

some.attachEvent("onAfterDelete", function(id){
    //... some code here ...
});

Details

In case of Tree and TreeTable - event will be called only for item which is deleted, and will not be called for its childs

See also

  • api
    • onBeforeDelete
    • remove
  • articles
    • Tree Nodes manipulations
    • Operations with Chart Data
    • Adding/Deleting Data Items


onBeforeDelete

fires before item deleting

boolean onBeforeDelete(id id){ ... };

Parameters

id id id of item in question

Returns

boolean returning false will prevent item deleting

Example

some.attachEvent("onBeforeDelete", function(id){
    //... some code here ...
    //return false to block operation
    return true;
});

Details

In case of Tree and TreeTable - event will be called only for item which is deleted, and will not be called for its childs

See also

  • api
    • onAfterDelete
    • remove
  • articles
    • Tree Nodes manipulations
    • Operations with Chart Data
    • Adding/Deleting Data Items


TreeTableClick

Contains tree specific click handlers.


TreeTablePaste

Implements copy-paste for treetable.

Methods
insert inserts new data in treetable


Methods

insert inserts new data in treetable


insert

inserts new data in treetable

void insert(array data);

Parameters

data array matrix of values

Example

treetable.insert([
  ["1", "First record"],
  ["2", "Second record"],
  ["3", "Third record"]
]);


TreeType

Contains elements of tree template.

Methods
checkbox | draws a check box
folder | draws an icon of the folder
icon | draws the '+'/'-' (state) icons for collapsed/expanded states of nodes
space | draws the space


Methods

checkbox | draws a check box
folder | draws an icon of the folder
icon | draws the '+'/'-' (state) icons for collapsed/expanded states of nodes
space | draws the space


checkbox

draws a check box

string checkbox(object obj,object common);

Parameters

obj | object | the data item object
common | object | the collection of predefined template functions

Returns

string the HTML string

Example

webix.ui({
    view:"tree",
    template:"{common.icon()} {common.checkbox()} {common.folder()} #value#"
});

See also

  • samples
    • 2-state Checkboxes
  • articles
    • Node templates


folder

draws an icon of the folder

string folder(object obj,object common);

Parameters

obj | object | the data item object
common | object | the collection of predefined template functions

Returns

string the HTML string

Example

webix.ui({
    view:"tree",
    template:"{common.folder()} #value#"
});

Details

If a tree features no template, state icon (common.icon()) and folder icons (common.folder()) are drawn for it.

If you set only a folder icon for a tree, state icons won't be drawn.

See also

  • samples
    • Tree Without Icons
  • articles
    • Node templates


icon

draws the '+'/'-' (state) icons for collapsed/expanded states of nodes

string icon(object obj,object common);

Parameters

obj | object | the data item object
common | object | the collection of predefined template functions

Returns

string the HTML string

Example

webix.ui({
    view:"tree",
    template:"{common.icon()} {common.folder()} #value#"
});

Details

If a tree features no template, state icon (common.icon()) and folder icons (common.folder()) are drawn for it.

If you set only a state icon for a tree, folder icons won't be drawn.

See also

  • samples
    • Tree Without Icons
  • articles
    • Node templates


space

draws the space

string space(object obj,object common);

Parameters

obj | object | the data item object
common | object | the collection of predefined template functions

Returns

string the HTML string

Example

webix.ui({
    view:"tree",
    template:"{common.icon()} {common.space()} {common.folder()} #value#"
});

See also

  • articles
    • Node templates


UIExtension

Can be used to extend base views with custom methods.


UIManager

Controls focus and hotkeys for webix.ui.

Object is created automatically, and can be accessed as webix.UIManager

Methods
addHotKey | adds the hot key handler
applyChanges | triggers onChange handlers for active component
canFocus | checks whether the view can be focused
destructor | Destructor. Destroys the UIManager instance
getFocus | retrieves the view which has focus
getNext | gets the next view in the focus|tab order
getPrev | gets the previous view in the focus|tab order
getState | retrieves the current state of the specified view
getTop | returns the top-most parent to the specified view
hasFocus | checks whether the specified view has focus
removeHotKey | removes the hot key handler
setFocus | sets focus to the specified view
setState | restores the specified state


Methods

addHotKey | adds the hot key handler
applyChanges | triggers onChange handlers for active component
canFocus | checks whether the view can be focused
destructor | Destructor. Destroys the UIManager instance
getFocus | retrieves the view which has focus
getNext | gets the next view in the focus|tab order
getPrev | gets the previous view in the focus|tab order
getState | retrieves the current state of the specified view
getTop | returns the top-most parent to the specified view
hasFocus | checks whether the specified view has focus
removeHotKey | removes the hot key handler
setFocus | sets focus to the specified view
setState | restores the specified state


addHotKey

adds the hot key handler

void addHotKey(string key,function handler, [object obj] );

Parameters

key | string | string with the key name
handler | function | the hot key handler
obj | object | if provided, the handler will fire only when focus is in the target view

Example

//global key handler
webix.UIManager.addHotKey("up", my_function);

//activates the handler only when focus is inside of myview
webix.UIManager.addHotKey("ctrl-up", my_function, myview);


applyChanges

triggers onChange handlers for active component

void applyChanges();

Example

webix.UIManager.applyChanges();

Details

Can be used to ensure that form data is saved before calling the action.


canFocus

checks whether the view can be focused

boolean canFocus(id id);

Parameters

id id the id of the view in question

Returns

boolean true if the specified view can take focus. Otherwise, false

Example

webix.UIManager.canFocus($$('books'));

Details

The function helps single out currently disabled and hidden views on the page. They cannot take focus and should be enabled (shown back) to acquire focusing ability.

See also

  • api
    • isVisible
    • isEnabled


destructor

Destructor. Destroys the UIManager instance

void destructor();

Example

webix.UIManager.destructor();


getFocus

retrieves the view which has focus

WebixView getFocus();

Returns

WebixView the view object

Example

var obj = webix.UIManager.getFocus();
obj.define('width', 300); //to resize the view in focus

See also

  • api
    • setFocus


getNext

gets the next view in the focus|tab order

object getNext(object view);

Parameters

view object the current view

Returns

object the next view


getPrev

gets the previous view in the focus|tab order

object getPrev(object view);

Parameters

view object the current view

Returns

object the previous view


getState

retrieves the current state of the specified view

object getState(string id,boolean childs);

Parameters

id | string | the view id
childs | boolean | defines whether the state object besides configuration of the specified view should contain configuration of its childs. By default - false

Returns

object the state object

Available only in PRO Edition

Example

webix.UIManager.getState("mylayout", true);

Details

The state object reflects UI configuration of the specified view.

And it looks as in:

{
    gravity: 1
    height: 0 //returns 0 if the property isn't specified
    id: "myview"
    width: 0
}

The get/setState methods of the UIManager class is similar to the same-name methods from the DataState class.

The difference lies in the following: the UIManager methods allows you to save and restore outer visual scheme (layout) of the specified view (that allows restoring general view structure) while the DataState methods save ans restore the information about inner configuration of the view (selection, sorting direction etc.).

See also

  • api
    • setState
    • DataState


getTop

returns the top-most parent to the specified view

object getTop(id id);

Parameters

id id the ID of the view in question

Returns

object the top-most parent object of the view

Example

webix.UIManager.getTop($$('books'));


hasFocus

checks whether the specified view has focus

boolean hasFocus(id id);

Parameters

id id the ID of the view to check

Returns

boolean true, the view is in focus. Otherwise, false.

Example

webix.UIManager.hasFocus($$('books'));


removeHotKey

removes the hot key handler

void removeHotKey(string key, [function handler,object obj] );

Parameters

key | string | string with the key name
handler | function | the hot key handler
obj | object | if provided, the handler will fire only when focus is in the target view

Example

//removes ALL
webix.UIManager.removeHotKey("up");

//removes One
webix.UIManager.removeHotKey("up", my_function);

//removes One for specific view
webix.UIManager.removeHotKey("up", null, $$("button"));


setFocus

sets focus to the specified view

void setFocus(id id);

Parameters

id id ID of the view to set focus to

Example

webix.UIManager.setFocus($$('books'));

See also

  • api
    • getFocus


setState

restores the specified state

void setState(object state);

Parameters

state object the state object

Available only in PRO Edition

Example

webix.storage.local.put("state", webix.UIManager.getState("mylayout", true));
...

var state = webix.storage.local.get("state");
if (state)
    webix.UIManager.setState(state);

Details

The state object reflects UI configuration of the specified view.

The get/setState methods of the UIManager class is similar to the same-name methods from the DataState class.

The difference lies in the following:

  • the UIManager methods allows you to save and restore outer visual scheme (layout) of the specified view (that allows restoring general view structure);
  • the DataState methods save and restore the information about inner configuration of the view (selection, sorting direction etc.).

See also

  • api
    • getState
    • DataState


Undo

Allows reverting changes in data for datastore-based components.

Methods
ignoreUndo | calls a function that will be ignored in the undo history track
removeUndo | removes history about all the operations made to an item
undo | reverts the previously made change in the component
Properties
undo enables reverting changes in data components


Methods

ignoreUndo | calls a function that will be ignored in the undo history track
removeUndo | removes history about all the operations made to an item
undo | reverts the previously made change in the component


ignoreUndo

calls a function that will be ignored in the undo history track

void ignoreUndo(function function);

Parameters

function function function for which undo history track will be disabled

Example

// item adding won't be reverted by undo()
$$("list").ignoreUndo(function(){
    $$("list").addItem({...});
});

See also

  • api
    • removeUndo
    • undo
    • undo
  • articles
    • Undo for Data Components


removeUndo

removes history about all the operations made to an item

void removeUndo(string id);

Parameters

id string the id of an item

Example

list.removeUndo(id);

See also

  • api
    • ignoreUndo
    • undo
    • undo
  • articles
    • Undo for Data Components


undo

reverts the previously made change in the component

void undo(string id);

Parameters

id string optional, the id of an item. All the changes made to the item will be undone

Example

list.undo();

See also

  • api
    • removeUndo
    • ignoreUndo
    • undo
  • articles
    • Undo for Data Components


Properties

undo enables reverting changes in data components


undo

enables reverting changes in data components

boolean undo;

Example

webix.ui({
    view:"list",
    id:"mylist",
    template:"#title#",
    data:dataset
    undo:true
});

See also

  • api
    • removeUndo
    • undo
    • ignoreUndo
  • articles
    • Undo for Data Components


UploadDriver

Implements file uploader driver.

Other
flash | flash based uploader, used as fallback for html5 one
html5 | HTML5 uploader logic


Others

flash | flash based uploader, used as fallback for html5 one
html5 | HTML5 uploader logic


flash

flash based uploader, used as fallback for html5 one

object flash;
Details

Not purposed for direct usage. Uploader view will use flash uploader if html5 one is not supported


html5

HTML5 uploader logic

object html5;
Details

One of possible upload drivers


ValidateCollection

Implements validation for data collections.

Methods
clearValidation | removes all validation marks from the component
validate | validates one record or all dataset against validation rules
Events
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
Properties
rules set of validation rules for the component


Methods

clearValidation | removes all validation marks from the component
validate | validates one record or all dataset against validation rules


Properties

rules set of validation rules for the component


Events

onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully


ValidateData

Data validation logic.

Methods
clearValidation | removes "data incorrect" highlighting from invalid text fields
validate | checks data in the form
Events
onAfterValidation | fires after data has been validated
onBeforeValidate | called before running validation
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully
Properties
rules defines a set of rules for input field(s) of the form(htmlform)


Methods

clearValidation | removes "data incorrect" highlighting from invalid text fields
validate | checks data in the form


Properties

rules defines a set of rules for input field(s) of the form(htmlform)


Events

onAfterValidation | fires after data has been validated
onBeforeValidate | called before running validation
onValidationError | fires when the form fails to pass validation
onValidationSuccess | fires after the form has passed validation successfully


ValueBind

Binding logic for single value components.


Values

Manupilates values of the form and form fields.

Methods
clear | clears all the field in a specified form
focus | sets focus into the necessary component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getValues | derives input values from the form
isDirty | checks whether changes within form were made
markInvalid | marks a form control invalid
setDirty | marks the form as the one with changed values and vice versa
setValues | sets values into the inputs of a form/toolbar/property sheet control
Events
onAfterLoad | fires after server side loading is complete
onChange | fires when data in the input or related form/toolbar is changed
onValues | fires after values have been set within toolbar or form
Properties
complexData enables complex data parsing mode


Methods

clear | clears all the field in a specified form
focus | sets focus into the necessary component
getCleanValues | returns hash of original form values
getDirtyValues | returns hash of changed values
getValues | derives input values from the form
isDirty | checks whether changes within form were made
markInvalid | marks a form control invalid
setDirty | marks the form as the one with changed values and vice versa
setValues | sets values into the inputs of a form/toolbar/property sheet control


Properties

complexData enables complex data parsing mode


Events

onAfterLoad | fires after server side loading is complete
onChange | fires when data in the input or related form/toolbar is changed
onValues | fires after values have been set within toolbar or form


VirtualRenderStack

Allows on-demand rendering for plain datasets.

Methods
getItemNode | returns HTML element of the item
render | renders the specified item or the whole component
showItem | scrolls the component to make the specified item visible
Events
onAfterRender | occurs immediately after the component has been rendered
onBeforeRender | occurs immediately before the component has been rendered
Properties
datafetch | defines the number of records that will be loaded during each dynamic loading request
loadahead | how the number of records that need to be loaded in addition to mandatory ones during each dynamic loading request


Methods

getItemNode | returns HTML element of the item
render | renders the specified item or the whole component
showItem | scrolls the component to make the specified item visible


Properties

datafetch | defines the number of records that will be loaded during each dynamic loading request
loadahead | how the number of records that need to be loaded in addition to mandatory ones during each dynamic loading request


Events

onAfterRender | occurs immediately after the component has been rendered
onBeforeRender | occurs immediately before the component has been rendered


ui.baselayout

A base class for layout-based UI components.

The component serves as the base class that defines properties, methods, and events common for all layout-based components. Not intended for direct use. If you need to create a layout, please use (ui.layout)[ui.layout] or its descendants.

Constructor

    var baselayout = webix.ui({
        view:"baselayout",
        container:"mydiv",
        ...config options goes here..
    })
    //or, in case of jQuery
    $("#mydiv").webix_baselayout({
        ...config options goes here..
    });
Based on: EventSystem, ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
addView | add new view to layout-like component
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hasEvent | checks whether the component has the specified event
hide | hides the view
index | returns the cell index in the layout collection
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
mapEvent | routes events from one object to another
reconstruct | rebuilds the layout
removeView | removes view from layout-like component
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
show | makes the component visible
showBatch | makes visible those elements which parameter 'batch' is set to the specified name
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
cols | array of views objects arranged horizontally
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
responsive | enables responsive mode for horizontal layout
rows | array of views objects arranged vertically
visibleBatch | sets the batch that will be shown initially
width | sets the width of the component


ui.baseview

The very base object for all components.

The component serves as the base class that defines properties, methods, and events common for all other components that make up the library. Not intended for direct use.

Constructor

    var baseview = webix.ui({
        view:"baseview",
        container:"mydiv",
        ...config options goes here..
    })
    //or, in case of jQuery
    $("#mydiv").webix_baseview({
        ...config options goes here..
    });
Based on: Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
Events
onBindRequest | fires when the component is ready to receive data from the master component
onDestruct | occurs when component destroyed
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.checksuggest

A suggest control with a multiple-choice list.

Offers select options in the form of Webix list component equipped with checkboxes. Features the ability to select multiple items at a time.

Can be used standalone or as a suggest list for text, combo and richselect controls as well as component editors. Is used by a multiselect control already.

Based on: ui.multisuggest, ui.suggest, ui.popup, ui.window, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, Movable, Modality, EventSystem
Methods
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
close | removes a window
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getBody | gets the ui view of the window body
getButton | get button object of a multiselect popup
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getHead | gets the ui view of the window header
getItemText | returns rendered text of suggest's item
getList | returns inner data control from suggest
getMasterValue | returns current value of master control
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getSuggestion | returns id of top suggestion from the suggest list
getTopParentView | returns top parent view
getValue | gets the ID of a selected item in the option list
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
linkInput | links a suggest list to an input field
mapEvent | routes events from one object to another
resize | adjusts the view to a new size
resizeChildren | resizes all children of the calling component
setMasterValue | set value in master control
setPosition | sets window's position
setValue | selects an item in the option list
show | makes the component visible
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onAfterScroll | occurs when some webix view has been scrolled
onBeforeShow | fires right after show() method is called for the window (popup) and before the window is shown
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onHide | fires when window is hidden
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onShow | fires when window is shown
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValueSuggest | some item selected in the suggest control
onViewMove | fires while view is moving
onViewMoveEnd | fires when view has stopped moving
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
autofit | adjusts window size to the size of an html node it is initiated in
autofocus | sets focus on the window the moment it appears on the page
body | the content of window body: template or view
borderless | used to hide the component borders
button | sets a button at the bottom of the suggest
buttonText | defines text for the 'Select' button
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
filter | custom filtering function
fitMaster | size suggest box to the master control
gravity | sets the view gravity (1 by default)
head | sets the view header
headHeight | defines the header height (43 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
input | points to an HTML input field that houses the suggest list
keyPressTimeout | time between key pressing and filtering start
left | the left offset of the window
master | reference to the master view
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
modal | switches window modality
move | makes view movable
on | allows attaching custom handlers to inner events of the component
padding | sets paddings of the chart content
position | sets position of the window relative to the the screen
relative | positions a popup window relative to the component it's connected with
resize | enables/disables window resizing
separator | sets a delimiter for multisuggest values
template | template which will be used to fill parent input from selected record
textValue | defines which field from suggest list will be used as text after selecting an option
toFront | places window above other windows on clicking it
top | the top offset of a window
type | defines type of suggest control
value | sets the initial value for a control
width | sets the width of the component
zIndex | stack order of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.proto

The very base class for UI components.

The class defines properties, methods, and events related to loading and rendering data. Can serves as the base class while creating custom multi-item components. Not intended for direct initialization.

Constructor

    var proto = webix.ui({
        view:"proto",
        container:"mydiv",
        ...config options goes here..
    })
    //or, in case of jQuery
    $("#mydiv").webix_proto({
        ...config options goes here..
    });
Based on: PagingAbility, DataMarks, AutoTooltip, ValidateCollection, RenderStack, DataLoader, DataStore, AtomDataLoader, ui.view, ui.baseview, Settings, Destruction, BaseBind, UIExtension, EventSystem
Methods
add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getTopParentView | returns top parent view
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules
Events
onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
click | sets an action happening on a button click
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
template | the component template
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
type | set of properties and helpers for item rendering
types | collection of possible types


Methods

add | adds an item to the store
addCss | applied CSS class to a component item
adjust | adjusts the component to the size of the parent HTML container
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
bind | binds components
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
clearAll | removes all items from the component
clearCss | removes css class from all items
clearValidation | removes all validation marks from the component
count | returns the number of currently visible items
customize | redefines the "type" property
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
exists | checks whether an item with the specified id exists
filter | filters the component
find | returns rows that match the criterion
getChildViews | returns child views of the calling component
getFirstId | returns the ID of the first item
getFormView | returns master form for the input
getIdByIndex | returns the id of the item with the specified index
getIndexById | returns the index of the item with the specified id
getItem | gets the object of the data item with the specified id
getItemNode | returns HTML element of the item
getLastId | returns the id of the last item
getNextId | returns the ID of an item which is positioned the specified step after the specified item
getNode | returns the main HTML container for the calling object
getPage | returns the currently visible page in case of paged view
getPager | returns the pager object associated with the component
getParentView | returns the parent view of the component
getPrevId | returns the ID of an item which is positioned the specified step before the specified item
getTopParentView | returns top parent view
hasCss | checks if item has specific css class
hasEvent | checks whether the component has the specified event
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
load | loads data from an external data source.
loadNext | sends a request to load the specified number of records to the end of the clientside dataset or to the specified position
locate | gets the id of an item from the specified HTML event
mapEvent | routes events from one object to another
parse | loads data to the component from an inline data source
refresh | repaints the whole view or a certain item
remove | removes the specified item/items from datastore
removeCss | removes CSS class from a component item
render | renders the specified item or the whole component
resize | adjusts the view to a new size
serialize | serializes data to a JSON object
setPage | makes the specified page visible (assuming that the pager was defined )
show | makes the component visible
showItem | scrolls the component to make the specified item visible
sort | sorts datastore
sync | allows syncing two copies of data (all or just a part of it) from one DataCollection to another
unbind | breaks "bind" link
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
updateItem | sets properties of the data item
validate | validates one record or all dataset against validation rules


Properties

animate | defines or disables view change animation.
borderless | used to hide the component borders
click | sets an action happening on a button click
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
data | JavaScript array containing data for the component
datathrottle | sets the polling interval (the time period between the completion of a network request and the next request for data)
datatype | the type of loaded data
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
on | allows attaching custom handlers to inner events of the component
pager | defines paging configuration ( creates a 'ui.pager' object)
ready | event handler called just after the component has been completely initialized
removeMissed | defines how to treat items in case of reloading
rules | set of validation rules for the component
save | defines URLs for data saving
scheme | defines schemes for data processing
template | the component template
tooltip | sets a popup message appearing on pointing a mouse cursor over the dedicated item.
type | object that specifies items presentation
url | the URL which the component will use to load data after its initialization
width | sets the width of the component


Events

onAfterAdd | fires after adding item to datastore
onAfterDelete | fires after item deleting
onAfterLoad | fires after data loading is complete
onAfterRender | occurs immediately after the component has been rendered
onAfterScroll | occurs when some webix view has been scrolled
onAfterSort | fires after sorting dataset
onBeforeAdd | fires before adding item to datastore
onBeforeDelete | fires before item deleting
onBeforeLoad | occurs immediately before data loading has been started
onBeforeRender | occurs immediately before the component has been rendered
onBeforeSort | fires before sorting dataset
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDataRequest | fires when data from the server is requested for linear data structures (List, DataTable, DataView etc.) to implement dynamic data loading
onDataUpdate | fires when data item is in update process
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onItemRender | for each item rendering, occurs only for items with custom templates
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLoadError | fires when an error occurs during data loading ( invalid server side response )
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onValidationError | fires when newly loaded/added/edited data fails to pass validation
onValidationSuccess | fires after the newlyloaded/added/edited data has passes validation successfully
onViewResize | view size was changed by resizer


Others

$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)
type | set of properties and helpers for item rendering
types | collection of possible types


ui.resizearea

Visualization and handling resize movements.

Not purposed for direct initialization. Check Ui.resizearea. Common tips article for more detailed description.

Constructor

    var resizearea = webix.ui({
        view:"resizearea",
        container:"mydiv",
        ...config options goes here..
    })
    //or, in case of jQuery
    $("#mydiv").webix_resizearea({
        ...config options goes here..
    });
Based on: EventSystem, Settings
Methods
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
hasEvent | checks whether the component has the specified event
mapEvent | routes events from one object to another
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onResize | occures when the user moves the 'resize' cursor
onResizeEnd | occures when the user ends moving the 'resize' cursor (releases the mouse button)
Properties
border | enables border around resize area
container | html element to which area will be attached
cursor | which cursor to show during resize
dir | sets the direction of resizing
eventPos | the top (vertical resizing) or left (horizontal resizing) absolute event position
height | vertical size of resizing area
id | the component ID
on | allows attaching custom handlers to inner events of the component
start | sets the top (vertical resizing) or left (horizontal resizing) initial relative position of the 'resize' marker
width | horizontal size of resizing area
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
hasEvent | checks whether the component has the specified event
mapEvent | routes events from one object to another
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


Properties

border | enables border around resize area
container | html element to which area will be attached
cursor | which cursor to show during resize
dir | sets the direction of resizing
eventPos | the top (vertical resizing) or left (horizontal resizing) absolute event position
height | vertical size of resizing area
id | the component ID
on | allows attaching custom handlers to inner events of the component
start | sets the top (vertical resizing) or left (horizontal resizing) initial relative position of the 'resize' marker
width | horizontal size of resizing area


border

enables border around resize area

boolean border;

Example

webix.ui({
    view:"resizearea",
    border:true
})


container

html element to which area will be attached

string|HTMLElement container;

Example

webix.ui({
    view:"resizearea",
    container:"mydiv"
})


cursor

which cursor to show during resize

string cursor;

Example

webix.ui({
    view:"resizearea",
    cursor:"move"
})


dir

sets the direction of resizing

string dir;

Example

var resizeStick = new webix.ui.resizearea({
        container:"box",
        dir:"x",
        ...
});

See also

  • api
    • eventPos
    • dir
    • start
    • Details

    The parameter can take only one of a predefined set of values.
    The predefined values are:

    • 'x' - horizontal resizing
    • 'y' - vertical resizing


eventPos

the top (vertical resizing) or left (horizontal resizing) absolute event position

number eventPos;

Example

var parentContainer = document.getElementById("resizeDiv");

webix.event(parentContainer,"mousedown",function(e){

  var resizeStick = new webix.ui.resizearea({
       container:parentContainer,
       dir:"y",
       eventPos:webix.html.pos(e).y,
       height: 5,
       start:webix.html.pos(e).y-webix.html.offset(parentContainer).y,
       width: parentContainer.offsetWidth,
   });

})

See also

  • api
    • start
    • dir
    • html
    • Details

    Setting a pure number value doesn't make any sense.


height

vertical size of resizing area

number height;

Example

webix.ui({
    view:"resizearea",
    width:600, height:200
})


start

sets the top (vertical resizing) or left (horizontal resizing) initial relative position of the 'resize' marker

number start;

Example

var resizeStick = new webix.ui.resizearea({
        container:"box",
        dir:"x",
        start:240,
        ...
});

See also

  • api
    • eventPos
    • dir
    • html
    • Details

    The code example below allows you to coincide the 'resize' marker and event positions:

    • webix.html.pos(e).y - the vertical event position (y-coordinate of a point where the event occures)
    • webix.html.offset(parentContainer).y - the y-coordinate of the top left corner of the parent container
    var parentContainer = document.getElementById("resizeDiv");

webix.event(parentContainer,"mousedown",function(e){
     res = new webix.ui.resizearea({
           container:parentContainer,
           dir:"y",
           eventPos:webix.html.pos(e).y,
           height: 5,
           start:webix.html.pos(e).y-webix.html.offset(parentContainer).y,
           width: parentContainer.offsetWidth,
           border: 1
     });
})


width

horizontal size of resizing area

number width;

Example

webix.ui({
    view:"resizearea",
    width:600, height:200
})


Events

onResize | occures when the user moves the 'resize' cursor
onResizeEnd | occures when the user ends moving the 'resize' cursor (releases the mouse button)


onResize

occures when the user moves the 'resize' cursor

void onResize(number pos){ ... };

Parameters

pos number the top (vertical resizing) or left (horizontal resizing) relative position of the cursor (relative to the parent container)

Example

some.attachEvent("onResize", function(pos){
    //... some code here ...
});


onResizeEnd

occures when the user ends moving the 'resize' cursor (releases the mouse button)

void onResizeEnd(number pos){ ... };

Parameters

pos number the top (vertical resizing) or left (horizontal resizing) relative position of the cursor (relative to the parent container)

Example

some.attachEvent("onResizeEnd", function(pos){
    //... some code here ...
});


ui.view

A pure view with borders but without any content inside it.

The component serves as the base class that defines properties, methods, and events common for not layout-based UI components. Can be used as the placeholder in a layout. Check view documentation for more detailed description.

Constructor

    var view = webix.ui({
        view:"view",
        container:"mydiv",
        ...config options goes here..
    })
    //or, in case of jQuery
    $("#mydiv").webix_view({
        ...config options goes here..
    });
Based on: ui.baseview, Settings, Destruction, BaseBind, UIExtension
Methods
adjust | adjusts the component to the size of the parent HTML container
bind | binds components
define | redefines a single configuration property (or a hash of properties)
destructor | destructs the calling object
disable | disables the calling view (makes it dimmed and unclickable)
enable | enables the calling view that was disabled by the 'disable' method
getChildViews | returns child views of the calling component
getFormView | returns master form for the input
getNode | returns the main HTML container for the calling object
getParentView | returns the parent view of the component
getTopParentView | returns top parent view
hide | hides the view
isEnabled | checks whether the view is enabled
isVisible | checks whether the view is visible
resize | adjusts the view to a new size
show | makes the component visible
unbind | breaks "bind" link
Events
onAfterScroll | occurs when some webix view has been scrolled
onBindRequest | fires when the component is ready to receive data from the master component
onBlur | fires when focus is moved out of the view
onDestruct | occurs when component destroyed
onFocus | fires when a view gets focus
onKeyPress | occurs when keyboard key is pressed for the control in focus
onLongTouch | fires on holding finger in some position for a certain period of time
onSwipeX | occurs on a horizontal swipe movement
onSwipeY | occurs on a vertical swipe movement
onTimedKeyPress | fires after typing has been finished in the field
onTouchEnd | occurs when the touch event is ended
onTouchMove | occurs during touch movement
onTouchStart | when some webix view has been touched
onViewResize | view size was changed by resizer
Properties
animate | defines or disables view change animation.
borderless | used to hide the component borders
container | an html container (or its id) where the component needs initializing
css | the name of a css class that will be applied to the view container
disabled | indicates whether an item is enabled or not
gravity | sets the view gravity (1 by default)
height | sets the height of the component
hidden | defines whether the view will be hidden initially
id | the component ID
maxHeight | sets the maximum height for the view
maxWidth | sets the maximum width for the view
minHeight | sets the minimal height for the view
minWidth | sets the minimal width for the view
width | sets the width of the component
Other
$getSize | returns the current size of the component
$height | current height of the view
$scope | scope for resolving event and method names
$setSize | sets the component size
$skin | the method which will be called when skin is defined
$view | reference to top html element of the view
$width | current width of the view
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


ui.vscroll

Virtual scrolls.

The component renders plain scrolls without content.

Constructor

    var vscroll = webix.ui({
        view:"vscroll",
        container:"mydiv",
        ...config options goes here..
    })
    //or, in case of jQuery
    $("#mydiv").webix_vscroll({
        ...config options goes here..
    });
Based on: EventSystem, Settings
Methods
activeArea | assigns active mouse wheel zone
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
getScroll | return current state of scroller
getSize | returns full scrollable size ( scrollWidth or scrollHeight of content )
hasEvent | checks whether the component has the specified event
mapEvent | routes events from one object to another
scrollTo | set new position of scroller
sizeTo | set new size of scrollable content ( scrollWidth or scrollHeight )
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command
Events
onScroll fires when the scroll changes its position
Properties
container | an html container (or its id) where the component needs initializing
id | the component ID
on | allows attaching custom handlers to inner events of the component
scroll | the direction of scrolling
scrollHeight | the scrolling height of the object (vertical scrolling)
scrollPos | the top (vertical scrolling ) or left (horizontal scrolling) offset of the scroll.
scrollSize | the width(vertical scrolling) or height(horizontal scrolling) of the scroll
scrollStep | the number of items that will be scrolled on each mouse move
scrollVisible | defines visibility of scroll
scrollWidth | the scrolling width of the object (horizontal scrolling)
zoom | the zoom of the total scroll bar length
Other
config | all options from initial component configuration
name | indicates the name of the component (a read-only property)


Methods

activeArea | assigns active mouse wheel zone
attachEvent | attaches the handler to an inner event of the component (allows behaviour customizations)
blockEvent | temporarily blocks triggering of ALL events of the calling object
callEvent | calls an inner event
define | redefines a single configuration property (or a hash of properties)
detachEvent | detaches a handler from an event (which was attached before by the attachEvent method)
getScroll | return current state of scroller
getSize | returns full scrollable size ( scrollWidth or scrollHeight of content )
hasEvent | checks whether the component has the specified event
mapEvent | routes events from one object to another
scrollTo | set new position of scroller
sizeTo | set new size of scrollable content ( scrollWidth or scrollHeight )
unblockEvent | cancels blocking events that was enabled by the 'blockEvent' command


activeArea

assigns active mouse wheel zone

void activeArea(HTMLElement node);

Parameters

node HTMLElement DOM element mouse actions over which will be counted as scrolling


getScroll

return current state of scroller

number getScroll();

Returns

number position of scroller

Example

var x = scroll.getScroll();


getSize

returns full scrollable size ( scrollWidth or scrollHeight of content )

number getSize();

Returns

number full scrollable size ( scrollWidth or scrollHeight of content )

Example

var size = scroll.getSize();


scrollTo

set new position of scroller

void scrollTo(number pos);

Parameters

pos number the position of scroller

Example

scroll.scrollTo(150);


sizeTo

set new size of scrollable content ( scrollWidth or scrollHeight )

void sizeTo(number size);

Parameters

size number the size of scrollable content

Example

scroll.setSize(400);


Properties

container | an html container (or its id) where the component needs initializing
id | the component ID
on | allows attaching custom handlers to inner events of the component
scroll | the direction of scrolling
scrollHeight | the scrolling height of the object (vertical scrolling)
scrollPos | the top (vertical scrolling ) or left (horizontal scrolling) offset of the scroll.
scrollSize | the width(vertical scrolling) or height(horizontal scrolling) of the scroll
scrollStep | the number of items that will be scrolled on each mouse move
scrollVisible | defines visibility of scroll
scrollWidth | the scrolling width of the object (horizontal scrolling)
zoom | the zoom of the total scroll bar length


scroll

the direction of scrolling

string scroll;

Example

webix.ui.vscroll({
        container:"scroll_here",
        scrollHeight:500,
        scroll:"y"
});

Details

The parameter can take only one of a predefined set of values.
The predefined values are:

  • 'y' - vertical scrolling
  • 'x' - horizontal scrolling (the default value)


scrollHeight

the scrolling height of the object (vertical scrolling)

number scrollHeight;

Example

webix.ui.vscroll({
        container:"scroll_here",
        scrollHeight:500,
        scroll:"y"
});

See also

  • api
    • scroll


scrollPos

the top (vertical scrolling ) or left (horizontal scrolling) offset of the scroll.

number scrollPos;

Example

webix.ui.vscroll({
        container:"scroll_here",
        scrollPos:60
});

Details

The default value - 0


scrollSize

the width(vertical scrolling) or height(horizontal scrolling) of the scroll

number scrollSize;

Example

webix.ui.vscroll({
        container:"scroll_here",
        scrollSize:25
});

Details

The default value - 18px.


scrollStep

the number of items that will be scrolled on each mouse move

number scrollStep;

Example

webix.ui.vscroll({
        container:"scroll_here",
        scrollStep:10
});

Details

The default value - 40


scrollVisible

defines visibility of scroll

boolean scrollVisible;
Details

Visible by default


scrollWidth

the scrolling width of the object (horizontal scrolling)

number scrollWidth;

Example

webix.ui.vscroll({
        container:"scroll_here",
        scrollWidth:500
});

See also

  • api
    • scroll


zoom

the zoom of the total scroll bar length

number zoom;

Example

webix.ui.vscroll({
        container:"scroll_here",
        zoom:10
});

Details

Let's consider an example.
You have 30 records within the container with the height of 10px, each item takes 1px height. By default (zoom=1), the total length of the scroll bar is calculated automatically to display all the items, i.e. we get 30 x 1px = 30px.
If the user scrolls 2px down - the 11th and 12th records will be displayed.

That's so, but when you deal with big datasets the total length of the scroll bar can be incrediable large. Therefore, the component won't take the really required length but take maximum available and set the zoom parameter. In that case, each time the user makes a scroll move, the component will count the scrolled length and multiply it by zoom to get the real number of items to scroll.


Events

onScroll fires when the scroll changes its position


onScroll

fires when the scroll changes its position

void onScroll(number pos){ ... };

Parameters

pos number the scroll position

Example

var myScroll = new webix.ui.vscroll({
        container:"scroll_here",
        scrollWidth:800
});

myScroll.attachEvent('onScroll',function(pos){ alert(pos)});


Start

Migration to latest Webix version

Webix 3.2 -> 3.3

Data Export to PDF

In version 3.3 the header property is introduced in PDF export config. It is used to configure the look of header of an exported table.

To avoid ambiguity, the header and headerImage properties related to the document's header were renamed:

  • header is replaced with docHeader
  • headerImage is replaced with docHeaderImage

Changes in the webix.event helper

The context parameter of the webix.event helper was modified. Earlier it indicated an object to which this keyword refers (master). Now it awaits a context object with master, capture and id properties.

Webix 3.1 -> 3.2

Export API

Old export functionality of Datatable and Pivot is removed in version 3.2.

The methods exportToPDF() and exportToExcel() of Datatable and the methods toPDF() and toExcel() of Pivot are no longer available. You should use common methods toPDF and toExcel for these components instead:

webix.toPDF($$("myPivot"));

webix.toExcel($$("myDatatable"));

Loading Excel files into data components

The "excel" proxy was removed.

Instead, the "binary" proxy object is used to load files like Excel into data components and the "excel" datatype is introduced for parsing Excel files. It is the default datatype for Excel Viewer.

webix.ui({
    view:"spreadsheet",
    url: "binary->../common/test.xlsx@Data[0-10]",
    datatype:"excel"
});

Webix 3.0 -> 3.1

Form validation

Starting from version 3.1, form.validate() will not validate disabled fields. If you want to preserve the old behavior, use this command like next

form.validate({ disabled:true });

Webix 2.x -> 3.0

Strict JSON parsing

Starting from the version 3.0 strict JSON parsing rules are applied. It means that Webix won't process invalid JSON data.

Export API

Version 3.0 includes new export API. Old export functionality of datatable is deprecated and will be fully removed in version 3.2

Serverside response for Uploader

The expected format of JSON string returned by the uploading script has changed. Now the script should respond with "error" status to indicate that uploading ended with error:

echo "{ status:'error' }";

Any other response, e.g. "{status:'server'}" means that uploading ended successfully.

Webix 2.2 -> 2.3

Parse format

In version 2.2 the default parseFormat was "%Y-%m-%d" while from version 2.3 it becomes "%Y-%m-%d %H:%i".

It can be altered within current locale as:

webix.i18n.parseFormat = "%Y-%m-%d";
webix.i18n.setLocate();

Sizing in layout

In Webix 2.2 layout height and width were including padding and margin

//in Webix 2.2 will result in 140px height ( 20 + 100 + 20)
//in Webix 2.3 will result in 100px height
webix.ui({
    view:"layout", padding:20, height:100, rows:[{}]
})

In webix 2.3 size of layout is a full size, that already includes padding and margin. The same code as above one will result in layout with 100px height. If you preffer the old behavior, you can move height settings in the inner view

//in both Webix 2.2 and Webix 2.3 will result in 140px height
webix.ui({
    view:"layout", padding:20, rows:[{ height:100 }]
})

Webix 2.1 -> 2.2

Templates in datatable

In version 2.1 you could use "#value#" in the column's template to apply the same property that was defined as the column's id.

Version 2.2 will support this feature as well, but you need to use "#$value#" instead of the old syntax. It does affect only the "#value#" keyword, all other templates ("#some#") will work without any changes.

Ajax

ajax.header method was deprecated in favor of ajax.headers

Sizing

Starting from Webix 2.2, list, datataview and template view, width and height of container will include the width of scrollbar. It means that the resulting view will take exactly the same size that was defined for it (previously, it was the defined as:"size + size of scrollbar").

Webix 1.x -> 2.0

Number formating

"decimalDelimeter" property in number format was changed to "decimalDelimiter"

DHTMLX Touch -> Webix 2.0

Please check Migraton from DHTMLX Touch.


Migration from DHTMLX Touch

If you want to migrate to the Webix library, you should include two additional libraries: touchui_migration.js and touchui_migration.css, and also you can make the changes described in this article if they are needed:

You can grab those files by the next link

Data Components

(DataStore, Lists, Grid, Dataview, Chart)

The definition of sorting/grouping in the view configuration was changed. You need to use the scheme property and the field name without "#". For complex templates use functions

Old usage

dhx.ui({
    sort: "#name#"
});

New usage

webix.ui({
    scheme:{
        $sort: {
            by:"name"
        }
    }
});

Grouplist

"Back" items already contain the "<" icon by default. The templateBack property requires defining the text of a "back" item only

Old usage

templateBack:"&lt; #title#",

New usage

templateBack:"#title#",

DataProcessor

The onDBerror event is not supported any more. Use the onAfterSaveError event instead

Old usage

dp.attachEvent("onDBerror",function(response, state){
 ...
})

New usage

dp.attachEvent("onAfterSaveError",function(id,status,obj,details){
var state = dp.getItemState(id);
...
});

Window and Layout

Layout and related

Full screen layout considers the sizes of inner views and can have smaller sizes than document body. For example, if all rows of layout have fixed height, the layout's height will be calculated like a sum of these rows' heights. So, if you want your layout to occupy the whole page and to consist of rows/cols with fixed height, you should add a row/col without height/width specified.

Old usage

dhx.ui({
    rows:[
       {view: "text", ...}
    ]
});

New usage

webix.ui({
    rows:[
        {view: "text", ...},
        {}
    ]
});

Window

Now window is hidden by default. To show it, call the show method.

Old usage

dhx.ui({
    view: "window",...
});

New usage

webix.ui({
    view: "window",...
}).show();

Tabbar, Segmented,Radio, Richselect, Combo

We should use "id" to define options keys instead of "value" and "value" to define titles instead of "label"

Old usage

options: [
     {value: 1, label: "Option 1"}, ...
]

New usage

options: [
     {id: 1, value: "Option 1"}, ...
]

Tabbar

1) Tabbar has a new property tabMinWidth. It sets minimum width of tabbar buttons, the value is 100 by default. Options that do not fit will be put in a popup. This popup is displayed by clicking the "..." icon.

{view:"tabbar", tabMinWidth:90,...}

2) Parameters of the onBeforeTabClick and onAfterTabClick events were changed. Now event handlers take two paremeters: id of the clicked option and the native event object

Old usage

$$("tabbar").attachEvent("onAfterTabClick",
 function(tabbarId, optionId) {
..
});

New usage

$$("tabbar").attachEvent("onAfterTabClick",
function(optionId, event) {
..
});

Tabbar, Segmented

Use the "value" property instead of the "selected" one to set a button's value

Old usage

{ view: "tabbar" , selected: 2, ...}

New usage

{ view: "tabbar" , value: 2, ..}

Richselect, Combo

1) Use the "suggest" view instead of the "popup" one to define a custom popup in Richselect and Combo

Old usage

dhx.ui({
      view: "popup",
      id: "comboOptions",
      body:{ view:"list"}
});
dhx.ui({
      view: "combo",
      popup:"comboOptions"
});

New usage

webix.ui({
    view: "suggest",
    id: "comboOptions",
    body:{ view:"list",...}
});
webix.ui({
     view: "combo",
     suggest:"comboOptions"
});

2) Use control.getPopup().getList() instead of $$(controlId+"_list") to get list

Old usage

var list = $$("myCombo_list")

New usage

var list = $$("myCombo").getPopup().getList();

Form and Toolbar

1) The method setValues sets values to elements by their "name" properties. The getValues method returns hash of values by elements' names. The previous version accepted "id" as well as "name". Now ids are ignored.

Old usage

dhx.ui({
    view: "form",
    id: "myform",
    elements:[
        { view: "text", name: "valueA", value: 1},
        { view: "text", id: "valueB", value: 2}
    ]
});

$$("myForm").getValues();
//same returns {valueA: 1, valueB:2}

New usage

webix.ui({
    view: "form",
    id: "myform",
    elements:[
        { view: "text", name: "valueA", value: 1},
        { view: "text", id: "valueB", value: 2}
    ]
});

$$("myForm").getValues(); // returns {valueA: 1}

2) If you set an event handler (for example, onItemClick, onBeforeTabClick) for controls to their parent Toolbar or Form, the handler will be called only for those elements that have the "name" property.

Old usage

dhx.ui({
    view: "toolbar",
    id: "myToolbar",
    elements:[
       { view: "button", id: "btn1", ...},
       { view: "button", id: "btn2", ...},
       ...
    ]
});

$$("myToolbar").attachEvent("onItemClick", function(id){
       alert("Clicked item is "+id);
});

New usage

webix.ui({
    view: "toolbar",
    id: "myToolbar",
    elements:[
       { view: "button", name: "btn1", ...},
       { view: "button", name: "btn2", ...},
       ...
    ]
});

$$("myToolbar").attachEvent("onItemClick", function(name){
       alert("Clicked item is "+name);
});

Toolbar

The "type" property is not supported

Old usage

{ view: "toolbar", type: "SubBar" ...}

New usage

{ view: "toolbar", ...}

Slider

Options are not supported. Use the min, step and max properties to define the range

Old usage

{ view:"slider", ...,
   options:[
   {value: 1, label: 1},
   {value: 2, label: 2},
   ....
]}

New usage

{ view:"slider", min: 1, step: 1, max: 10}

Autogenerated ids

If you did not set the id for a certain view, it will get the id in the following format: "$"+ViewName+ViewIndex

Old usage

// we create a list without id definition
dhx.ui({view: "list",....});
// the id is set automatically - list1 (list2,...)
$$("list1").select(id);

New usage

// we create a list without id definition
webix.ui({view: "list",....});
// the id is set automatically - $list1 ($list2,...)
$$("$list1").select(id);

webix.message()

(dhx.notice() in old version)

Use the "type" property instead of the "css" one to customize style of the message container

Old usage

dhx.notice(css: "error",...)

New usage

webix.message(type: "error",...)

Controls

Toggle

Toggle now looks and behaves like a two-state button. It is one button that changes its style and label on click. If you want to use a control that is similar to the toggle used in the previous version, you should choose the segmented button instead.

Old usage

{ view:"toggle", id:'trip', options: ["Roundtrip","Oneway"] }

New usage

{ view:"segmented", name:'trip', options: ["Roundtrip","Oneway"]}

Round button

Button with the type "round" is not supported any more

Old usage

{view:"button",type: "round",...}

New usage

{view:"button",...}

History

We need to use the track(id) method instead of the start() one and pass the id of the tracked element (id of tabbar for example)

Old usage

dhx.history.start()

New usage

webix.history.track('tabbarId')

webix.proxy

The new version requires a new proxy definition

Old usage

var proxy= new dhx.proxy({
    url: "data.php",
    storage: dhx.storage.local
});

New usage

var proxy = new webix.proxy( "local", "data.php" );

webix.Date

Some Date methods do not create a copy by default. If the copy parameter is not set to true, the passed Date object will be modified.

Old usage

var next = dhx.Date.add(d,1,"day");

New usage

var next = webix.Date.add(d,1,"day",true);


Additional Migration Changes

In this article you'll find the migration issues that are solved by including the touchui_migration.js file.

Data Components

(DataStore, Lists, Grid, Dataview, Chart)

Some datastore methods and methods of views that based on DataStore (list,grid,dataview and others) were renamed:

Old usage | New usage
var count = list.dataCount(); | var count = list.count();
var item = list.item(id); | var item = list.getItem(id);
list.update(id,data); | list.updateItem(id,data);
var index = list.indexById(id); | var index = list.getIndexById(id);
var id = list.idByIndex(index); | var id = list.getIdById(index);
var nextId = list.next(id,step); | var nextId = list.getNextId(id,step);
var firstId = list.first(); | var firstId = list.getFirstId();
var lastid = list.last(); | var lastId = list.getLastId();
var prevId = list.prev(id,step); | var prevId = list.getPrevId(id,step);
var id = list.getSelected(); | var id = list.getSelectedId();

Dataview

Selection is not enabled by default

Old usage

{view: "dataview", ...}

New usage

{view: "dataview", select: true,...}

Grouplist

In case of json datasource you should use the item property in it to define child collection (there was "data" before)

Old usage

//JSON data source:
{ id:"root", value:"top item", data:[ ... ]}

New usage

//JSON data source:
{ id:"root", value:"top item", item:[ ... ]}

Pagelist

Use the getActiveId() method instead of the getActive() one to get the id of the first visible item

Old usage

var id = $$("list").getActive();

New usage

var id = $$("list").getActiveId();

DataProcessor

If you are using connector on the server side, you should start definition of the url property of DataProcessor with "connector->"

Old usage

var dp = new dhx.DataProcessor({
     url:"update.php",
     ...
});

New usage

var dp = new webix.DataProcessor({
     url:"connector->update.php",
     ..
});

Views of Layout and Window

Use the getParentView() method instead of the getParent() one

Old usage

var parentView =  view.getParent()

New usage

var parentView = view.getParentView()

Window

By default window is hidden and doesn't have fixed size. Its size is adjusted to the size of its content. Window view appears in the left:0, top:0 position.

Old usage

Library sets by default for this view: top:300, left:100, width:300, height:200

New usage

Library sets by default for this view: top:0, left:0, autofit:true

Scrollview

Use the "body" property instead of the "content" one to define the inner view of Scrollview

Old usage

{
    view: "scrolview",...,
    content:{ view: "template",...}
}

New usage

{
    view: "scrolview",...,
    body:{ view: "template",...}
}

Tabbar

The default type of tabbar was changed. You should set the type:"bottom" if you want to show a tabbar below a multiview

Old usage

{ view:"tabbar", ...}

New usage

{ view:"tabbar", type: "bottom",...}

Multiview

Use the getActiveId() method instead of the getActive() one to get the id of an active view

Old usage

var id = $$("views").getActive();

New usage

var id = $$("views").getActiveId();

Datepicker and other cases

1) The default date format is set by the dhx.i18n.parseFormat. It is "%Y-%m-%d" by default.

Old usage

The default date format "%d.%m.%Y".

New usage

The default date format is "%Y-%m-%d".

2) Use the "value" property instead of the "date" one to define the control's value

Old usage

{ view:"datepicker", date:new Date(2014,7,1)}

New usage

{ view:"datepicker", value:new Date(2014,7,1)}

Message Boxes

notice

Use webix.message instead of dhx.notice

Old usage

dhx.notice(text)

New usage

webix.message(text)

webix.alert, webix.confirm, webix.message

Use the text property instead of the message one to define the popup text

Old usage

dhx.alert({message:'Incorrect password!"})

New usage

webix.alert({text:'Incorrect password!"})

Controls

Imagebutton

Use the view "button" with the type "image"

Old usage

dhx.ui({ view: "imagebutton", ...});

New usage

webix.ui({ view: "button", type: "image", ...});

Button

By default, a button's alignment is "left" ("center" in the previous version)

Old usage

dhx.ui({view:"button",inputWidth:100,..})

New usage

webix.ui({
view:"button",inputWidth:100, align:"center",...})

webix.KeyEvents

This module does not exist any more. The onTimedKeyPress event listening is enabled by default.

Old usage

dhx.extend($$('filter'),dhx.KeyEvents);