Using ORGENIC UI Datatable Component

Timo Krieger — Mon, 20 May 2019 13:01:44 +0000

ORGENIC UI is a growing set of web components with focus on UX and design. This tutorial shows how to use the datatable component.

The datatable component can be used to display large sets of data in a high-performance flexible table. The component is based on Tabulator and some easy-to-use interfaces to hide the complexity of the library.

In this tutorial we are using plain JS without any framework, but you can also use any framework like Angular, React or Vue with its comfortable databinding.

General

The datatable itself is just a single line of code. Everything else like configuration and data providers are set via JavaScript or can be set via data binding using the framework of your choice.

<og-datatable id="datatable"></og-datatable>

In JavaScript resolve the data table element using query selector:

const datatable = document.querySelector('#datatable');

Configuration

The datatable only has one configuration object with column definition and a data service which can serve client side data or (lazy loaded) data from the backend. Also an optional message which is displayed if no data is available can be defined.

datatable.config =  {
    noDataMessage: 'No items available',
    dataService: paginatedDataService,
    columns: columnConfiguration
};

Columns

A basic column declaration is very simple. It's just the definition of the data property and the column title.

const columnConfiguration = [
    //...
    {
        property: 'name',
        title: 'Label'
    },
    //...
];

Custom Column Formatter

A custom column formatter can be specified as string or a function to add custom code. This example shows how to draw colored circles according to the value of the activity property.

const columnConfiguration = [
    //...
    {
        property: 'activity',
        title: 'Activity',
        formatter: (cell, formatterParams, onRendered) => {
            let colored = '';
            for (let i = 0; i < cell.getValue(); i++) {
                const hue = 150 - (37.5 * i);
                colored += '<span style="color: hsl(' + hue + ',100%,40%)">&#10687;</span>';
            }
            return '<strong>' + colored + '</strong>';
        }
    }
    //...
]

You can read more about the formatter specification at the Tabulator documentation.

Custom Column Sorter

If you need a column sorter for e.g. columns containing formatted dates, you can add a sort function.

This function has two parameters that represent to cell values to be compared. The result should be a negative value if a is smaller than b, 0 if the two values are equal or a positive value if a is greater than b.

const columnConfiguration = [
    //...
    {
        property: 'date',
        title: 'Date',
        sorter: (a, b) => {
            // this example requires momentjs
            return moment(a, 'DD.MM.YYYY').valueOf() - moment(b, 'DD.MM.YYYY').valueOf();
        }
    }
    //...
]

Data Service

The datatable component can be used in two different presentation modes: you can have an infinite scrolling table or a paginated table. Both modes can be used with in-memory-data or with lazy loaded data from a remote resource.

If you have a large amount of data on the client side, you can also implement a lazy loading data service. This data service serves smaller chunks of data on demand to boost performance of the table.

The data service interface is split into these parts:

type (scrolled / paginated)
options (optional)
provider
- type (default / lazy)
- getData (async function returning array of data or object of type LazyDataResponse)

Scrolling

The first scenario is an infinite scrolling data service with all data available on client side. You just have to return the array in an async function.

const scrollDataService = {
    type: 'scrolled',
    provider: {
        type: 'default',
        getData: async () => tableData
    }
};

Scrolling + Lazy Loading

If you need to have a large amount of data, you should load it lazily. Also if you have all the data available on client side it might be a good idea to use a lazy data provider to improve table initialization performance.

The property requestLimit within the options object defines how many items will be requested per chunk.

The return value of the async function getData must contain the total row count (totalRows) and the data array.

const scrollLazyDataService = {
    type: 'scrolled',
    options: {
        requestLimit: 10
    },
    provider: {
        type: 'lazy',
        getData: async (page, size, sorters) => {
            // request data from server and return:
            return {
                totalRows: 0, // total number of available rows
                data: [ ] // data array
            };
        }
    }
};

Pagination

If you'd like to use a paginated table you configure this service type and set the page size within the options object. The default data provider has an async function getData returning the plain data array.

const paginatedDataService = {
    type: 'paginated',
    options: {
        pageSize: 5
    },
    provider: {
        type: 'default',
        getData: async () => tableData
    }
};

Pagination + Lazy Loading

Using a lazy data provider for paginated table does not need any additional configuration. The chunk size for each request is defined by pageSize.

The return value of the async function getData must contain the total row count (totalRows) and the data array.

const paginatedLazyDataService = {
    type: 'paginated',
    options: {
        pageSize: 5
    },
    provider: {
        type: 'lazy',
        getData: async (page, size, sorters) => {
            // request data from server and return:
            return {
                totalRows: 0, // total number of available rows
                data: [ ] // data array
            };
        }
    }
};

Handling Selection Events

Selecting items will emit an event that you can handle with an event listener. You can add this event listener on the HTML object selected by a query selector or by binding an event listener when working with a framework like angular, react or vue.

const datatable = document.querySelector('#datatable');
datatable.addEventListener('itemSelected', e => {
    // e.detail contains selected object
});

Comments

For using the async function or a function returning a promise you should use babel to transpile your code to ES5 if you need to enhance browser support.

To see the datatables in action, take a look at this CodePen:

Please visit us at:

Using the ORGENIC UI Expander Component

Timo Krieger — Tue, 07 May 2019 11:41:02 +0000

ORGENIC UI is a growing set of web components with focus on UX and design. This tutorial shows how to use the expander component.

The expander is a component that can be used to organize large amounts of content in expandable blocks. These blocks can be hidden by collapsing so that only the heading is visible. Common usecases are FAQs or settings pages with some expert parameters that are hidden by default.

Expander

Using ORGENIC UI, all you have to do is to og-expander tag with the heading as attribute name and the content which will be transcluded into a slot:

<og-expander name="Expander #1">
    <p>Expander content #1</p>
</og-expander>

If you want the expander to be expanded by default, you can simply add an "extended" attribute.

<og-expander name="Expander #1" expanded>
    <p>Expander content #1</p>
</og-expander>

The result looks like this:

This is pretty simple... but there is more...

Accordion

If you think about an FAQ, you might just want to open one expander after the other to focus on the one element the user selects. The common name for components with this behavior is accordion. In ORGENIC UI we avoided creating a new component just for this use case. Instead, you can simply add a group attribute to add multiple expanders to one category.

<og-expander name="Accordion Expander #1" group="accordion" expanded>
    <p>Accordion expander content #1</p>
</og-expander>
<og-expander name="Accordion Expander #2" group="accordion">
    <p>Accordion expander content #2</p>
</og-expander>

These expanders behave like an accordion now.

This approach gives you the flexibility to spread expanders over the entire page, and they don't have to be enclosed by an accordion component.

Take a look at this CodePen: