Skip to content
This repository was archived by the owner on Jun 1, 2025. It is now read-only.

feat: allow providing custom date format via base Date Formatter #496

Merged
merged 1 commit into from
Apr 26, 2025
Merged

feat: allow providing custom date format via base Date Formatter #496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/column-functionalities/formatters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ A good example of a `Formatter` could be a timestamp or a `Date` object that we
* `Formatters.dateTimeShortUs`: Takes a Date object and displays it as an US Date+Time (without seconds) format (MM/DD/YYYY HH:mm:ss)
* `Formatters.dateTimeUsAmPm` : Takes a Date object and displays it as an US Date+Time+(am/pm) format (MM/DD/YYYY hh:mm:ss a)
* `Formatters.dateUtc` : Takes a Date object and displays it as a TZ format (YYYY-MM-DDThh:mm:ssZ)
* `Formatters.date`: Base Date Formatter, this formatter is a bit different compare to other date formatter since this one requires the user to provide a custom format in `params.dateFormat`
- for example: `{ type: 'date', formatter: Formatters.date, params: { dateFormat: 'MMM DD, YYYY' }}`
* `Formatters.decimal`: Display the value as x decimals formatted, defaults to 2 decimals. You can pass "minDecimal" and/or "maxDecimal" to the "params" property.
* `Formatters.dollar`: Display the value as 2 decimals formatted with dollar sign '$' at the end of of the value.
* `Formatters.dollarColored`: Display the value as 2 decimals formatted with dollar sign '$' at the end of of the value, change color of text to red/green on negative/positive value
Expand Down
15 changes: 12 additions & 3 deletions docs/column-functionalities/sorting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
- [Custom Sort Comparer](#custom-sort-comparer)
- [Update Sorting Dynamically](#update-sorting-dynamically)
- [Dynamic Query Field](#dynamic-query-field)
- [Sorting Dates](#sorting-dates)
- [Pre-Parse Date Columns for better perf](#pre-parse-date-columns-for-better-perf)

### Demo
Expand Down Expand Up @@ -139,6 +140,14 @@ queryFieldNameGetterFn: (dataContext) => {
},
```

### Sorting Dates

Date sorting should work out of the box as long as you provide the correct column field type. Note that there are various field types that can be provided and they all do different things. For the Sorting to work properly, you need to make sure to use the correct type for Date parsing to work accordingly. Below is a list of column definition types that you can provide:

- `type`: input/output of date fields, or in other words, parsing/formatting dates with the field `type` provided
- `outputType`: when a `type` is provided for parsing (i.e. from your dataset), you could use a different `outputType` to format your date differently
- `saveOutputType`: if you already have a `type` and an `outputType` but you wish to save your date (i.e. save to DB) in yet another format

### Pre-Parse Date Columns for better perf
##### requires v5.8.0 and higher

Expand All @@ -154,11 +163,11 @@ The summary, is that we get a 10x boost **but** not only that, we also get an ex

#### Usage

You can use the `preParseDateColumns` grid option, it can be either set as either `boolean` or a `string` but there's big distinction between the 2 approaches (both approaches will mutate the dataset).
You can use the `preParseDateColumns` grid option, it can be set as either a `boolean` or a `string` but there's a big distinction between the 2 approaches as shown below (note that both approaches will mutate the dataset).
1. `string` (i.e. set to `"__"`, it will parse a `"start"` date string and assign it as a `Date` object to a new `"__start"` prop)
2. `boolean` (i.e. parse `"start"` date string and reassign it as a `Date` object on the same `"start"` prop)

> **Note** this option **does not work** with Backend Services because it simply has no effect.
> **Note** this option **does not work** with the Backend Service API because it simply has no effect.

For example if our dataset has 2 columns named "start" and "finish", then pre-parse the dataset,

Expand All @@ -184,7 +193,7 @@ data = [
]
```

Which approach to choose? Both have pros and cons, overwriting the same props might cause problems with the column `type` that you use, you will have to give it a try yoursel. On the other hand, with the other approach, it will duplicate all date properties and take a bit more memory usage and when changing cells we'll need to make sure to keep these props in sync, however you will likely have less `type` issues.
Which approach to choose? Both have pros and cons, overwriting the same props might cause problems with the column `type` that you use, you will have to give it a try yourself. On the other hand, with the other approach, it will duplicate all date properties and take a bit more memory usage and when changing cells we'll need to make sure to keep these props in sync, however you will likely have less `type` issues.

What happens when we do any cell changes (for our use case, it would be Create/Update), for any Editors we simply subscribe to the `onCellChange` change event and we re-parse the date strings when detected. We also subscribe to certain CRUD functions as long as they come from the `GridService` then all is fine... However, if you use the DataView functions directly then we have no way of knowing when to parse because these functions from the DataView don't have any events. Lastly, if we overwrite the entire dataset, we will also detect this (via an internal flag) and the next time you sort a date then the pre-parse kicks in again.

Expand Down
92 changes: 73 additions & 19 deletions src/examples/slickgrid/Example40.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
import { format as dateFormatter } from '@formkit/tempo';
import { ExcelExportService } from '@slickgrid-universal/excel-export';
import React, { useEffect, useRef, useState } from 'react';
import {
Aggregators,
type Column,
FieldType,
Filters,
Formatters,
type GridOption,
type Grouping,
Expand All @@ -16,6 +18,7 @@ import {
} from '../../slickgrid-react';

import './example39.scss';
import { randomNumber } from './utilities';

const FETCH_SIZE = 50;

Expand Down Expand Up @@ -43,11 +46,63 @@ const Example40: React.FC = () => {
function defineGrid() {
const columnDefinitions: Column[] = [
{ id: 'title', name: 'Title', field: 'title', sortable: true, minWidth: 100, filterable: true },
{ id: 'duration', name: 'Duration (days)', field: 'duration', sortable: true, minWidth: 100, filterable: true, type: FieldType.number },
{ id: 'percentComplete', name: '% Complete', field: 'percentComplete', sortable: true, minWidth: 100, filterable: true, type: FieldType.number },
{ id: 'start', name: 'Start', field: 'start', formatter: Formatters.dateIso, exportWithFormatter: true, filterable: true },
{ id: 'finish', name: 'Finish', field: 'finish', formatter: Formatters.dateIso, exportWithFormatter: true, filterable: true },
{ id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven', sortable: true, minWidth: 100, filterable: true, formatter: Formatters.checkmarkMaterial }
{
id: 'duration',
name: 'Duration (days)',
field: 'duration',
sortable: true,
minWidth: 100,
filterable: true,
type: FieldType.number,
},
{
id: 'percentComplete',
name: '% Complete',
field: 'percentComplete',
sortable: true,
minWidth: 100,
filterable: true,
type: FieldType.number,
},
{
id: 'start',
name: 'Start',
field: 'start',
type: FieldType.date,
outputType: FieldType.dateIso, // for date picker format
formatter: Formatters.date,
exportWithFormatter: true,
params: { dateFormat: 'MMM DD, YYYY' },
sortable: true,
filterable: true,
filter: {
model: Filters.compoundDate,
},
},
{
id: 'finish',
name: 'Finish',
field: 'finish',
type: FieldType.date,
outputType: FieldType.dateIso, // for date picker format
formatter: Formatters.date,
exportWithFormatter: true,
params: { dateFormat: 'MMM DD, YYYY' },
sortable: true,
filterable: true,
filter: {
model: Filters.compoundDate,
},
},
{
id: 'effort-driven',
name: 'Effort Driven',
field: 'effortDriven',
sortable: true,
minWidth: 100,
filterable: true,
formatter: Formatters.checkmarkMaterial,
},
];
const gridOptions: GridOption = {
autoResize: {
Expand All @@ -59,6 +114,8 @@ const Example40: React.FC = () => {
enableGrouping: true,
editable: false,
rowHeight: 33,
enableExcelExport: true,
externalResources: [new ExcelExportService()],
};

setColumnDefinitions(columnDefinitions);
Expand Down Expand Up @@ -126,38 +183,35 @@ const Example40: React.FC = () => {
}

function newItem(idx: number) {
const randomYear = 2000 + Math.floor(Math.random() * 10);
const randomMonth = Math.floor(Math.random() * 11);
const randomDay = Math.floor((Math.random() * 29));
const randomPercent = Math.round(Math.random() * 100);

return {
id: idx,
title: 'Task ' + idx,
duration: Math.round(Math.random() * 100) + '',
percentComplete: randomPercent,
start: new Date(randomYear, randomMonth + 1, randomDay),
finish: new Date(randomYear + 1, randomMonth + 1, randomDay),
effortDriven: (idx % 5 === 0)
percentComplete: randomNumber(1, 12),
start: new Date(2020, randomNumber(1, 11), randomNumber(1, 28)),
finish: new Date(2022, randomNumber(1, 11), randomNumber(1, 28)),
effortDriven: idx % 5 === 0,
};
}

function onSortReset(shouldReset: boolean) {
shouldResetOnSortRef.current = shouldReset;
}

function refreshMetrics(args: OnRowCountChangedEventArgs) {
function handleOnRowCountChanged(args: OnRowCountChangedEventArgs) {
if (reactGridRef.current && args?.current >= 0) {
// we probably want to re-sort the data when we get new items
reactGridRef.current?.dataView?.reSort();

// update metrics
const itemCount = reactGridRef.current?.dataView?.getFilteredItemCount() || 0;
setMetrics({ ...metrics, itemCount, totalItemCount: args.itemCount || 0 });
}
}

function setFiltersDynamically() {
// we can Set Filters Dynamically (or different filters) afterward through the FilterService
reactGridRef.current?.filterService.updateFilters([
{ columnId: 'percentComplete', searchTerms: ['50'], operator: '>=' },
]);
reactGridRef.current?.filterService.updateFilters([{ columnId: 'start', searchTerms: ['2020-08-25'], operator: '<=' }]);
}

function setSortingDynamically() {
Expand Down Expand Up @@ -242,7 +296,7 @@ const Example40: React.FC = () => {
gridOptions={gridOptionsRef.current}
dataset={dataset}
onReactGridCreated={$event => reactGridReady($event.detail)}
onRowCountChanged={$event => refreshMetrics($event.detail.args)}
onRowCountChanged={$event => handleOnRowCountChanged($event.detail.args)}
onSort={_ => handleOnSort()}
onScroll={$event => handleOnScroll($event.detail.args)}
/>
Expand Down
9 changes: 9 additions & 0 deletions src/examples/slickgrid/utilities.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
export function randomNumber(min: number, max: number, floor = true) {
const number = Math.random() * (max - min + 1) + min;
return floor ? Math.floor(number) : number;
}

export function zeroPadding(input: string | number) {
const number = parseInt(input as string, 10);
return number < 10 ? `0${number}` : number;
}
93 changes: 56 additions & 37 deletions test/cypress/e2e/example40.cy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,44 +18,37 @@ describe('Example 40 - Infinite Scroll from JSON data', () => {
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 0');
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(1)`).contains(/[0-9]/);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(2)`).contains(/[0-9]/);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(3)`).contains(/20[0-9]{2}-[0-9]{2}-[0-9]{2}/);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(4)`).contains(/20[0-9]{2}-[0-9]{2}-[0-9]{2}/);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(5)`).find('.mdi.mdi-check').should('have.length', 1);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(3)`).contains('2020');
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(4)`).contains('2022');
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(5)`)
.find('.mdi.mdi-check')
.should('have.length', 1);
});

it('should scroll to bottom of the grid and expect next batch of 50 items appended to current dataset for a total of 100 items', () => {
cy.get('[data-test="totalItemCount"]')
.should('have.text', '50');
cy.get('[data-test="totalItemCount"]').should('have.text', '50');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('bottom');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');

cy.get('[data-test="totalItemCount"]')
.should('have.text', '100');
cy.get('[data-test="totalItemCount"]').should('have.text', '100');
});

it('should scroll to bottom of the grid again and expect 50 more items for a total of now 150 items', () => {
cy.get('[data-test="totalItemCount"]')
.should('have.text', '100');
cy.get('[data-test="totalItemCount"]').should('have.text', '100');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('bottom');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');

cy.get('[data-test="totalItemCount"]')
.should('have.text', '150');
cy.get('[data-test="totalItemCount"]').should('have.text', '150');
});

it('should disable onSort for data reset and expect same dataset length of 150 items after sorting by Title', () => {
cy.get('[data-test="onsort-off"]').click();

cy.get('[data-id="title"]')
.click();
cy.get('[data-id="title"]').click();

cy.get('[data-test="totalItemCount"]')
.should('have.text', '150');
cy.get('[data-test="totalItemCount"]').should('have.text', '150');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('top');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');

cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 0');
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 1}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 1');
Expand All @@ -66,14 +59,11 @@ describe('Example 40 - Infinite Scroll from JSON data', () => {
it('should enable onSort for data reset and expect dataset to be reset to 50 items after sorting by Title', () => {
cy.get('[data-test="onsort-on"]').click();

cy.get('[data-id="title"]')
.click();
cy.get('[data-id="title"]').click();

cy.get('[data-test="totalItemCount"]')
.should('have.text', '50');
cy.get('[data-test="totalItemCount"]').should('have.text', '50');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('top');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');

cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 9');
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 1}px;"] > .slick-cell:nth(0)`).should('contain', 'Task 8');
Expand All @@ -84,27 +74,56 @@ describe('Example 40 - Infinite Scroll from JSON data', () => {
it('should "Group by Duration" and expect 50 items grouped', () => {
cy.get('[data-test="group-by-duration"]').click();

cy.get('[data-test="totalItemCount"]')
.should('have.text', '50');
cy.get('[data-test="totalItemCount"]').should('have.text', '50');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('top');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');

cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-toggle.expanded`).should('have.length', 1);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-title`).contains(/Duration: [0-9]/);
});

it('should scroll to the bottom "Group by Duration" and expect 50 more items for a total of 100 items grouped', () => {
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('bottom');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');

cy.get('[data-test="totalItemCount"]')
.should('have.text', '100');
cy.get('[data-test="totalItemCount"]').should('have.text', '100');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left')
.scrollTo('top');
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');

cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-toggle.expanded`).should('have.length', 1);
cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(0) .slick-group-title`).contains(/Duration: [0-9]/);
});

it('should clear all grouping', () => {
cy.get('#grid40').find('.slick-row .slick-cell:nth(1)').rightclick({ force: true });

cy.get('.slick-context-menu.dropright .slick-menu-command-list')
.find('.slick-menu-item')
.find('.slick-menu-content')
.contains('Clear all Grouping')
.click();
});

it('should hover over the "Start" column header menu of 1st grid and click on "Sort Descending" command', () => {
cy.get('[data-test="clear-filters-sorting"]').click();
cy.get('#grid40').find('.slick-header-column:nth(3)').trigger('mouseover').children('.slick-header-menu-button').invoke('show').click();

cy.get('.slick-header-menu .slick-menu-command-list').should('be.visible').should('contain', 'Sort Descending').click();

cy.get(`[style="top: ${GRID_ROW_HEIGHT * 0}px;"] > .slick-cell:nth(3)`).contains('2020');
});

it('should load 200 items and filter "Start" column with <=2020-08-25', () => {
cy.get('[data-test="set-dynamic-filter"]').click();
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
cy.wait(10);
cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('bottom');
cy.get('[data-test="totalItemCount"]').should('have.text', '200');

cy.get('.slick-viewport.slick-viewport-top.slick-viewport-left').scrollTo('top');

cy.get(`[data-row=0] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
cy.get(`[data-row=1] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
cy.get(`[data-row=2] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
cy.get(`[data-row=3] > .slick-cell:nth(3)`).contains(/^Aug [0-9]{2}, 2020$/);
});
});