From c692c8dbf3d9c0f7203d6ee28c3a2d7160038c76 Mon Sep 17 00:00:00 2001
From: Kristjan ESPERANTO <35647502+KristjanESPERANTO@users.noreply.github.com>
Date: Fri, 6 Feb 2026 01:04:20 +0100
Subject: [PATCH] docs(calendar): clarify pastDaysCount and broadcastPastEvents
Resolves #290
- Clarify that pastDaysCount only affects broadcasts, not display
- Explain that broadcastPastEvents requires pastDaysCount to be set
- Fix incorrect reference to maximumNumberOfDays (should be pastDaysCount)
- Emphasize that calendar module never displays past events
The previous documentation caused confusion as users expected
pastDaysCount to show past events in the calendar display, when
it only affects the CALENDAR_EVENTS broadcast to other modules.
---
modules/calendar.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/modules/calendar.md b/modules/calendar.md
index 515d0881..aa528b73 100755
--- a/modules/calendar.md
+++ b/modules/calendar.md
@@ -28,7 +28,7 @@ The following properties can be configured:
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maximumEntries` | The maximum number of events shown. / **Possible values:** `0` - `100`
**Default value:** `10` |
| `maximumNumberOfDays` | The maximum number of days in the future.
**Default value:** `365` |
-| `pastDaysCount` | The number of days of which events in the past should be displayed.
**Default value:** `0`
`NOTE: this value is advisory to any module processing the events broadcast.`
`the default calendar module never displays events from the past` |
+| `pastDaysCount` | The number of days in the past to include when broadcasting events to other modules (via `CALENDAR_EVENTS`). This option does **not** make the calendar module display past events — the calendar module only ever shows upcoming events. It must be used together with `broadcastPastEvents: true` to have any effect.
**Possible values:** `0` - `365`
**Default value:** `0` |
| `displaySymbol` | Display a symbol in front of an entry.
**Possible values:** `true` or `false`
**Default value:** `true` |
| `defaultSymbol` | The default symbol.
**Possible values:** See [Font Awesome](https://fontawesome.com/search?ic=free&o=r) website.
**Default value:** `calendar-days` |
| `showLocation` | Whether to show event locations.
**Possible values:** `true` or `false`
**Default value:** `false` |
@@ -58,7 +58,7 @@ The following properties can be configured:
| `hidePrivate` | Hides private calendar events.
**Possible values:** `true` or `false`
**Default value:** `false` |
| `hideOngoing` | Hides calendar events that have already started.
**Possible values:** `true` or `false`
**Default value:** `false` |
| `excludedEvents` | An array of words / phrases from event titles that will be excluded from being shown.
Additionally advanced filter objects can be passed in. Below is the configuration for the advance filtering object.
**Required**
`filterBy` - string used to determine if filter is applied.
**Optional**
`until` - Time before an event to display it Ex: [`'3 days'`, `'2 months'`, `'1 week'`]
`caseSensitive` - By default, excludedEvents are case insensitive, set this to true to enforce case sensitivity
`regex` - set to `true` if filterBy is a regex. For those not familiar with regex it is used for pattern matching, please see [here](https://regexr.com/) for more info.
**Example:** `['Birthday', 'Hide This Event', {filterBy: 'Payment', until: '6 days', caseSensitive: true}, {filterBy: '^[0-9]{1,}.*', regex: true}]`
**Default value:** `[]` |
-| `broadcastPastEvents` | If this is set to true, events from the past `maximumNumberOfDays` will be included in event broadcasts
**Default value:** `false` |
+| `broadcastPastEvents` | If set to true, past events will be included in the `CALENDAR_EVENTS` broadcast to other modules. Use `pastDaysCount` to control how many days in the past are included. This does **not** affect the calendar display itself — past events are never shown in the calendar module.
**Possible values:** `true` or `false`
**Default value:** `false` |
| `sliceMultiDayEvents` | If this is set to true, events exceeding at least one midnight will be sliced into separate events including a counter like (1/2). This is especially helpful in "dateheaders" mode. Events will be sliced at midnight, end time for all events but the last will be 23:59
**Default value:** `false` |
| `nextDaysRelative` | If this is set to true, the **FULL DAY** appointments of today and tomorrow are displayed relatively, even if the timeformat is set to absolute.
**Default value:** `false` |
| `customEvents` | An array of `keyword`/`symbol`/`color`/`transform` that will customize events based on keyword in title.
`keyword` is a case-insensitive string that if present in event title will trigger the use of custom symbol and/or color for that event,
`symbol` is the Font Awesome icon to use as symbol and
`color` is the CSS color to use for the event.
`transform` is an object for regular expression text replacement of the calendar title consisting of the following elements:
- `search` regular expression to search for
- `replace` replace string, may contain group match references
- `yearmatchgroup` (optional) the regex match group of a year that you want to replace to the current age
`keyword` and at least one of `symbol`, `color`, `transform` is required.
**Examples:**
`customEvents: [{keyword: 'Birthday', symbol: 'birthday-cake', color: 'Gold'}]`
`customEvents: [{keyword: 'Geburtstag', symbol: 'birthday-cake', color: 'Gold', transform: { search: '^([^\']*) \'(\\d{4})$' , replace: '$1 ($2.)', yearmatchgroup: 2}},{keyword: 'in Hamburg', transform: { search: ' in Hamburg$' , replace: ''}} ]`
Will transform
to
 |