|
| 1 | +# Calendar API Feed |
| 2 | + |
| 3 | +The CalendarApiFeedType retrieves locations, resources and events from 3 JSON endpoints |
| 4 | +set in the environment variables: |
| 5 | + |
| 6 | +```dotenv |
| 7 | +CALENDAR_API_FEED_SOURCE_LOCATION_ENDPOINT= |
| 8 | +CALENDAR_API_FEED_SOURCE_RESOURCE_ENDPOINT= |
| 9 | +CALENDAR_API_FEED_SOURCE_EVENT_ENDPOINT= |
| 10 | +``` |
| 11 | + |
| 12 | +## Mapping the json data |
| 13 | + |
| 14 | +By default, the three endpoints should return data as follows: |
| 15 | + |
| 16 | +### Locations |
| 17 | + |
| 18 | +```json |
| 19 | +[ |
| 20 | + { |
| 21 | + "id": "Location Id 2", |
| 22 | + "displayName": "Location display name 1" |
| 23 | + }, |
| 24 | + { |
| 25 | + "id": "Location Id 2", |
| 26 | + "displayName": "Location display name 2" |
| 27 | + } |
| 28 | +] |
| 29 | +``` |
| 30 | + |
| 31 | +* The `id` (Mapping key: LOCATION_ID) should be unique for the location and is used to identify it in the resource relation. |
| 32 | +* The `displayName` (Mapping key: LOCATION_DISPLAY_NAME) is the name of the location in the admin. |
| 33 | + |
| 34 | +### Resources |
| 35 | + |
| 36 | +```json |
| 37 | +[ |
| 38 | + { |
| 39 | + "id": "Resource Id 1", |
| 40 | + "locationId": "Location Id 1", |
| 41 | + "displayName": "Resource 1", |
| 42 | + "includedInEvents": true |
| 43 | + }, |
| 44 | + { |
| 45 | + "id": "Resource Id 2", |
| 46 | + "locationId": "Location Id 1", |
| 47 | + "displayName": "Resource 2", |
| 48 | + "includedInEvents": false |
| 49 | + } |
| 50 | +] |
| 51 | +``` |
| 52 | + |
| 53 | +* The `id` (Mapping key: RESOURCE_ID) should be unique for the resource. |
| 54 | +* The `locationId` (Mapping key: RESOURCE_LOCATION_ID) is the id of the location the resource belongs to. |
| 55 | +* The `displayName` (Mapping key: RESOURCE_DISPLAY_NAME) is the name the resource is presented by in templates and admin. |
| 56 | +* The `includedInEvents` (Mapping key: RESOURCE_INCLUDED_IN_EVENTS) determines if the resource is included in the events |
| 57 | +endpoint. |
| 58 | + This property can be excluded in the data. If this is the case, it defaults to `true`. |
| 59 | + |
| 60 | +### Events |
| 61 | + |
| 62 | +```json |
| 63 | +[ |
| 64 | + { |
| 65 | + "title": "Event Title 1", |
| 66 | + "startTime": "2025-02-15T13:00:00+02:00", |
| 67 | + "endTime": "2025-02-15T13:30:00+02:00", |
| 68 | + "resourceDisplayName": "Resource 1", |
| 69 | + "resourceId": "Resource Id 1" |
| 70 | + }, |
| 71 | + { |
| 72 | + "title": "Event Title 2", |
| 73 | + "startTime": "2025-02-15T15:00:00+02:00", |
| 74 | + "endTime": "2025-02-15T15:30:00+02:00", |
| 75 | + "resourceDisplayName": "Resource 1", |
| 76 | + "resourceId": "Resource Id 1" |
| 77 | + } |
| 78 | +] |
| 79 | +``` |
| 80 | + |
| 81 | +* The `title` (Mapping key: EVENT_TITLE) is the title of the event. |
| 82 | +* The `startTime` (Mapping key: EVENT_START_TIME) is the start time of the event. |
| 83 | +Should be formatted as an `ISO 8601 date`, e.g. `2004-02-15T15:00:00+02:00`. |
| 84 | +* The `endTime` (Mapping key: EVENT_END_TIME) is the end time of the event. |
| 85 | +Should be formatted as an `ISO 8601 date`, e.g. `2004-02-15T15:30:00+02:00`. |
| 86 | +* The `resourceDisplayName` (Mapping key: EVENT_RESOURCE_ID) is display name of the resource the event belongs to. |
| 87 | +* The `resourceId` (Mapping key: EVENT_RESOURCE_DISPLAY_NAME) is the id of the resource the event belongs to. |
| 88 | + |
| 89 | +## Overriding mappings |
| 90 | + |
| 91 | +Mappings can be overridden changing the following environment variable: |
| 92 | + |
| 93 | +```dotenv |
| 94 | +CALENDAR_API_FEED_SOURCE_CUSTOM_MAPPINGS='{}' |
| 95 | +``` |
| 96 | + |
| 97 | +E.g. |
| 98 | + |
| 99 | +```dotenv |
| 100 | +CALENDAR_API_FEED_SOURCE_CUSTOM_MAPPINGS='{ |
| 101 | + "LOCATION_ID": "Example1", |
| 102 | + "LOCATION_DISPLAY_NAME": "Example2", |
| 103 | + "RESOURCE_ID": "Example3", |
| 104 | + "RESOURCE_LOCATION_ID": "Example4", |
| 105 | + "RESOURCE_DISPLAY_NAME": "Example5", |
| 106 | + "RESOURCE_INCLUDED_IN_EVENTS": "Example6", |
| 107 | + "EVENT_TITLE": "Example7", |
| 108 | + "EVENT_START_TIME": "Example8", |
| 109 | + "EVENT_END_TIME": "Example9", |
| 110 | + "EVENT_RESOURCE_ID": "Example10", |
| 111 | + "EVENT_RESOURCE_DISPLAY_NAME": "Example11" |
| 112 | +}' |
| 113 | +``` |
| 114 | + |
| 115 | +## Dates |
| 116 | + |
| 117 | +By default, dates are assumed to be `Y-m-d\TH:i:sP` e.g. `2004-02-15T15:00:00+02:00`. |
| 118 | + |
| 119 | +If another date format is supplied for the date fields, these can be set with: |
| 120 | + |
| 121 | +```dotenv |
| 122 | +CALENDAR_API_FEED_SOURCE_DATE_FORMAT= |
| 123 | +CALENDAR_API_FEED_SOURCE_DATE_TIMEZONE= |
| 124 | +``` |
| 125 | + |
| 126 | +E.g. |
| 127 | + |
| 128 | +```dotenv |
| 129 | +CALENDAR_API_FEED_SOURCE_DATE_FORMAT="m/d/YH:i:s" |
| 130 | +CALENDAR_API_FEED_SOURCE_DATE_TIMEZONE="Europe/Copenhagen" |
| 131 | +``` |
| 132 | + |
| 133 | +## Modifiers |
| 134 | + |
| 135 | +Modifiers can be set up to modify the output of the feed. |
| 136 | + |
| 137 | +Two types of modifiers are available: |
| 138 | + |
| 139 | +* EXCLUDE_IF_TITLE_NOT_CONTAINS: Removes entries from the feed if the title not contain the trigger word. |
| 140 | +* REPLACE_TITLE_IF_CONTAINS: Changes the title if it contains the trigger word. |
| 141 | + |
| 142 | +Parameters: |
| 143 | + |
| 144 | +* type: EXCLUDE_IF_TITLE_NOT_CONTAINS or REPLACE_TITLE_IF_CONTAINS |
| 145 | +* id: Unique identifier for the modifier. |
| 146 | +* title: Display name when showing the modifier in the admin. |
| 147 | +* description: Help text for the modifier. |
| 148 | +* activateInFeed: Should this filter be optional? If false the rule will always apply. |
| 149 | +* trigger: The string that should trigger the modifier. |
| 150 | +* replacement: The string to replace the title with. |
| 151 | +* removeTrigger: Should the trigger word be filtered from the title? |
| 152 | +* caseSensitive: Should the trigger word be case-sensitive? |
| 153 | + |
| 154 | +Examples of modifiers: |
| 155 | + |
| 156 | +```json |
| 157 | +[ |
| 158 | + { |
| 159 | + "type": "EXCLUDE_IF_TITLE_NOT_CONTAINS", |
| 160 | + "id": "excludeIfNotContainsListe", |
| 161 | + "title": "Vis kun begivenheder med (liste) i titlen.", |
| 162 | + "description": "Denne mulighed fjerner begivenheder, der IKKE har (liste) i titlen. Den fjerner også (liste) fra titlen.", |
| 163 | + "activateInFeed": true, |
| 164 | + "trigger": "(liste)", |
| 165 | + "removeTrigger": true, |
| 166 | + "caseSensitive": false |
| 167 | + }, |
| 168 | + { |
| 169 | + "type": "REPLACE_TITLE_IF_CONTAINS", |
| 170 | + "id": "replaceIfContainsOptaget", |
| 171 | + "activateInFeed": false, |
| 172 | + "trigger": "(optaget)", |
| 173 | + "replacement": "Optaget", |
| 174 | + "removeTrigger": true, |
| 175 | + "caseSensitive": false |
| 176 | + }, |
| 177 | + { |
| 178 | + "type": "REPLACE_TITLE_IF_CONTAINS", |
| 179 | + "id": "onlyShowAsOptaget", |
| 180 | + "activateInFeed": true, |
| 181 | + "title": "Overskriv alle titler med Optaget", |
| 182 | + "description": "Denne mulighed viser alle titler som Optaget.", |
| 183 | + "trigger": "", |
| 184 | + "replacement": "Optaget", |
| 185 | + "removeTrigger": false, |
| 186 | + "caseSensitive": false |
| 187 | + } |
| 188 | +] |
| 189 | +``` |
0 commit comments