Embed dashboards with your application filters

The Sumboard SDK supports a variety of filters, defined by the FilterType enumeration. The basic filter structure serves as the foundation for creating specific filter types such as TimeRange, Aggregation, Custom, and External.

Filter structure

Below is the interface for the basic filter structure:

export interface Filter<T extends FilterType, V = unknown> {
  type: T;
  place: FilterPlace;
  values: FilterValue<V>[];
  name?: string;
  order?: number;
}

Properties of the filter interface:

• type: Represents the type of filter (e.g., TimeRange, Aggregation, Select, or External).
• place: Specifies where the filter is displayed within the application, using the FilterPlace enumeration.
• values: An array of filter values.
• name (optional): The name of the filter, which is displayed in the filter bar.
• order (optional): The order in which the filter should appear in the filter bar.

FilterPlace enumeration

The FilterPlace enumeration defines the possible locations where filters can be displayed:

export enum FilterPlace {
  Apps = 'apps',
  Extern = 'extern',
  Token = 'token',
}

Values of the FilterPlace:

• FilterPlace.Apps: Filters are displayed above the charts in the application. These filters can be modified within the application, via the SDK, or through the token (when generated by the backend).
• FilterPlace.Extern: Filters are displayed outside the application. These filters can be modified externally via the SDK or through the token.
• FilterPlace.Token: Filters added to the token when generated by a third party. These filters can only be modified through the token.

Filter types

The Sumboard SDK supports different filter types, defined by the FilterType. Below is the interface for the filter types:

export enum FilterType {
  TimeRange = 'time_range',
  Aggregation = 'aggregation',
  Select = 'select',
  Unknown = 'unknown',
}

TimeRange filter (FilterType.TimeRange)

The TimeRange filter allows users to select a time range. The value is structured as from~to, where both from and to can be a custom range or a timestamp. The TimeRangeType represents the various time range options supported by this filter.

Here is the interface for the TimeRange filter:

export type Time = number;

export enum CustomRange {
  Today = 'today',
  Yesterday = 'yesterday',
  LastWeek = 'lastWeek',
  LastMonth = 'lastMonth',
  Last7Days = 'last7Days',
  Last30Days = 'last30Days',
}

export type TimeRangeType =
  | CustomRange.Today
  | CustomRange.Yesterday
  | CustomRange.LastWeek
  | CustomRange.LastMonth
  | CustomRange.Last7Days
  | CustomRange.Last30Days
  | `${Time}~${Time}`
  | `${Time}~`
  | `~${Time}`;

export type FilterTimeRange = Filter<FilterType.TimeRange, TimeRangeType>;

These predefined ranges (e.g., Today, Yesterday) and custom time ranges (using ${Time}) allow you to configure the TimeRange filter according to your needs.

Aggregation filter (FilterType.Aggregation)

The Aggregation filter is used for aggregating data. Its value follows the structure DateFormat[].

Here is the interface for the Aggregation filter:

export enum DateFormat {
  Hour = 'hour',
  Day = 'day',
  Week = 'week',
  Month = 'month',
  Quarter = 'quarter',
  Year = 'year',
}

export type FilterAggregation = Filter<FilterType.Aggregation, DateFormat>;

The DateFormat enumeration represents various aggregation options such as hour, day, week, month, quarter, and year. The Aggregation filter allows you to customize how your data is aggregated based on these options.

Custom filter (FilterType.Select)

The Custom filter is used for filtering data by selected values from another query.

Here is the interface for the Custom filter:

export interface FilterSelect extends Filter<FilterType.Select, (string | number)[]> {}

The Custom filter allows you to filter your data based on selected values, which can be strings or numbers, from another query. This is useful for creating dependent filters or conditional data displays based on user selections.

External filter (FilterType.Unknown)

The Unknown (External Filter) allows for custom filters that can be used in FilterPlace.Extern or FilterPlace.Token.

Here is the interface for the Unknown (Custom Filter):

export type FilterUnknown<T = unknown> = Filter<FilterType.Unknown, T>;

The Unknown (External Filter) enables you to create custom filters with user-defined value structures, useful for integrating filters not part of the predefined types, and can be used in external or token-based filter placements.

Filter implementation

Implementing filters during SDK initialization To implement filters during the initialization of the Sumboard SDK, create a filters object containing the desired filter configurations and pass it to the sumboard.init() method along with the token and dashboard ID.

Here's an example of how to implement filters during initialization:

const filters: FiltersMap<FilterType> = {
  aggregation: {
    type: FilterType.Aggregation,
    place: FilterPlace.Apps,
    values: [
      {
        value: DateFormat.Month,
        label: 'Month',
      },
    ],
  },
  timeRange: {
    type: FilterType.TimeRange,
    place: FilterPlace.Apps,
    values: [
      {
        value: CustomRange.Last30Days,
        label: 'Last 30 days',
      },
    ],
  },
  users: {
    type: FilterType.Select,
    place: FilterPlace.Apps,
    values: [
      {
        value: ['user-uuid-1', 'user-uuid-2'],
        label: 'User Name 1, User Name 2',
      },
    ],
  },
};

fetch('https://your-backend.com/api/token')
  .then<{ token: string }>((response) => response.json())
  .then(({ token }) => sumboard.init({ token, filters, dashboardId: '<DASHBOARD_ID>' }));

Replace https://your-backend.com/api/token with the URL of your backend's API endpoint for token generation and <DASHBOARD_ID> with the ID of the dashboard you want to embed.

You can also test this code in this StackBlitz Demo.

INFO

The demo uses a mock API to simulate fetching a token, and is for demonstration purposes only.

Changing filters after SDK initialization To change filters after initialization, you can call the changeFilters method of the Sumboard instance. This method takes an object where each key represents the name of the filter you want to change, and the value is an object containing the updated values for that filter.

Here is an example of changing the Aggregation filter:

document.getElementById('aggregation').onchange = ({ target }) => {
  const value = (target as HTMLSelectElement).value as DateFormat;

  sumboard.changeFilters({
    aggregation: {
      type: FilterType.Aggregation,
      place: FilterPlace.Extern,
      values: [{ value }],
    },
  });
};

In this example, the aggregation filter is updated to a new value specified by the user through an HTML select element. The changeFilters method can change one or several filters at once, depending on the keys of the object passed as an argument.

You can also test this code in this StackBlitz Demo.

INFO

The demo uses a mock API to simulate fetching a token, and is for demonstration purposes only.