j-DataGrid — Total.js part 1

j-DataGrid is part of the jComponent library from Total.js. You can find more information about j-DataGrid on componentator.com or GitHub.

j-DataGrid is a component that can render a lot of data on a web page with many functionalities. It looks like a table with headers and it can render more than 30 000 rows seamlessly. It supports sorting data, filtering data, checkboxes, resizing of columns, vertical and horizontal scrolling with custom scrollbars independent of OS, also supports drag & drop columns, responsiveness and dark mode. All this makes it a complex yet versatile component you can use in a matter of moments.

Data grid is a very complex component, and it is difficult to cover all its capabilities in one blog post, so I will divide it into two parts. In the first part, we will discuss different data types for columns. In the second, we will cover more functionalities like control panel, checkbox usage, and how we can handle click events on a row.

How to use j-DataGrid

As the first step, you have to know how to use the jComponent library. I wrote about it in my previous blog, so for more information please read this blog post.

This component is used differently from previous components because here we will use script inside our ui-component HTML element. In this script we will define which columns will be rendered, how will they look and also some functionality for them. (Just to be clear, our datasource has to contain columns we want to render).

Initialization

When we want to initialize j-DataGrid we have to as a first step use the HTML tag ui-component as we used to in other components. This is the same as before and we should fill attributes name, path and config. In the config, we can insert settings for overall settings for the component.

As a next step, we have to add a script tag inside this component. This script has to have an attribute type with value text/plain. Inside this script, we will put an array of objects, where every object represents one column of our datagrid, with properties name (name of the property which will be listed here), text (name of a column in datagrid), and some more optional properties. With these settings, we can affect different options for each column separately.

Example:

Please keep in mind, that this is only simple a example and you can do a lot more with this component.

<ui-component name="datagrid" path="?.items" config="margin:22">
  <script type="text/plain">
    [
      { name: 'name', text: 'Name', width: 200 },
      { name: 'age', text: 'Age', type: 'number' },
      { name: 'phone', text: 'Phone', type: 'phone' },
      { name: 'email', text: 'Email', type: 'email' },
      { name: 'online', text: 'Online', type: 'boolean', options: [{ name: 'Yes', id: true }, { name: 'No', id: false }] },
      { name: 'created', text: 'Created', template: '{{ created | format(\'dd.MM.yyyy\') }}', align: 2, alignheader: 2, filter: false }, 
    ]
  </script>
</ui-component>

As you can see in the example above, we want to use datagrid, this component will read data from the path ?.items (I wrote about paths in my previous blog, so if you are new here, please read this blog first) and in the configuration we used only margin with value 22. This margin is used to adjust the height of our datagrid.

As you have surely noticed there is also a mentioned script. We used some basic data types here to show you how to work with them. We chose string, number, phone, email, boolean and one option to render a date. In some of them, we used additional properties, which we will explain later.

Now we can see empty datagrid on our page.

For our case, we will add some data to our path.

var arr = [];
arr.push({ id: '1', name: 'Palo', age: 26, phone: '[phone]', email: '[e-mail]', online: true, created: NOW });
arr.push({ id: '2', name: 'Peťo', age: 40, phone: '[phone]', email: '[e-mail]', online: false, created: NOW.add('-1 day') });
arr.push({ id: '3', name: 'Dodo', age: 34, phone: '[phone]', email: '[e-mail]', online: true, created: NOW.add('-2 day') });
arr.push({ id: '4', name: 'Marek', age: 32, phone: '[phone]', email: '[e-mail]', online: false, created: NOW.add('-3 day') });
arr.push({ id: '5', name: 'Louis', age: 25, phone: '[phone]', email: '[e-mail]', online: true, created: NOW.add('-4 day') });
exports.set('items', arr);

This code is part of our PLUGIN and as you can see, it is in form of array of objects. Every object includes properties id, name, age, phone, email, online and created which fits exactly to values of property name in objects in script in j-DataGrid definition.

With this code, we can see our items rendered in j-DataGrid on our web.

Now, when we prepared our example, we can continue with the possibilities of each column.

String column

Used code:

{ name: 'name', text: 'Name', width: 200 }

This object defined in the component declaration means, that in this column will be listed property name from objects in our data, the header of this column will be Name, and the width of this column will be 200 pixels (default value is 150 pixels).

Also, we can filter in this column by writing a string for search in the filter under the column heading.

Number column

Used code:

{ name: 'age', text: 'Age', type: 'number' }

This object defined in the component declaration means, that in this column will be listed property age from objects in our data, the header of this column will be Age, and the type of this column will be number.

As you can see already in the example, columns with type number are automatically aligned to the right side of the cell. It is better for orientation in the numbers. But if you want to change that, you can do it easily with property align.

Filtering in this column is the same as in the string column, but here you can filter also in ranges (e.g. 26–32 — there has to be space between numbers and dash).

Phone column

Used code:

{ name: 'phone', text: 'Phone', type: 'phone' }

This object defined in the component declaration means, that in this column will be listed property phone from objects in our data, the header of this column will be Phone, and the type of this column will be a phone.

In the example you can see, that there is a phone icon added in front of each number. An underscore appears when hovering over a number and there is a functionality, that you can call this number by clicking on it.

Filtering in phone columns works the same as in string columns.

Email column

Used code:

{ name: 'email', text: 'Email', type: 'email' }

This object defined in the component declaration means, that in this column will be listed property email from objects in our data, the header of this column will be Email, and the type of this column will be email.

There is some similarity between type email and type phone. But here is an email icon added in front of each email. Also, an underscore appears when hovering over an email and by clicking on some email you are automatically redirected to your mail and you can send an email to a selected email address.

Filtering in email columns works the same as in string columns.

Boolean column

Used code:

{ name: 'online', text: 'Online', type: 'boolean', options: [{ name: 'Yes', id: true }, { name: 'No', id: false }] }

This object defined in the component declaration means, that in this column will be listed property online from objects in our data, the header of this column will be Online, and the type of this column will be boolean. A new property for us here is options, which are options for filtering. Here you can see an array with two objects. Each object has a property name and id. In id, we can see values true and false, which represent values in this column and names are Yes and No, which will be used in our filter as options.

Boolean values are represented in datagrid as checkboxes, where checked, means true and unchecked means false.

For filtering used in this column, we also have to declare component j-Directory (you can learn more about this component in my previous blog). Then after clicking on the filter, the directory will appear and we can choose from the options we defined in the datagrid declaration.

Date column — improvised

Used code:

{ name: 'created', text: 'Created', template: '{{ created | format(\'dd.MM.yyyy\') }}', align: 2, alignheader: 2, filter: false }

There is a date type for columns in j-DataGrid, but for example purposes, we will use another method.

This object defined in the component declaration means, that in this column will be a property created from objects in our data, the header of this column will be Created. As the next property, we can see the template where is used a template for the format of a date. So every date will be transformed to the form dd.MM.yyyy. The next two properties align and alignheader are used to align values in the column and header to the right side of a cell. The last property is filter, where we inserted the value false to disable the filtering option in this column.

I hope you learned something new with this blog, but do not forget, that this was only for example purposes and you can do a lot more with component j-DataGrid.

Video tutorial