. | all_startdate |
+| sortdir | Sort direction for sorting the output. Unused when the sortby property contains a valid JSON object. | ASC |
+| start | The start date to filter the displayed events. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | today 0:00 |
+| toPlaceholder | If set, the snippet result will be assigned to this placeholder instead of outputting it directly. | - |
+| totalVar | The key of a placeholder that indicates the total number of events. | agendalist.total |
+| tpl | Name of a chunk that contains the template for one event. | tplAgendaEventRow |
+| usergroups | Comma separated list of user group names to filter the displayed events. | - |
+| users | Comma separated list of user IDs to filter the displayed events. | - |
+| videoTpl | Name of a chunk that contains the template for one video in the video list of an event. | tplAgendaEventVideo |
+| where | **Since 1.5.0** JSON encoded xPDO where clause to filter the displayed events. | - |
+| wrapperTpl | Name of a chunk that contains the wrapper template for all events. | tplAgendaEventWrapper |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaEventRow
+
+| Placeholder | Description |
+|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| allday | Contains 1 if the event is an all day event (otherwise 0). |
+| calendar_background | The background color of the calendar of the event. |
+| calendar_foreground | The foreground color of the calendar of the event. |
+| calendar_name | The calendar name. |
+| categories | All categories of the event formatted by the chunk set with the categoryTpl property |
+| description | The description of the event. |
+| detail_url | The url that shows the event detail. Will be generated with the system/context setting `agenda.detail_id`. This resource should contain an AgendaDetail snippet call. |
+| duration | The formatted duration of the event. The details of the duration could be set with the `durationParts` snippet property. |
+| enddate | The start date of the event formatted in ISO 8601 (could be formatted i.e. with ```[[+enddate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| idx | The number of the event starting with 1. |
+| images | All images of the event formatted by the chunk set with the imageTpl property |
+| imageurls | An array of all image urls. The placeholder `[[+imageurls.1]]` contains the url of the first image |
+| location | The location of the event formatted by the chunk set with the locationTpl property |
+| range | The formatted date range of the event. The format is defined with the lexicon entries `agenda.php_format_daterange` and `agenda.php_format_separator` and could be overridden by the `daterangeFormat` snippet property. The [format rules](#range-placeholder-format) are described below. |
+| repeating | Contains 1 if the event is an repeating event (otherwise 0). |
+| resource_id | The id of a linked resource of the event. |
+| startdate | The start date of the event formatted in ISO 8601 (could be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| title | The title of the event. |
+| videos | All videos of the event formatted by the chunk set with the videosTpl property |
+| videourls | An array of all video urls. The placeholder `[[+videourls.1]]` contains the url of the first video |
+
+[Extended fields](../06_Extended_Fields) are available as placeholder with the prefix `extended` in the
+event row template.
+
+### tplAgendaEventWrapper
+
+| Placeholder | Description |
+|-------------|---------------------------------------------------------------------------------------------|
+| count | Count of the events filtered by the snippet properties (without limit/offset) |
+| output | All events collected by the snippet separated by the string in the outputSeparator property |
+
+### tplAgendaEventEmpty
+
+Only the current script properties are available as placeholders.
+
+### tplAgendaEventCategory
+
+| Placeholder | Description |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| alias | The alias of the category. |
+| background | The background color of the category of the event. |
+| foreground | The foreground color of the category of the event. |
+| name | The name of the category. |
+| resource_id | The id of a linked resource of the category. |
+| selected | Contains `selected="selected"`, when the category request value is equal to the alias of the category. |
+| url | The url that shows the event list filtered by the displayed category. Will be generated with the system/context setting `agenda.list_id`. This resource should contain an AgendaList snippet call. |
+
+### tplAgendaEventImage
+
+| Placeholder | Description |
+|-------------|------------------------------------------|
+| description | The description of the image. |
+| idx | The number of the image starting with 1. |
+| title | The title of the image. |
+| url | The url that shows the event image. |
+
+### tplAgendaEventLocation
+
+| Placeholder | Description |
+|-------------|--------------------------------------------------------------------------------------------------------|
+| address | The address of the location. |
+| alias | The alias of the location. |
+| center_lat | The latitude of the center of a map of the location. |
+| center_lng | The longitude of the center of a map of the location. |
+| description | The description of the location. |
+| lat | The latitude of the location. |
+| lng | The longitude of the location. |
+| name | The name of the location. |
+| resource_id | The id of a linked resource of the location. |
+| selected | Contains `selected="selected"`, when the location request value is equal to the alias of the location. |
+| zoom | The zoom level of a map of the location. |
+
+### tplAgendaEventVideo
+
+| Placeholder | Description |
+|-------------|------------------------------------------|
+| description | The description of the video. |
+| idx | The number of the video starting with 1. |
+| title | The title of the video. |
+| url | The url that shows the event video. |
+
+## Range placeholder format
+
+The `range` placeholder could be formatted with the lexicon entries
+`agenda.php_format_daterange` and `agenda.php_format_separator` or the snippet
+properties `daterangeFormat` and `daterangeSeparator`. The format string has to
+use exactly 7 parts separated by `|`. The default english lexicon entry is
+`j.| F |Y|, |g|:i a|`.
+
+The daterrange is formatted with the following rules:
+
+- If both dates are different and the hour/minute of start and end is 0, parts 4-7 are removed from start and end date.
+- If both dates are different and the hour/minute of start and end is 0 and year of start and end is equal, parts 4-7 are removed from start and end date and part 3 is removed from start date.
+- If both dates are different and the hour/minute of start and end is 0 and year and month of start and end are equal, parts 4-7 are removed from start and end date and parts 2-3 are removed from start date.
+- If both dates are different and the hour/minute of start and end is 0 and year, month and day of start and end are equal, parts 4-7 are removed from start and end date and parts 1-3 are removed from start date.
+- If both dates are different and the hour/minute of start and end is not 0 and one detail of year, month and day of start and end is not equal, all parts are used in the start and end date.
+- If both dates are different and the hour/minute of start and the hour of end is 0 and all details of year, month and day of start and end are equal, parts 4-7 are removed from start date.
+- If both dates are different and the hour or minute of start or the hour of end not 0 and all details of year, month and day of start and end are equal, part 7 is removed from start date.
+- If both dates are equal and the hour/minute of start is 0, part 4-7 is removed from the start date and separator and end date are removed.
+- If both dates are equal and the hour/minute of start is not 0, separator and end date are removed.
diff --git a/en/01_Agenda/v1/04_Snippets/02_AgendaCalendar.md b/en/01_Agenda/v1/04_Snippets/02_AgendaCalendar.md
new file mode 100755
index 00000000..b7072e97
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/02_AgendaCalendar.md
@@ -0,0 +1,146 @@
+This snippet displays events in a list view separared into intervals. The
+snippet was introduced with Agenda 1.1.0.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
+| active | **Since 1.6.3** If this option is disabled, the active status of an event is not regarded. | 1 (Yes) |
+| ajax | **Since 1.4.0** If set, the snippet output will be directly returned to the browser as a JSON result when the page is requested with the same value in the ajax request parameter. | 0 (No) |
+| allowedRequestKeys | Comma-separated list of request keys, that can be used to filter the displayed events. Defaults to all allowed. | - |
+| calendars | Comma-separated list of aliases of calendars to filter the displayed events. | - |
+| categories | Comma separated list of aliases of categories to filter the displayed events. | - |
+| categoryTpl | Name of a chunk that contains the template of one category in the category list of an event. | tplAgendaEventCategory |
+| contexts | Comma separated list of context keys to filter the displayed events. | - |
+| daterangeFormat | Format of the daterange displayed in an event. | - |
+| daterangeSeparator | Separator in the daterange displayed in an event. | - |
+| detailId | ID of a resource containing an AgendaDetail snippet call. | - |
+| durationParts | Number of detail parts of the event duration output. | 1 |
+| durationRound | **Since 1.5.0** Rounding type for event duration. | ceil |
+| end | The end date to filter the displayed events. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | - |
+| excludeEvents | Comma separated list of event IDs to exclude from the displayed events. | - |
+| excludeRepeats | Comma separated list of repeating event IDs to exclude from the displayed events. | - |
+| imageTpl | Name of a chunk that contains the template for one image in the image list of an event. | tplAgendaEventImage |
+| interval | The interval into which the period between start and end date is divided. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | - |
+| intervalTpl | Name of a chunk that contains the template for an interval. | tplAgendaEventInterval |
+| listId | ID of a resource containing an AgendaList snippet call. | - |
+| locale | The locale for the displayed formatted date. Defaults to the current system/context locale setting. | - |
+| locations | Comma separated list of aliases of locations to filter the displayed events. | - |
+| locationTpl | Name of a chunk that contains the template for the location of an event. | tplAgendaEventLocation |
+| outputSeparator | An optional string to separate each tpl instance. | - |
+| resourceTpl | Name of a chunk that contains the template for the linked resource of an event. | - |
+| start | The start date to filter the displayed events. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | - |
+| toPlaceholder | If set, the snippet result will be assigned to this placeholder instead of outputting it directly. | - |
+| tpl | Name of a chunk that contains the template for one event. | tplAgendaEventRow |
+| usergroups | Comma separated list of user group names to filter the displayed events. | - |
+| users | Comma separated list of user IDs to filter the displayed events. | - |
+| videoTpl | Name of a chunk that contains the template for one video in the video list of an event. | tplAgendaEventVideo |
+| where | **Since 1.5.0** JSON encoded xPDO where clause to filter the displayed events. | - |
+| wrapperTpl | Name of a chunk that contains the wrapper template for all events. | tplAgendaEventWrapper |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaEventRow
+
+| Placeholder | Description |
+|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| allday | Contains 1 if the event is an all day event (otherwise 0). |
+| calendar_background | The background color of the calendar of the event. |
+| calendar_foreground | The foreground color of the calendar of the event. |
+| calendar_name | The calendar name. |
+| categories | All categories of the event formatted by the chunk set with the categoryTpl property |
+| description | The title of the event. |
+| detail_url | The url that shows the event detail. Will be generated with the system/context setting `agenda.detail_id`. This resource should contain an AgendaDetail snippet call. |
+| duration | The formatted duration of the event. The details of the duration can be set with the `durationParts` snippet property. |
+| enddate | The start date of the event formatted in ISO 8601 (can be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| idx | The number of the event starting with 1. |
+| images | All images of the event formatted by the chunk set with the imageTpl property |
+| imageurls | An array of all image urls. The placeholder `[[+imageurls.1]]` contains the url of the first image |
+| location | The location of the event formatted by the chunk set with the locationTpl property |
+| range | The formatted date range of the event. The format is defined with the lexicon entries `agenda.php_format_daterange` and `agenda.php_format_separator` and can be overridden by the `daterangeFormat` snippet property. The [format rules](01_AgendaList#range-placeholder-format) are described on the AgendaList page. |
+| repeating | Contains 1 if the event is an repeating event (otherwise 0). |
+| resource_id | The id of a linked resource of the event. |
+| startdate | The start date of the event formatted in ISO 8601 (can be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| title | The title of the event. |
+| videos | All videos of the event formatted by the chunk set with the videosTpl property |
+| videourls | An array of all video urls. The placeholder `[[+videourls.1]]` contains the url of the first video |
+
+[Extended fields](../06_Extended_Fields) are available as placeholder with the prefix `extended` in the
+event row template.
+
+### tplAgendaInterval
+
+| Placeholder | Description |
+|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| count | Count of the events filtered by the snippet properties (without limit/offset) |
+| output | All events in one interval collected by the snippet separated by the string in the outputSeparator property |
+| startdate | The start date of the interval formatted in ISO 8601 (could be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| enddate | The end date of the interval formatted in ISO 8601 (could be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| range | The formatted date range of the interval. The format is defined with the lexicon entries `agenda.php_format_daterange` and `agenda.php_format_separator` and could be overridden by the `daterangeFormat` snippet property. The [format rules](01_AgendaList#range-placeholder-format) are described below. |
+| idy | The number of the interval starting with 1. |
+
+### tplAgendaEventWrapper
+
+| Placeholder | Description |
+|-------------|------------------------------------------------------------------------------------------------|
+| output | All intervals collected by the snippet separated by the string in the outputSeparator property |
+
+### tplAgendaEventEmpty
+
+Only the current script properties are available as placeholders.
+
+### tplAgendaEventCategory
+
+| Placeholder | Description |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| alias | The alias of the category. |
+| background | The background color of the category of the event. |
+| foreground | The foreground color of the category of the event. |
+| name | The name of the category. |
+| resource_id | The id of a linked resource of the category. |
+| selected | Contains `selected="selected"`, when the category request value is equal to the alias of the category. |
+| url | The url that shows the event list filtered by the displayed category. Will be generated with the system/context setting `agenda.list_id`. This resource should contain an AgendaList snippet call. |
+
+### tplAgendaEventImage
+
+| Placeholder | Description |
+|-------------|------------------------------------------|
+| description | The description of the image. |
+| idx | The number of the image starting with 1. |
+| title | The title of the image. |
+| url | The url that shows the event image. |
+
+### tplAgendaEventLocation
+
+| Placeholder | Description |
+|-------------|--------------------------------------------------------------------------------------------------------|
+| address | The address of the location. |
+| alias | The alias of the location. |
+| center_lat | The latitude of the center of a map of the location. |
+| center_lng | The longitude of the center of a map of the location. |
+| description | The description of the location. |
+| lat | The latitude of the location. |
+| lng | The longitude of the location. |
+| name | The name of the location. |
+| resource_id | The id of a linked resource of the location. |
+| selected | Contains `selected="selected"`, when the location request value is equal to the alias of the location. |
+| zoom | The zoom level of a map of the location. |
+
+### tplAgendaEventVideo
+
+| Placeholder | Description |
+|-------------|------------------------------------------|
+| description | The description of the video. |
+| idx | The number of the video starting with 1. |
+| title | The title of the video. |
+| url | The url that shows the event video. |
diff --git a/en/01_Agenda/v1/04_Snippets/03_AgendaDetail.md b/en/01_Agenda/v1/04_Snippets/03_AgendaDetail.md
new file mode 100755
index 00000000..0e37b88d
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/03_AgendaDetail.md
@@ -0,0 +1,129 @@
+This snippet displays one event in a detail view.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
+| active | If this option is disabled, the active status of an event is not regarded. | 1 (Yes) |
+| ajax | **Since 1.4.0** If set, the snippet output will be directly returned to the browser as a JSON result when the page is requested with the same value in the ajax request parameter. | 0 (No) |
+| allowedRequestKeys | Comma-separated list of request keys, that can be used to filter the displayed event. Defaults to all allowed. | - |
+| calendars | Comma-separated list of aliases of calendars to filter the displayed event. | - |
+| categories | Comma separated list of aliases of categories to filter the displayed event. | - |
+| categoryTpl | Name of a chunk that contains the template of one category in the category list of an event. | tplAgendaEventCategory |
+| contexts | Comma separated list of context keys to filter the displayed event. | - |
+| daterangeFormat | Format of the daterange displayed in an event. | - |
+| daterangeSeparator | Separator in the daterange displayed in an event. | - |
+| detailId | ID of a resource containing an AgendaDetail snippet call. | - |
+| durationParts | Number of detail parts of the event duration output. | 1 |
+| durationRound | **Since 1.5.0** Rounding type for event duration. | ceil |
+| emptyTpl | Name of a chunk that contains the template for not found event. | tplAgendaEventEmpty |
+| id | ID of one event to retrieve the displayed event. | - |
+| imageTpl | Name of a chunk that contains the template for one image in the image list of an event. | tplAgendaEventImage |
+| listId | ID of a resource containing an AgendaList snippet call. | - |
+| locale | The locale for the displayed formatted date. Defaults to the current system/context locale setting. | - |
+| locations | Comma separated list of aliases of locations to filter the displayed event. | - |
+| locationTpl | Name of a chunk that contains the template for the location of an event. | tplAgendaEventLocation |
+| repeating | ID of one repeating event to retrieve the displayed event. | - |
+| resourceTpl | Name of a chunk that contains the template for the linked resource of an event. | - |
+| toPlaceholder | If set, the snippet result will be assigned to this placeholder instead of outputting it directly. | - |
+| tpl | Name of a chunk that contains the template for one event. | tplAgendaEventDetail |
+| usergroups | Comma separated list of user group names to filter the displayed event. | - |
+| users | Comma separated list of user IDs to filter the displayed event. | - |
+| videoTpl | Name of a chunk that contains the template for one video in the video list of an event. | tplAgendaEventVideo |
+| where | **Since 1.5.0** JSON encoded xPDO where clause to filter the event. | - |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaEventDetail
+
+| Placeholder | Description |
+|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| allday | Contains 1 if the event is an all day event (otherwise 0). |
+| calendar_background | The background color of the calendar of the event. |
+| calendar_foreground | The foreground color of the calendar of the event. |
+| calendar_name | The calendar name. |
+| categories | All categories of the event formatted by the chunk set with the categoryTpl property |
+| description | The title of the event. |
+| detail_url | The url that shows the event detail. Will be generated with the system/context setting `agenda.detail_id`. This resource should contain an AgendaDetail snippet call. |
+| duration | The formatted duration of the event. The details of the duration can be set with the `durationParts` snippet property. |
+| enddate | The start date of the event formatted in ISO 8601 (can be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| images | All images of the event formatted by the chunk set with the imageTpl property |
+| imageurls | An array of all image urls. The placeholder `[[+imageurls.1]]` contains the url of the first image |
+| location | The location of the event formatted by the chunk set with the locationTpl property |
+| range | The formatted date range of the event. The format is defined with the lexicon entries `agenda.php_format_daterange` and `agenda.php_format_separator` and can be overridden by the `daterangeFormat` snippet property. The [format rules](01_AgendaList#range-placeholder-format) are described on the AgendaList page. |
+| repeating | Contains 1 if the event is an repeating event (otherwise 0). |
+| resource_id | The id of a linked resource of the event. |
+| startdate | The start date of the event formatted in ISO 8601 (can be formatted i.e. with ```[[+startdate:strtotime:date=`%a. %d.%m.%Y`]]```). |
+| title | The title of the event. |
+| videos | All videos of the event formatted by the chunk set with the videosTpl property |
+| videourls | An array of all video urls. The placeholder `[[+videourls.1]]` contains the url of the first video |
+
+[Extended fields](../06_Extended_Fields) are available as placeholder with the prefix `extended` in the
+event row template.
+
+### tplAgendaEventWrapper
+
+| Placeholder | Description |
+|-------------|---------------------------------------------------------------------------------------------|
+| count | Count of the events filtered by the snippet properties (without limit/offset) |
+| output | All events collected by the snippet separated by the string in the outputSeparator property |
+
+### tplAgendaEventEmpty
+
+Only the current script properties are available as placeholders.
+
+### tplAgendaEventCategory
+
+| Placeholder | Description |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| alias | The alias of the category. |
+| background | The background color of the category of the event. |
+| foreground | The foreground color of the category of the event. |
+| name | The name of the category. |
+| resource_id | The id of a linked resource of the category. |
+| selected | Contains `selected="selected"`, when the category request value is equal to the alias of the category. |
+| url | The url that shows the event list filtered by the displayed category. Will be generated with the system/context setting `agenda.list_id`. This resource should contain an AgendaList snippet call. |
+
+### tplAgendaEventImage
+
+| Placeholder | Description |
+|-------------|------------------------------------------|
+| description | The description of the image. |
+| idx | The number of the image starting with 1. |
+| title | The title of the image. |
+| url | The url that shows the event image. |
+
+### tplAgendaEventLocation
+
+| Placeholder | Description |
+|-------------|--------------------------------------------------------------------------------------------------------|
+| address | The address of the location. |
+| alias | The alias of the location. |
+| center_lat | The latitude of the center of a map of the location. |
+| center_lng | The longitude of the center of a map of the location. |
+| description | The description of the location. |
+| lat | The latitude of the location. |
+| lng | The longitude of the location. |
+| name | The name of the location. |
+| resource_id | The id of a linked resource of the location. |
+| selected | Contains `selected="selected"`, when the location request value is equal to the alias of the location. |
+| zoom | The zoom level of a map of the location. |
+
+### tplAgendaEventVideo
+
+| Placeholder | Description |
+|-------------|------------------------------------------|
+| description | The description of the video. |
+| idx | The number of the video starting with 1. |
+| title | The title of the video. |
+| url | The url that shows the event video. |
diff --git a/en/01_Agenda/v1/04_Snippets/04_AgendaDetailIcal.md b/en/01_Agenda/v1/04_Snippets/04_AgendaDetailIcal.md
new file mode 100755
index 00000000..559762ba
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/04_AgendaDetailIcal.md
@@ -0,0 +1,39 @@
+This snippet displays an iCalendar link or download an iCalendar file of an event.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|----------------|-----------------------------------------------------------------------------------------------------|------------------------------|
+| active | If this option is disabled, the active status of an event is not regarded. | 1 (Yes) |
+| calendars | Comma-separated list of aliases of calendars to filter the iCal download. | - |
+| categories | Comma separated list of aliases of categories to filter the iCal download. | - |
+| contexts | Comma separated list of context keys to filter the iCal download. | - |
+| descriptionTpl | Name of a chunk that contains the template for the description in the iCal event. | - |
+| id | ID of one event to retrieve the ical event. | - |
+| locale | The locale for the displayed formatted date. Defaults to the current system/context locale setting. | - |
+| locations | Comma separated list of aliases of locations to filter the iCal download. | - |
+| locationTpl | Name of a chunk that contains the template for the location of the ical event. | tplAgendaEventLocationICal |
+| repeating | ID of one repeating event to retrieve the ical event. | - |
+| tpl | Name of a chunk that contains the template for iCal download link. | tplAgendaEventDetailICalLink |
+| usergroups | Comma separated list of user group names to filter the iCal download. | - |
+| users | Comma separated list of user IDs to filter the iCal download. | - |
+| where | **Since 1.5.0** JSON encoded xPDO where clause to filter the ical event. | - |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaEventDetailIcal
+
+| Placeholder | Description |
+|-------------|-----------------------------------------------|
+| key | The request key for the iCal download link. |
+| value | The request value for the iCal download link. |
diff --git a/en/01_Agenda/v1/04_Snippets/05_AgendaCalendars.md b/en/01_Agenda/v1/04_Snippets/05_AgendaCalendars.md
new file mode 100755
index 00000000..994ebd26
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/05_AgendaCalendars.md
@@ -0,0 +1,57 @@
+This snippet displays a list of calendars.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| ajax | **Since 1.4.0** If set, the snippet output will be directly returned to the browser as a JSON result when the page is requested with the same value in the ajax request parameter. | 0 (No) |
+| allowedRequestKeys | Comma-separated list of request keys, that can be used to filter the displayed calendars. Defaults to all allowed. | - |
+| calendars | Comma-separated list of aliases of calendars to filter the displayed calendars. | - |
+| emptyTpl | Name of a chunk that contains the template for not found calendars. | tplAgendaCalendarsEmpty |
+| filterByEvents | **Since 1.5.0** If set, the calendars with no future events are filtered from the result. | 0 (No) |
+| limit | Limit the number of calendars in the result. Use "0" for unlimited calendars. | 20 |
+| listId | ID of a resource containing an AgendaList snippet call. | - |
+| offset | The offset of calendars to skip. | - |
+| outputSeparator | An optional string to separate each tpl instance. | - |
+| selected | Comma separated list of calendar aliases, that have the placeholder selected filled. | - |
+| sortby | **Since 1.5.0** Sort field for sorting the output. It could also contain a JSON object to sort the ouput by multiple fields like
. | sortindex |
+| sortdir | **Since 1.5.0** Sort direction for sorting the output. Unused when the sortby property contains a valid JSON object. | ASC |
+| toPlaceholder | If set, the snippet result will be assigned to this placeholder instead of outputting it directly. | - |
+| totalVar | The key of a placeholder that indicates the total number of calendars. | agendacalendars.total |
+| tpl | Name of a chunk that contains the template for one calendar. | tplAgendaCalendar |
+| where | **Since 1.5.0** JSON encoded xPDO where clause to filter the calendars. | - |
+| wrapperTpl | Name of a chunk that contains the wrapper template for all calendars. | tplAgendaCalendarsWrapper |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaCalendar
+
+| Placeholder | Description |
+|-------------|--------------------------------------------------------------------------------------------------------|
+| alias | The alias of the calendar. |
+| background | The background color of the calendar of the event. |
+| foreground | The foreground color of the calendar of the event. |
+| name | The name of the calendar. |
+| resource_id | The id of a linked resource of the calendar. |
+| selected | Contains `selected="selected"`, when the calendar request value is equal to the alias of the calendar. |
+
+### tplAgendaCalendarsEmpty
+
+Only the current script properties are available as placeholders.
+
+### tplAgendaCalendarsWrapper
+
+| Placeholder | Description |
+|-------------|------------------------------------------------------------------------------------------------|
+| count | Count of the calendars filtered by the snippet properties (without limit/offset) |
+| output | All calendars collected by the snippet separated by the string in the outputSeparator property |
diff --git a/en/01_Agenda/v1/04_Snippets/06_AgendaCategories.md b/en/01_Agenda/v1/04_Snippets/06_AgendaCategories.md
new file mode 100755
index 00000000..3fd35af8
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/06_AgendaCategories.md
@@ -0,0 +1,58 @@
+This snippet displays a list of categories.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| ajax | **Since 1.4.0** If set, the snippet output will be directly returned to the browser as a JSON result when the page is requested with the same value in the ajax request parameter. | 0 (No) |
+| allowedRequestKeys | Comma-separated list of request keys, that can be used to filter the displayed categories. Defaults to all allowed. | - |
+| categories | Comma-separated list of aliases of categories to filter the displayed categories. | - |
+| emptyTpl | Name of a chunk that contains the template for not found categories. | tplAgendaCategoriesEmpty |
+| filterByEvents | **Since 1.5.0** If set, the categories with no future events are filtered from the result. | 0 (No) |
+| limit | Limit the number of categories in the result. Use "0" for unlimited categories. | 20 |
+| listId | ID of a resource containing an AgendaList snippet call. | - |
+| offset | The offset of categories to skip. | - |
+| outputSeparator | An optional string to separate each tpl instance. | - |
+| selected | Comma separated list of category aliases, that have the placeholder selected filled. | - |
+| sortby | **Since 1.5.0** Sort field for sorting the output. It could also contain a JSON object to sort the ouput by multiple fields like
. | sortindex |
+| sortdir | **Since 1.5.0** Sort direction for sorting the output. Unused when the sortby property contains a valid JSON object. | ASC |
+| toPlaceholder | If set, the snippet result will be assigned to this placeholder instead of outputting it directly. | - |
+| totalVar | The key of a placeholder that indicates the total number of categories. | agendacategories.total |
+| tpl | Name of a chunk that contains the template for one category. | tplAgendaCategory |
+| where | **Since 1.5.0** **Since 1.5.0** JSON encoded xPDO where clause to filter the categories. | - |
+| wrapperTpl | Name of a chunk that contains the wrapper template for all categories. | tplAgendaCategoriesWrapper |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaCategory
+
+| Placeholder | Description |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| alias | The alias of the category. |
+| background | The background color of the category of the event. |
+| foreground | The foreground color of the category of the event. |
+| name | The name of the category. |
+| resource_id | The id of a linked resource of the category. |
+| selected | Contains `selected="selected"`, when the category request value is equal to the alias of the category. |
+| url | The url that shows the event list filtered by the displayed category. Will be generated with the system/context setting `agenda.list_id`. This resource should contain an AgendaList snippet call. |
+
+### tplAgendaCategoriesEmpty
+
+Only the current script properties are available as placeholders.
+
+### tplAgendaCategoriesWrapper
+
+| Placeholder | Description |
+|-------------|-------------------------------------------------------------------------------------------------|
+| count | Count of the categories filtered by the snippet properties (without limit/offset) |
+| output | All categories collected by the snippet separated by the string in the outputSeparator property |
diff --git a/en/01_Agenda/v1/04_Snippets/07_AgendaLocations.md b/en/01_Agenda/v1/04_Snippets/07_AgendaLocations.md
new file mode 100755
index 00000000..7fe0cf60
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/07_AgendaLocations.md
@@ -0,0 +1,62 @@
+This snippet displays a list of locations.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| ajax | **Since 1.4.0** If set, the snippet output will be directly returned to the browser as a JSON result when the page is requested with the same value in the ajax request parameter. | 0 (No) |
+| allowedRequestKeys | Comma-separated list of request keys, that can be used to filter the displayed locations. Defaults to all allowed. | - |
+| emptyTpl | Name of a chunk that contains the template for not found locations. | tplAgendaLocationsEmpty |
+| filterByEvents | **Since 1.5.0** If set, the locations with no future events are filtered from the result. | 0 (No) |
+| limit | Limit the number of locations in the result. Use "0" for unlimited locations. | 20 |
+| listId | ID of a resource containing an AgendaList snippet call. | - |
+| locations | Comma-separated list of aliases of locations to filter the displayed locations. | - |
+| offset | The offset of locations to skip. | - |
+| outputSeparator | An optional string to separate each tpl instance. | - |
+| selected | Comma separated list of calendar aliases, that have the placeholder selected filled. | - |
+| sortby | **Since 1.5.0** Sort field for sorting the output. It could also contain a JSON object to sort the ouput by multiple fields like
. | sortindex |
+| sortdir | **Since 1.5.0** Sort direction for sorting the output. Unused when the sortby property contains a valid JSON object. | ASC |
+| toPlaceholder | If set, the snippet result will be assigned to this placeholder instead of outputting it directly. | - |
+| totalVar | The key of a placeholder that indicates the total number of locations. | agendalocations.total |
+| tpl | Name of a chunk that contains the template for one location. | tplAgendaLocation |
+| where | **Since 1.5.0** JSON encoded xPDO where clause to filter the locations. | - |
+| wrapperTpl | Name of a chunk that contains the wrapper template for all locations. | tplAgendaLocationsWrapper |
+
+## Placeholders
+
+The following placeholders are available in the different (default) chunks. Each
+snippet property will be set as placeholder in each template chunk, i.e. a
+snippet call ```[[!AgendaDetail? &subtitle=`whatever`]]``` will fill the
+placeholder subtitle in each used chunk with the value `whatever`.
+
+**CAUTION:** The default template chunks for both snippets are overwritten
+during each package update, so please rename the chunks before editing them.
+
+### tplAgendaLocation
+
+| Placeholder | Description |
+|-------------|--------------------------------------------------------------------------------------------------------|
+| address | The address of the location. |
+| alias | The alias of the location. |
+| center_lat | The latitude of the center of a map of the location. |
+| center_lng | The longitude of the center of a map of the location. |
+| description | The description of the location. |
+| lat | The latitude of the location. |
+| lng | The longitude of the location. |
+| name | The name of the location. |
+| resource_id | The id of a linked resource of the location. |
+| selected | Contains `selected="selected"`, when the location request value is equal to the alias of the location. |
+| zoom | The zoom level of a map of the location. |
+
+### tplAgendaLocationsEmpty
+
+Only the current script properties are available as placeholders.
+
+### tplAgendaLocationsWrapper
+
+| Placeholder | Description |
+|-------------|------------------------------------------------------------------------------------------------|
+| count | Count of the locations filtered by the snippet properties (without limit/offset) |
+| output | All locations collected by the snippet separated by the string in the outputSeparator property |
diff --git a/en/01_Agenda/v1/04_Snippets/08_AgendaGetDate.md b/en/01_Agenda/v1/04_Snippets/08_AgendaGetDate.md
new file mode 100755
index 00000000..046c6652
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/08_AgendaGetDate.md
@@ -0,0 +1,11 @@
+This retrieves and format a date from a GET parameter. The snippet was
+introduced with Agenda 1.4.0.
+
+## Properties
+
+It uses the following snippet properties:
+
+| Property | Description | Default |
+|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
+| format | The output format for the date that is retrieved with a GET parameter. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | Y-m-d H:i:s |
+| requestKey | The GET parameter key that is used to retrieve a date. | date |
diff --git a/en/01_Agenda/v1/04_Snippets/09_AgendaEventGet.md b/en/01_Agenda/v1/04_Snippets/09_AgendaEventGet.md
new file mode 100755
index 00000000..31c44369
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/09_AgendaEventGet.md
@@ -0,0 +1,53 @@
+This hook loads the data of an Agenda event into FormIt fields. The hook was introduced with Agenda 1.1.0.
+
+The event is retrieved with the event ID or the repeat ID, if the event ID is
+not set. If no event can be retrieved, the hook returns false
+
+## FormIt Hook Properties
+
+The hook uses the following hook properties:
+
+| Property | Description | Default |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
+| agendaActiveOnly | Load only active events into FormIt. | true |
+| agendaCalendars | Comma-separated list of aliases of calendars to filter the loaded event. | - |
+| agendaCategories | Comma separated list of aliases of categories to filter the loaded event. | - |
+| agendaContexts | Comma separated list of context keys to filter the loaded event. | - |
+| agendaDateformat | Format of the startdate and enddate field, set by the hook. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | Y-m-d H:i:s |
+| agendaDateformatAllday | Format of the startdate and enddate field, set by the hook, when the event is an all day event. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | Y-m-d |
+| agendaId | ID of one event to load into FormIt. | 0 |
+| agendaLocations | Comma separated list of aliases of locations to filter the loaded event. | - |
+| agendaOwnEvent | Load only own events (created by the current user) into FormIt. | false |
+| agendaRepeating | ID of one repeating event to load into FormIt. | 0 |
+| agendaUsergroups | Comma separated list of user group names to filter the loaded event. | - |
+| agendaUsers | Comma separated list of user IDs to filter the loaded event. | - |
+
+## Hook fields
+
+The following FormIt fields are set by the loaded Agenda event in the hook.
+
+| Field | Description |
+|-----------------|----------------------------------------------------------------------------------------------------------------|
+| active | The active status of the loaded event. |
+| allday | The all day status of the loaded event. |
+| calendar | The alias of the calendar of the loaded event. |
+| calendar_id | The id of the calendar of the loaded event. |
+| category | The aliases of the categories of the loaded event. |
+| content | The content of the loaded event. |
+| context_key | The context key of the loaded event. |
+| description | The description of the loaded event. |
+| enddate | The enddate of the loaded event (or the loaded repeating event). |
+| id | The id of the loaded event. |
+| location | The alias of the location of the loaded event. |
+| location_id | The id of the location of the loaded event. |
+| repeat_enddate | The enddate of the repeats of the loaded event. |
+| repeat_interval | The repeat interval of the loaded event. |
+| repeat_on | The repeat weekdays of the loaded event, when the repeat type is weekly |
+| repeat_ordinal | The repeat ordinal of the loaded event, when the repeat type is monthly by weekday |
+| repeat_type | The repeat type of the loaded event. (1 = daily , 2 = weekly, 3 = monthly, 4 = yearly, 5 = montly by weekday ) |
+| repeat_weekday | The repeat weekday of the loaded event, when the repeat type is weekly |
+| repeating | The repeating status of the loaded event. |
+| repeating_id | The id of the loaded repeating event. |
+| resource_id | The id of the linked resource of the loaded event. |
+| startdate | The startdate of the loaded event (or the loaded repeating event). |
+| title | The title of the loaded event. |
diff --git a/en/01_Agenda/v1/04_Snippets/10_AgendaEventSet.md b/en/01_Agenda/v1/04_Snippets/10_AgendaEventSet.md
new file mode 100755
index 00000000..e122d460
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/10_AgendaEventSet.md
@@ -0,0 +1,56 @@
+This hook saves FormIt fields as an Agenda event. The hook was introduced with Agenda 1.1.0.
+
+It can update an existing event, if an event ID or a repeating ID is set. This
+can be done by FormIt hook properties or by request parameters. The FormIt
+hook properties supercede the request parameters.
+
+If no event_id or repeating_id is set, a new event is created.
+
+## FormIt Hook Properties
+
+The hook uses the following hook properties:
+
+| Property | Description | Default |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
+| agendaAllowedFields | Comma separated list of fields, that are set by the hook. Per default all fields are allowed. | - |
+| agendaCalendars | Comma-separated list of aliases of calendars to filter the loaded event. | - |
+| agendaCategories | Comma separated list of aliases of categories to filter the loaded event. | - |
+| agendaContexts | Comma separated list of context keys to filter the loaded event. | - |
+| agendaDateformat | Format of the startdate and enddate field, set by the hook. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | Y-m-d H:i:s |
+| agendaDateformatAllday | Format of the startdate and enddate field, set by the hook, when the event is an all day event. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | Y-m-d |
+| agendaId | ID of one event to load into FormIt. | 0 |
+| agendaLocations | Comma separated list of aliases of locations to filter the loaded event. | - |
+| agendaOwnEvent | Load only own events (created by the current user) into FormIt. | false |
+| agendaRepeating | ID of one repeating event to load into FormIt. | 0 |
+| agendaUsergroups | Comma separated list of user group names to filter the loaded event. | - |
+| agendaUsers | Comma separated list of user IDs to filter the loaded event. | - |
+
+## Hook fields
+
+The following FormIt fields are used in the hook and saved in the Agenda event, when they are allowed.
+
+| Field | Description |
+|-----------------|---------------------------------------------------------------------------------------------------------------|
+| active | The active status of the saved event. |
+| allday | The all day status of the saved event. |
+| calendar | The alias of the calendar of the saved event. |
+| calendar_id | The id of the calendar of the saved event. |
+| category | The aliases of the categories of the saved event. |
+| content | The content of the saved event. |
+| context_key | The context key of the saved event. |
+| description | The description of the saved event. |
+| enddate | The enddate of the saved event (or the saved repeating event). |
+| event_id | The id of the saved event. |
+| location | The alias of the location of the saved event. |
+| location_id | The id of the location of the saved event. |
+| repeat_enddate | The enddate of the repeats of the saved event. |
+| repeat_interval | The repeat interval of the saved event. |
+| repeat_on | The repeat weekdays of the saved event, when the repeat type is weekly |
+| repeat_ordinal | The repeat ordinal of the saved event, when the repeat type is monthly by weekday |
+| repeat_type | The repeat type of the saved event. (1 = daily , 2 = weekly, 3 = monthly, 4 = yearly, 5 = montly by weekday ) |
+| repeat_weekday | The repeat weekday of the saved event, when the repeat type is weekly |
+| repeating | The repeating status of the saved event. |
+| repeating_id | The id of the saved repeating event. |
+| resource_id | The id of the linked resource of the saved event. |
+| startdate | The startdate of the saved event (or the saved repeating event). |
+| title | The title of the saved event. |
diff --git a/en/01_Agenda/v1/04_Snippets/11_AgendaSearch.md b/en/01_Agenda/v1/04_Snippets/11_AgendaSearch.md
new file mode 100755
index 00000000..3b1e0007
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/11_AgendaSearch.md
@@ -0,0 +1,20 @@
+This hook retrieves Agenda events with as faceted search in SimpleSearch. The
+hook was introduced with Agenda 1.2.1.
+
+It fills the facet `events` in SimpleSearch.
+
+## SimpleSearch Hook Properties
+
+The hook uses the following hook properties:
+
+| Property | Description | Default |
+|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
+| agendaStartdate | The start date to filter the searched events. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | today 0:00 |
+| agendaEnddate | The end date to filter the displayed events. Must contain a [supported date and time format](https://www.php.net/manual/de/datetime.formats.php). | +99 year 0:00 |
+| agendaSearchLocation | Search the location address. When disabled, only the location title is searched. | true |
+| agendaCategoryTpl | Name of a chunk that contains the template of one category in the category list of an event. | tplAgendaEventCategory |
+| agendaImageTpl | Name of a chunk that contains the template of one image in the image list of an event. | tplAgendaEventImage |
+| agendaVideoTpl | Name of a chunk that contains the template of one video in the video list of an event. | tplAgendaEventVideo |
+| agendaLocationTpl | Name of a chunk that contains the template for the location of an event. | tplAgendaEventLocation |
+| agendaResourceTpl | Name of a chunk that contains the template for the linked resource of an event. | tplAgendaEventResource |
+| agendaEventExtractTpl | Name of a chunk that contains the template for the search extract of an event. | tplAgendaEventSearchExtract |
diff --git a/en/01_Agenda/v1/04_Snippets/12_AgendaCalcDate.md b/en/01_Agenda/v1/04_Snippets/12_AgendaCalcDate.md
new file mode 100755
index 00000000..e99b8209
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/12_AgendaCalcDate.md
@@ -0,0 +1,11 @@
+This output filter calculates a date with the given input and the options. The
+output filter was introduced with Agenda 1.4.0.
+
+## Output Filter Properties
+
+The output filter uses the following properties:
+
+| Property | Description | Default |
+|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| input | A date that can be [parsed](https://www.php.net/manual/en/datetime.formats.php) by php DateTime. | - |
+| options | The modifier string that alters the DateTime object. If the option is invalid, the result is empty and the modified placeholder is reset to the original value. | - |
diff --git a/en/01_Agenda/v1/04_Snippets/13_AgendaCalcFirstFullWeek.md b/en/01_Agenda/v1/04_Snippets/13_AgendaCalcFirstFullWeek.md
new file mode 100755
index 00000000..a2d0a70b
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/13_AgendaCalcFirstFullWeek.md
@@ -0,0 +1,12 @@
+This output filter calculates the startdate of the first full week with the
+given input. This snippet can be used to set the start date of the
+[AgendaCalender](02_AgendaCalendar.md) snippet. The output filter was introduced
+with Agenda 1.4.0.
+
+## Output Filter Properties
+
+The output filter uses the following properties:
+
+| Property | Description | Default |
+|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| input | A date that can be [parsed](https://www.php.net/manual/en/datetime.formats.php) by php DateTime. | - |
diff --git a/en/01_Agenda/v1/04_Snippets/14_AgendaCalcLastFullWeek.md b/en/01_Agenda/v1/04_Snippets/14_AgendaCalcLastFullWeek.md
new file mode 100755
index 00000000..21513484
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/14_AgendaCalcLastFullWeek.md
@@ -0,0 +1,12 @@
+This output filter calculates the enddate of the last full week with the given
+input. This snippet can be used to set the end date of the
+[AgendaCalender](02_AgendaCalendar.md) snippet. The output filter was introduced
+with Agenda 1.4.0.
+
+## Output Filter Properties
+
+The output filter uses the following properties:
+
+| Property | Description | Default |
+|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| input | A date that can be [parsed](https://www.php.net/manual/en/datetime.formats.php) by php DateTime. | - |
diff --git a/en/01_Agenda/v1/04_Snippets/index.md b/en/01_Agenda/v1/04_Snippets/index.md
new file mode 100755
index 00000000..11331c74
--- /dev/null
+++ b/en/01_Agenda/v1/04_Snippets/index.md
@@ -0,0 +1,64 @@
+_Agenda_ contains some _snippets_ in the `Agenda` category.
+
+#### AgendaList
+
+The [AgendaList](01_AgendaList.md) snippet displays Agenda events in a view.
+
+#### AgendaCalendar
+
+The [AgendaCalendar](02_AgendaCalendar.md) snippet displays Agenda events in a list divided into.
+
+#### AgendaDetail
+
+The [AgendaDetail](03_AgendaDetail.md) snippet displays one Agenda event in a view.
+
+#### AgendaDetailIcal
+
+The [AgendaDetailIcal](04_AgendaDetailIcal.md) snippet displays the iCal Download link of one event and downloads the iCal file.
+
+#### AgendaCalendars
+
+The [AgendaCalendars](05_AgendaCalendars.md) snippet displays a list of Agenda calendars.
+
+#### AgendaCategories
+
+The [AgendaCategories](06_AgendaCategories.md) snippet displays a list of Agenda categories.
+
+#### AgendaLocations
+
+The [AgendaLocations](07_AgendaLocations.md) snippet displays a list of Agenda locations.
+
+#### AgendaGetDate
+
+The [AgendaGetDate](08_AgendaGetDate.md) snippet retrieves and formats a date from an GET parameter.
+
+## FormIt Hooks
+
+_Agenda_ contains FormIt/SimpleSearch _hooks_ in the `Agenda` category.
+
+#### AgendaEventGet
+
+The [AgendaEventGet](09_AgendaEventGet.md) hook allows to fill FormIt values by Agenda events.
+
+#### AgendaEventSet
+
+The [AgendaEventSet](10_AgendaEventSet.md) hook allows to set Agenda events values by FormIt.
+
+#### AgendaSearch
+
+The [AgendaSearch](11_AgendaSearch.md) hook allows to search for Agenda events in SimpleSearch faceted search.
+
+## Output Filter
+
+#### AgendaCalcDate
+
+The [AgendaCalcDate](12_AgendaCalcDate.md) output filter calculates a date with the given input and the options.
+
+#### AgendaCalcFirstFullWeek
+
+The [AgendaCalcFirstFullWeek](13_AgendaCalcFirstFullWeek.md) output filter calculates the startdate of the first full week with the given input.
+
+#### AgendaCalcLastFullWeek
+
+The [AgendaCalcLastFullWeek](14_AgendaCalcLastFullWeek.md) output filter calculates the enddate of the last full week with the given input.
+
diff --git a/en/01_Agenda/v1/05_Cronjob.md b/en/01_Agenda/v1/05_Cronjob.md
new file mode 100755
index 00000000..cff897cc
--- /dev/null
+++ b/en/01_Agenda/v1/05_Cronjob.md
@@ -0,0 +1,73 @@
+_Agenda_ can be controlled by a _cronjob command_.
+
+## Executing the cronjob command
+
+The cronjob command can be executed from the command line with
+
+`php /path/to/your/modx/installation/assets/components/agenda/cron.php`
+
+or with an external webcronjob using the following url:
+
+`https://your.domain/assets/components/agenda/cron.php?cronjob_id=xxx`
+
+The value xxx has to be filled with the random string in the MODX system setting
+`agenda.cronjob_id`
+
+## The cronjob command tasks
+
+The cronjob command will run three different tasks:
+
+- [refresh the feeds](#refresh-the-feeds-task)
+- [refresh the repeating events](#refresh-the-repeating-events-task)
+- [import events](#import-events-task)
+
+Normally the feeds and the repeating events are refreshed together when no
+property is set for the cronjob command. To run a single task you can use the
+property `mode=feed` or `mode=repeating` for the cronjob:
+
+`php /path/to/your/modx/installation/assets/components/agenda/cron.php mode=feed`
+
+or
+
+`https://your.domain/assets/components/agenda/cron.php?cronjob_id=xxx&mode=feed`
+
+### Refresh the feeds task
+
+All active feeds are refreshed. New events of a feed are created, existing
+events of a feed are changed and no longer existing events of a feed are
+removed.
+
+### Refresh the repeating events task
+
+Per default each repeating event is only repeated to the maximum count of the
+`agenda.repeating_max_occurance` system setting. The refresh of the repeating
+events creates new repeats from the **current date** until the maximum count of
+the `agenda.repeating_max_occurance` system setting. So there will be no
+inifinite creation of repeats but the repeats will not stay at the limit, when
+the repeating event was created. Only events after the last existing repeating
+event are created and old (maybe edited) repeats are not changed.
+
+### Import events task
+
+With the property `mode=import` new events can be imported into Agenda with a
+cronjob. The cronjob call has to use the full filepath in the file property.
+
+`php /path/to/your/modx/installation/assets/components/agenda/cron.php mode=import file=/path/to/the/file`
+
+or
+
+`https://your.domain/assets/components/agenda/cron.php?cronjob_id=xxx&mode=import&file=/path/to/the/file`
+
+The import uses the same code as the import events button in the [events
+tab](02_Custom_Manager_Page/02_Events.md) of the custom manager page. The import
+mode is append. The import can be overridden in an [Agenda
+module](02_Custom_Manager_Page/07_Modules.md).
+
+## Debug the cronjob
+
+To detect cronjob issues, you can enable the Agenda [system
+setting](02_Custom_Manager_Page/08_Settings) `agenda.debug`. The file
+`{core_path}/cache/logs/agenda.log` will then contain a lot of debug
+information. Per default cronjob errors are logged in the standard MODX error
+log.
+
diff --git a/en/01_Agenda/v1/06_Extended_Fields.md b/en/01_Agenda/v1/06_Extended_Fields.md
new file mode 100755
index 00000000..b1d2cbb5
--- /dev/null
+++ b/en/01_Agenda/v1/06_Extended_Fields.md
@@ -0,0 +1,85 @@
+## Extended Event Fields
+
+The extended event fields were introduced with Agenda 1.1.0.
+
+Each event in Agenda can use predefined extended fields. The field values are
+stored as JSON encoded array in a text field. So sorting and filtering by
+extended fields is not possible.
+
+To define the extended fields the system setting `agenda.extended_event_fields`
+has to be filled with a nested JSON encoded array. The following value gives an
+example:
+
+```
+[
+ {
+ "name": "price",
+ "label": "Price"
+ },
+ {
+ "fields": [
+ {
+ "xtype": "numberfield",
+ "name": "minimum",
+ "renderer": "agenda-combo-example-resource",
+ "label": "Minimum number of participants",
+ "width": 0.5,
+ "column_label": "min.",
+ "column_width": 50
+ "hidden": false
+ },
+ {
+ "xtype": "numberfield",
+ "name": "maximum",
+ "renderer": "agenda-combo-example-resource",
+ "label": "Maximum number of participants",
+ "width": 0.5,
+ "column_label": "max.",
+ "column_width": 50,
+ "hidden": false
+ }
+ ]
+ }
+]
+```
+
+It will add the fields price, and the fields minimum and maximum in two columns
+to the event create/update window.
+
+Each array will create one extended field. The `name` key is required. The
+`label` key will be used, when it exists. Otherwise, a lexicon entry with the
+field name prefixed by `agenda.extended.` is searched in the lexicon. An `xtype`
+key will be used, when it exists. Otherwise, the xtype defaults to `textfield`.
+A `renderer` key will be used, when it exists. The renderer has to be defined in
+the file referenced in the `agenda.extended_xtypes_script` system setting.
+
+If a nested `fields` key contains an array value, this value will be used for
+subfields in columns. The `width` key inside is then used for the subfield
+column width.
+
+The extended fields can also generate columns in the events grid. The
+`column_label` key is required to add a column in the grid. The `column_width`
+key will define the width of the grid column. The column_width defaults to 100.
+The column can be hidden in the grid with the `hidden` key.
+
+Extended fields are available as placeholder with the prefix `extended` in the
+event row template. The `price` field from the example will be available with
+the `[[+extended.price]]` placeholder.
+
+The setting can use `@FILE` or `@CHUNK` bindings. Path
+placeholders like `{core_path}`, `{base_path}` and `{assets_path}` can be used.
+All paths have to stay inside the MODX base path because of security reasons.
+
+## Extended Repeat Fields
+
+The extended repeat fields were introduced with Agenda 1.4.0.
+
+They work the same as the extended event fields, can use `@FILE` or `@CHUNK`
+bindings and are shown in the edit repeat window and the repeats grid.
+
+## Extended Location Fields
+
+The extended location fields were introduced with Agenda 1.4.0.
+
+They work the same as the extended event fields, can use `@FILE` or `@CHUNK`
+bindings and are shown in the edit location window and the locations grid.
diff --git a/en/01_Agenda/v1/07_Export_Import_Events.md b/en/01_Agenda/v1/07_Export_Import_Events.md
new file mode 100755
index 00000000..23f69c2e
--- /dev/null
+++ b/en/01_Agenda/v1/07_Export_Import_Events.md
@@ -0,0 +1,21 @@
+## Export and Import Events
+
+The export and import of events were introduced with Agenda 1.5.0.
+
+To export or import the events the user has to get the `agenda_export` or
+`agend_import` permissions. After that an export and import button is displayed
+right of the create event button in the events tab of the custom manager page.
+
+The export and import format can be set with the `agenda.import_export_type`
+system setting. The supported formats are `csv`, `excel` and `yaml`. The default
+format is `csv`.
+
+The default export method will create a list of events for repeating events. If
+the repeating event does not have an identifier for the main event (i.e. by a
+field in agenda.extended_event_fields), it is difficult to reimport those
+events. During an import, events with the same event data (except start and end
+dates) are treated as a repeating event. The repeat is set to user defined and
+the repeat data is set for each recurrence.
+
+The import/export methods can be overridden in a [Agenda
+module](02_Custom_Manager_Page/07_Modules.md) with extended methods.
diff --git a/en/01_Agenda/v1/08_System_Events.md b/en/01_Agenda/v1/08_System_Events.md
new file mode 100755
index 00000000..ae8c2a10
--- /dev/null
+++ b/en/01_Agenda/v1/08_System_Events.md
@@ -0,0 +1,27 @@
+## System Events
+
+The OnAgendaBeforeSave, OnAgendaSave and OnAgendaBeforeRemove system events were
+introduced in Agenda 1.5.0.
+
+The OnAgendaValidate system event was introduced in Agenda 1.6.3.
+
+The use of these events allows additional code to be executed before and after
+saving and before deleting Agenda database entries.
+
+The following Agenda database objects invoke the system events: AgendaCalendars,
+AgendaCategories, AgendaEventCursus, AgendaEventDates, AgendaEventImages,
+AgendaEvents, AgendaEventVideos and AgendaLocations.
+
+The following properties can be used in the plugin events:
+
+| Property | Content |
+|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| mode | The state of the Agenda object. It can contain the following states: `modSystemEvent::MODE_NEW` or `modSystemEvent::MODE_UPD`. Not available in OnAgendaBeforeRemove |
+| className | The class name of the saved object. |
+| id | The identifier of the saved object. |
+| object | The Agenda object. |
+
+Skeleton classes for the events can be found in
+`core/components/agenda/src/Plugins/Events`. To use them, you have to remove the
+underscore prefix from the filename and activate the according event in the
+Agenda plugin.
diff --git a/en/01_Agenda/v1/09_Tutorials/Dynamic_Opening_Hours.md b/en/01_Agenda/v1/09_Tutorials/Dynamic_Opening_Hours.md
new file mode 100644
index 00000000..4f83c692
--- /dev/null
+++ b/en/01_Agenda/v1/09_Tutorials/Dynamic_Opening_Hours.md
@@ -0,0 +1,90 @@
+Using Agenda, you can manage and display dynamic opening hours on your site.
+When you've completed this tutorial, you'll have a simple list showing the
+opening hours in the next week.
+
+
+
+[TOC]
+
+## Basic Setup
+
+First create a new Calendar under Extras > Agenda > Calendars tab. Name it
+"Opening Hours" with an alias of "openinghours", or something similar. Make sure
+it's active, and give it a recognisable color.
+
+In your events overview, start adding (repeating) events to your new calendar.
+
+If you're **closed** on a certain day, add an **all day event** with what you
+want to show as the event title (e.g. "Closed", or "Closed for private party").
+
+If you're **open** on a certain day, add an event with a start and end date,
+which corresponds with your opening hours.
+
+Use the repeating events' functionality to automatically repeat the opening hours
+weekly. Once created, you can edit the start and end date/time of an event from
+the Repeats tab, for when the opening hours are different.
+
+**It's important to have an event for each day of the week**. If you're missing
+*a day, it won't show up in our list of opening hours at all.
+
+If you add multiple events for a single day (e.g. if the store is open in the
+morning and afternoon, but closed during lunch), each one will show separately
+in the list.
+
+## Snippets & Chunks
+
+To render the opening hours, we'll use the
+[AgendaList](../04_Snippets/01_AgendaList.md) snippet with some custom chunks and
+logic.
+
+Here's our `AgendaList` call; make sure to adjust the `&calendars` filter to
+match the alias of your opening hours calendar.
+
+```html
+
+```
+
+We're using a little trick to automatically set the `&end` property 7 days in
+advance (which uses `+6 days` as today is the first day), and let Agenda
+automatically start on todays' events, sorting by the start date.
+
+Create the **AgendaOpeningHours** chunk with the following:
+
+```html
+[[+startdate:strtotime:date=`%Y-%m-%d`:toPlaceholder=`start_ymd`]]
+[[+id:notempty=`now`:strtotime:date=`%Y-%m-%d`:toPlaceholder=`today_ymd`]]
+
+```
+
+Some notes:
+
+- First we're creating a placeholder `start_ymd` and `today_ymd` dynamically bases on the startdate for the event and the current time respectively. We use those in the wrapping `
` tag to highlight events for today in bold.
+- We parse the startdate into the name of the day in the first cell. If this is in the wrong language, make sure to update the `locale` system setting in MODX to the right value.
+- In the second cell we're outputting the date (e.g. `8 Oct`). You can skip this if you want, but it can be useful to show what exact date the opening hours are for to indicate that they may differ from week to week.
+- In the third cell we have the logic that switches between open and closed. If the event is not an all-day event, we output the hours of the event as open hours. For an all-day event, we output the title of the event (e.g. "Closed" or "Closed for private party").
+
diff --git a/en/01_Agenda/v1/09_Tutorials/Frontend_Editing.md b/en/01_Agenda/v1/09_Tutorials/Frontend_Editing.md
new file mode 100644
index 00000000..8175920f
--- /dev/null
+++ b/en/01_Agenda/v1/09_Tutorials/Frontend_Editing.md
@@ -0,0 +1,110 @@
+Using the Agenda FormIt hooks, you can create and edit events by users in the
+frontend. When you've completed this tutorial, you'll can create and edit an
+event on a frontend page.
+
+[TOC]
+
+## Basic Setup
+
+First install FormIt and create a new MODX Resource. Then create a new Calendar
+under Extras > Agenda > Calendars tab. Name it i.e. "User Events" with an alias
+of "userevents" and make sure it's active.
+
+## FormIt Call and form code
+
+To render and execute the form, we have to add a FormIt call to a MODX resource.
+This FormIt Call uses the [AgendaEventGet](../04_Snippets/09_AgendaEventGet.md) and
+the [AgendaEventSet](../04_Snippets/10_AgendaEventSet.md) hooks.
+
+Here's our `FormIt` example call; make sure to adjust the `&agendaEvent` property to
+the ID of an existing event, that should be editable in the frontend.
+
+```html
+[[!FormIt?
+ &successMessage=`The event was edited!`
+ &hooks=`agendaeventset`
+ &preHooks=`agendaeventget`
+ &agendaEvent=`xxx`
+ &clearFieldsOnSuccess=`0`
+]]
+```
+
+The form code (based on Bootstrap 3) should be added below of the `FormIt` call with the following content:
+
+```
+[[!+fi.validation_error_message:notempty=`
[[!+fi.validation_error_message]]
`]]
+[[!+fi.successMessage:notempty=`
[[!+fi.successMessage]]
`]]
+
+
+
+
+
+
+```
+
+On the page with the FormIt call the title, the start date, the end date, the
+category and the description of an existing event can be edited. The category
+can be set with a dropdown showing all active categories.
+
+Some notes:
+
+- The `agendaEvent` property can be set by request parameter. Please make sure
+that all events on your page can be edited, if you allow this. You can
+restrict the editing to events created by the current user with the
+`agendaOwnEvent` property.
+- You can't set multiple categories with the dropdown at the moment, because of
+a restriction in the `AgendaCategories` snippet.
+- If you change the `agendaEvent` property to `agendaRepeating`, you can edit
+the start date and end date of the repeating event. The other fields will change
+the event itself.
+- All editable fields are shown on the documentation of the
+[AgendaEventGet](../04_Snippets/09_AgendaEventGet.md) and the
+[AgendaEventSet](../04_Snippets/10_AgendaEventSet.md) hooks.
diff --git a/en/01_Agenda/v1/09_Tutorials/FullCalendar_Display.md b/en/01_Agenda/v1/09_Tutorials/FullCalendar_Display.md
new file mode 100644
index 00000000..c45b08cc
--- /dev/null
+++ b/en/01_Agenda/v1/09_Tutorials/FullCalendar_Display.md
@@ -0,0 +1,65 @@
+You can use the FullCalendar 3 script in the frontend with the following steps.
+
+[TOC]
+
+## Basic Setup
+
+First rename the file assets/components/agenda/_overview.php to overview.php.
+Afterwards edit it and remove the exit(); in line 12.
+
+The Agenda backend uses FullCalendar for the calendar display. You have to
+create a working FullCalendar script according to the [FullCalendar 3
+documentation](https://fullcalendar.io/docs/v3/installation) or the
+[current FullCalendar documentation](https://fullcalendar.io/docs/getting-started).
+
+## Restrict the request
+
+If you need to restict the overview connector to a special calendar, category,
+time range etc., you can apply your own request variables after the line 29 in
+the overview connector.
+
+## Call the frontend scripts
+
+Finally, you have to initialize the FullCalendar script with the following code:
+
+### FullCalendar 3
+
+```js
+$('#fullcalendar').fullCalendar({
+ events: {
+ url: 'assets/components/agenda/overview.php',
+ type: 'POST',
+ startParam: 'startdate',
+ endParam: 'enddate',
+ data: function () {
+ return {
+ // calendars: calendars || 0,
+ // categories: categories || 0,
+ // query: query || '',
+ limit: 0
+ };
+ }
+ }
+});
+```
+
+### FullCalendar 4 and later
+
+```js
+$('#fullcalendar').fullCalendar({
+ events: {
+ url: 'assets/components/agenda/overview.php',
+ type: 'POST',
+ startParam: 'startdate',
+ endParam: 'enddate',
+ extraParams: function () {
+ return {
+ // calendars: calendars || 0,
+ // categories: categories || 0,
+ // query: query || '',
+ limit: 0
+ };
+ }
+ }
+});
+```
diff --git a/en/01_Agenda/v1/09_Tutorials/img/opening-hours.jpg b/en/01_Agenda/v1/09_Tutorials/img/opening-hours.jpg
new file mode 100644
index 00000000..bbb06dc4
Binary files /dev/null and b/en/01_Agenda/v1/09_Tutorials/img/opening-hours.jpg differ
diff --git a/en/01_Agenda/v1/10_FAQ.md b/en/01_Agenda/v1/10_FAQ.md
new file mode 100755
index 00000000..9cb2c00f
--- /dev/null
+++ b/en/01_Agenda/v1/10_FAQ.md
@@ -0,0 +1,96 @@
+We're collecting the questions we get most often into a FAQ. If your question is
+not in the list, please reach out to us via treehillstudio-support@modmore.com,
+and we would be glad to help.
+
+[TOC]
+
+## How are events displayed on the website?
+
+To render events to your visitors, you can use the provided snippets:
+
+- [AgendaList](04_Snippets/01_AgendaList) used for rendering a list of events
+- [AgendaCalendar](04_Snippets/02_AgendaCalendar) used for rendering events in a list divided into intervals (i.e. days)
+- [AgendaDetail](04_Snippets/03_AgendaDetail) used for showing one specific event on a detail page
+
+There are other snippets to help you render calendars, categories, and locations.
+
+## How can an event repeat more than 100 times?
+
+By default, repeating events are scheduled for 100 recurrences.
+
+You have two possibilitiesto change that:
+
+- [Set up a cron job](05_Cronjob) to refresh repeating events for up to 100 repeats in the future from the current date.
+- Increase the `agenda.repeating_max_occurance` [system setting](02_Custom_Manager_Page/08_Settings) to a larger value.
+
+## Can events, categories, calendars or locations be connected to a resource?
+
+Yes!
+
+Agenda comes with a number of [system
+settings](02_Custom_Manager_Page/08_Settings). Configure them with a comma
+separated list of resource IDs to use as parent resources. When set up, a new
+resource selection field will be added to the edit windows in the manager.
+
+- For events: `agenda.parents_event`
+- For categories: `agenda.parents_category`
+- For calendars: `agenda.parents_calendar`
+- For locations: `agenda.parents_location`
+
+## How often is an event feed refreshed?
+
+When creating the [feed](02_Custom_Manager_Page/06_Feeds) for events to be
+imported, you can set how often the feed should be checked for new or updated
+events, with a minimum interval of once a minute.
+
+You also need to set up the cron job to fire often enough for the feed refreshes
+to happen at the right time.
+
+## Can a map be used in the location address tab?
+
+Yes, you will need to enter a [Google Maps API
+Key](https://developers.google.com/maps/documentation/javascript/get-api-key) in
+the `agenda.google_maps_api_key` system setting to use the map.
+
+In the project in the Google Cloud Platform console, activate the Maps
+JavaScript API and the Geocoding API.
+
+# What's the difference between a calendar and a category?
+
+They're both ways of organising your events into logical sections, and can be
+filtered on in the [AgendaList](04_Snippets/01_AgendaList) snippet.
+
+A Calendar is best seen as the "owner" or "target" for an event. For example a
+conference center can use calendars for organising events as "Public events",
+"Private parties" and "Staff-only events", which are then shown in different
+sections of the website. An event must have one Calendar.
+
+A Category is then the type of event, which can be a sub-filter on the detail
+pages. For example "Weddings", "Conference", "Expo", "Training/workshops". An
+event can have many categories.
+
+For events grouped into a location or room, you can use the Locations
+functionality as well. That can also be used with maps, ideal for businesses
+with different venues or events hosted in varying places.
+
+## Is the cron job required?
+
+If you use Feeds or repeating events, yes, the cron job is required for Agenda
+to work as expected.
+
+If your server doesn't allow you to configure cron jobs, you can trigger it
+through web requests as well using online cron job services.
+
+## Can the cron job log more information?
+
+Yes, enable the `agenda.debug` [system
+setting](02_Custom_Manager_Page/08_Settings). A new log will be created in
+`{core_path}/cache/logs/agenda.log` with a lot of debug information.
+
+By default, errors are logged to the standard MODX error log.
+
+## I can't use my own daterange format in the lexicon or in the snippet properties
+
+|The format string has to use exactly 7 parts separated by `|`. The description|
+of the formatting rules can be found below the placeholder descriptions on the
+[AgendaList](04_Snippets/01_AgendaList#range-placeholder-format) snippet description.
diff --git a/en/01_Agenda/v1/index.md b/en/01_Agenda/v1/index.md
new file mode 100644
index 00000000..79e1ed85
--- /dev/null
+++ b/en/01_Agenda/v1/index.md
@@ -0,0 +1,16 @@
+---
+title: Agenda
+description: Documentation for Agenda, a premium calendar for MODX by Treehill Studio.
+---
+
+[Agenda](https://modmore.com/agenda/) is a feature rich MODX calendar extra. It comes with a lot of options like the ability to create and edit repeating events, assign categories and a MODX resource to an event. The location of an event can be displayed with Google Maps. It also supports importing an external iCalendar/XML feed into one calendar, which can be updated with a cronjob. Events can be assigned to a MODX user, usergroup or context.
+
+It is a perfect solution for users looking for an extensive MODX event management calendar or just a well-supported MODX calendar component.
+
+# Recommended Reading
+
+- [Installation](01_Installation)
+- [Custom Manager Page](02_Custom_Manager_Page)
+- [Snippets](04_Snippets)
+- [FAQ](10_FAQ)
+
diff --git a/en/01_Commerce/images/gateways/paypal-nvp.jpg b/en/01_Commerce/images/gateways/paypal-nvp.jpg
new file mode 100644
index 00000000..f51844e0
Binary files /dev/null and b/en/01_Commerce/images/gateways/paypal-nvp.jpg differ
diff --git a/en/01_Commerce/images/gateways/paypal-tools.jpg b/en/01_Commerce/images/gateways/paypal-tools.jpg
new file mode 100644
index 00000000..5e8d62f1
Binary files /dev/null and b/en/01_Commerce/images/gateways/paypal-tools.jpg differ
diff --git a/en/01_Commerce/images/gettingstarted/cron-notok.jpg b/en/01_Commerce/images/gettingstarted/cron-notok.jpg
new file mode 100644
index 00000000..ddcd2fd5
Binary files /dev/null and b/en/01_Commerce/images/gettingstarted/cron-notok.jpg differ
diff --git a/en/01_Commerce/images/gettingstarted/cron-ok.jpg b/en/01_Commerce/images/gettingstarted/cron-ok.jpg
new file mode 100644
index 00000000..4703cf1d
Binary files /dev/null and b/en/01_Commerce/images/gettingstarted/cron-ok.jpg differ
diff --git a/en/01_Commerce/images/gettingstarted/multilingual-ex.jpg b/en/01_Commerce/images/gettingstarted/multilingual-ex.jpg
new file mode 100644
index 00000000..75320bd8
Binary files /dev/null and b/en/01_Commerce/images/gettingstarted/multilingual-ex.jpg differ
diff --git a/en/01_Commerce/images/modules/create-refund.jpg b/en/01_Commerce/images/modules/create-refund.jpg
new file mode 100644
index 00000000..e4a94f66
Binary files /dev/null and b/en/01_Commerce/images/modules/create-refund.jpg differ
diff --git a/en/01_Commerce/images/products/collections_view_column_edit.png b/en/01_Commerce/images/products/collections_view_column_edit.png
new file mode 100644
index 00000000..cae7e26b
Binary files /dev/null and b/en/01_Commerce/images/products/collections_view_column_edit.png differ
diff --git a/en/01_Commerce/images/products/collections_view_config.png b/en/01_Commerce/images/products/collections_view_config.png
new file mode 100644
index 00000000..479a2e50
Binary files /dev/null and b/en/01_Commerce/images/products/collections_view_config.png differ
diff --git a/en/01_Commerce/images/products/collections_view_custom.png b/en/01_Commerce/images/products/collections_view_custom.png
new file mode 100644
index 00000000..bf02137a
Binary files /dev/null and b/en/01_Commerce/images/products/collections_view_custom.png differ
diff --git a/en/01_Commerce/images/products/collections_view_grid.png b/en/01_Commerce/images/products/collections_view_grid.png
new file mode 100644
index 00000000..a771cf38
Binary files /dev/null and b/en/01_Commerce/images/products/collections_view_grid.png differ
diff --git a/en/01_Commerce/images/products/collections_view_json.png b/en/01_Commerce/images/products/collections_view_json.png
new file mode 100644
index 00000000..a767832c
Binary files /dev/null and b/en/01_Commerce/images/products/collections_view_json.png differ
diff --git a/en/01_Commerce/images/products/matrix-empty.jpg b/en/01_Commerce/images/products/matrix-empty.jpg
new file mode 100644
index 00000000..3fbe756b
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-empty.jpg differ
diff --git a/en/01_Commerce/images/products/matrix-first-order-rows.jpeg b/en/01_Commerce/images/products/matrix-first-order-rows.jpeg
new file mode 100644
index 00000000..51e46adc
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-first-order-rows.jpeg differ
diff --git a/en/01_Commerce/images/products/matrix-first-order.jpg b/en/01_Commerce/images/products/matrix-first-order.jpg
new file mode 100644
index 00000000..2d05ea5f
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-first-order.jpg differ
diff --git a/en/01_Commerce/images/products/matrix-first.jpg b/en/01_Commerce/images/products/matrix-first.jpg
new file mode 100644
index 00000000..3fde83b8
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-first.jpg differ
diff --git a/en/01_Commerce/images/products/matrix-optgroup-row.jpg b/en/01_Commerce/images/products/matrix-optgroup-row.jpg
new file mode 100644
index 00000000..4ad03a4e
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-optgroup-row.jpg differ
diff --git a/en/01_Commerce/images/products/matrix-sample.jpg b/en/01_Commerce/images/products/matrix-sample.jpg
new file mode 100644
index 00000000..4515da23
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-sample.jpg differ
diff --git a/en/01_Commerce/images/products/matrix-table.jpg b/en/01_Commerce/images/products/matrix-table.jpg
new file mode 100644
index 00000000..fe28f191
Binary files /dev/null and b/en/01_Commerce/images/products/matrix-table.jpg differ
diff --git a/en/01_Commerce/v1/00_Requirements.md b/en/01_Commerce/v1/00_Requirements.md
index 496ac499..eff8696b 100644
--- a/en/01_Commerce/v1/00_Requirements.md
+++ b/en/01_Commerce/v1/00_Requirements.md
@@ -1,7 +1,8 @@
-Commerce has the following requirements to run and/or to enable live mode. When Commerce is installed, the checklist under Configuration will help you make sure all requirements are met.
+Commerce has the following requirements to run and/or to enable live mode. When Commerce is installed, the checklist under Configuration will help you make sure all requirements are met.
-- MODX 2.5.2 or higher, and all its requirements
-- PHP 5.5 or higher, 5.6 or 7.x encouraged.
+- MODX 2.7.0 or higher, and all its requirements; 2.8 or 3.0 recommended
+- PHP 7.1.5 or higher, 7.4 or 8.0 recommended
+ - Starting with Commerce 1.3, the lowest supported version is PHP 7.4
- Website accessible over HTTPS
Payment gateways communicate over a HTTPS connection, as do some other integrations, so your server needs to be capable of opening secure connections. If you're able to download Commerce from the modmore package provider that's a good sign.
@@ -14,9 +15,8 @@ Payment gateways communicate over a HTTPS connection, as do some other integrati
We strongly recommend verifying the following in your MODX configuration.
-- Latest MODX version (2.5.2 at the very least)
-- Email sending should be set up with an authenticated SMTP email account. Using services like Amazon Simple Email Service, Mandrill, or Mailgun is strongly encouraged.
-- Emails sent via MODX should have matching DKIM and SPF set up. Use [Mail Tester](https://www.mail-tester.com/) to verify your emails have a good chance of getting delivered.
-- Friendly URLs should be enabled, including `friendly_alias_path`.
-- The `core` folder should either be moved outside the webroot, or be renamed and locked down to prevent direct access.
-
+- Latest MODX version (either 2.8 or MODX3)
+- Email sending should be set up with an authenticated SMTP email account. Using services like Amazon Simple Email Service, Mandrill, or Mailgun is strongly encouraged.
+- Emails sent via MODX should have matching DKIM and SPF set up. Use [Mail Tester](https://www.mail-tester.com/) to verify your emails have a good chance of getting delivered.
+- Friendly URLs should be enabled, including `friendly_alias_path`.
+- The `core` folder should be locked down to prevent direct access.
diff --git a/en/01_Commerce/v1/01_Getting_Started/02_Configuration.md b/en/01_Commerce/v1/01_Getting_Started/02_Configuration.md
index a3a3b3db..288be80a 100644
--- a/en/01_Commerce/v1/01_Getting_Started/02_Configuration.md
+++ b/en/01_Commerce/v1/01_Getting_Started/02_Configuration.md
@@ -6,123 +6,133 @@ On this page:
## The Commerce Dashboard
-Whenever we talk about the Commerce Dashboard, we mean Extras » Commerce in your MODX Manager. This section of your MODX installation contains the configuration, products, reporting and more.
+Whenever we talk about the Commerce Dashboard, we refer to the **Extras » Commerce** section in your MODX Manager. This section of your MODX installation contains the orders, products, configuration, reporting and more.
## Choosing Modules to use
-One of the first things you should do is decide whatmodules you want to use. In Commerce, many features are implemented as optional modules that can be enabled/disabled at will, and may contain additional configuration options.
-
-The majority of modules ship with the Commerce core, but [additional extensions](https://www.modmore.com/commerce/extensions/) are also available from modmore or third parties.
+One of the first things you should do is decide which modules you want to use, because this will determine what features are available and need to be configured.
+
+In Commerce, many features are implemented as optional modules that can be enabled/disabled at will, and may contain additional configuration options. The majority of modules ship with the Commerce core, but [additional extensions](https://modmore.com/commerce/extensions/) are also available. Some extensions were built by modmore, and are covered by your standard support, while others have been built by the larger community and are _not_ covered by standard support.
-In the Commerce Dashboard, navigate to Configuration » Modules to take a look at the modules that are available.
+In the Commerce Dashboard, navigate to **Configuration » Modules** to take a look at the available modules.
-To enable and configure a module, click its name in the list. You can enable modules in either test, live, or both modes by checking the appropriate boxes.
+To enable and configure a module, click its name in the list. There you can enable modules in either test mode, live mode, or both modes by checking the appropriate boxes.
-Which modules you'll use depend on the type of shop and how you want to run things. We'll highlight a couple here.
+Which modules you use depends on the type of shop and how the shop will be run. We'll highlight a couple of common modules here, but it's recommended to go through the list and look at the descriptions to see if any others might be useful for your shop.
-Note that the names are translated, so if you use the manager in a different language than English they will be named differently and may be in a different order.
+**Note:** The module names are translated, so if you use the manager in a different language than English they will be named differently and may be in a different order.
### Customer, Address, and Shipping related
-We **strongly recommended** to enable the [Basic Address Validation](../50_Modules/Address_Validation/Basic) module. This module ensures that address information is filled in before the customer can move along in the checkout. In the module configuration you can enter the fields that should be required, depending on your locality, the `state` field may be best taken out.
+It is **strongly recommended** to enable the [Basic Address Validation](../50_Modules/Address_Validation/Basic) module. This module ensures that address information is filled in before the customer can move along in the checkout. In the module configuration, you can enter the fields that should be required depending on your locality. For example the `state` field is not required in a large part of the world.
+
+You should also enable either the [Autofill GeoIP](../50_Modules/Cart/AutoFillGeoIP) module or the [Default Address](../50_Modules/Cart/DefaultAddress) module. These modules will set an expected address on the order before the customer gets to the address step. This expected address is used by the taxes and shipping configuration to determine what rates and options to show before the customer entered their information.
-You should also enable either [Autofill GeoIP](../50_Modules/Cart/AutoFillGeoIP) or the [Default Address](../50_Modules/Cart/DefaultAddress) module. These modules will set an expected address on the order before the customer gets to the address step, which is used by your taxes and shipping configuration to determine what rates and options to show in the cart.
+- The [Default Address module](../50_Modules/Cart/DefaultAddress) is useful if you serve a distinct demographic. For example, if you only (or predominantly) ship to one country or state, you can configure the Default Address module to use that by default, which should be accurate for the majority of your customers.
+- If your customer base is more spread out, the Autofill GeoIP module will automatically geolocate the customer by their IP address and use the country (and optionally the state) instead. This uses the [ipinfo.io](https://ipinfo.io/) service (free for up to 1000 lookups per day) which is fairly accurate.
-- The Default Address module is useful if you serve a distinct demographic; for example if you only (or predominantly) ship to one country or state, you can configure the Default Address module to use that by default, which should be accurate for the majority of your customers.
-- If your customer-base is more spread out, the Autofill GeoIP module will automatically geolocate the customer by their IP address and use the country (and optionally state) instead. This uses the [ipinfo.io](https://ipinfo.io/) service (free for up to 1000 lookups per day).
+If you only sell in specific countries, the [Country Validation](../50_Modules/Address_Validation/Country) module is useful to restrict country selection. (Note that this does not remove countries from the country field in the address step, but you can do that by changing the templates.)
-If you only sell in specific countries, the [Country Validation](../50_Modules/Address_Validation/Country) module is useful to restrict that.
+If you require the customer to accept terms and conditions before initiating a payment, you can use the [Accept Terms](../Modules/Cart/AcceptTerms) module.
### Discounts
-You'll likely want to enable the [Coupons](../50_Modules/Discounts/Coupons) module to get access to coupon codes. After enabling the module, refresh the page to see the Coupons tab being added to the top navigation.
+You'll likely want to enable the [Coupons](../50_Modules/Discounts/Coupons) module to get access to coupon codes. After enabling the module, refresh the page to see the Discounts tab added to the top navigation.
+
+There is also a [User & Usergroup Discounts](../50_Modules/Discounts/UserDIscounts) module that can be used for percentage discounts for users or user groups, accessible from the same Discounts tab once the module is enabled.
### Taxes
-- If you sell to customers in the European Union, enable the [EU VAT](../50_Modules/Taxes/EUVat) module to enable the EU VAT Rate Provider that enables automatically up-to-date tax rates across all countries in the EU.
-- If you sell to customers in the United States, the [TaxJar](../50_Modules/Taxes/TaxJar) module can be used to get automated sales tax calculations.
+Very few people enjoy paying taxes, but it is important to charge the right taxes to your customers.
+
+- If you sell to customers in the European Union, enable the [EU VAT](../50_Modules/Taxes/EUVat) module to enable the EU VAT Rate Provider that enables automatically up-to-date tax rates across all countries in the EU. This loads (and caches) tax rates from an open-source, community-maintained dataset for standard and reduced tax rates around the EU.
-We'll look at configuring the actual [tax rates](../Taxes) in the next sections.
+- If you sell to customers across the United States, the [TaxJar](../50_Modules/Taxes/TaxJar) module can be used to get automated sales tax calculations. This service covers virtually all possible Sales Tax rules, including product-specific exemptions if you configure the right product codes, and can also be used to help with your tax reporting, but does have a monthly cost to use.
+
+For all other regions, or if you prefer to manually set rates, you can use the standard configuration. We'll look at configuring the actual [tax groups and rates](../Taxes) in a minute.
### Products & Cart
-Enable [CombineProducts](../50_Modules/Cart/CombineProducts) if you want multiple items with the same product to be combined into a single item in the cart. Note that this is not compatible with [ItemData](../50_Modules/Cart/ItemData) which we'll discuss later.
+Enable [CombineProducts](../50_Modules/Cart/CombineProducts) if you want multiple items with the same product to be combined into a single item in the cart. Note that this is not compatible with [ItemData](../50_Modules/Cart/ItemData), which we'll discuss later.
## Setting up Statuses
-The default installation created a simple status workflow for you. In Configuration > Statuses you can see that in action.
+The default installation created a simple [status workflow](../Statuses) for you. At **Configuration > Statuses** you can see that in action.
-For now, we'll leave that as-is, but later on you may want to change the emails that get send when an order is paid. Click on "Payment Received" in the Status Changes column for Draft to see the actions that are fired when the payment is received.
+For now, we'll leave that as-is, but later on you may want to change the emails that Commerce sends when an order is paid. You can find those by clicking on "Payment Received" in the Status Changes column for Draft, to see the actions that are fired when the payment is received.
You'll see two email actions are configured here, a confirmation email to the customer, and the order notification to the merchant. By clicking on the name (or "Edit Status Change Action" in the Actions menu), you can see the subject, recipient, and content configuration for each. By default these use templates, but you may need to tweak the recipient email on the order notification to merchant.
## Setting up Payment Methods
-In the installation, a "Dummy Payment" was automatically created. This uses the [manual payment gateway](../Payment_Methods/Manual) which just marks the order as paid. If you want to add other payment method options, you can do that at Configuration > Payment Methods.
+In the installation, a "Dummy Payment" was automatically created. This uses the [manual payment gateway](../Payment_Methods/Manual) which just marks the order as paid. If you want to add [other payment method options](../Payment_Methods), you can do that at **Configuration » Payment Methods**.
## Setting up Delivery Types & Shipping Methods
-Depending on what you will be selling, you may or may not need to tweak the delivery types in Configuration > Delivery Types. For basic shops where every sold product fits in the same type of box or is distributed digitally in the same way, you will only need a single delivery delivery type.
-
-If you have different types of products, for example a combination of ebooks and physical books, you'll need to create an additional delivery type.
+Depending on what you will be selling, you may or may not need to tweak the [delivery types](../Delivery_Types) in **Configuration » Delivery Types**. For basic shops, where every sold product fits in the same type of box or is distributed digitally in the same way, you will only need a single delivery type.
-It's best to set up delivery types for distinct ways of getting the customer their order. While you'll create a delivery type for an ebook and another one for a physical books, you wont typically need a different delivery type if you also sell t-shirts, as those are delivered the same way as a book.
+If you have different types of products however, for example a combination of ebooks and physical books, you'll need to create an additional delivery type.
-For now, we'll only use the default "Standard Shipping" delivery type. You can edit the delivery type to make the shipping step required or never shown, depending on your requirements. In the default shipping step mode of "Depends", the shipping step is only shown in the checkout if there are 2 or more shipping methods available for an order.
+As a way of determining if you need different delivery types, consider whether or not the way a product is delivered to the customer. While you'll create a delivery type for an ebook and another one for a physical books, you wont typically need a different delivery type if you also sell t-shirts, as those are delivered the same way as a book. If you use different fulfillment partners or warehouses, different delivery types can also be useful if that distinction is clear to the customer.
-Next, go to Configuration > Shipping Methods. You'll have a free shipping method already from the installation, that's assigned to the Standard Shipping delivery type we just saw in Configuration > Delivery Types.
+For now, we'll stick with the the default "Standard Shipping" delivery type. You can edit the delivery type to make the shipping step required or never shown, depending on your requirements. In the default shipping step mode of "Depends", the shipping step is only shown in the checkout if there are 2 or more shipping methods available for an order.
-If you created extra delivery types, you'll also need to create additional shipping methods for each.
+Next, navigate to **Configuration » Shipping Methods**. You'll already have a free shipping method from the setup, which is assigned to the Standard Shipping delivery type we just saw in **Configuration » Delivery Types**. If you created extra delivery types, you'll also need to create additional shipping methods for each.
-To help with testing, you can choose to set the Free Shipping method to a minimum order total of €50 by editing it (click on its name in the grid) and setting "Min. Order Total" at the bottom to 5000 ($50). And then create another shipping method of type "Standard Shipping Method" that costs $7,50 for orders with a "Max. Order Total" of 5000 ($50).
+To help with testing, you can choose to set the Free Shipping method to a minimum order total of $50 by editing it (click on its name in the grid) and setting "Min. Order Total" at the bottom to 5000 ($50). And then create another shipping method of type "Standard Shipping Method" that costs $7,50 for orders with a "Max. Order Total" of 5000 ($50).
-_» Tip:_ Prices in Commerce are configured in cents, but you'll see the formatted price when you remove focus from the field.
+**» Tip:** Prices in Commerce are configured in cents, but you'll see the formatted price when you remove focus from the field.
## Setting up Currencies
-The most common currencies for modmore customers will have already been created for you in the installation, but if you want to change the formatting or decide which one is used, head over to Configuration > Currencies.
+The most common currencies have already been created for you in the installation, but if you want to change the formatting, or set which one to use, navigate to **Configuration » Currencies**.
-Click on the currency name or choose Edit Currency in the actions menu to change the formatting options. In the Actions menu you can also choose _Set as Default_ to change the default currency.
+Click on the currency name or choose Edit Currency in the actions menu to change the formatting options. In the Actions menu you can also choose _Set as Default_ to change the default currency.
For Euro, some countries prefer to use the comma instead of the dot for the decimal separator. Click on Euro and switch out the values for "Decimal Point" and "Thousands Separator" to tweak that.
-If you need to add a currency that is not included in Commerce by default, [this site has a comprehensive list of the ISO4217 codes and formatting to use](https://www.thefinancials.com/Default.aspx?SubSectionID=curformat).
+If you need to add a currency that is not included in Commerce by default, [this site has a comprehensive list of the ISO4217 codes and formatting to use](https://www.thefinancials.com/Default.aspx?SubSectionID=curformat). The ISO codes are important to get right for certain payment providers.
+
+Use a different currency often? Let us know, maybe we can save you some time in the future by including it in the standard installation.
[Learn more about currencies here](../Currencies).
## Setting up Tax Groups
-Next up, create a tax group under Configuration > Tax Groups. Give it a name that describes the **type** of tax, not the actual rate to charge. For example you could have "Standard" and "Food", but you should not name them "21%" or "9%".
+Next up, create a tax group under **Configuration » Tax Groups**. Give it a name that describes the **type** of tax, not the actual rate to charge. For example you could have "Standard Tax" and "Food", but you would not, typically, name them "21%" or "9%".
+
+After creating the tax group, choose **Manage Tax Rules**, in the Actions menu.
-After creating the tax group, choose Manage Tax Rules in the Actions menu.
+What the tax rules should be exactly depends on your jurisdiction and what you're selling, and to who. In many cases there is a tax rate that applies to local customers, and one (or more) for international customers. [The taxes documentation](../Taxes) explains in more detail how you can configure different rates and rules, but for now let's keep it simple, and add a simple singular tax rate that applies to every purchase.
-What the tax rules should be exactly depends on your jurisdiction and what you're selling, and to two. In many cases there is a tax rate that applies to local customers, and one (or more) for international customers. [The taxes documentation](../Taxes) explains in more detail how you can configure different rates and rules, but for now let's keep it simple, and add a simple singular tax rate that applies to every purchase.
+Click **Add Tax Rule**. Give it a priority of 1, set "Field name" to "country", and "Condition" to "Always". Leave the Rate Provider set to _Manual Tax Rate_. Save.
-Click Add Tax Rule. Give it a priority of 1, set "Field name" to "country", and "Condition" to "Always". Leave the Rate Provider set to Manual Tax Rate.
+After saving the rule, a new section _Rate Provider Options_ will be show. There you can enter the tax rate you want to charge, for example 21, give it a Tax Key like "STANDARD-NL", and a name that is shown to customers like `21% VAT` or `Standard VAT`. Save again.
-When you save the tax rule, a new section "Rate Provider Options" will be shown. Enter the tax rate you want to charge, for example 21, give it a Tax Key like "STANDARD-NL", and a name that is shown to customers like "21% VAT" or "Standard VAT". Save again.
+If you want to add more tax rules for different rates, repeat this process. The priority determines the order that the tax rules will be evaluated from top-to-bottom in the grid, so set the conditions so that the lowest priority number is the most specific, and eventually fall back to an "Always" condition with the highest priority number. When using conditions that depend on customer information that is not yet be available, the rule is ignored, so keep that in mind.
-(If you want to add more tax rules, repeat this process. The priority determines in what order the tax rules will be evaluated, from top-to-bottom in the grid, so set the conditions so that the lowest priority number is the most specific, and eventually fall back to an "Always" condition with the highest priority number.)
+When creating products, you'll select the tax group to use for that specific product. Or, if only one tax group is configured, it is selected for you automatically.
## Some final System Settings
-Now that you've explored all parts of the configuration in the Commerce Dashboard, there are a few more system settings you may want to consider tweaking. These can be found by going to System (cog icon in the manager) > System Settings, and choosing "Commerce" in the first filter (namespace).
+Now that you've explored the configuration in the Commerce Dashboard, there are a few more system settings you may want to consider tweaking. These can be found by going to System (cog icon in the manager) » System Settings, and choosing "Commerce" in the first filter (namespace).
- There are some settings related to the account step in the checkout. [Read more about how to configure them for what result in the Users documentation](../Users)
- The `commerce.default_weight_unit` setting is useful to configure before creating products. It defaults to `kg`, but virtually all weight units are supported.
- Don't want to see the beta warning? Disable `commerce.show_beta_warning`.
-- The E-mail & Notifications settings are useful to configure some default email options, like an image to use as image header with `commerce.email_header_url`.
+- The E-mail & Notifications settings are useful to configure some default email options, like an image to use as image header with `commerce.email_header_url`. Other email options are configured through the [status workflow](../Statuses)
- In the Taxes area, set the `commerce.tax_calculation` to `inclusive` if you want product prices to be treated as having taxes included in them, instead of adding taxes on top of it.
+- The resource related settings should already be (partially) configured for you as part of the setup, but you may want to tweak your `login_resource` ([how to setup your login page](../Users/Login_Resource)), `register_resource` ([how to setup your registration page](../Users/Register_Resource)), and `shop_resource` settings. You can ignore the _Resource Product_ settings for now.
## Up next: set up your Product Catalog
-Now that the most important configuration is in place, it's time to start [setting up your products](Product_Catalog)!
+Now that the most important configuration is in place, let's start [setting up your products](Product_Catalog)!
diff --git a/en/01_Commerce/v1/01_Getting_Started/03_Product_Catalog.md b/en/01_Commerce/v1/01_Getting_Started/03_Product_Catalog.md
index 73c84ad7..70f2aa0a 100644
--- a/en/01_Commerce/v1/01_Getting_Started/03_Product_Catalog.md
+++ b/en/01_Commerce/v1/01_Getting_Started/03_Product_Catalog.md
@@ -1,7 +1,160 @@
-This page is still waiting to be written! It will explain the different ways you can manage products and what decisions you'll need to make about that, and will then guide you through creating your first products and related templates.
+_This document assumes [Commerce was downloaded and installed with the default options](index) and that [you've gone through the basic configuration](Configuration)._
-For now, [see the Product Catalog reference](../Product_Catalog).
+Now that your basic shop configuration is in place, and you have an idea of the different pieces that are involved, let's start talking about the actual products and your catalog.
-## Next: setting up your Cart & Checkout
+[TOC]
-What good are products if you can't buy them? [Lets work on the cart and checkout next](Cart_Checkout).
+## Products and the Catalog
+
+In Commerce there is a distinction between the _products_ and the _catalog_. This may seem a bit odd, but is by design to enable more flexible and powerful shops.
+
+**Products** are simple representations of an item that you sell. A product could be "Rainbow shirt in size M", which has its SKU, price, weight, stock, etc. Commerce doesn't natively have variations within products: each unique option you have in your warehouse is a unique product.
+
+The **Catalog** is how your products are organised and presented to customers. This contains your products, of course, but may also cover reviews, categories, filters, product videos and galleries, brands, etc.
+
+**Commerce focuses primarily on the products**. You'll use a selection of tools, not necessarily tools provided by modmore, to build out the catalog exactly how you want it to work. Then you'll hook in the products in Commerce.
+
+## Laying out your product catalog
+
+For most MODX shops, we recommend building the catalog based around resources. For example, you might use:
+
+- [Collections](https://modx.com/extras/package/collections) as categories. Collections show up in the resource tree like regular resources, except it hides regular child resources from the tree. That allows you to have hundreds or even thousands of resources, without overloading the tree. Each child resource would be a product page.
+- [Tagger](https://modx.com/extras/package/tagger) and/or [mSearch2](https://en.modstore.pro/packages/ecommerce/msearch2) to allow a customer to drill down products within categories based on values you store in TVs on each product page.
+- [pdoTools](https://modx.com/extras/package/pdotools) to list resources and to generate menus.
+
+These tools allow you to use MODX in the same way you would for normal sites.
+
+To hook up Commerce, you will then use what we call the **Products TV** or **Matrix TV** on your product pages. These are template variable types that ship with Commerce that let you maintain either a list or a matrix of products that are associated with the page.
+
+Imagine this resource structure:
+
+- Clothing
+ - Shirts
+ - Design A
+ - Design B
+ - Design C
+ - Jeans
+ - Design D
+ - Design E
+ - Design F
+
+All designs will have a set of sizes that are available for selection on that product page. You will manage the general catalog page through the resources, while the sizes are the products in Commerce, with their own price and stock. The Products TV lets you manage a one-dimensional list of product variations.
+
+**About the Product Matrix:**
+
+> The Product Matrix TV works in a similar way to the Products TV, but instead of a one-dimensional list, it lets you define 2 properties and products are automatically created for the intersections of those properties. This is useful for a variety of use cases, but it's a bit more complex to get started with. If this is your first time working with Commerce, we'd recommend first getting to grips with the system using the Products TV. When you have that working, you can [learn more about the product matrix](../Product_Catalog/Product_Matrix) for more powerful product management.
+
+So let's start building. Install Collections, and create a sample resource structure for your shop, perhaps based on the sample above. Make sure to create a template for your categories, and a template for your product resources.
+
+### Product Template
+
+Create a [Products TV](../Product_Catalog/Products_TV) with name `products`, and assign it to your product template. Use it to create some products on one of your product pages. (For example, on your _Design A_ resource, add `Design A - M`, `Design A - L` and `Design A - XL` and give them different prices.)
+
+In your product template, add `[[*products]]` to see the comma separated list of product IDs for that specific product page. We can turn that into a list of product variations with the [get_product](../Snippets/get_product) and [get_products](../Snippets/get_products) snippets.
+
+Start by making the first product in the list available as the main product information:
+
+````html
+[[!commerce.get_product? &product=`[[*products]]` &toPlaceholders=`product_info`]]
+````
+
+Now we can use placeholders prefixed with `product_info` to get any of the product fields. For example, we may show the resource title followed by the SKU and price of the first product, and then the main resource content that may include a product description:
+
+````html
+[[!commerce.get_product? &product=`[[*products]]` &toPlaceholders=`product_info`]]
+
+[[*content]]
+````
+
+We'll also need to add the ability to select from the different products, and submit that to the cart. [There are 2 different form structures you can use](../Product_Catalog/Add_to_Cart_Form), we'll use the single product variation.
+
+````html
+
+````
+
+The `product_as_select` chunk:
+
+````html
+
+````
+
+What's important to note here is that we have 3 required fields we're submitting to the cart:
+
+- `add_to_cart` with value 1 to indicate we want to add something
+- `product` with the ID of a Commerce Product that we want to add. In the example above, this is a `