vue-dg v1.6.0

Vue-dg (vue data grid)

Data grid for Vue.js with sorting, filtering, paging, templating and remote data loading. Depends only on Vue.js.

Installation

1. Run: npm install vue-dg
2. Import module:

import DataGrid from "vue-dg";
//optional locale:
DataGrid.setLocale(DataGrid.locales.plPL);
Vue.use(DataGrid);

3. Import css with:

 import 'vue-dg/dist/DataGrid.css';

Features

• Can bind to local data (array) or remote data (WebApi or Kendo DataSourceRequest)
• Server side filtering, sorting paging
• Column definitions as sub-components
• Built in filter panels for a date, date-time, number, text, boolean and enumerable types
• Localization support (language and data formatting settings)
• Custom column templates with slots, functions and rendering functions
• Row details
• Data grouping

Example

<data-grid source="api/products" type="odata">
   <data-column field="status" title="Status" :values="statuses"></data-column>
   <data-column field="created" title="Create date" type="date" :sort-order="1" sort-dir="desc"></data-column>
   <data-column field="important" title="Important" type="bool" icon="fa fa-exclamation"></data-column>
   <data-column title="Commands" template="commands-tpl" width="150px"></data-column>
   <div slot="commands-tpl" slot-scope="{row}">
      <a :href="'details/'+row.id">Details</a>
   </div>
</data-grid>

Usage

Grid columns

Use DataColumn component to data columns. DataColumn is a full functional Vue component. You can bind it's attributes to your Vue instance, use v-if for conditional rendering or v-for for dynamic column insertion.

DataColumn properties

type property

Data grid supports few commonly used data types. Each data type has it's formatting rules and filtering component specified. If you don't specify the column type attribute you won't be able to filter data.

Default data types

values property

This property can be used for two things. Displaying key value mapped data and/ or creating drop down filter with defined values.

Key value mapping

Suppose you have enum field with status represented as int value. You can use type property to specify how this value should be mapped to a user friendly value. Column filter will be changed to drop down filter containing all available values.

<data-column field="status" :values="[{key:1, value:'Pending'}, {key:2, value:'Accepted'}]"></data-column>

Drop down filter

values property can be also used when you want to narrow down the list of available values that can be used in the column's filter.

<data-column field="userLogin" :values="['admin','root','john.doe']"></data-column>

Column template

You can use slots for defining column and header template.

<data-column template="custom-template"></data-column>
<div slot="custom-template" slot-scope="{row}">
    {row.price} {row.currency}
</div>

Footer template

You can add custom content to the grid page footer using footer slot.

<div slot="footer">
    custom footer item
</div>

DataGrid properties

Manual data reloading

If you need to reload currently displayed grid page emit event from your Vue model:

this.$emit("grid-reload");

Local data source

You can bind directly to array of objects by simply using source attribute.

<data-grid :source="someArray">...</data-grid>

Remote data source

Use source attribute for specifying the data url. Use type attribute for specifying remote source type.

Additional OData url variables

If you need to pass additional variables to OData source you can use sourceArgs property:

<data-grid source="odata/items" type="odata" :source-args="[{name: 'customVar', value: 'value'}]">...</data-grid>

Custom data source

You can create custom data source type by registering it with:

DataGrid.addRemoteSource("typeName", urlBuilder, dataMapper);

urlBuilder is a function called with url and request parameters. dataMapper is a function used to map server response to a single data page. See mapData and buildUrl function definitions in OData implementaiton for more details.

Data grouping

You can group data rows using GroupField component. All properties of GroupField component are reactive so you can bind them or use v-if for conditional grouping.

<data-grid group-template="group-tpl">
    <group-field field="category" :order="0" direction="desc"></group-field>
    <group-field field="subCategory"></group-field>
    <div slot="group-tpl" slot-scope="{group}">
        <span>Category: {{group.category}}</span>
        <span>Sub category: {{group.subCategory}}</span>
    </div>
</data-grid>

GroupField properties

Grouping header

You can use the groupTemplate property of the DataGrid component to specify the template of data group header row. You can bind a named slot name or a function which should return a VNode or named slot name. If you bind a function, it will be called with the following arguments: object with grouped key values, CreateElement function.

groupTemplate: string | ((item: any, h: CreateElement) => string | VNode)

Data filtering

There are three sources of data filters in use.

• User filters. Filters selected by user from filter popups. Use columnFilters property to view them.
• Bound filters. Additional filters read from filters property.
• Filter components. Filters defined with components placed inside DataGrid.

Filter components

You can specify filters that will be always applied to the data source by using sub components placed inside DataGrid.

<data-grid>
   <filter-group>
      <filter-field :field="status" :value="2"></filter-field>
      <filter-field :field="status" :value="1"></filter-field>
   </filter-group>
   <filter-group>
      <filter-field :field="price" :value="200" operator="gt"></filter-field>
   </filter-group>
   <filter-field :field="active" :value="true"></filter-field>
</data-grid>

Filter produced by this definition: (status=2 OR status=1) AND (price > 200) AND active=true

You can use v-if directive for conditionally enabling or disabling filters.

Bound filters

If you want to define filters in code you can bind them to filter property:

<data-grid :filters="[{filters: [{field: 'status', value:2}, {field: 'status', value:1}]}, {field: 'active', value: true}]"</data-grid>

User selected filters

Filters selected by the user are stored in columnFilters property. Always use sync modifier when binding to this property.

Filter operators

Row details

You can use slot or provide function returning VNode with row details.

<data-grid details-template="details-tpl">
   ...
   <div slot="details-tpl" slot-scope="{item}">
      <div>Id: {{item.id}}</div>
      <div>Status: {{item.status}}</div>
   </div>
</data-grid>

Details function can be defined like this:

methods: {
    details(row, h) {
        return h("div", {}, row.id);
    }
}

Configuration

Localization

DataGrid component can be fully localized. You can configure language and calendar settings with:

DataGrid.setLocale(DataGrid.locales.plPL);

You can use English or Polish localization. If you want to create your own localization, check example localization file.

Custom data types

You can define custom data types that can be used to format column value and/ or provide custom filter control.

DataGrid.addType("customType", {
    //every parameter is optional:
    //you can return VNode:
    formatter: (value, options, h, rowData) => h("b", ["custom html", value]),
    //or string:
    //formatter: (value) => "Hello: "+value,
    filterComponent: "CustomFilter",
    filterParams: { customParam: true }
});

The formatter is a function invoked for each cell value in the given column. Arguments passed to the function are: field raw value, options defined in formatOptions column property, rendering function. The function should return VNode created with rendering function or plain string. The filterComponent parameter can be used to specify what type of component should be used in column filter popup menus. If this value is not specified or empty data column of this type will not be filterable. The filterParams is an optional object that will be passed as property to filterComponent instance. This value can be used to parameterize filtering component.

Built in filter components

Config parameters

You can use the setSettings method to configure DataGrid. You can pass an object containing only those settings which should be overridden.

DataGrid.setSettings({idField: "id"});

Calendar parameters

You can use setCalendar method to customize the calendar used in data and dateTime filter components. You can pass an object containing only those settings which should be overridden.

DataGrid.setCalendar({weekStart: 0});

License

MIT License