refactor the date filter and update the Readme

refactor the date filter in order to use the original date filter when a `%` is present inside the format string

README.md

@@ -64,23 +64,65 @@ For now I'll keep the documentation of the filters here, when they become more I
 
 ### `date`
 
-The `date` filter has been replaced with a custom one
-<!-- TODO: explain why and insert some example -->
+The LiquidJS [built-in `date` filter](https://liquidjs.com/filters/date.html) has been replaced with a custom one.
+For now, if there is a `%` character in the date format the old filter is used, otherwise the new one will take place.
+
+The new `date` filter uses [date-fns](https://date-fns.org/) as library to handle dates, and the format strings to use are showed here: [date-fns formats](https://date-fns.org/v2.21.3/docs/format)
+
+There are also some special words that can be used with this filter:
+
+| word | example | effect |
+| ---- | ------- | ------ |
+| "now" | {{ "now" | date: "yyyy-MM-dd" }} | Use the date from `new Date` and formatted with the given format |
+| "today" | {{ "today" | date: "yyyy-MM-dd" }} | same as `now` |
+| "yesterday" | {{ "yesterday" | date: "yyyy-MM-dd" }} | use the [`subDays`](https://date-fns.org/v2.21.3/docs/subDays) function to subtract `1` from `Date.now()` and formatted with the given format |
+| "tomorrow" | {{ "tomorrow" | date: "yyyy-MM-dd" }} | use the [`addDays`](https://date-fns.org/v2.21.3/docs/addDays) function to add `1` to `Date.now()` and formatted with the given format |
+
+#### Default format
+
+Now you can use the "Date Format" you defined inside the plugin settings in a easier way:
+
+**Before**: `{{ "now" | date: default_date_format }}`
+
+**Now**: `{{ "now" | date }}` the format you specified in the settings is now used as default
 
 ### `days_ago`
 
-<!-- TODO: explain the filter and add some example -->
+A simple filter that uses the [`subDays`](https://date-fns.org/v2.21.3/docs/subDays) to subtract days from the current date (`Date.now()`)
+
+Keep in mind that this filter returns a date that needs to be formatted, so needs to be used with the `date` filter, like this:
+
+`{{ 1 | days_ago | date }}` same as `{{ "yesterday" | date }}`
+
+`{{ 2 | days_ago | date }}` return the date from two days ago
+
+This can be used for a "Weekly Review" template, something like:
+
+- [[{{ 7 | days_ago | date }}]]
+- [[{{ 6 | days_ago | date }}]]
+- [[{{ 5 | days_ago | date }}]]
+- [[{{ 4 | days_ago | date }}]]
+- [[{{ 3 | days_ago | date }}]]
+- [[{{ 2 | days_ago | date }}]]
+- [[{{ 1 | days_ago | date }}]]
+
 
 ### `days_after`
 
-<!-- TODO: explain the filter and add some example -->
+A simple filter that uses the [`addDays`](https://date-fns.org/v2.21.3/docs/addDays) to add days to the current date (`Date.now()`)
+
+Keep in mind that this filter returns a date that needs to be formatted, so needs to be used with the `date` filter, like this:
+
+`{{ 1 | days_after | date }}` same as `{{ "tomorrow" | date }}`
+
+`{{ 2 | days_after | date }}` return the date from two days from now
 
 ## Template context
 
 Other than the classic, `date`, `time` and `title` variable you also have:
 
-| Name                | Description                                                                                                                              |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Name                | Description                                                                                                                                         |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
 | default_date_format | The date format that you have specified in the plugin settings and can be used like this: <code>{{ "now" &#124; date: default_date_format }}</code> |
 | default_time_format | The time format that you have specified in the plugin settings and can be used like this: <code>{{ "now" &#124; date: default_time_format }}</code> |
 

src/engine/filters/base_filter.ts

@@ -2,17 +2,22 @@ import { Liquid, FilterImplOptions } from 'liquidjs';
 
 import LiquidTemplates from '../../main';
 
-export default class BaseFilter {
+export interface BaseFilterProps {
+  engine: Liquid,
+  plugin: LiquidTemplates,
+  filterName?: string;
+}
+
+export class BaseFilter {
   readonly plugin: LiquidTemplates;
   readonly engine: Liquid;
-  readonly filterName: string = 'base_filter';
+  readonly filterName: string;
   handler: FilterImplOptions;
 
-  constructor(plugin: LiquidTemplates, engine: Liquid) {
+  constructor({ plugin, engine, filterName }: BaseFilterProps) {
     this.plugin = plugin;
     this.engine = engine;
-
-    this.register();
+    this.filterName = filterName;
   }
 
   register(): void {

src/engine/filters/date.ts

@@ -1,9 +1,14 @@
 import { addDays, format, subDays } from 'date-fns';
 
-import BaseFilter from './base_filter';
+import { BaseFilter, BaseFilterProps } from './base_filter';
 
 export default class DateFiler extends BaseFilter {
-  filterName = 'date';
+  originalFilter: Function;
+
+  constructor(props: BaseFilterProps) {
+    super({ ...props, filterName: 'date' });
+    this.originalFilter = this.engine.filters.get('date');
+  }
 
   handler = (givenValue: number | string, dateFormat?: string): string | number => {
     const dateToFormat = (typeof givenValue === 'number')
@@ -11,6 +16,12 @@ export default class DateFiler extends BaseFilter {
       : this.parseDate(givenValue)
     const formatToUse = dateFormat || this.plugin.settings.dateFormat;
 
+    // TODO: improve or remove me: keep backwards compatibility with the current 0.1.5 version
+    if (formatToUse.includes('%')) {
+      // TODO: send a notification when using this function
+      return this.originalFilter(givenValue, dateFormat);
+    }
+
     try {
       return format(dateToFormat, formatToUse)
     } catch (e) {

src/engine/filters/days_after.ts

@@ -1,9 +1,11 @@
 import { addDays } from 'date-fns';
 
-import BaseFilter from './base_filter';
+import { BaseFilter, BaseFilterProps } from './base_filter';
 
 export default class DaysAfter extends BaseFilter {
-  filterName = 'days_after';
+  constructor(props: BaseFilterProps) {
+    super({ ...props, filterName: 'days_after' });
+  }
 
   handler = (daysToSub: number): Date => addDays(Date.now(), daysToSub);
 }

src/engine/filters/days_ago.ts

@@ -1,9 +1,11 @@
 import { subDays } from 'date-fns';
 
-import BaseFilter from './base_filter';
+import { BaseFilter, BaseFilterProps } from './base_filter';
 
 export default class DaysAgo extends BaseFilter {
-  filterName = 'days_ago';
+  constructor(props: BaseFilterProps) {
+    super({ ...props, filterName: 'days_ago' });
+  }
 
   handler = (daysToSub: number): Date => subDays(Date.now(), daysToSub);
 }

src/engine/index.ts

@@ -13,7 +13,7 @@ export function applyCustomFilters(engine: Liquid, plugin: LiquidTemplates) {
     DateFilter,
     DaysAgo,
     DaysAfter
-  ].forEach(filter => new filter(plugin, engine))
+  ].forEach(filter => new filter({ plugin, engine }).register())
 }
 
 export function initEngine(app: App, plugin: LiquidTemplates): Liquid {