DataTables logo
≡

Templates

CardView makes use of a source template which is cloned and populated for each row of data to be displayed. There are two ways of doing this:

  • Built in templates
  • Custom templates

Built in templates

The easiest way of using CardView, is simply to enable it and optionally specify one of the built in templates that should be used to generate the display cards. There are three built in templates, each of which can be accessed on the DataTable.CardView.templates object:

  • dlList - Makes use of dl to show a dt (column title) / dl (data point value) list of entries. This is the default template that CardView will use.
  • ulList - Uses a ul / li list to display a simple list of the data from the table in column order.
  • miniTable - In this case a table is used to nicely align the column titles and data point values in the cards.

In each case, the build in templates will display the data for each column in the table, in table order. It uses the same display orthogonal value for the data, so the same data that is shown in the table, will be shown in the card (although this can be customised with cardView.orthogonal).

To make use of one of the built in templates, assign it to the cardView.template option - e.g.:

new DataTable('#myTable', {
    cardView: {
        template: DataTable.CardView.templates.ulList
    }
});

You can see examples of the built in templates in use in the CardView examples.

Custom templates

The built in templates are quick and convenient, however, they are limited by their very nature of being generic. The real power of CardView becomes more apparent when you use a custom template - that is, HTML that you specify and customise to exactly fit your web-site. For example, you might be working on a product sales site where each card is a product to buy and should have an "Add to cart" button with an image of the product, or you have a members database, with a card per person that should basic summary information. The HTML and styling of the cards is completely under your control, so you can use any layout you wish!

To use a custom template from HTML with CardView, make use of the template element and then reference that element in the CardView initialisation. template elements will note dispaly on your page by itself, making it perfect as a basis for the cloning display of CardView.

Consider the following template:

<template id="cardView">
    <div class="cardView">
        Name: <span data-dtcv-dataSrc="name" /><br />
        Position: <span data-dtcv-dataSrc="salary" />
    </div>
</template>

To initialise CardView with this template use cardView.template set to be a CSS selector that will pick out the template element (hence way it has been given an id attribute here, for easy selection!). This also allows multiple templates to be defined on your page which can be used for different tables, or for the same table if you want to switch configurations.

new DataTable('#example', {
    cardView: {
        mode: 'cards',
        template: '#cardView'
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' }
    ]
});

Data referencing

In your template you need to be able to tell CardView where you want the values from the data source object from each row to go (i.e. the cell data). This is done by using the data-dtcv-dataSrc attribute which should be assigned to an element that you want the data to be displayed in. This should be an empty element as the data value will be used to replace anything else in the element - a span is often used, as in this example, as it is semantically meaningless.

You'll notice that the value of the data-dtcv-dataSrc attribute corresponds to the data point for the column that we wish to display. This provides a lot of flexibility as you can position the data anywhere in your HTML, use as many data points as you want, or even use values from the data source object that are not displayed in the table columns.

This proper supports all string and integer options of columns.dataSrc (e.g. dotted Javascript notation for nested data) and will attempt to find the corresponding column from the table in order to apply the same orthogonal rendering (as noted above). If a column is not found, the data will be used directly.

In the example above objects are used for the data source for each row, but if you have arrays of data (or are reading the data from HTML without specified data points to read the values into), you should use the indexes for the data you wish to display rather than a property name.

Attributes

While the dataSrc attribute is the most important for displaying data, it is not the only one that CardView supports. You can also use the following:

  • data-dtcv-dataSrc - as above. Shown here for completeness!
  • data-dtcv-title - applied to an element where a column title shown be shown. Set to be the target column index.
  • data-dt-column - used for DataTable API selectors when passing in an element. This is particularly useful if you want to have a click event on an element reference a particular column (and cell when combined with data-dt-row). An element (or child of an element with this attribute) can be passed in as a column selector for column() or cell().
  • data-dt-row - As with the data-dt-column attribute, this is used by the row() selector to be able to determine which row an element is attached to. This should be set on the card container, since each card represents a single row. Furthermore, the value should be empty, allowing CardView to fill the row index in automatically as it draws the cards.

Looping

It is possible that you might need to design a card for tables where you don't know what the data structure will be (this is the case for the built in template types for example). For this, CardView provides data-dtcv-for. This attribute must be set to the value "columns" (more values might be added in future). When encountered, CardView will clone the element the attribute is attached to, once for the columns specified by the cardView.columns initialisation option (all columns by default).

The template elements in the loop can make use of the attributes specified above and the values should all be empty strings, allowing CardView to fill the values in automatically for each column.

As an example, consider the following template, which will have a div per column, that contains two span elements - one for the column title and one for the data to display:

<template id="cardView">
    <div class="cardView" data-dt-row="">
        <div data-dtcv-for="columns" data-dt-column="">
            <span data-dtcv-title="" />: <span data-dtcv-dataSrc="" />
        </div>
    </div>
</template>