All docs
V19.2
19.2
19.1
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Date Filter

  • 6 min to read

The Date Filter dashboard item allows you to filter dashboard data based on the selected data range. The range can be relative (Last 3 Months), use fixed dates (01-01-2018), or presets (Month-to-date). You can also filter dates before or after a specified date.

DateFilter Demo

The DateFilter item displays a set of intervals that can be used as quick filters:

End-users can click the Set Filter button to invoke the Date Picker:

Date Filter - Date Picker Drop-Down

Add a New Date Filter to the Dashboard

To create a Date Filter item, click the Date Filter item (the icon) in the Toolbox Filter section:

wdd-toolbox-filter-elements

In code, create the DateFilterItem class instance and add it to the Dashboard.Items collection:

DateFilterItem

A Date Filter dashboard item that allows end users to filter other dashboard items by date-time values.

Dashboard.items

Provides access to a collection of dashboard items.

Bind to Data

Click the Dimension placeholder in the data section and select the required data source field in the Binding section of the invoked data item menu to bind the Date Filter to data:

Bindings

In code, use the following API member:

DateFilterItem.dimension

Specifies a dimension that provide values for the Date Filter.

Date Picker

The Date Filter item displays a Date Picker that is a button with a drop-down calendar. A drop-down calendar allows the end-user to select a single date or a date range:

Date Picker

You can specify whether the Date Picker is located at the near end of the Quick Filter series, at the far end, or whether it is hidden. Go to the dashboard item Options menu, open the Layout section and set the Date Picker Location option.

To change the Date Picker location, use the following property:

DateFilterItem.datePickerLocation

Specifies the Date Picker's location in the Date Filter.

Display Format

To specify the date-time value format, use the Format Type option in the Format section of the data item menu, as described in the Formatting Data topic.

You can specify a custom string displayed in the Date Picker component. Go to the dashboard item Options menu, open the Layout section and fill in the Display Text Pattern text field:

Options

You can include placeholders in a custom string. The {0} placeholder is the interval's start, the {1} placeholder is the interval's end.

In code, use the following API members:

DataItem.dateTimeFormat

Provides access to the format settings for date-time values.

DateFilterItem.displayTextPattern

Specifies a string displayed in the Date Picker.

Create Quick Filters

Quick Filters are buttons displayed within the Date Filter item. Each button is bound to a predefined date-time period that can be used to perform a selection. You can click the button to apply a custom period to a Date filter:

Quick Filters

You can use the Select Date Time Period button in the Date Filter's item caption that invokes the drop-down list with quick filters.

To add quick filters, open the Date Filter's Options menu and go to the Custom Periods section. Click "+" to add a new period:

Custom Periods

Click the edit icon to invoke the editor's panel and configure a custom period. The following image illustrates how to modify the Month-to-Date custom period:

Month-to-Date

You can specify the following settings for the start/end boundaries.

  • Caption - Specifies a custom periods caption.
  • Start Mode - Specifies a mode of the start boundary.
  • End Mode - Specifies a mode of the end boundary.

The following modes used to set custom periods are available.

  • None - The selection will begin from the start/end of the visible range.
  • Fixed - Allows you to select a specific date value using the calendar. Use the Start/End Date option to set a value.
  • Flow - Allows you to select a relative date value. The Interval option specifies the interval between the current date and the required date. The Offset option allows you to set the number of such intervals.

    Note that the Offset option can accept negative and positive values. Negative values correspond to dates before the current date, while positive values correspond to future dates.

Below you can find some examples of how to set up custom periods:

Fixed custom periods

Name

Settings

2018

Start Point

  • Mode: Fixed
  • Start Date: 01/01/2018

End Point

  • Mode: Fixed
  • End Date: 12/31/2018

Q1 2017

Start Point

  • Mode: Fixed
  • Start Date: 01/01/2017

End Point

  • Mode: Fixed
  • End Date: 03/31/2018

Flow custom periods

Name

Settings

6 Months

Start Point

  • Mode: Flow
  • Interval: Month
  • Offset: -5

End Point

  • Mode: None

Year to date

Start Point

  • Mode: Flow
  • Interval: Year
  • Offset: 0

End Point

  • Mode: Flow
  • Interval: Day
  • Offset: 0

Last Month

Start Point

  • Mode: Flow
  • Interval: Month
  • Offset: -1

End Point

  • Mode: Flow
  • Interval: Month
  • Offset: 0

In code, create the DateTimePeriod objects and add them to the DateFilterItem.dateTimePeriods collection to create quick filters:

DateTimePeriod

A date-time period that is used to select a predefined range in the Range Filter and Date Filter items.

DateFilterItem.DateTimePeriods

Gets a collection of date-time periods used as Quick Filters.

Arrange Quick Filters

Quick filters in the DateFilter item can be arranged horizontally or vertically. The default mode is auto height, in which quick filters are displayed horizontally and the dashboard item shrinks automatically to fit the items and save space.

To specify the arrangement mode, go to the dashboard item Options menu, open the Layout section and specify the Arrangement Mode setting:

Options

In code, use the following API member:

DateFilterItem.arrangementMode

Specifies a layout of the elements inside the Date Filter.

Example

The following example shows how to create the Date Filter item, bind it to data and add to the existing dashboard.

Create a dimension and use the dataMember property to bind it to the existing data source's column. Then use the created dimension in the dashboard item to bind the Date Filter to data.

Create a DateTimePeriod instance and add it to the DateFilterItem.dateTimePeriods collection to create quick filters.

After you add the created dashboard item to the Dashboard.items collection, call the Dashboard.rebuildLayout method to rebuild the dashboard layout and display changes.

// Use the line below for a modular approach:
// import * as Model from 'devexpress-dashboard/model'
// Use the line below for an approach with global namespaces:
// var Model = DevExpress.Dashboard.Model;

// ...
public createDateFilter() { 
    // Create a data item for the Date Filter item.
    var dateFilterDate = new Model.Dimension();
    dateFilterDate.dataMember("OrderDate");
    dateFilterDate.dateTimeGroupInterval("DayMonthYear")

    // Create the Date Filter and bind it to data.
    var dateFilter = new Model.DateFilterItem();
    dateFilter.name('Date Filter');
    dateFilter.dataSource(sqlDataSource.componentName());
    dateFilter.dataMember(sqlDataSource.queries()[0].name());
    dateFilter.dimension(dateFilterDate);

    // Create a custom period for quick filters.
    var monthToDayPeriod = new Model.DateTimePeriod();
    monthToDayPeriod.name("Month to Date");
    monthToDayPeriod.start.flow.interval("Month").offset(0);
    monthToDayPeriod.start.mode("Flow");
    monthToDayPeriod.end.flow.interval("Day").offset(1);
    monthToDayPeriod.end.mode("Flow");

    dateFilter.dateTimePeriods.push(monthToDayPeriod);

    control.dashboard().items.push(dateFilter);
    // ...
    control.dashboard().rebuildLayout();
}