diff --git a/craft-calendar/headless/graphql.mdx b/craft-calendar/headless/graphql.mdx index d96012c1..ca80403c 100644 --- a/craft-calendar/headless/graphql.mdx +++ b/craft-calendar/headless/graphql.mdx @@ -19,6 +19,12 @@ Calendar supports querying calendars and events via GraphQL. This guide assumes Calendar has a root `solspace_calendar` query, which contains all the possible queries nested inside it to avoid conflicts with other plugins. +:::warning Upcoming Calendar 6 change + +The legacy `solspace_calendar` GraphQL wrapper will be deprecated in Calendar 6. These v5 queries will continue to work in Calendar 5, but plan to update headless implementations to use the top-level Calendar GraphQL queries after upgrading. + +::: + ## Querying multiple Calendars To query all or some calendars, you have to use the `calendars` query: diff --git a/craft-calendar_versioned_docs/version-v6/calendars/_category_.json b/craft-calendar_versioned_docs/version-v6/calendars/_category_.json new file mode 100644 index 00000000..476dfc5a --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/calendars/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Calendars", + "position": 6 +} diff --git a/craft-calendar_versioned_docs/version-v6/calendars/fieldtype.mdx b/craft-calendar_versioned_docs/version-v6/calendars/fieldtype.mdx new file mode 100644 index 00000000..7ceb49a0 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/calendars/fieldtype.mdx @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +title: Element Field Type +description: Use the Calendar Events Field Type to relate events to other elements in Craft CMS. +--- + +# Element Field Type + +The Calendar Calendars field type allows you to assign/relate whole calendars (ID's) to other element types such as Craft Entries. What actually is related is the calendar ID, thus allowing you to then pull in events for the given calendar attached to the Craft element. + +### Creating a Calendars field + +Creating a Calendar Calendars field is done just like any other fieldtype, here's an overview of the process: + +1. Go to the **Settings** area in Craft control panel. Click on **Fields**. +2. Click the **New field** button in the top right corner. +3. Name the field as you wish. For example: _Related Calendars_ with a handle of _relatedCalendars_. +4. For the **Field Type** option, select _Calendar Calendars_ from the list. +5. Click the **Save** button in the top right corner to save the new field. + +Your Calendar Calendars field is now available to be assigned to other sections. + +### How the Fieldtype works + +The Calendar Calendars fieldtype lets the user choose 1 calendar to assign to any element: a section entry, categories, assets, etc. diff --git a/craft-calendar_versioned_docs/version-v6/calendars/index.mdx b/craft-calendar_versioned_docs/version-v6/calendars/index.mdx new file mode 100644 index 00000000..980b86e5 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/calendars/index.mdx @@ -0,0 +1,89 @@ +--- +title: Managing Calendar +description: Overview of calendars, events, and management features in Solspace Calendar 6.x for Craft CMS. +--- + +import { Photo, Badge } from '@site/src/components/utils'; + +# Managing Calendars + +Calendar allows you to group your events into calendars, very similar to popular calendaring apps like _Apple Calendar_ and _Google Calendar_. Calendars can be customized to have their own fields / field layouts and calendar color. + +## Overview + +The calendar area in the control panel displays a list of all existing calendars. You can update or remove existing ones, as well as create new ones here. + +:::warning +Removing calendar(s) will also permanently remove ALL associated events! +::: + + + + + +Calendars allow you to set the following data for each one: + +### Name + +The name of the calendar that will be visible everywhere. + +### Handle + +The name you'll use when referring to the calendar in your templates. Auto-generated from the _Name_ field. + +### Description + +The description of the calendar. Can be accessed in your templates. + +### Color + +The unique color for each calendar. Choose from picker (Calendar also automatically internally generates a lighter and darker version of this color for use in control panel and front end templates) + +### Site Setting + +Enable this to set up automatic routing of URL's for your events. Enabling this will also allow you to use the Live Preview feature. + +:::info +The templates will look for `event.`, not `entry.` (e.g. `event.title`, not `entry.title`). +::: + +- **Event URI Format** - what the event URLs should look like. You can include tags that output event properties, such as `{slug}` or `{postDate|date("Y")}`. +- **Template** - the template to use when an event's URL is requested. + +### Show the Title field + +Uncheck this to set your own title format, auto-generated from other field(s). + +- **Title Format** - What the auto-generated event titles should look like. You can include tags that output entry properties, such as `{myCustomField}`. + +### Allow Repeating Events + +Disable this option to allow only single occurrence events for this calendar. + +### Forced ICS Event Timezone + +Choose a timezone that will be forced upon exported ICS event dates. Default is _Floating Timezone_ (recommended), which means no timezone. + +:::warning +ICS subscriptions currently do not work correctly for Google Calendar when using _Floating Timezone_. The issue is that there's a "bug" or at least oddity in [the way Google Calendar handles events with floating dates](https://productforums.google.com/forum/#!topic/calendar/Xjxs5UjhsXI) compared to all other calendaring apps. Google does not to conform to [iCal standards](https://tools.ietf.org/html/rfc5545#section-3.3.5) for this. You can work around this by setting the **Forced ICS Event Timezone** setting to a real timezone. +::: + +### ICS Description field + +Set the custom field which is used for event description in ICS exports. + +### ICS Location field + +Set the custom field which is used for event location in ICS exports. + +### Design Field Layout + +Works just like regular Craft field layouts. Simply create how you want your event publishing experience to be. Layouts are unique per Calendar. + +Calendars also include an option to share calendars with a publicly accessible ICS subscription URL (Pro), allowing users to subscribe (one way sync) their calendaring app to your sites' calendar(s). To enable this, click on the **Share this calendar** button next to the applicable calendar(s) on the list view of calendars. Once enabled, you can then copy the ICS URL and share it with whoever you wish (admins, show it publicly, etc). diff --git a/craft-calendar_versioned_docs/version-v6/configuration/_category_.json b/craft-calendar_versioned_docs/version-v6/configuration/_category_.json new file mode 100644 index 00000000..0aea1748 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/configuration/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Configuration", + "position": 4 +} diff --git a/craft-calendar_versioned_docs/version-v6/configuration/demo-templates.mdx b/craft-calendar_versioned_docs/version-v6/configuration/demo-templates.mdx new file mode 100644 index 00000000..8b2c46d0 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/configuration/demo-templates.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 5 +title: Demo Templates +description: Install and use demo templates for Solspace Calendar 6.x in Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Demo Templates + +Calendar includes a complete set of demo templates. These demo templates let you have a fully functioning area on your website with just a couple clicks! Further to this, it allows you to see real world examples of the template code in action, which will help you get acquainted with Calendar quicker. + +Included in the demo templates is an implementation of the [FullCalendar JS library](http://fullcalendar.io). Users with appropriate administrative privileges will also be able to modify events. + + + +## Installing the Demo Templates + +To install the Demo Templates, simply visit the **Settings** page for Calendar and click on the **Demo Templates** nav item (**Calendar > Settings > Demo Templates**). + +By default, the Demo Templates page will have **calendar-demo** as the _Install Path_ for your template path. You can change this to whatever you like. So for example, if you set the _Install Path_ value as `my-precious`, the demo templates will be installed to **site.com/my-precious/**. + +During installation of demo templates, Calendar will copy the template folders and files (as shown on page) to the Craft **/templates/** directory. So using the above example, your templates would be located at **/templates/my-precious/**. + +Calendar will also look for an **assets** folder in your **public** directory and attempt to load files such as CSS, JS, fonts and image files (as shown on page) to a folder inside that, named **my-precious** (using the example above). If an **/assets/** directory does not exist, Calendar will attempt to create that directory as well. + +And lastly, Calendar will create several template routes for you (as shown on page) for the demo templates to work correctly. + +If you ever want to refresh the demo templates back to what they were by default (or if there's been an update to them in a new version), you can simply reinstall the Demo Templates and use the same _Install Path_ value. Calendar will then overwrite the files and only add new routes (if applicable), rather than installing duplicate routes. + +If you encounter any issues while attempting to install the demo templates, please see the [Troubleshooting](#troubleshooting) guide. + +## Troubleshooting + +If you encounter any issues trying to install the demo templates, it's likely that your database user does not have sufficient privileges or your server configuration does not allow some or all of the actions. + +If you cannot change or adjust your permissions or configuration, you can install the demo templates manually. To install them manually, refer to the [Manual Install](#manual-install) instructions below. + +## Manual Install + +To install the demo templates manually, just follow the instructions below: + +1. Inside the **/vendor/solspace/craft-calendar/src/codepack/** directory, copy the **templates** folder into the Craft **/templates/** directory, and rename the Calendar **templates** folder to **demo** (so it should now be located at **/templates/demo/**). +2. In your root public directory, create a directory called **assets** if it does not already exist. +3. Inside the **/vendor/solspace/craft-calendar/src/codepack/** directory, copy the **assets** folder into the public **/assets/** directory, and rename the Calendar **assets** folder to **demo** (so it should now be located at **/assets/demo/**). +4. Copy and paste the following routes into your _routes.php_ configuration file (**/config/routes.php**): + +```php showLineNumbers +'demo/month/(?P\d{4})/(?P\d{2})' => 'demo/month', +'demo/month/calendar/(?P[^\/]+)' => 'demo/month', +'demo/month/calendar/(?P[^\/]+)/(?P\d{4})/(?P\d{2})' => 'demo/month', +'demo/week/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/week', +'demo/week/calendar/(?P[^\/]+)' => 'demo/week', +'demo/week/calendar/(?P[^\/]+)/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/week', +'demo/day/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/day', +'demo/day/calendar/(?P[^\/]+)' => 'demo/day', +'demo/day/calendar/(?P[^\/]+)/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/day', +'demo/calendars/(?P[^\/]+)' => 'demo/calendars', +'demo/event/(?P\d+)' => 'demo/event', +'demo/event/(?P\d+)/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/event', +'demo/events/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/events', +'demo/export/event/(?P\d+)' => 'demo/export', +'demo/export/calendar/(?P\d+)' => 'demo/export', +'demo/fullcalendar/(?P[^\/]+)/(?P\d{4})/(?P\d{2})/(?P\d{2})' => 'demo/fullcalendar', +'demo/resources/event_data/(?P\d+)' => 'demo/resources/event_data' +``` + +Visit your demo templates at: **yoursite.com/demo** diff --git a/craft-calendar_versioned_docs/version-v6/configuration/permissions.mdx b/craft-calendar_versioned_docs/version-v6/configuration/permissions.mdx new file mode 100644 index 00000000..da1501e2 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/configuration/permissions.mdx @@ -0,0 +1,36 @@ +--- +sidebar_position: 4 +title: Permissions +description: Set user and group permissions for Solspace Calendar 6.x in Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Permissions + +Solspace Calendar ties into regular Craft User Group Permissions. Simply visit the permissions page for the applicable user group(s) (**Settings > Users > User Groups**) to grant/edit/remove permissions to Calendar. + +Calendar 6 reorganizes permissions to match the structure used by Freeform. The older Calendar permission IDs are migrated to the new IDs during the Calendar 6 update so existing user group access continues working. + + + +- **General** + - _Access Calendar_ - required for users to access Solspace Calendar at all. +- **Access Events** + - _Read All Events_ - allows users to view events in all calendars. This overrides individual _Read Events by Calendar_ selections. + - _Read Events by Calendar_ - allows users to view events in selected calendars only. + - _Manage All Events_ - allows users to create, edit, delete, and save events in all calendars. This also grants read access and overrides individual _Manage Events by Calendar_ selections. + - _Manage Events by Calendar_ - allows users to create, edit, delete, and save events in selected calendars only. +- **Access Calendars** + - _Create New Calendars_ - allows users to create calendars. + - _Delete Calendars_ - allows users to delete calendars. + :::danger + Deleting a calendar deletes ALL events associated with that calendar as well, so be careful which users have access to this permission. + ::: + - _Manage All Calendars_ - allows users to edit all calendars. + - _Manage Calendars Individually_ - allows users to edit selected calendars only. +- _Access Settings_ - access to the settings area for Calendar and [Demo Templates](../configuration/demo-templates.mdx) install page. +- _Access Resources_ - access to the resources area for Calendar. diff --git a/craft-calendar_versioned_docs/version-v6/configuration/project-config.mdx b/craft-calendar_versioned_docs/version-v6/configuration/project-config.mdx new file mode 100644 index 00000000..ae832be5 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/configuration/project-config.mdx @@ -0,0 +1,122 @@ +--- +sidebar_position: 7 +title: Project Config +description: Manage Solspace Calendar 6.x settings via Craft CMS Project Config. +--- + +# Project Config + +Calendar supports Craft's [Project Config](https://craftcms.com/docs/5.x/system/project-config.html). You can modify the general configuration and settings for Calendar, as well as settings and field layouts for each calendar. + +## General config for Calendar + +All of Calendar's settings can be controlled/overrided here (in `/config/project/project.yaml`): + +```yaml showLineNumbers +calendar: + edition: pro # You'll get license errors if you don't have a valid Pro license. + enabled: true + licenseKey: EXAMPLETEST12EXAMPLETEST + schemaVersion: 4.0.0 + settings: + pluginName: '' # Custom name for plugin (Pro). + firstDayOfWeek: '-1' # The starting day of the week when viewing front end and control panel Month and Week views as well as datepickers. '-1' is default, which the current user's locale. '0' is Sunday, '1' is Monday, etc. + timeFormat: auto # Time format for dates and date pickers. 'auto' is current user's locale, Use '12-hour' or '24-hour' to set the same for all users. + showMiniCal: '1' # Displays a side menu with mini calendar and list of calendars, allowing you to filter your event results. + showDisabledEvents: '1' # Events that are disabled will be displayed in the views with faded styles. + quickCreateEnabled: '1' # Allows all users with event creation privileges to use the Quick Create event feature. + authoredEventEditOnly: '1' # Users (excluding Admins) with event creation privileges will only be able to edit or delete their own events. + defaultView: month # The default page to go to when clicking the Calendar nav item. + demoBannerDisabled: '1' # Hides the alert message suggesting to install demo templates when this setting is enabled. + eventDuration: '60' # The default event time duration for fieldtype, in minutes. + timeInterval: '30' # The time picker interval for fieldtype, in minutes. + allDay: '' # Have the 'All Day' option selected by default for new events. + overlapThreshold: '5' # The amount of hours in the next day which are still considered as those of the previous day. + guestAccess: # The calendar ID's guests should have access to create events for on the front end. + - '5' + - '1' + - '3' + - '6' +``` + +## Settings & field layouts for Calendars + +Calendar will also store settings and field layouts for calendars (e.g. `/config/project/solspace/calendar/calendarsblueThunder--59e6448b-613a-424c-98db-f9ae36dd2bc8.yaml`) and will look something like this: + +```yaml showLineNumbers +name: 'Blue Thunder' +handle: blueThunder +description: '' +color: '#20A8B9' +allowRepeatingEvents: true +icsHash: ac3478d69a3c81fa62e60f5c3696165a4e5e6ac45aaa947450b782.65239311 +icsTimezone: floating +descriptionFieldHandle: '0' +locationFieldHandle: '0' +hasTitleField: true +titleFormat: '' +titleLabel: Title +siteSettings: + 2394f11a-d45d-40d2-a5ee-5bd9f176417d: + enabledByDefault: true + hasUrls: true + siteId: 5f1d37f9-004d-414a-8e9c-48d763fba635 + template: blue-thunder/_entry + uriFormat: 'blue-thunder/de/{slug}' + 5968dff9-9263-456b-8f8e-5bb02b73f377: + enabledByDefault: true + hasUrls: true + siteId: 24990881-e55d-42d1-b228-92652cf50dfb + template: blue-thunder/_entry + uriFormat: 'blue-thunder/fr/{slug}' + a8560321-d302-4716-8045-13345fb36adf: + enabledByDefault: true + hasUrls: true + siteId: bfdeaad5-5273-4cf1-a390-05c8929e7795 + template: blue-thunder/_entry + uriFormat: 'blue-thunder/{slug}' + c07e3df4-aa17-46a3-8ffa-077719d56011: + enabledByDefault: false + hasUrls: false + siteId: 8f0a08fa-5b1c-4c7b-84dd-bd93d571d031 + template: null + uriFormat: null +fieldLayout: + tabs: + - elements: + - fieldUid: ad144815-0d08-4ec6-948a-0b0c00190e2d + instructions: null + label: null + required: '0' + tip: null + type: craft\fieldlayoutelements\CustomField + warning: null + width: 100 + - fieldUid: 252c0982-bae0-4040-b669-e2fd9149eff6 + instructions: null + label: null + required: '0' + tip: null + type: craft\fieldlayoutelements\CustomField + warning: null + width: 100 + - fieldUid: 390f343e-55c9-4362-996f-60e17d649e62 + instructions: null + label: null + required: '0' + tip: null + type: craft\fieldlayoutelements\CustomField + warning: null + width: 100 + - fieldUid: fcdc1067-21d1-4a91-8094-b38a27c60ebb + instructions: null + label: null + required: '0' + tip: null + type: craft\fieldlayoutelements\CustomField + warning: null + width: 100 + name: 'Tab 1' + sortOrder: 1 + uid: 079608e5-4374-408a-b6de-ad776486ba33 +``` diff --git a/craft-calendar_versioned_docs/version-v6/configuration/settings.mdx b/craft-calendar_versioned_docs/version-v6/configuration/settings.mdx new file mode 100644 index 00000000..d9ffe1f6 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/configuration/settings.mdx @@ -0,0 +1,163 @@ +--- +sidebar_position: 3 +title: Settings +description: Configure global settings for Solspace Calendar 6.x in Craft CMS. +--- + +import { Photo, Badge } from '@site/src/components/utils'; +import { FlexCards } from '@site/src/components/docs'; + +import Icons from '@site/static/icons/cards'; + +# Plugin Settings + +Calendar includes a wide variety of settings that allow you to customize your event management experience. To adjust your settings, click the **Settings** menu item while in the Calendar plugin, or go to **Settings → Plugins → Calendar** and click the settings link. These can also be configured within your Craft [Project Config](./project-config.mdx) file. + + + +## General Settings + + + +### Custom Plugin Name + +Override the plugin name by specifying your own here. + +### Week Starting Day + +The starting day of the week when viewing front end and control panel Month and Week views as well as datepickers. Default is _Current user's Locale_, meaning that Calendar will display the first day of the week depending on the currently logged in user. + +Options are: + +- Current user's locale +- Sunday +- Monday +- Tuesday +- Wednesday +- Thursday +- Friday +- Saturday + +### Time Format + +Time format for dates and date pickers throughout the control panel. This allows you to override what all users see instead of it varying between each user's locale. + +Options are: + +- Current user's locale +- 12-hour format +- 24-hour format + +### Display Mini Calendar & Calendars list in Month/Week/Day views? + +Displays a side menu with mini calendar and list of calendars, allowing you to filter your event results. + +### Include Disabled Events in Month/Week/Day views? + +Events that are disabled will be displayed in the views with faded styles. + +### Allow new events to be created in Month/Week/Day views? + +Allows all users with event creation privileges to use the Quick Create event feature. + +### Restrict users to editing their own events only? + +Users (excluding Admins) with event creation privileges will only be able to edit or delete their own events. + +### Default View + +The default page to go to when clicking the Calendar nav item. Options are: + +- Month view +- Week view +- Day view +- Events +- Calendars + +### Hide "Install Demo" alert message? + +Hides the alert message suggesting to install demo templates when this setting is enabled. + +## Event Settings + + + +### Default Event Duration + +The default event time duration for fieldtype, in minutes. When event Start Time is selected, this number of minutes will automatically be added to that time for End Time field. + +### Time Interval + +The time picker interval for fieldtype, in minutes. The Start Time and End Time field time pickers will contain a list of times of the day by this interval. + +### Select 'All Day' by default? + +When enabled, when creating new events the 'All Day' option will be selected by default. + +### Date Overlap Threshold + +Specify the amount of hours in the next day which are still considered as those of the previous day. This prevents late night events from showing up the next day for calendars in control panel and front end. + +### Timezones and Occurrences + +Calendar 6 stores event timezones and generated occurrences more explicitly than Calendar 5. When events are saved, Calendar normalizes the event schedule and updates the persisted occurrence records used by template queries, the control panel, and GraphQL. + +## Guest Access + + + +### Allow Guest Access on Front End? + +Enable this to allow guests to post events to specific calendars on the front end. + +### Allowed Calendars + +Select which calendars Guests should have access to create events for on the front end. + +## Demo Templates + + + +Allows you to install the [Demo Templates](./demo-templates.mdx) to get Calendar up and running on the front end with just a couple clicks! diff --git a/craft-calendar_versioned_docs/version-v6/configuration/translating.mdx b/craft-calendar_versioned_docs/version-v6/configuration/translating.mdx new file mode 100644 index 00000000..a1754ceb --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/configuration/translating.mdx @@ -0,0 +1,21 @@ +--- +sidebar_position: 8 +title: Translating +description: Translate Solspace Calendar 6.x for Craft CMS, including control panel and front-end strings. +--- + +# Translating + +All of the Calendar control panel area and front end templates are translatable. + +To make a translation, follow Craft's instructions for [Translating Static Text](https://craftcms.com/docs/4.x/static-translations.html), and then check out the Calendar-specific guide below: + +- Duplicate the _calendar.php_ file inside the Calendar plugin located at the **./vendor/solspace/craft-calendar/src/translations/en-US** folder, and add it into the language ID folder (e.g. `de`) of your Craft **./translations/** directory. If the _translations_ directory does not yet exist, you'll need to create it (e.g. `./translations/de/calendar.php`). You can then update those language keys inside your Calendar translation file. +- Not all month and weekday name strings that are part of dates are translated through static translation files however: + - The CP Month/Week/Day views use the [FullCalendar JS library](http://fullcalendar.io) which contain their own translations. Calendar will detect the locale you're using and automatically load the corresponding translation file. If it's not, please [contact us](/support/) and let us know which translation and 2 or 4 letter language ID you're using (e.g. `fr-BE`). + - When using properties from the [Event object](../templates/objects/event.mdx) such as `startDate` and `endDate`, you'll want to be sure to use the `|date` filter instead of `.format` to allow Craft to automatically translate the date strings. Due to a conflict between how Craft and Calendar each work, you'll need to also append `Localized` to the date property (e.g. `startDateLocalized`) in order to see dates/times that aren't incorrectly localized to the user's timezone. Your final code might look something like: `event.startDateLocalized|date("l, F j, Y g:ia")`. + - If you're testing this in the [demo templates](./demo-templates.mdx) included with Calendar, you'll need to comb through the templates to switch any references of `.format` to `|date` instead. + +Visit the Craft documentation for more information about [Setting Up a Localized Site](https://craftcms.com/docs/4.x/localization.html). + +If you'd like to share your translation with others, [send us an email](/support/) with a link to the translation file, and we'll consider including it in the main Solspace Calendar plugin package. diff --git a/craft-calendar_versioned_docs/version-v6/developer/_category_.json b/craft-calendar_versioned_docs/version-v6/developer/_category_.json new file mode 100644 index 00000000..2da82f68 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/developer/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Developer", + "position": 9 +} diff --git a/craft-calendar_versioned_docs/version-v6/developer/console-commands.mdx b/craft-calendar_versioned_docs/version-v6/developer/console-commands.mdx new file mode 100644 index 00000000..53184405 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/developer/console-commands.mdx @@ -0,0 +1,67 @@ +--- +title: Console Commands +sidebar_position: 4 +description: Console commands for Solspace Calendar 6.x in Craft CMS. +--- + +import { Badge } from '@site/src/components/utils'; + +# Console Commands + +Calendar includes several console commands to allow you to run cleanup tasks and other tasks. + +:::info Calendar 6 upgrade note + +Calendar 6 ships with a database migration that handles the major v5-to-v6 refactor automatically, including timezone columns, RRULE normalization, persisted occurrence generation, field layout updates, and legacy GraphQL permission ID migration. The older Craft 4-to-Craft 5 repair commands below are only needed for sites affected by those earlier upgrade paths. + +::: + +## Resave Events + +If you need to resave all Calendar events, you can do so with the `calendar/events/resave` CLI command. Most of the arguments available to Craft's `resave/entries` command are available here too, so if you need to also update the Craft Search Index, be sure to add `--update-search-index`. + +```sh +php craft calendar/events/resave --update-search-index +``` + +## Migrate Craft 4 Element Titles + +If you have upgraded your Craft 4 site to Craft 5, please note that the Craft migration process does not automatically migrate submission Element titles. In Craft 5, Element titles are now stored in the `elements_sites` table, and the `content` table which used to store Element titles is no longer used. + +While most plugins could include a separate migration script to handle this, Calendar supported both Craft 4 and Craft 5 when this upgrade path was introduced, making this path impossible. Instead, a CLI command has been included that needs to be executed once after upgrading from Craft 4 to Craft 5. + +:::warning +This CLI command is only applicable to sites that have migrated from Craft 4 to Craft 5 while Calendar was installed. +::: + +```sh +php craft calendar/events/fix-titles +``` + +## Migrate Craft 4 Event Content + +If you were running Calendar 5.x on Craft 4.x before upgrading to Craft 5.x, some of your event data may not automatically be carried over. In Craft 5, Calendar event Element data is no longer stored in the `content` table. + +While most plugins could include a separate migration script to handle this, Calendar supported both Craft 4 and Craft 5 when this upgrade path was introduced, making this path impossible. Instead, a CLI command has been included that needs to be executed once after upgrading from Craft 4 to Craft 5. + +:::warning +This CLI command is only applicable to sites that were running Calendar 5.x on Craft 4.x before upgrading to Craft 5.x. +::: + +```sh +php craft calendar/events/fix-contents +``` + +## Fix Field Layout Tabs Elements UIDs + +There was a bug in Calendar 4.x and earlier versions of 5.0.x where unique UIDs were not being generated for field layout elements when duplicating calendars. The issue has been resolved in later versions of Calendar 4.x and 5.x, but the issue still needs to be resolved if your site is affected. + +To help the smaller number of affected sites resolve this issue, we have included a CLI command that should be executed once after upgrading to the latest 4.x or 5.x version of Calendar while still on Craft 4.x. + +:::warning +This CLI command is only applicable to sites on Craft 4 that may have duplicated calendars in earlier versions of Calendar 4.x and 5.x. This command will not work on Craft 5 due to bigger differences in how the data is stored. +::: + +```sh +php craft calendar/calendars/fix-field-layout-tabs-elements-uids --rebuildProjectConfig +``` diff --git a/craft-calendar_versioned_docs/version-v6/developer/events.mdx b/craft-calendar_versioned_docs/version-v6/developer/events.mdx new file mode 100644 index 00000000..228caec3 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/developer/events.mdx @@ -0,0 +1,86 @@ +--- +title: Events +sidebar_position: 1 +description: Developer events available for extending Solspace Calendar 6.x in Craft CMS. +--- + +# Developer Events + +If you wish to extend the capabilities of Calendar, you can use any of the events below: + +## Events for Calendar Events + +`\Solspace\Calendar\Services\EventsService` + +- `::EVENT_BEFORE_SAVE` # + - Called before saving the event data + - `\Solspace\Calendar\Events\SaveElementEvent` contains these methods: + - `getElement()` - returns `\Solspace\Calendar\Elements\Event` + - `isNew()` - bool +- `::EVENT_AFTER_SAVE` # + - Called after saving the event data + - `\Solspace\Calendar\Events\SaveElementEvent` contains these methods: + - `getElement()` - returns `\Solspace\Calendar\Elements\Event` + - `isNew()` - bool +- `::EVENT_BEFORE_DELETE` # + - Called before deleting an event + - `\Solspace\Calendar\Events\DeleteElementEvent` contains these methods: + - `getElement()` - returns `\Solspace\Calendar\Elements\Event` +- `::EVENT_AFTER_DELETE` # + - Called after deleting an event + - `\Solspace\Calendar\Events\DeleteElementEvent` contains these methods: + - `getElement()` - returns `\Solspace\Calendar\Elements\Event` + +## Events for Calendars + +`\Solspace\Calendar\Services\CalendarsService` + +- `::EVENT_BEFORE_SAVE` # + - Called before saving the calendar data + - `\Solspace\Calendar\Events\SaveModelEvent` contains these methods: + - `getModel()` - returns `\Solspace\Calendar\Models\CalendarModel` + - `isNew()` - bool +- `::EVENT_AFTER_SAVE` # + - Called after saving the calendar data + - `\Solspace\Calendar\Events\SaveModelEvent` contains these methods: + - `getModel()` - returns `\Solspace\Calendar\Models\CalendarModel` + - `isNew()` - bool +- `::EVENT_BEFORE_DELETE` # + - Called before deleting a calendar + - `\Solspace\Calendar\Events\DeleteModelEvent` contains these methods: + - `getModel()` - returns `\Solspace\Calendar\Models\CalendarModel` +- `::EVENT_AFTER_DELETE` # + - Called after deleting a calendar + - `\Solspace\Calendar\Events\DeleteModelEvent` contains these methods: + - `getModel()` - returns `\Solspace\Calendar\Models\CalendarModel` + +## Usage Examples + +In your plugin's `::init()` method, subscribe to any of these events by using the `Event::on()` static method: + +```php showLineNumbers +isNew(); + $event = $event->getElement(); + // Do something with this data + } + ); + } +} +``` diff --git a/craft-calendar_versioned_docs/version-v6/developer/hooks.mdx b/craft-calendar_versioned_docs/version-v6/developer/hooks.mdx new file mode 100644 index 00000000..690cc405 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/developer/hooks.mdx @@ -0,0 +1,91 @@ +--- +title: Hooks +sidebar_position: 2 +description: Template hooks for customizing Solspace Calendar 6.x output in Craft CMS. +--- + +import { Badge } from '@site/src/components/utils'; + +# Developer Hooks + +Calendar provides hooks that give plugins the opportunity to insert their own template code into Calendar's templates. This allows you to add HTML, Javascript and Twig variables to extend the capabilities of Calendar. + +## Control Panel + +When viewing calendars in the control panel, you'll have access to the following hooks: + +### `cp.solspace.calendar.filters` + +This hook can be used to customize the calendar filters. Using the option `criteria`, you can pass [additional parameters](../templates/queries/events.mdx#parameters) when querying event data. + +## Usage Examples + +### Add Author Filtering to Month/Week/Day View + +In your plugin's `::init()` method, or by using the `Event::on()` static method: + +```php showLineNumbers +view->hook('cp.solspace.calendar.filters', function () { + $calendarId = 5; + + $events = Calendar::getInstance()->events + ->getEventQuery([ + 'calendarId' => [$calendarId], + ]) + ->all(); + + $authors = []; + + foreach ($events as $event) { + $authorsList = ''; + $authorsList .= ''; + + return $authorsList; + }); + + Event::on( + UrlManager::class, + UrlManager::EVENT_REGISTER_CP_URL_RULES, + function (RegisterUrlRulesEvent $event) { + $event->rules['cpActionTrigger1'] = 'events/create'; + $event->rules['cpActionTrigger2'] = 'submissions/create'; + $event->rules['cpActionTrigger3'] = 'spam/create'; + } + ); + } +} +``` diff --git a/craft-calendar_versioned_docs/version-v6/events/_category_.json b/craft-calendar_versioned_docs/version-v6/events/_category_.json new file mode 100644 index 00000000..dcc7296e --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/events/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Events", + "position": 5 +} diff --git a/craft-calendar_versioned_docs/version-v6/events/exporting.mdx b/craft-calendar_versioned_docs/version-v6/events/exporting.mdx new file mode 100644 index 00000000..7db48a9e --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/events/exporting.mdx @@ -0,0 +1,23 @@ +--- +sidebar_position: 3 +title: Exporting Events +description: Export events and calendars from Solspace Calendar 6.x in Craft CMS. +--- + +import { Badge } from '@site/src/components/utils'; + +# Exporting Events + +Calendar currently allows for both downloading of ICS Export files and ICS Subscriptions URLs. + +## ICS Export + +The [calendar.export](../templates/queries/export.mdx) template query lets you export all or specific calendar events as an `ICS` formatted file. This will cause the user to receive a file download dialogue, and allow them to import the event(s) into a calendaring app like Apple Calendar or Google Calendar. + +## ICS Subscriptions + +[Calendars](./index.mdx) include an option to share calendars with a publicly accessible ICS subscription URL, allowing users to subscribe (one way sync) their calendaring app to your sites' calendar(s). To enable this, click on the **Share this calendar** button next to the applicable calendar(s) on the list view of calendars in control panel. Once enabled, you can then copy the ICS URL and share it with whoever you wish (admins, show it publicly, etc). + +:::warning +ICS subscriptions currently do not work correctly for Google Calendar when using _Floating Timezone_. The issue is that there's a "bug" or at least oddity in [the way Google Calendar handles events with floating dates](https://productforums.google.com/forum/#!topic/calendar/Xjxs5UjhsXI) compared to all other calendaring apps. Google does not to conform to [iCal standards](https://tools.ietf.org/html/rfc5545#section-3.3.5) for this. You can work around this by setting the **Forced ICS Event Timezone** setting for each calendar to a real timezone. +::: diff --git a/craft-calendar_versioned_docs/version-v6/events/fieldtype.mdx b/craft-calendar_versioned_docs/version-v6/events/fieldtype.mdx new file mode 100644 index 00000000..0b88d051 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/events/fieldtype.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 6 +title: Element Field Types +description: Calendar Events Field Type for relating events to other elements in Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Element Field Types + +Calendar includes Calendar Events and Calendar Calendars fieldtypes, which allows you to assign/relate events and whole calendars (ID's) to other element types such as Craft Entries and even other events themselves. + +## Calendar Events + +The Calendar Events field type allows you to assign/relate events to other element types such as Craft Entries and even other Calendar events. + +### Creating an Events field + +Creating a Calendar Events field is done just like any other fieldtype, here's an overview of the process: + +1. Go to the **Settings** area in Craft control panel. Click on **Fields**. +2. Click the **New field** button in the top right corner. +3. Name the field as you wish. For example: _Related Events_ with a handle of _relatedEvents_. +4. For the **Field Type** option, select _Calendar Events_ from the list. +5. The **Sources** list lets you narrow down the possible assignable events to this field by calendar. Select all or whichever calendar(s) you'd like. +6. **Limit** limits the number of events you can select for this field. +7. **Selection Label** is the text that will appear on the button which opens the Event selection pop-up dialog. +8. Click the **Save** button in the top right corner to save the new field. + +Your Calendar Events field is now available to be assigned to other sections. + + + +### How the Fieldtype works + +The Calendar Event fieldtype lets the user assign any events that have been created in the Calendar Events page to any element: a section entry, categories, assets, etc. Even events themselves. + + + + +### Use in Templates + +You add the Calendar Event fieldtype to your template code just like you would for any other field. Continuing off the example above (with handle of _relatedEvents_), your code would look something like this: + +```twig showLineNumbers +{% if entry.relatedEvents is defined and entry.relatedEvents is not empty %} +
    + {% for event in entry.relatedEvents.status(null).all %} +
  • + {{ event.title }} - {{ event.startDate.format("l, F j, Y \\a\\t g:ia") }} + ({{ event.duration.humanReadable }}) + in {{ event.calendar.name }} calendar. + {% if event.repeating %} + Repeats {{ event.readableRepeatRule }} + {% endif %} +
    • + {% endfor %} +
+{% else %} +

No events related to this entry.

+{% endif %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/events/importing.mdx b/craft-calendar_versioned_docs/version-v6/events/importing.mdx new file mode 100644 index 00000000..addd7e3b --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/events/importing.mdx @@ -0,0 +1,98 @@ +--- +sidebar_position: 4 +title: Importing Events +description: Import events and calendars into Solspace Calendar 6.x for Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Importing Events + +Calendar now has an official integration for the Craft [Feed Me](https://docs.craftcms.com/feed-me/v4/) plugin, which allows you to import and/or update existing Calendar events. When using **Feed Me**, please be sure to look for the _Solspace Calendar Events (official)_ option for the **Element Type** type option when setting up a new feed. To get the Craft [Feed Me](https://plugins.craftcms.com/feed-me) plugin, search for `feed me` in the Craft Plugin Store. + + + +## Overview + +Currently, there are 5 different feed types available to choose from: + +- **ATOM** +- **CSV** +- **JSON** +- **RSS** +- **XML** + +You can select which calendar to check against, and decide from any of the following behaviors: + +- **Create new events**: Adds new events if they do not already exist. +- **Update existing events**: Updates events that match the Unique Identifier (next step). +- **Disable missing events**: Disables any events that are missing from the feed. +- **Delete missing events**: Deletes any events that are missing from the feed. Be careful. + +The most important fields to import on the **Event Fields** mapping page are: + +- **Title** +- **Start Date** (e.g. `2021-02-14 07:00:00`) +- **End Date** (e.g. `2021-02-14 13:00:00`) +- **All Day** (e.g. `1` for all-day, `0` for non all-day events) +- **Repeat Rule** (e.g. `RRULE:FREQ=MONTHLY;UNTIL=20211016T235959Z;BYMONTHDAY=14;INTERVAL=1`) + - This is only necessary when you have repeating events. + - If you have a valid _RRULE_ mapped to the **Repeat Rule** setting, Calendar will automatically map the necessary parts over to the other fields/columns in the database. By default, if `INTERVAL` is not included in the _RRULE_ value, Calendar will assume and default it to `1`. + - The other remaining **Recurrence Fields** options are all optional and likely not necessary for most setups if you have a valid _RRULE_ value. + - If you have repeating events but do not have a valid _RRULE_ value to map, you can map the other **Recurrence Fields** options individually. However, without a value _RRULE_ passed off to the Calendar event's **RRULE** column in the database, Calendar will not be able to properly display recurrences until the event is resaved manually. + +See the [example JSON file](#example-json-file) below. + +## Example JSON file + +```json showLineNumbers +{ + "events": { + "event": [ + { + "title": "Feed Me Test Regular Event", + "startDate": "2021-02-11 07:00:00", + "endDate": "2021-02-11 13:00:00", + "allDay": 0 + }, + { + "title": "Feed Me Test Recurring Event with RRULE", + "startDate": "2021-02-14 07:00:00", + "endDate": "2021-02-14 13:00:00", + "allDay": 0, + "repeatRule": "RRULE:FREQ=MONTHLY;UNTIL=20211016T235959Z;BYMONTHDAY=14" + }, + { + "title": "Feed Me Test Recurring Event with RRULE and INTERVAL", + "startDate": "2021-02-14 07:00:00", + "endDate": "2021-02-14 13:00:00", + "allDay": 0, + "repeatRule": "RRULE:FREQ=MONTHLY;UNTIL=20211016T235959Z;BYMONTHDAY=14;INTERVAL=2" + }, + { + "title": "Feed Me Test Recurring Event without RRULE", + "startDate": "2021-02-14 07:00:00", + "endDate": "2021-02-14 13:00:00", + "allDay": 0, + "repeatInterval": 1, + "repeatFrequency": "MONTHLY", + "repeatCount": null, + "repeatUntil": "2021-10-16 23:59:59", + "repeatByMonth": null, + "repeatByYearDay": null, + "repeatByMonthDay": 14, + "repeatByDay": null + }, + { + "title": "Feed Me Test All Day Event", + "startDate": "2021-02-17 00:00:00", + "endDate": "2021-02-17 23:59:59", + "allDay": 1 + } + ] + } +} +``` diff --git a/craft-calendar_versioned_docs/version-v6/events/index.mdx b/craft-calendar_versioned_docs/version-v6/events/index.mdx new file mode 100644 index 00000000..798b20b8 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/events/index.mdx @@ -0,0 +1,151 @@ +--- +title: Managing Events +description: Manage and create events in Solspace Calendar 6.x for Craft CMS. +--- + +import Player from 'react-player'; + +import { Photo, Badge } from '@site/src/components/utils'; + +# Managing Events + +_Solspace Calendar_ is an **Element Type** that allows you create and manage event entries similar to regular Craft Entries. The control panel also includes a groundbreaking approach to event management that feels very similar to popular calendaring apps like _Apple Calendar_ and _Google Calendar_. + +You can also manage a set of calendars that become available to assign to each event. + +## Month, Week & Day views + +Similar to popular calendaring apps, _Solspace Calendar_ allows you to view a full month, week and day view of your existing events, and click on any day of the month or time slot to quickly "pencil in" new events, click on existing events to edit them, and drag and drop events to move them to other days or times. + +Also available is an optional sidebar for Month/Week/Day views that allows you to filter your events by calendar, and quickly navigate to certain days. + + + + + +Just to be clear, while these views will closely resemble popular calendaring apps, there are some limitations with more complex things. + +The following actions are currently available: + +- **Create Events** # + - Allows you to set event **title**, **calendar**, **start date** and **time**, **end date** and **time**, **all day** event. + - Currently, all other field data has to be done within _Edit Event_ area. + :::info + This feature currently bypasses required fields. Since we currently don't support displaying any fields here, and cannot make an exception for required fields to display (especially if a field layout contains complex and/or third party fields and/or many fields), we feel it's the lesser of two evils to bypass required fields at this time. The intended workflow is that this feature is used to quickly "pencil in" an event or set of events, and then edit the details of them later. + ::: + - **Click anywhere** on the page to **create an event**. If you click on May 14th in month view, it'll assume you want the event created for that start date. If you click on 8:00 am slot for May 14th of Day or Week view, it will assume you want the event created for that start date and time. + - **Click and hold** on a date in Month view, then drag your mouse to another date and let go to create **multi-day events**. If you click on May 14th, and let go on May 17th, it will assume you're wanting an event that starts May 14th and ends May 17th. + - **Click and hold** on an hour slot in Week or Day view, then drag your mouse to another time slot and let go to specifically **set the duration** of an event. If you click and hold on 8:00 am time slot for May 14th, and let go on 1:30 pm time slot, it will assume you're wanting an event on May 14th that starts at 8:00 am and ends at 1:30 pm. In Month view, dragging can span multiple days as well. +- **Modify Events** # + - **Click, drag and drop** on event blocks to **move** them to different dates or times. In Month view, if you click on an event on May 14th, and drag it to May 15th, it'll update to that date. In Week or Day view, if you click on an event that's on May 14th from 8:00 am to 11:00 am, and drag it to 3:00 pm, it will be updated to be May 14th from 1:00 pm to 4:00 pm. + - **Click and drag** handle at bottom of event blocks to **shorten or lengthen the duration** of events in Week and Day views. + - **Click, and hold** on events in **all day** time slot, and drag them to any time slot to switch them from all day and specify a start time. Click and drag the handle at the bottom of event block to shorten or lengthen the event duration. Events can also be switched to **all day** events by dragging an event block into the **All Day** area. + - **Hover mouse** over an event to **view more information** for it. + - **Hover mouse** over an event and click on **Edit** button to edit the event in the _Edit Event_ area. +- **Delete Events or Occurrences** # + - **Hover mouse** over an event and click on **Delete** button to delete the entire event and its recurrences (if applicable). If this is a recurring event, this will remove ALL occurrences BEFORE and AFTER the date you selected, not just that one and future ones. + - **Hover mouse** over a **recurring event** and click on **Delete Occurrence** button to delete only that specific recurrence of the event. An exception will be made for that particular date. +- **Switch Site** # + - Calendar includes a site switcher dropdown menu at the top right of the Month/Week/Day CP pages. Simply select the applicable site if you wish to see events for that site and their localized titles. + + + +### Current Limitations + +_Solspace Calendar_ attempts to adjust start dates, end dates, repeat rule options and exclusions when you modify events in the Month, Week and Day views. However, some complex recurring events currently may not update as you expect (particularly with the **On the First/Second/etc** rule option): + +- Events that repeat **Monthly** with the **On the First/Second/etc** rule will only stay within its current **On the First/Second/etc** rule. So for example, dragging an event with the rule of **On the Second Thursday** to the equivalent of **On the Third Wednesday** will change the rule to **On the Second Wednesday**, while the first start date will be set at the date of the Third Wednesday, so you may also notice that you have missing or extra occurrence(s) at the beginning. +- Events that repeat **Yearly** with the **On the First/Second/etc** rule will only stay within its current **On the First/Second/etc** rule. SO for example, dragging an event with the rule of **On the Second Monday** to the equivalent of **On the Third Wednesday** will change the rule to **On the Second Wednesday**, while the first start date will be set at the date of the Third Wednesday, so you may also notice that you have missing or extra occurrence(s) at the beginning. If events like these are modified enough times, it's very possible that all the event data for the event will get very out of whack, such as repeating into the next month, etc. +- Expected behavior when **moving occurrences** with the **Select Date** repeat rule type is that only the touched occurrence will be moved (all other occurrences will stay in their current days). However, when adjusting the time of one of these occurrences will update the time for ALL occurrences, as event times must be uniform. +- When dragging an event across 3 months (skipping the main month being viewed) may have the event(s) skip the number of days the month is short of `31` days, e.g. Dragging an event from _March 1_ to _January 28_ may have the event shoot forward 3 days to _January 31_, presumably because February contains only `28` days, `3` short of `31`. This appears to be due to a bug in PHP where the date interval does not work as expected. If you experience this, you can work around it by dragging the event one more time to the appropriate date and it should work correctly. + +## Managing Events + +This area will appear very similar to traditional Craft Entries approach. You can view, filter and sort a list of available events, as well as create, edit or delete events. + + + + + + + + + +### Event Options + + + + + You can watch the video to see all of the available Event Element UI options + and interactions. A list of this is available below the video. + + +The _Solspace Calendar_ Event Element UI allows you to create events with the following options: + +- **Calendar** + - Displays the calendar the event is assigned to. + - This currently cannot be changed. +- **Date** (required) + - Datepicker & timepickers in 15, 30 or 60 minute increments for start date, start time, and end time. If the event will span more than one day, toggle the **Multi-Day** lightswitch. +- **All Day** event option + - If selected, the Start and End Time fields hide. +- **Multi-Day** event option + - If selected, an End Date field becomes visible to specify the end date. +- **Repeats** option + - When enabled, additional options are displayed for recurrence rules: + - Every **# Days** + - Every **# Weeks** on + - **S M T W T F S** (multiple select) + - Every **# Months** + - Each: + - **1** through **31** full month calendar picker table view (multiple select) + - On the **First**/**Second**/**Third**/**Fourth**/**Last** + - **S M T W T F S** (multiple select) + - Every **# Years** + - On same month and day selected in Start Date (default) + - (optional) On the **First**/**Second**/**Third**/**Fourth**/**Last** + - **S M T W T F S** (multiple select) of + - **January** through **December** (multiple select) + - on **Select Dates** - displays a date picker that allows you to select days to manually include recurrences. Select date inclusions can be applied either by clicking the date in the date picker, or by typing the date in the input field and hitting **Enter**. + - For each date selected, they are displayed in a list. Each selected date can be removed by clicking the `-` beside it. + :::info + Selected dates cannot be used in conjunction with other rule types. All selected dates cannot have different times, as event times must be uniform. + ::: + - **End Repeat** + - **Never ends** (default) - event will repeat forever + - **On date** - use the date picker or type the date in the input field + - **After # times** - enter the number of times you'd like the event to repeat, including the first instance + - **Except On** - displays a date picker that allows you to select days to exclude recurrences from displaying in the front end. Exclusions can be applied either by clicking the date in the date picker, or by typing the date in the input field and hitting **Enter**. + - For each date selected, they are displayed in a list. Each selected date can be removed by clicking the **-** beside it. + +### Element Field Types + +Because _Calendar_ is an Element Type, you're able to assign/relate events to other element types such as Entries and even other events themselves. Calendar also allows you to assign/relate entire calendars (their calendar ID) to other element types such as Entries and even other events themselves. + +To create and use the _Calendar_ Event and Calendars field types, refer to the [Element Field Types](./fieldtype.mdx) documentation. diff --git a/craft-calendar_versioned_docs/version-v6/events/widgets.mdx b/craft-calendar_versioned_docs/version-v6/events/widgets.mdx new file mode 100644 index 00000000..f61a935d --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/events/widgets.mdx @@ -0,0 +1,37 @@ +--- +sidebar_position: 5 +title: Dashboard Widgets +description: Dashboard widgets for Solspace Calendar 6.x in Craft CMS. +--- + +import { Photo, Badge } from '@site/src/components/utils'; + +# Dashboard Widgets + +Calendar includes 4 different widgets for use on the Craft Dashboard page. + +## Quick Event widget + +With the Quick Event widget, you'll have the ability to quickly add simple events to your calendars without leaving the dashboard! + + + +## Calendar Agenda widget + +The Calendar Agenda widget is really a **3-in-1** widget that allows you to select simplified mini versions of the **Month**, **Week** and **Day** views you see in the _Solspace Calendar_ control panel area. Select the type you most prefer, or make one of each! Use the settings to set which calendars you'd like to include, and what you'd like for the title of the widget. For **Week** and **Day** widgets, it will automatically scroll to the current time for the logged in user. + + + +## Upcoming Events widget + +With the Upcoming Events widget, you'll be able to see an overview of upcoming events from your calendar. Use the settings to set which calendars you'd like to include, the title for the widget, and how many events it should display. + +## Mini Calendar widget + +With the Mini Calendar widget, you'll be able to browse through months with AJAX and see which days in the current month have events in them, as well as go directly to any date in the Day view when you click on a day number. Use the settings to set which calendars you'd like to include in the display. diff --git a/craft-calendar_versioned_docs/version-v6/guides/_category_.json b/craft-calendar_versioned_docs/version-v6/guides/_category_.json new file mode 100644 index 00000000..ef8e9dca --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "User Guides", + "position": 3 +} diff --git a/craft-calendar_versioned_docs/version-v6/guides/common-issues.mdx b/craft-calendar_versioned_docs/version-v6/guides/common-issues.mdx new file mode 100644 index 00000000..34ebef51 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/common-issues.mdx @@ -0,0 +1,49 @@ +--- +sidebar_position: 2 +title: Common Issues +description: Common issues and troubleshooting for Solspace Calendar 6.x in Craft CMS. +--- + +# Frequently Asked Questions + +Below are some common questions that are asked about how _Solspace Calendar_ works, and what its limitations are: + +## Can I use Calendar as a Booking System? + +Calendar is best suited as an internal or editorial event system, not a booking or appointment system. It's designed for administrators to create and manage events, not for customers to make bookings through a front-end flow. + +While Calendar's features appear to get you most of the way there to a booking system, it does not support customer-facing booking features such as: + +- Availability or time-slot enforcement +- Preventing double bookings +- Booking rules or constraints +- Payments or payment integrations + +Although it's possible to have users [submit events on the front end](./templating/events-front-end.mdx), extending this in a way that is intuitive for regular users and includes features not available in Calendar would require significant custom development to deliver a suitable end-user experience. + +If customer bookings, conflict prevention, or payments are required, we recommend using a dedicated booking or appointment solution rather than Calendar. + +## How does Calendar handle timezones? + +Calendar does not use Timezones. All event date data is stored as **UTC+0**, and retrieved as **UTC+0**. So, no matter where you are in the world, an event start date entered at **6pm** will be stored and displayed always as **6pm**. The [calendar.export](../templates/queries/export.mdx) template query compensates for this by setting the timezone as **[floating](https://tools.ietf.org/html/rfc5545#section-3.3.5)**, which (in the current example) means the event will show up at 6pm no matter what timezone the user is located in. + +The only place timezones are used is when it checks the current date/time of the currently logged in user, or logged out user. If a user is logged in, Calendar will show/consider **today** as whichever day it is for that user. If the user is not logged in, Calendar will use the site's current timezone to determine when **today** is. For example, this is used for highlighting the correct date in a month or week view calendar as **Today**, or determining which month to show (in the case of last or first day of the month). + +## How do I have Calendar use a different first day of the week? + +This can be configured in the General Settings of Calendar using the [Week Starting Day](../configuration/settings.mdx#week-starting-day) setting. +Calendar defaults to the _Current user's Locale_ option, which means the first day of the week to the currently logged in user's first day of week. If the user is not logged in, it defaults to the global _First Day of Week_ Craft setting (`defaultWeekStartDay` setting in the Craft general config file located at **/config/general.php**). To have Calendar use a day like _Monday_ as the first day of the week, simply add this line to your general config file: + +```php showLineNumbers +'defaultWeekStartDay' => 2, +``` + +You can also override at the template level by using the `firstDay` parameter available in the [calendar.month](../templates/queries/month.mdx), [calendar.week](../templates/queries/week.mdx) or [calendar.day](../templates/queries/day.mdx) queries and specifying an `int` value representing the first day of week (**0-6**, `0` being **Sunday**, `6` being **Saturday**). + +## Can I have different Field Layouts per Calendar? + +Yes, Calendar allows each calendar group to have its [own set of fields and unique field layout](../events/index.mdx). + +## Are there User Group Permissions for Calendar, and how granular are they? + +Currently, Calendar includes permission controls through the regular Craft User Group Permissions. Simply visit the permissions page for the applicable user group(s) (**Settings > Users > User Groups**) to grant/edit/remove permissions to Solspace Calendar. [View Permissions documentation](../configuration/permissions.mdx). diff --git a/craft-calendar_versioned_docs/version-v6/guides/getting-started.mdx b/craft-calendar_versioned_docs/version-v6/guides/getting-started.mdx new file mode 100644 index 00000000..90144d9e --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/getting-started.mdx @@ -0,0 +1,156 @@ +--- +sidebar_position: 1 +title: 'Getting Started' +description: Getting started guide for Solspace Calendar 6.x in Craft CMS. +--- + +import Icons from '@site/static/icons/cards'; + +# Introduction + +The _Solspace Calendar_ add-on is very powerful and flexible, and therefore complex, and can require a bit of time to learn and understand how all things work. Included with _Solspace Calendar_ is a set of [Demo Templates](../configuration/demo-templates.mdx) that can be installed on your site, instantaneously giving you a real-world set of styled, working templates. To help you better understand each template query and their use, we've also included this resource. + +## Overview + +The document below serves as a templating guide. For information about creating events and adding them to other entries, view the [Managing Events](../events/index.mdx) documentation. + +Calendar includes the following template queries: + +- [calendar.events](#calendarevents) +- [calendar.occurrences](#calendaroccurrences) +- [calendar.calendars](#calendarcalendars) +- [calendar.calendar](#calendarcalendar) +- [calendar.month](#calendarmonth) +- [calendar.week](#calendarweek) +- [calendar.day](#calendarday) +- [calendar.hour](#calendarhour) +- [calendar.export](#calendarexport) + +### calendar.events + +The [calendar.events](../templates/queries/events.mdx) template query allows you to display lists of Calendar Event elements. You can filter events by calendars, authors, statuses, date fields, custom fields, and more. + +It would be most common to use this template query when you want the actual Event element records. If you need each generated recurring date in chronological order, use `calendar.occurrences`. + +### calendar.occurrences + +The [calendar.occurrences](../templates/queries/events.mdx#occurrence-query) template query allows you to display generated event occurrences ordered chronologically. Calendar 6 stores occurrences in dedicated occurrence tables, so this is the preferred query for date-range calendar views, upcoming event lists, and specific recurrence detail pages. + +### calendar.calendars + +The [calendar.calendars](../templates/queries/calendars.mdx) template query simply lets you display lists of calendars and information about each one. You would commonly use this template query to display a list of available calendars, letting your users filters lists of events by calendars, etc. If you wish to display the calendar that is assigned to your event, each event contains a calendar object which contains the calendar data. + +### calendar.calendar + +The [calendar.calendar](../templates/queries/calendar.mdx) template query simply lets you display a single calendar and information about it. + +### calendar.month + +The [calendar.month](../templates/queries/month.mdx) template query lets you to display a traditional month calendar grid view for a specified month, or the current month. It comes ready to go with nested week, day and hour lists, event lists and queries that help you create the full month view table. It also automatically knows to make sure each week at the beginning and end of the month is displayed as full week with the previous and next months overflowing. For example, if the current month is **March**, and **March 1st** starts on **Tuesday**, [calendar.month](../templates/queries/month.mdx) will automatically include **Sunday & Monday** of **February** at the beginning of the month table. + +The result is that your calendar full month view will feel and look similar to _Apple Calendar_ or _Google Calendar_, etc. + +### calendar.week + +The [calendar.week](../templates/queries/week.mdx) template query lets you display a week view of events for a specified week, or the current week. It comes ready to go with nested day and hour lists, event lists and queries to assist with formatting. It also automatically knows to make sure each week is displayed as full week. + +The result is that you're able to construct a week view calendar that can look somewhat similar to _Apple Calendar_ or _Google Calendar_, etc. + +### calendar.day + +The [calendar.day](../templates/queries/day.mdx) template query lets you to display a full day view of events for a specified day, or the current day / today. It comes ready to go with a nested hour list, event lists and queries to assist with formatting. + +The result is that you're able to construct a day view calendar that can look somewhat similar to _Apple Calendar_ or _Google Calendar_, etc. + +### calendar.hour + +The [calendar.hour](../templates/queries/hour.mdx) template query lets you display events for a specific hour of the day. It comes ready to go with an event list and queries to assist with formatting. + +### calendar.export + +The [calendar.export](../templates/queries/export.mdx) template query is available for event exporting purposes. It outputs an **ICS (RFC-2445)** compatible file, which can then be imported into other programs such as _Google Calendar_, _Apple Calendar_, _Microsoft Outlook_, etc. + +This query contains pre-formatted info, so you just need to specify the template query and apply some parameters and link to it. When the template that contains this query is accessed, the browser will instantly provide users with a download dialog of an **ICS** file. + +## Understanding how Recurrences are handled + +Calendar 6 stores generated occurrences in dedicated occurrence tables and refreshes them when events are saved. This makes date-range queries more reliable and gives each occurrence a stable occurrence key while the event itself remains a single Craft element. + +Most template queries still return familiar Calendar Event objects in chronological order. If an event repeats, the original event is still the parent event and each occurrence points back to that same event ID. The occurrence date is what changes between results. This is important to understand because most users like to link events from their Month, Week or Day calendars to an event detail page that shows in-depth information about the event or its recurrence(s). There is [a way around this though](#getting-around-recurrence-date-limitations-on-event-detail-page) (see below)... + +## Getting around Recurrence date limitations on Event Detail page + +Because all recurrences share the same ID, unfortunately there isn't an automatic way for your event detail page to know which dates to display (for example - if you have an event that starts on **February 6** and **repeats every week on Wednesday**, the recurrences on **February 13**, **20**, etc of course happen on different days). While you will likely want to display the date of the recurrence when clicked to, Calendar will generally only know how to display the very first start/end date of the parent event. + +A simple way around this is to **include date segments in the URI** when you link to your event detail page. So for example, if you have a full month view template, instead of just linking each recurrence to its parent entry ID, be sure to also include the date of the recurrence in the URI as segments as well. + +```twig showLineNumbers + + {{ event.title }} + +``` + +When using a Calendar template query such as [calendar.month](../templates/queries/month.mdx), each [Event object](../templates/objects/event.mdx) in the `month.events` list will have the correct date of each recurrence. So simply sneak that into your link to the event detail page, and you will now have some data to work with. + +In the event detail template, use [calendar.occurrences](../templates/queries/events.mdx#occurrence-query) to load the occurrence represented by the URL date segments. + +```twig showLineNumbers +{% set occurrenceDate = null %} +{% if seg3 and seg4 and seg5 %} + {% set occurrenceDate = seg3~"-"~seg4~"-"~seg5 %} +{% endif %} + +{% set occurrenceEnd = occurrenceDate ? occurrenceDate|date_modify('+1 day')|date('Y-m-d') : null %} + +{% set occurrence = craft.calendar.occurrences({ + event: seg2, + startsAfterOrAt: occurrenceDate, + startsBefore: occurrenceEnd, +}).one() %} + +{{ occurrence.startDateLocalized|date('l, F j, Y') }} +``` + +## Preventing Endless Search Engine Crawling + +When using some of Calendar's template queries to generate month calendar views, a mini calendar, etc, these will inadvertently create neverending links to dynamically generated URL's to account for endless date possibilities. What can then happen is that search engine crawlers can get stuck on this endlessly. To work around this, you can use some simple Twig conditional checks to wrap around **Previous** and **Next** month/week/day links to prevent them from showing after a certain number of days. + +```twig {7,11,16,29,34} showLineNumbers +
+ {% set month = craft.calendar.month({ + date: targetDate, + calendar: calendarHandle, + }) %} + + {% set dateBoundsHelper = now.diff(month.nextDate)|date('%r%a') %} + +
+
+ {% if dateBoundsHelper > -365 %} + + {{ month.previousDate.format('F') }} + + {% endif %} +
+ +
+

+ {{ date.format('F Y') }}   + + {{ month.eventCount }} event{{ month.eventCount > 1 or month.eventCount == 0 ? "s" }} + +

+
+ +
+ {% if dateBoundsHelper < 365 %} + + {{ month.nextDate.format('F') }} + + {% endif %} +
+
+ ... +``` diff --git a/craft-calendar_versioned_docs/version-v6/guides/security.mdx b/craft-calendar_versioned_docs/version-v6/guides/security.mdx new file mode 100644 index 00000000..dd4f8709 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/security.mdx @@ -0,0 +1,44 @@ +--- +sidebar_position: 7 +description: Security best practices and considerations for Solspace Calendar 6.x in Craft CMS. +--- + +# Security Vulnerability Disclosure + +At Solspace, we take the security of our software seriously. We greatly appreciate security researchers and users who responsibly report vulnerabilities so they can be addressed quickly. + +If you believe you have discovered a security vulnerability in one of our products (such as Freeform or our other plugins), please let us know so we can investigate and resolve the issue. + +## Reporting a Vulnerability + +Please report vulnerabilities by emailing support@solspace.com + +To help us investigate the issue efficiently, please include as much of the following information as possible: + +- A description of the vulnerability +- Steps to reproduce the issue +- A proof-of-concept (if available) +- The affected product and version +- Any relevant screenshots, logs, or code samples + +## Responsible Disclosure Guidelines + +When reporting vulnerabilities, we ask that you: + +- Provide us with a reasonable amount of time to investigate and fix the issue before publicly disclosing it. +- Avoid accessing or modifying data that does not belong to you. +- Avoid actions that could negatively impact the availability or stability of our services or software. + +## Safe Harbor + +We will not pursue legal action against security researchers who report vulnerabilities in good faith and follow the guidelines outlined in this policy. + +## Rewards + +Solspace does not currently operate a formal bug bounty program and cannot guarantee monetary rewards. However, we may offer discretionary rewards (such as free plugin licenses or other recognition) for valid vulnerabilities that are responsibly disclosed. + +## Recognition + +With your permission, we may acknowledge your contribution in release notes or security advisories once the issue has been resolved. + +Thank you for helping us keep our software and users safe. \ No newline at end of file diff --git a/craft-calendar_versioned_docs/version-v6/guides/templating/_category_.json b/craft-calendar_versioned_docs/version-v6/guides/templating/_category_.json new file mode 100644 index 00000000..7b36e075 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/templating/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Templating", + "position": 3 +} diff --git a/craft-calendar_versioned_docs/version-v6/guides/templating/cache.mdx b/craft-calendar_versioned_docs/version-v6/guides/templating/cache.mdx new file mode 100644 index 00000000..9450d526 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/templating/cache.mdx @@ -0,0 +1,60 @@ +--- +title: Cache +sidebar_position: 4 +description: Caching strategies for Calendar 6.x templates in Craft CMS. +--- + +# Cache tag + +Calendar event data and calendar data can be cached with the [Cache tag](https://craftcms.com/docs/4.x/dev/tags.html#cache). However, if you want the cache to refresh whenever you create, update or remove an event or calendar, you will need to specify a **cache key** when doing so. + +For example, caching a calendars list would look like this, and will refresh automatically whenever you create, update or delete a calendar: + +```twig showLineNumbers +{% set calendars = craft.calendar.calendars %} + +{% cache using key craft.calendar.calendarsCacheKey %} +

Calendars

+ {% for calendar in calendars %} +
+ {{ calendar.title }} +
+ {% endfor %} +{% endcache %} +``` + +To cache an events list, it would look like this, and will refresh automatically whenever you create, update or delete an event: + +```twig showLineNumbers +{% set events = craft.calendar.events %} + +{% cache using key craft.calendar.eventsCacheKey %} +

Events

+ {% for event in events %} +
+ {{ event.title }} +
+ {% endfor %} +{% endcache %} +``` + +In this example however, only the event data cache will be refreshed. Since calendars and their data is separate, updating a calendar will not refresh any related calendar specific data in the above example (such as calendar name, handle, color, etc). + +To work around this, you would include a **cache key** for both _calendar_ data and _event_ data, so that all of the cache would refresh if a calendar or event is created, updated or deleted. + +For example: + +```twig showLineNumbers +{% set events = craft.calendar.events %} + +{% cache using key (craft.calendar.calendarsCacheKey ~ craft.calendar.eventsCacheKey) %} +

Event calendars

+ {% for event in events %} +
+ {{ calendar.title }} in {{ event.calendar.name }} +
+ {% endfor %} +{% endcache %} +``` + +You can also clear your cache manually by going into Craft's Settings, and clicking the **Clear Caches** button (choose the **Template caches** option). diff --git a/craft-calendar_versioned_docs/version-v6/guides/templating/events-front-end.mdx b/craft-calendar_versioned_docs/version-v6/guides/templating/events-front-end.mdx new file mode 100644 index 00000000..41b0855a --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/templating/events-front-end.mdx @@ -0,0 +1,123 @@ +--- +title: Creating/Editing Events +sidebar_position: 3 +description: Create and edit Solspace Calendar 6.x events from front-end templates in Craft CMS. +--- + +# Creating/Editing Events on the Front End + +Calendar 6 includes an updated front-end event creation flow. The demo templates are still the best starting point, but the request payload is more direct than Calendar 5 and aligns with the v6 event model, recurrence handling, and persisted occurrence generation. + +## Overview + +A few important things to note are that: + +- Use `craft.calendar.createEvent(siteId, calendarId)` when rendering a new event form. +- Use `craft.calendar.events({...}).one()` when editing an existing event. +- Submit event forms to `calendar/events-api/save`. +- Core event fields are submitted as top-level POST fields. +- Custom fields are submitted in Craft's normal `fields[]` array. For example, a field handle of `location` should use `fields[location]`. +- When the event is saved, Calendar normalizes the event schedule and regenerates persisted occurrences. + +## Loading the Event + +```twig showLineNumbers +{% set currentSite = craft.app.sites.currentSite %} +{% set routeEventId = id is defined ? id : 'new' %} +{% set allowedCalendars = craft.calendar.allowedCalendars %} + +{% if routeEventId == 'new' %} + {% set selectedCalendar = allowedCalendars|first %} + {% set event = craft.calendar.createEvent(currentSite.id, selectedCalendar.id) %} +{% else %} + {% set event = craft.calendar.events({ + id: routeEventId, + siteId: currentSite.id, + status: null, + }).one() %} +{% endif %} +``` + +## Saving the Event + +```twig showLineNumbers +{% if event %} + {% requireEventEditPermissions event %} + +
+ {{ csrfInput() }} + + + + + + + + + + + + + + + + + + + +
+{% endif %} +``` + +## Recurring Events + +For recurring events, submit the normalized recurrence fields alongside the event schedule: + +```twig showLineNumbers + + + + +``` + +The `rrule` value can contain `DTSTART`, `RRULE`, `RDATE`, and `EXDATE` lines. Calendar 6 normalizes this data when the event is saved and regenerates the stored occurrence rows. + +```text +DTSTART:20260714T090000 +RRULE:FREQ=WEEKLY;INTERVAL=1;COUNT=6 +EXDATE:20260728T090000 +``` + +For all-day events, use date-only values: + +```text +DTSTART:20260714 +RRULE:FREQ=DAILY;COUNT=3 +``` + +## JSON Responses + +If the request accepts JSON, Calendar returns a JSON response containing the saved event data transformed for front-end calendar use: + +```json +{ + "success": true, + "event": { + "id": 123, + "title": "Example Event" + } +} +``` + +## Permissions + +Calendar checks the same permissions for front-end event management as it does in the control panel: + +- users need _Manage All Events_ or _Manage Events by Calendar_ access for the target calendar; +- changing an event to another calendar requires create/manage access for the destination calendar; +- guest event creation must also be enabled in Calendar's Guest Access settings. + +The included demo templates contain a complete vanilla JavaScript example for schedule, all-day, recurrence, and custom field handling. diff --git a/craft-calendar_versioned_docs/version-v6/guides/templating/fullcalendar.mdx b/craft-calendar_versioned_docs/version-v6/guides/templating/fullcalendar.mdx new file mode 100644 index 00000000..cca1cbf0 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/templating/fullcalendar.mdx @@ -0,0 +1,24 @@ +--- +title: FullCalendar JS Library +sidebar_position: 5 +description: Integrate FullCalendar.js with Solspace Calendar 6.x in Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# FullCalendar JS Library for Front End + +_Solspace Calendar_ allows you to implement the same [FullCalendar JS library](https://fullcalendar.io) that's used in the CP Month/Week/Day views inside your front end templates, giving you an even prettier and more powerful interface. Because this is a complex integration of the library with Calendar, there currently isn't any documentation for this. Instead, it's best to observe its functionality and example code in the [Demo Templates](../../configuration/demo-templates.mdx). Simply install the Demo Templates that come included with Calendar, and click to the **Create** tab. + +Users with administrative privileges for Calendar will also be able to edit and drag and drop events through the front end. + +It's important to note that this is a fairly limited method for handling the display of your events. Any adjustments needed for this will need to be done by yourself by editing CSS or modifying the code that comes included. We do not provide help/support for this. + + + diff --git a/craft-calendar_versioned_docs/version-v6/guides/templating/relating-elements.mdx b/craft-calendar_versioned_docs/version-v6/guides/templating/relating-elements.mdx new file mode 100644 index 00000000..c4ef8fd8 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/templating/relating-elements.mdx @@ -0,0 +1,135 @@ +--- +title: Relating Elements +sidebar_position: 2 +description: Relating Calendar events to other elements in Solspace Calendar 6.x for Craft CMS. +--- + +# Relating Elements + +This page serves as an example of how to [relate elements](https://craftcms.com/docs/4.x/relations.html) to _Solspace Calendar_ events. + +## Displaying Events Related to a User + +In this first example, we have a **Users** relation field in a Calendar field layout. This allows you to assign/relate a user to each event. At some point, you may wish to display a list of all upcoming events for that given user in your front end templates. + +In the example below, we'll first get the user's username from the 2nd segment of the URL, populate a user profile page, and feed the user ID to a Calendar Events query to display related events (the key here, being the `relatedTo` parameter): + +```twig showLineNumbers +{# Get the username #} +{% set requestedUsername = craft.app.request.getSegment(2) %} + +{# Fetch that user #} +{% set user = craft.users() + .username(requestedUsername|literal) + .one() %} + +

{{ user.name }}

+

{{ user.bio }}

+ +

This User's Events

+{% set events = craft.calendar.events({ + rangeStart: "24 months ago", + rangeEnd: "99 months", + limit: 15, + relatedTo: user.id +}) %} + +
    +{% for event in events %} +
  • {{ event.title }} / {{ event.startDate.format('l, F j, Y') }}
    • +{% else %} +
  • No events could be found for this user.
    • +{% endfor %} +
      +``` + +## Relating Events to other Events + +In this next example, we have set up two calendars. One is a **Tournaments** (`tournaments`) calendar, which holds all of our upcoming tournaments. The other is an **Events** (`events`) calendar, which holds sub-events happening during the tournaments. + +The relationship is unidirectional, going from Tournaments to Events. Meaning, our Tournaments know which Events happen in them, but Events don't know which Tournaments they belong to. + +Listing tournaments and their respective sub-events is easy: + +```twig showLineNumbers +

      Upcoming Tournaments

      + +{# Getting tournaments only here #} +{% set tournaments = craft.calendar.events({ + calendar: ["tournaments"] +}) %} + +{% for tournament in tournaments %} +
        +
      • +
        + {{ tournament.title }}: + {{ tournament.startDate.toDateString }} - {{ tournament.endDate.toDateString }} +
        + + {% if tournament.tournamentEvents|length %} + + {# + We could just iterate over tournament.tournamentEvents but + since Calendar_EventModel contains unneeded logic which + becomes a problem when loading thousands of events, we have + to fetch thin Event objects using the craft.calendar.events() + template query + #} + + {% set events = craft.calendar.events({ + id: tournament.tournamentEvents.ids + }) %} + +
          + {% for event in events %} +
        • +
          + {{ event.title }}: + {{ event.startDate.toDateTimeString }} ({{ event.duration }}) +
          +
          • + {% endfor %} +
        + {% endif %} +
        • +
      +{% endfor %} +``` + +Listing sub-events and the tournament they belong to is a little bit more complicated: + +```twig showLineNumbers +

      Event list

      + +{# Getting non-tournament events here #} +{% set events = craft.calendar.events({ + calendar: ["events"] +}) %} + +{% for event in events %} +
        +
      • +
        + {{ event.title }}: + {{ event.startDate.toDateString }} - {{ event.endDate.toDateString }} +
        + + {# We get any related tournaments here. Since two tournaments MIGHT link to the same event #} + {% set tournaments = craft.calendar.events().relatedTo(event.id) %} + {% if tournaments|length %} +
          + {% for tournament in tournaments %} +
        • +
          + {{ tournament.title }}: + {{ tournament.startDate.toDateString }} ({{ tournament.duration }}) +
          +
          • + {% endfor %} +
        + {% endif %} +
        • +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/guides/templating/searching-events.mdx b/craft-calendar_versioned_docs/version-v6/guides/templating/searching-events.mdx new file mode 100644 index 00000000..452f5f04 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/guides/templating/searching-events.mdx @@ -0,0 +1,110 @@ +--- +title: Searching Events +sidebar_position: 1 +description: Search events in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Searching Events + +This page serves as an example of how to perform basic searching into _Solspace Calendar_ events. Some of the paths assume you're working with the demo templates that come with Calendar. + +## Searching via _calendar.month_ + +```twig showLineNumbers +{% set searchTerm = craft.app.request.getParam("search") %} + +
      +
      + + +
      +
      + +{% set eventOptions = { + date: targetDate, + calendar: calendarHandle, + search: searchTerm ? "customFieldHandle:"~searchTerm : null +} %} +{% set month = craft.calendar.month(eventOptions) %} + + + + + {% for day in month|first %} + + {% endfor %} + + + + {% for week in month %} + + {% for day in week %} + {% if month.containsDate(day.date) %} + + {% endfor %} + + {% endfor %} + +
      + {{ day.date.format('l') }} +
      +
      + + {{ day.date.format('j') }} + +
      + {% else %} +       		+
      + + {{ day.date.format('j') }} + +
      + {% endif %} + {% for event in day.events %} + {% include "calendar_demo/layouts/_event.html" %} + {% endfor %} +
      +``` + +## Searching via _calendar.events_ + +```twig showLineNumbers +{% set searchTerm = craft.app.request.getParam("search") %} + +
      +
      + + +
      +
      + +{% set eventOptions = { + rangeStart: targetStartDate, + rangeEnd: targetEndDate, + limit: 15, + search: searchTerm ? "customFieldHandle:"~searchTerm : null +} %} + +{% paginate craft.calendar.events(eventOptions) as pageInfo, events %} + +{% for event in events %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/headless/_category_.json b/craft-calendar_versioned_docs/version-v6/headless/_category_.json new file mode 100644 index 00000000..a589c484 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/headless/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Headless", + "position": 8 +} diff --git a/craft-calendar_versioned_docs/version-v6/headless/graphql.mdx b/craft-calendar_versioned_docs/version-v6/headless/graphql.mdx new file mode 100644 index 00000000..3052e2e2 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/headless/graphql.mdx @@ -0,0 +1,384 @@ +--- +title: GraphQL +sidebar_position: 1 +--- + +import { Photo } from '@site/src/components/utils'; + +# GraphQL + +Calendar supports querying and mutating calendars and events via GraphQL. This guide assumes you have some GraphQL experience. To learn more about GraphQL and Craft, please check out the [Fetch content with GraphQL](https://craftcms.com/docs/getting-started-tutorial/build/graphql.html) guide. + + + +## Permissions + +Calendar GraphQL schemas use separate read and manage permissions for calendars and events. In the GraphQL schema editor, enable the permissions that match the data a token should access. + +- **Access Events** allows event queries. +- **Read All Events** allows reading events from all calendars. +- **Read Events by Calendar** allows reading events from selected calendars. +- **Manage All Events** allows saving and publishing events in all calendars. +- **Manage Events by Calendar** allows saving and publishing events in selected calendars. +- **Access Calendars** allows calendar queries and calendar management permissions. +- **Create New Calendars**, **Delete Calendars**, **Manage All Calendars**, and **Manage Calendars Individually** control calendar mutations and management access. + +## Querying Calendar data + +Calendar 6 adds top-level GraphQL queries for calendars, events, and occurrences. The legacy `solspace_calendar` wrapper from Calendar 5 is still available for compatibility, but it is deprecated. New headless implementations should use the top-level queries shown below. + +## Querying multiple Calendars + +To query all or some calendars, use the top-level `calendars` query: + +```graphql showLineNumbers +query { + calendars { + id + uid + name + handle + description + color + lighterColor + darkerColor + icsHash + allowRepeatingEvents + + events { + id + uid + title + calendarId + startDate + startDateLocalized + endDate + endDateLocalized + allDay + rrule + } + } +} +``` + +## Querying a single Calendar + +To query a single calendar, use the top-level `calendar` query: + +```graphql showLineNumbers +query { + calendar(handle: "default") { + id + name + handle + events { + id + title + startDateLocalized + endDateLocalized + } + } +} +``` + +## Querying Events + +To query events, use the top-level `events`, `event`, and `eventCount` queries: + +```graphql showLineNumbers +query { + events(calendarId: [1], startsAfterOrAt: "2026-07-01") { + id + uid + title + calendarId + calendar { + id + name + handle + } + startDate + startDateLocalized + endDate + endDateLocalized + allDay + rrule + } + + eventCount(calendarId: [1]) +} +``` + +To query a single event: + +```graphql showLineNumbers +query { + event(id: [123]) { + id + title + startDateLocalized + endDateLocalized + } +} +``` + +## Querying Occurrences + +Calendar 6 includes occurrence queries for expanded event occurrences: + +```graphql showLineNumbers +query { + occurrences(calendarId: [1], startsAfterOrAt: "2026-07-01") { + id + startDate + startDateLocalized + endDate + endDateLocalized + event { + id + title + } + calendar { + id + handle + } + } + + occurrenceCount(calendarId: [1]) +} +``` + +## Calendar Query Arguments + +The following arguments are available when querying single or multiple calendars: + +| Argument | Type | Description | +| --------- | ---------- | --------------------------------------------------- | +| `id` | `[int]` | Narrow the queried calendars by one or more IDs | +| `uid` | `[string]` | Narrow the queried calendars by one or more UIDs | +| `handle` | `[string]` | Narrow the queried calendars by one or more handles | +| `limit` | `int` | Limit the amount of returned calendar results | +| `offset` | `int` | Offset the returned calendar results | +| `orderBy` | `string` | Order the calendars by a specific property | +| `sort` | `string` | Sort by `asc` or `desc` order | + +## Event Query Arguments + +You can query events by the following arguments: + +| Argument | Type | Description | +| ------------------ | -------- | ------------------------------------------------------------------------- | +| `id` | `[int]` | Narrow the queried events by ID | +| `uid` | `[string]` | Narrow the queried events by UID | +| `calendarId` | `[int]` | Narrow the queried events by calendar ID | +| `authorId` | `[int]` | Narrow the queried events by author ID | +| `allDay` | `bool` | Only select all-day events | +| `rangeStart` | `string` | Filter events starting from a certain date. Example: `2026-07-01` | +| `rangeEnd` | `string` | Filter events ending by a certain date. Example: `2026-07-31` | +| `startDate` | `string` | Filter events that start at a certain date | +| `startsBefore` | `string` | Filter events that start before a certain date | +| `startsBeforeOrAt` | `string` | Filter events that start before or at a certain date | +| `startsAfter` | `string` | Filter events that start after a certain date | +| `startsAfterOrAt` | `string` | Filter events that start after or at a certain date | +| `endDate` | `string` | Filter events that end at a certain date | +| `endsBefore` | `string` | Filter events that end before a certain date | +| `endsBeforeOrAt` | `string` | Filter events that end before or at a certain date | +| `endsAfter` | `string` | Filter events that end after a certain date | +| `endsAfterOrAt` | `string` | Filter events that end after or at a certain date | + +Occurrence queries use the same date and calendar filtering pattern as event queries. + +## Saving Calendars + +Use `saveCalendar` to create or update a calendar. Creating calendars requires the **Create New Calendars** GraphQL permission. Updating calendars requires **Manage All Calendars** or access to manage the selected calendar. + +```graphql showLineNumbers +mutation { + saveCalendar( + name: "Courses" + handle: "courses" + color: "#57DB2B" + hasTitleField: true + titleLabel: "Title" + allowRepeatingEvents: true + ) { + id + uid + name + handle + } +} +``` + +To update an existing calendar, pass its `id` or `uid`. + +## Saving Events + +Calendar creates one event mutation per calendar. The mutation name uses the calendar handle: + +```graphql +save_{calendarHandle}_Event +``` + +For example, a calendar with the handle `default` exposes `save_default_Event`. + +```graphql showLineNumbers +mutation saveEvent($siteId: Int, $title: String) { + save_default_Event( + siteId: $siteId + title: $title + startDate: "2026-07-14 09:00" + endDate: "2026-07-14 10:00" + ) { + id + title + startDateLocalized + endDateLocalized + } +} +``` + +Pass `id` to update an existing event. The available custom field arguments depend on the calendar's field layout and the active GraphQL schema. + +## Saving Event Drafts + +Calendar creates one draft mutation per calendar: + +```graphql +save_{calendarHandle}_Draft +``` + +Omit `draftId` to create a new unpublished draft event. Include `draftId` to update an existing draft. + +```graphql showLineNumbers +mutation saveDraft($siteId: Int, $title: String) { + save_default_Draft( + siteId: $siteId + title: $title + draftName: "Headless draft" + ) { + id + draftId + title + } +} +``` + +The response includes both IDs: + +| Field | Description | +| --------- | ----------------------------------------------------------------- | +| `id` | The element ID for the draft event | +| `draftId` | The Craft drafts table ID. Use this value when updating or publishing the draft | + +To update the draft later: + +```graphql showLineNumbers +mutation updateDraft($draftId: ID!, $title: String) { + save_default_Draft( + draftId: $draftId + title: $title + ) { + id + draftId + title + } +} +``` + +## Publishing Event Drafts + +Use `publishEventDraft` to publish a Calendar event draft. This mutation returns the published event ID, so do not add a selection set. + +```graphql showLineNumbers +mutation publishDraft($draftId: ID!) { + publishEventDraft(id: $draftId) +} +``` + +The `id` argument must be the draft's `draftId`, not the event element `id`. + +## Repeating Events and RRULE + +The `rrule` mutation argument accepts an RFC 5545 recurrence rule string. Include a `DTSTART` line and one or more recurrence lines: + +```graphql showLineNumbers +mutation { + save_default_Event( + title: "Weekly Course" + startDate: "2026-07-14 09:00" + endDate: "2026-07-14 10:00" + rrule: "DTSTART:20260714T090000Z\nRRULE:FREQ=WEEKLY;INTERVAL=1;COUNT=6" + ) { + id + title + rrule + } +} +``` + +For all-day repeats, use a date-only `DTSTART`: + +```text +DTSTART;VALUE=DATE:20260714 +RRULE:FREQ=DAILY;COUNT=3 +``` + +You can also include `RDATE` and `EXDATE` lines. + +## Calendar Interface + +These are the fields available for the `CalendarInterface`: + +| Field | Type | Description | +| ---------------------- | -------- | ---------------------------------------------- | +| `id` | `int` | ID | +| `uid` | `string` | UID | +| `name` | `string` | Name | +| `handle` | `string` | Handle | +| `description` | `string` | Description | +| `color` | `string` | Color | +| `lighterColor` | `string` | Lighter variant of the `color` | +| `darkerColor` | `string` | Darker variant of the `color` | +| `icsHash` | `string` | ICS hash of this calendar | +| `allowRepeatingEvents` | `bool` | If the calendar allows repeating events or not | + +## Event Interface + +These are the common fields available for event results: + +| Field | Type | Description | +| -------------------- | ------------------------------------------ | ----------------------------------------- | +| `id` | `int` | Event or draft element ID | +| `uid` | `string` | UID | +| `draftId` | `int` | Draft ID from Craft's drafts table | +| `siteId` | `int` | Site ID | +| `authorId` | `int` | Author's ID | +| `calendarId` | `int` | Calendar ID | +| `calendar` | [`CalendarInterface`](#calendar-interface) | Calendar | +| `title` | `string` | Title of the event | +| `postDate` | `string` | Post Date | +| `startDate` | `string` | Start Date | +| `startDateLocalized` | `string` | Start Date localized | +| `initialStartDate` | `string` | Initial Start Date for repeating events | +| `endDate` | `string` | End Date | +| `endDateLocalized` | `string` | End Date localized | +| `initialEndDate` | `string` | Initial End Date for repeating events | +| `allDay` | `bool` | Whether the event is all-day | +| `multiDay` | `bool` | Whether the event spans multiple days | +| `duration` | `DurationInterface` | Event duration | +| `url` | `string` | Event URL | +| `uri` | `string` | Event URI | +| `rrule` | `string` | RFC 5545 recurrence rule | +| `freq` | `string` | Repeat frequency | +| `interval` | `int` | Repeat interval | +| `count` | `int` | Number of times the event should repeat | +| `until` | `string` | Date until the event repeats | +| `untilLocalized` | `string` | Localized version of the `until` date | +| `byMonth` | `string` | Repeat by month rule | +| `byYearDay` | `string` | Repeat by year day rule | +| `byMonthDay` | `string` | Repeat by month day rule | +| `byDay` | `string` | Repeat by day rule | diff --git a/craft-calendar_versioned_docs/version-v6/intro.mdx b/craft-calendar_versioned_docs/version-v6/intro.mdx new file mode 100644 index 00000000..a1d97b2b --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/intro.mdx @@ -0,0 +1,557 @@ +--- +sidebar_position: 1 +title: 'Overview' +slug: / +hide_table_of_contents: true +id: landing-page +--- + +import { FlexCards, Section } from '@site/src/components/docs'; +import { CraftCalendarPageHeader } from '@site/src/components/docs/PageHeader'; +import SearchBar from '@theme/SearchBar'; +import NavbarSearch from '@theme/Navbar/Search'; + +import Icons from '@site/static/icons/cards'; +import OldIcons from '@site/static/icons/old'; +import { + Photo, + PrimaryButtonWithLink, + SimpleTextLink, + FlexButton, +} from '@site/src/components/utils'; + +# Overview + +
      +
      +
      + + for + +
      + Calendar gives you full control over event management in Craft CMS. Calendar 6 modernizes the event editing experience, stores recurring occurrences for faster querying, supports Craft drafts for events, and expands headless support with richer GraphQL queries and mutations. +
      +
      + + + + + +
      + + + +
      +
      +
      + +
      +
      Docs
      +
      + +
      +
      + +
      + + + +## Key Features + +Calendar is loaded with features that have been battle-tested over the years from hundreds of sites using them. Calendar 6 is a major refactor of Calendar 5, focused on a more Craft-native event model, better recurrence handling, and improved permission control while keeping legacy APIs available where possible. + +:::info Calendar 6 refactor highlights + +- Events now support Craft drafts, including CP draft workflows and GraphQL draft mutations. +- Recurring event occurrences are persisted and queried from dedicated occurrence tables for more reliable date-range filtering. +- Recurrence data is normalized to RRULE/RSet strings, with support for `RRULE`, `RDATE`, `EXDATE`, and all-day date normalization. +- Event timezone handling has been improved with per-calendar defaults and per-event timezone storage. +- Calendar permissions have been reorganized around _Access Events_ and _Access Calendars_, matching the structure used by Freeform. +- GraphQL now includes top-level Calendar queries, occurrence queries, calendar/event mutations, event draft mutations, and legacy compatibility for the v5 `solspace_calendar` wrapper. + +::: + + + +## Intuitive + +Add, edit, move, delete events within intuitive Month/Week/Day views for easier management of events. + + + +## Powerful + +Create complex recurring events with exclusions! + + + +## Calendars + +Create as many different calendars as you need, each with their own layout. + + + +## Dashboard Widgets + +Includes 4 different powerful, customizable dashboard widgets. + + + +## Customizable + +Adjust a wide range of settings to change the way Calendar behaves. + + + +## Live Preview + +Get a feel for how your events will look on the front end, as you create them! + + + +## FullCalendar JS implementation + +Includes a sample front end integration with the FullCalendar JS library. + + + +## Demo Templates + +With one click, you can have a set of working, styled templates ready to go! + + + +## Element Fieldtype + +Attach events to any other Craft Element type. + + + +
      +
      + +|

      |

      Lite

      |

      Pro

      | +|:--- |:---:|:---:| +| One-time Cost | **$99** | **$199** | +| Renewals (optional) | $49/yr | $99/yr | +| [Compatibility](./setup/installing-updating.mdx#requirements)
      _Calendar 6.x supports Craft 5.x, Craft 4.x and [Craft Cloud](https://craftcms.com/cloud)._ | Craft 5+, 4+, _Cloud_ | Craft 5+, 4+, _Cloud_ | +| Intuitive event creation interface | ✓ | ✓ | +| Intuitive month, week & day views in CP | ✓ | ✓ | +| All day & multi-day events | ✓ | ✓ | +| Recurring event rules | ✕ | ✓ | +| Exclusion dates from recurrences | ✕ | ✓ | +| Unlimited calendar groups & colors | ✓ | ✓ | +| Element fieldtype for adding events to other Craft Elements | ✓ | ✓ | +| ICS exporting | ✕ | ✓ | +| ICS subscriptions | ✕ | ✓ | +| Powerful & flexible templating | ✓ | ✓ | +| Show events by lists, months, weeks, and days | ✓ | ✓ | +| Dashboard widgets | ✕ | ✓ | +| 1-click demo templates | ✓ | ✓ | +| GraphQL support | ✓ | ✓ | +| Translatable | ✓ | ✓ | +| Rename plugin | ✕ | ✓ | +| Try out a free unlimited trial today! |
      $99 |
      $199 | + +
      +
      +
      +

      Start exploring Calendar...

      +

      Check out these helpful links.

      +
      + +
      +
      + +
      + +
      +
      + ★★★★★ +

      Provides exactly what it says on the tin. Incredibly powerful and flexible to meet the demands of any calendaring feature.

      + Steven Grant +
      +
      + ★★★★★ +

      I had never dealt with your support until now... I'm seriously impressed.

      +
      +
      + ★★★★★ +

      I consider Solspace plugins to be top-notch, among the best in the Craft community!

      +
      +
      + ★★★★★ +

      Very glad to find that Solspace has such great support. Never really needed it before, but now twice in one week, I was quickly helped back on track!

      +
      +
      + ★★★★★ +

      Calendar has so many repeating event options - it's awesome and my client loves it!

      +
      +
      + +
      + +
      + +
      +
      +

      Start exploring Calendar...

      +

      Check out these helpful links.

      +
      + +
      +
      + +
      +
      +
      + Can I test Calendar before I buy? + + Yes! You can use Calendar on any private domain name for as long as you need, just like with Craft. Whether it's on your local dev server or a staging site, you're good to go. You only have to buy a license when you're ready to launch your site live, just like with Craft. +
      +
      + How many sites does a license cover? + + You only need to buy a Calendar license for each Craft license you have. So, if you're running a Craft multi-site on one install, you just need one license. It's just like Craft! There's no need to get separate licenses for other environments of the same site, like development or staging. +
      +
      + Can I switch to a different edition later? + + Yes! You can switch to the _Lite_ or _Pro_ editions at any time! You just pay the difference in price. For example, if you're using the _Lite_ edition and wish to switch to _Pro_, you will just pay $100. You don't need to reinstall anything and you won't lose any of your data. + + Check out the [Changing Editions](./setup/installing-updating/#changing-editions) guide for more information! +
      +
      + Do you offer discounts to non-profits? + + Yes! We offer a discount to non-profits for 20% off the regular price upon proof of non-profit status. Please [contact us](/support/) for more information about this. +
      +
      + Does the Trial version limit features? + + The trial versions of Solspace software are fully functional and not limited in any way. However, if you try to use a trial version on a production site, Craft will display a red banner at the top of your control panel, prompting you to purchase a license. + + More information about [Craft's license enforcement](https://craftcms.com/knowledge-base/how-craft-license-enforcement-works). +
      +
      + How long does a license last for? + + A single license provides one year of updates and support. After this period, you can continue using the plugin but will no longer receive updates or support. To maintain access to updates and support, you will need to renew your license each year at a discounted rate. +
      +
      + Do I have to renew my license each year? + + You can renew your license after the initial one-year support period has ended. Your plugin will continue to work properly in the meantime. If you prefer, you can wait until the following year to renew and receive the latest updates. + + However, we don't recommend avoiding updates altogether, as you would miss out on new features and important fixes. +
      +
      + What are renewals and how do they work? + + Renewals help you keep your plugin updated and access technical support. However, they are entirely optional. + + For example, if you purchase the _Lite_ edition of Calendar for $99, the renewal price after one year is $49. Your initial purchase of $99 includes support and updates for one year. When it's time to renew, you can extend your updates and support for another year at the renewal price of just $49, rather than paying the full amount of $99 again. +
      +
      + How do I install Calendar? + + Installing Calendar is done just like any other plugin for Craft, similar to how you would install Craft itself. Please refer to the [Installation guide](./setup/installing-updating.mdx) in the documentation. +
      +
      + How do I get support for Calendar? + + We provide free support for Calendar. If you have any questions or encounter issues, you can [create an issue on GitHub](https://github.com/solspace/craft-calendar/issues/new/choose) or [send us a private support ticket](/support/). We're here to help! +
      +
      +
      +
      +

      Start exploring Calendar...

      +

      Check out these helpful links.

      +
      + +
      +
      + +
      diff --git a/craft-calendar_versioned_docs/version-v6/setup/_category_.json b/craft-calendar_versioned_docs/version-v6/setup/_category_.json new file mode 100644 index 00000000..2c084183 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/setup/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Installing & Updating", + "position": 2 +} diff --git a/craft-calendar_versioned_docs/version-v6/setup/changelog.mdx b/craft-calendar_versioned_docs/version-v6/setup/changelog.mdx new file mode 100644 index 00000000..48e6a186 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/setup/changelog.mdx @@ -0,0 +1,285 @@ +--- +title: Changelog +sidebar_label: Changelog +sidebar_position: 2 +toc_max_heading_level: 2 +description: Changelog for Solspace Calendar 6.x for Craft CMS. +--- + +import { TitleDate } from '@site/src/components/docs' + +## 6.0.0-alpha.1 - Unreleased + +### Added +- Added Craft draft support for Calendar events. +- Added persisted occurrence storage and occurrence window tracking for recurring events. +- Added `craft.calendar.occurrences()` for querying generated event occurrences. +- Added per-event timezone storage and per-calendar default timezone support. +- Added top-level Calendar GraphQL queries, occurrence queries, calendar/event mutations, event draft mutations, and draft publishing support. +- Added Calendar 6 GraphQL schema permissions for reading and managing events/calendars, including per-calendar controls. + +### Changed +- Refactored recurrence handling to normalize legacy recurrence data to RRULE/RSet strings. +- Updated front-end event creation to use the `calendar/events-api/save` endpoint and top-level event schedule fields. +- Updated Calendar permissions to use _Access Events_ and _Access Calendars_ groupings. +- Updated calendar event field layouts during migration to ensure the required Calendar Event field layout element exists. + +### Deprecated +- Deprecated the legacy `craft.calendar.event()` helper. Use `craft.calendar.events(...).one()` for existing events and `craft.calendar.createEvent()` for new event form models. +- Deprecated the legacy `solspace_calendar` GraphQL wrapper. It remains available for compatibility, but new Calendar 6 implementations should use the top-level Calendar GraphQL queries. + +## 5.0.29 + +### Added +- Added the ability to disable drag-and-drop event editing in the control panel Month/Week/Day views. + +### Fixed +- Fixed an issue where the field mapping source for the Freeform element integration was stored as a numeric ID instead of the field handle. +- Fixed a tooltip positioning issue in the control panel Month/Week/Day views. + +## 5.0.28 + +### Changed +- Migrated event popups in the CP Month/Week/Day views from **qTip JS** to **Tippy JS** to address some display issues. + +### Fixed +- Fixed an issue where event content could fail to migrate correctly when multiple calendars used different field layouts while running the `calendar/events/fix-titles` and `calendar/events/fix-contents` console commands. +- Fixed a `TypeError` in `EventQuery::setAllDay()` by allowing `null` values. +- Fixed an issue where recurring events could be missing from the search index due to a six-month end date limit. +- Fixed formatting of **Start Date** and **End Date** columns in the CP Events list view for timed vs. all-day events. +- Fixed an issue where control panel-specific CSS was being registered on non-CP requests. + +## 5.0.27 + +### Changed +- Replaced the **Title** column in the **Events** control panel page with a new **Event** column that displays the event title and properly respects **Manage Events** permissions. + +### Fixed +- Fixed an issue where sorting by date columns such as _Date Created_ and _Date Updated_ in the **Events** control panel page was not always accurate. +- Fixed an issue where **Manage Events** permissions did not display event titles correctly in the **Events** control panel page. +- Fixed an issue where **Start Date** and **End Date** values were not localized correctly in the **Events** control panel page. +- Fixed styling issues in the Calendar event date picker. + +## 5.0.26 + +### Added +- **GraphQL**: Added an `eventCount` argument to calendar interfaces. + +### Fixed +- Fixed a **Craft 5.8.22+** compatibility issue where saving Calendar settings could partially save and drop values from other settings pages. +- **GraphQL**: Fixed a `relatedToEntries` filter issue in the event resolver on Craft 5. +- Fixed the **New Event** button when viewing a custom source in the CP Events Index page. +- Fixed event ordering and pagination in the CP Events Index page. + +## 5.0.25 + +### Fixed +- Fixed compatibility issues with the **Blitz** plugin. +- Fixed an issue where **ICS Export** could generate an invalid file. +- Fixed an issue where deleting events could error in multi-site environments when the event's calendar doesn't have the primary site enabled. +- Fixed an issue where filtering by **Date Created** could throw a `server error occurred` message. +- Fixed an issue where the GraphQL field resolver did not work correctly for the **Calendars** field type. +- Fixed a `TypeError` in `EventQuery` when date filters (`dateCreated` / `dateUpdated` / `postDate`) were provided as arrays. + +## 5.0.24 + +### Fixed +- Fixed a bug where months that had days spanning across 6 rows of weeks were being cut off at 5. + +## 5.0.23.1 + +### Fixed +- Fixed the Blitz integration to use the correct event type for `afterDelete` handlers, preventing type errors when deleting events. + +## 5.0.23 + +### Fixed +- Fixed the Blitz integration to use Blitz's `addElement()` and `refresh()` methods instead of the non-existent `purgeElement()` method for cache purging. + +## 5.0.22 + +### Fixed +- Fixed a bug where events couldn't be deleted. + +## 5.0.21 + +### Fixed +- Fixed a potential issue with the Blitz plugin in the Calendar 5.0.20 update. + +## 5.0.20 + +### Fixed +- Fixed a bug where pagination was not showing in the CP Events index. +- Fixed a _Call to a member function getStartDate() on null_ error when using Blitz caching. +- Fixed a bug where an error could occur when editing or creating a calendar in Craft 5.x. + +## 5.0.19 + +### Fixed +- Fixed a bug where modifying an event's date on the CP Month, Week, or Day pages would trigger an error. +- Fixed a bug with querying events by custom fields in GraphQL. +- Fixed a bug where an invalid date fed to the `targetDate` parameter in `calendar.event` would not fail gracefully. + +## 5.0.18 + +### Fixed +- Fixed a bug where events could not be removed from a Calendar field type in another element. + +## 5.0.17 + +### Added +- Verified support for Craft 5.7 and 4.15. + +### Fixed +- Fixed a bug where editing events in a multi-site setup with Site Groups would cause an error. + +## 5.0.16 + +### Added +- Added support for ordering events in the CP Events page by _Calendar_, _Post Date_, _Date Created_, and _Date Updated_. + +### Changed +- Updated the _Delete_ button in the CP Event edit page to match Craft 5. + +### Fixed +- Fixed a bug where attempting to order the CP Events page by custom fields would result in an error and show no results. +- Fixed a bug where an error would display if a _FeedMe_ feed exists for a deleted Calendar. +- Fixed a bug where some events might not have titles generated for them on multi-sites. +- Fixed a bug where ordering events in the CP Events page by _Post Date_ could result in an error. +- Fixed a bug where viewing an event in the CP Event edit page might cause an error if an exclusion exists for the event's _Start Date_. + +## 5.0.15 + +### Added +- Added `calendar/events/fix-contents` command to help fix missing event data after upgrading from Craft 4 to Craft 5. + +## 5.0.14 + +### Changed +- Updated the plugin icon. +- Updated the Calendar dashboard widgets and field types to include the Calendar icon. + +### Fixed +- Fixed a bug where some parts of the event details popup window were not translatable. +- Fixed a bug where events could not be ordered by multiple criteria on the front end. +- Fixed a deprecation warning in the control panel (`ucfirst` to `capitalize`). + +## 5.0.13 + +### Fixed +- Fixed a bug where exporting events would fail if the ICS Description and Location fields were not filled in. +- Fixed a bug that prevented orphaned event field layouts from being deleted during garbage collection. +- Fixed a bug where `getOccurrences` would sometimes not correctly retrieve events results when `rangeEnd` was not set for neverending repeating events. +- Fixed a bug where uploading files to events via the front-end form would not work as of Calendar 5.0.7. +- Fixed various issues with Neo fields. + +## 5.0.12 + +### Fixed +- Fixed a bug that prevented orphaned event field layouts from being deleted during garbage collection. +- Fixed a bug that stopped Neo field translations from working in some situations. +- Fixed a deprecation notice when using Calendar in Craft 5.x. + +## 5.0.11 + +### Changed +- Updated the `fix-field-layout-tabs-elements-uids` console command to address orphaned field layout tabs belonging to the Calendar Event element type. + +### Fixed +- Fixed a bug where the **Author** attribute was included by mistake in the Sort options list for the CP Events index. + +## 5.0.10 + +### Added +- Added support for `Elements::EVENT_REGISTER_ELEMENT_TYPES`. +- Added `calendar/calendars/fix-field-layout-tabs-elements-uids --rebuildProjectConfig` CLI command to resolve issues for Calendar 4.x and earlier versions of 5.0.x where unique UIDs were not being generated for field layout elements when duplicating calendars. This CLI command only applies to sites on Craft 4 that may have duplicated calendars in earlier versions of Calendar 4.x and 5.x. This command will not work on Craft 5 due to bigger differences in storing the data. + +### Fixed +- Fixed a bug where Calendar event titles and fields were not translating correctly in Craft 5. + +### Removed +- Removed the migration that attempted to resolve the issue of unique UIDs not being generated for field layout elements when duplicating calendars. +- Removed unnecessary Craft version helper. + +## 5.0.9 + +### Added +- Added the ability to filter events by _Author_ in the control panel Events index. + +### Fixed +- Fixed a bug where calendars with reused instanced fields in the same field layout (Craft 5) were not saving values. +- Fixed a bug where the _ICS Description_ and _ICS Location_ field dropdowns would not show reused instanced fields (Craft 5) in calendar settings. +- Fixed a bug where the _Calendar Events_ field type could trigger a `Serialization of 'Closure is not allowed'` error. +- Fixed a bug where unique UIDs were not generated for field layout elements when duplicating calendars. Added a migration for Craft 4 installs. + +## 5.0.8 + +### Fixed +- Fixed a bug where unique UIDs were not generated for field layout elements when duplicating calendars. + +## 5.0.7 + +### Fixed +- Fixed issues with permissions when using the Craft Team edition. +- Fixed a bug where using the `groupedBy` methods would return an error when listing events. +- Fixed a bug where importing Calendar events with empty RRULES via Feed Me would fail. +- Fixed a bug where importing Calendar events via _Feed Me_ was incorrectly updating translatable fields. +- Fixed a bug where data from some third-party field types were not saving correctly. + +## 5.0.6 + +### Fixed +- Fixed a bug where installation of Craft CMS would break if the Calendar plugin was enabled in Project Config. +- Fixed a bug where using the `groupedByWeek()` method returns an error. + +## 5.0.5 + +### Changed +- Replaced the custom `UpdateEventsUriJob` with Craft's `UpdateElementSlugsAndUris` job to correctly parse URI parameters. +- Updated the plugin icon with subtle improvements for Craft 5. + +### Fixed +- Fixed a bug where CP breadcrumbs for events in Craft 5 were not displaying correctly. +- Fixed a bug where viewing an event in the CP would sometimes error in Craft 4. + +## 5.0.4 + +### Added +- Added favicons to the demo templates. +- Added `calendar/events/fix-titles` CLI command to fix the migration of Element titles for sites that have upgraded from Craft 4 to Craft 5. This command needs to be run once after the migration. + +### Changed +- Updated the `nesbot/carbon` dependency to include `^3.0.0"`. +- Updated Calendar to support Carbon 3.x. + +### Fixed +- Fixed a bug where reoccurring events were not returning when using batch calls. +- Fixed a number of breadcrumbs throughout Calendar control panel pages. + +## 5.0.3 + +### Changed +- Updated the `symfony/property-access`, `symfony/finder`, and `symfony/filesystem` dependencies to include `^7.0`. + +## 5.0.2 + +### Added +- Added `selectDatesAsDatesLocalized` and `exceptionsLocalized` to aid with timezone issues when using `|date` to translate dates. + +### Fixed +- Fixed a bug where running any GraphQL query would result in an Internal Server Error. +- Fixed a bug where events with "Selected Dates" repeat rules would not always save correctly via a front-end form. + +## 5.0.1 + +### Fixed +- Fixed several potential issues with queries to better support prefixes and updated variable names to be more meaningful. + +## 5.0.0 + +### Added +- Added compatibility with Craft 5.x (in addition to Craft 4.x). + +### Changed +- Updated plugin icon. +- Removed _Resources_ area in control panel. diff --git a/craft-calendar_versioned_docs/version-v6/setup/installing-updating.mdx b/craft-calendar_versioned_docs/version-v6/setup/installing-updating.mdx new file mode 100644 index 00000000..aede5ea6 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/setup/installing-updating.mdx @@ -0,0 +1,676 @@ +--- +sidebar_position: 1 +description: Installation and update instructions for Solspace Calendar 6.x in Craft CMS. +--- + +import Player from 'react-player'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import { Badge, Photo } from '@site/src/components/utils'; +import { + VerticalStepWrapper, + StepMarkdown, + FlexCards, +} from '@site/src/components/docs'; + +import Icons from '@site/static/icons/cards'; + +# Installing & Updating + + + +## Requirements + +Calendar 6.x supports both [Craft 5.x](https://craftcms.com/docs/5.x/requirements.html) and [Craft 4.x](https://craftcms.com/docs/4.x/requirements.html). It meets mostly the same requirements as listed on the Craft Requirements page. + + + + +- **Craft 5.0.0+** +- PHP 8.2.0+ +- MySQL 8.0.17+ using InnoDB, MariaDB 10.4.6+, or PostgreSQL 13+ +- 256MB+ of memory allocated to PHP +- [BC Math](http://php.net/manual/en/book.bc.php) and [GD](http://php.net/manual/en/book.image.php) PHP extensions +- Windows and macOS browsers: + - Chrome 63+ + - Firefox 67+ + - Safari 11.1+ + - Edge 79+ + + + + +- **Craft 4.0.0+** +- PHP 8.0.2+ +- MySQL 5.7.8+ with InnoDB, MariaDB 10.2.7+, or PostgreSQL 10+ +- 256MB+ memory allocated to PHP +- [BC Math](http://php.net/manual/en/book.bc.php) and [GD](http://php.net/manual/en/book.image.php) PHP extensions +- Windows and macOS browsers: + - Chrome 63+ + - Firefox 67+ + - Safari 11.1+ + - Edge 79+ + + + + +## Installation + +Calendar can be installed one of two ways: + + + + +### Install from the CLI + +Calendar can be installed through the CLI: + + + +Open your CLI app and go to your Craft project: + +```sh +cd /path/to/project +``` + + + +Then tell _Composer_ to require the plugin: + + + + +```sh +composer require solspace/craft-calendar -w +``` + + + + +```sh +composer require solspace/craft-calendar:^6.0 -w +``` + + + + + +Install Calendar by running the following command: + +```sh +php craft plugin/install calendar +``` + +**OR** to install via the Craft control panel, go to _Settings → Plugins_ and click the **Cog button** for Calendar and select **Install**. + + + +Craft will automatically install the _Lite_ edition of Calendar. If you'd like the _Pro_ edition, you can switch the edition 1 of 2 ways: + + + + +1. Open up your [Project Config](https://craftcms.com/docs/5.x/system/project-config.html) file (`/config/project/project.yaml`). +2. Search for `calendar`. +3. Where it says `edition: lite`, switch that to `edition: pro`. + ```diff + calendar: + - edition: lite + + edition: pro + enabled: true + ``` +4. Approve the update inside the CP. + + + + +1. Go to the _Settings_ → _Plugins_ page in the Craft control panel. +2. Click on the _**LITE** / trial_ button beside Calendar's name. +3. On the Plugin Store page it takes you to, scroll down to the bottom and click on the **Try** button for the _Pro_ edition (see video below). + + + + + + + +If Calendar is right for your site, [purchase a copy](#purchasing) of it through the Plugin Store when you're ready! + + + + + + + +### Install from the Control Panel + + + + +Go to the **Plugin Store** area inside your Craft control panel and click on _Calendar_. + + + + + + +Once the product page opens, choose whether you want to install it by clicking the **Try** button under the _Lite_ or _Pro_ edition. + + + + + + +If Calendar is right for your site, [purchase a copy](#purchasing) of it through the Plugin Store when you're ready! + + + + + + + + +## Updating + +Calendar uses the **Craft Updates Service**, which means that every time there's an update available, it'll show up in the _Updates_ area (**Utilities** → **Updates**) of the Craft control panel. You can then review the changelog there, or [view it here](./changelog.mdx). + +:::warning +Be sure to back up the database before updating to Calendar 6. This is a major refactor that adds new occurrence tables, normalizes recurrence data, and updates field layouts and permissions during the migration. +::: + +## Updating from Calendar 5.x to 6.x + +Calendar 6 includes an upgrade bridge that prepares Calendar 5 data for the new event and occurrence model. During the update, Calendar will: + +- add per-calendar and per-event timezone storage; +- convert the event `rrule` column to long text; +- ensure each calendar event field layout contains the required Calendar Event field layout element; +- rewrite legacy recurrence data to normalized RRULE/RSet strings; +- generate persisted event occurrences and occurrence windows; +- migrate legacy GraphQL permission IDs to the new Calendar 6 permission IDs. + +Existing Calendar 5 template queries and the legacy `solspace_calendar` GraphQL wrapper are kept for compatibility, but new projects should use the Calendar 6 APIs documented in this version. + +Calendar can be updated one of three ways: + + + + +### Update from the CLI + +You can use the Craft [_update_ command](https://craftcms.com/docs/5.x/update.html#updating-from-the-terminal) to update Calendar. + +:::warning +Be sure to back up the database before proceeding. +::: + + + +Open your CLI and go to your Craft project: + +```sh +cd /path/to/project +``` + + + + +To see available updates, run this command: + +```sh +php craft update +``` + + + +Follow the prompts, or run: + + + + +```sh +php craft update calendar +``` + + + + +```sh +php craft update calendar:6.0.0 +``` + + + + + + + +If you are upgrading from Craft 4.x to Craft 5.x, you will likely need to run the following console command to migrate event titles: + +```sh +php craft calendar/events/fix-titles +``` + +If you were running Calendar 5.x on Craft 4.x before upgrading to Craft 5.x, you will likely need to run the following console command to resolve some potentially missing event content: + +```sh +php craft calendar/events/fix-contents +``` + + + + + + + +### Update via Composer from the CLI + +You can also update Calendar more manually if you like, using Composer (`composer update`). This may also be helpful in certain scenarios where you need to workaround an issue while updating. + +:::warning +Be sure to back up the database before proceeding. +::: + + + +Open your Craft site's main `composer.json` file and adjust the version number for Calendar ([see guide below](#understanding-versions-and-composer-update)). + +```diff + "require": { + "craftcms/cms": "^5.0.0", + "vlucas/phpdotenv": "^5.4.0", +- "solspace/craft-calendar": "^5.0.0", ++ "solspace/craft-calendar": "^6.0.0", + "solspace/craft-freeform": "^5.0.0" + }, +``` + + + + +Open your CLI app and go to your Craft project: + +```sh +cd /path/to/project +``` + + + + +To run any available updates for your site, run: + +```sh +composer update +``` + + + + +Enter one of the following commands: + + + + +Check for available migrations for Craft and all plugins: + +```sh +php craft migrate/all +``` + + + + +Check for available migrations for Calendar only: + +```sh +php craft migrate --plugin=calendar +``` + + + + +_OR_ + +Proceed to the Craft control panel and click the **Finish Updates** button if it shows. + + + + +If you are upgrading from Craft 4.x to Craft 5.x, you will likely need to run the following console command to migrate event titles: + +```sh +php craft calendar/events/fix-titles +``` + +If you were running Calendar 5.x on Craft 4.x before upgrading to Craft 5.x, you will likely need to run the following console command to resolve some potentially missing event content: + +```sh +php craft calendar/events/fix-contents +``` + + + + + + + +### Update from the Control Panel + +:::warning +Be sure to back up the database before proceeding. +::: + + + + +Go to the Craft Updates area inside the control panel (**Utilities** → **Updates**) and review the changelog for Calendar. + + + + + + +Simply click the **Update** button and Craft will do the rest. + + + + + + + + +## Disable Calendar + +Calendar can be temporarily disabled from the CLI or control panel. The benefit of this is to troubleshoot potential issues and conflicts while preserving your data until a proper fix or change to the site is made. + + + + +Open your CLI app and go to your Craft project: + +```sh +cd /path/to/project +``` + + + + +Disable Calendar by running the following command in your CLI app: + +```sh +php craft plugin/disable calendar +``` + +**OR** to disable via the Craft control panel, go to _Settings → Plugins_ and click the **Cog button** for Calendar and select **Disable**. + + + + +## Uninstall Calendar + +Follow the steps below to uninstall Calendar from your site. + + + + +Open your CLI app and go to your Craft project: + +```sh +cd /path/to/project +``` + + + + +Uninstall Calendar by running the following command in your CLI app: + +:::danger +This action cannot be undone. All of your Calendar data be will lost forever, unless you have made a backup. +::: + +```sh +php craft plugin/uninstall calendar +``` + +**OR** to uninstall via the Craft control panel, go to _Settings → Plugins_ and click the **Cog button** for Calendar and select **Uninstall**. + + + + +Then tell _Composer_ to remove the plugin: + +:::danger +Do not remove a plugin package with Composer before uninstalling it from the control panel or with Craft's CLI. +::: + +```sh +composer remove solspace/craft-calendar +``` + + + + +## Understanding versions and `composer update` + +- For example, under the `"require"` area, change `"solspace/craft-calendar": "5.0.29",` to `"solspace/craft-calendar": "^6.0.0",`. +- You can also use `~` and `^` to somewhat automate your updating process. + - `1.0.0` - means exactly & only this version + - `~1.0.0` - means this version & any _patch_ release (up to `1.0.99̅`) + - `^1.0.0` - means this version & any _minor_ release (up to `1.99̅.99̅`) + - Specifying `"solspace/craft-calendar": "^6.0.0",` for example, would always get you the latest version of Calendar **6.x** (e.g. `6.1.9`), but never the next _major_ version of Calendar like **7.x**. + +Your final `composer.json` file might have something like this: + +```json {4} +"require": { + "craftcms/cms": "^5.0.0", + "vlucas/phpdotenv": "^5.4.0", + "solspace/craft-calendar": "^6.0.0", + "solspace/craft-freeform": "^5.0.0", +}, +``` + +### Getting Latest Unreleased Version + +Sometimes you need to update your site to use the latest _unreleased_ changes in the Calendar repository. This could be in the main branch or a temporary fix/feat branch, e.g. `v6` or `feat/SFT-123`. + +To access the latest unreleased version of Calendar (`v6`), you would set the version in your `composer.json` file to just `v6.x-dev` and run `composer update` after. Your final `composer.json` file might have something like this: + +```json {4} +"require": { + "craftcms/cms": "^5.0.0", + "vlucas/phpdotenv": "^5.4.0", + "solspace/craft-calendar": "v6.x-dev", + "solspace/craft-freeform": "^5.0.0", +}, +``` + +To access an unreleased version from a different branch (e.g. `feat/SFT-123`), you would prefix the branch with `dev-` + the exact branch path/name. We also recommend that you run those changes as a "dummy" next version number and append a beta version. For example, if the current released version of Calendar is `6.0.0` and there are new unreleased changes in the `feat/SFT-123` branch you want to grab, go up 1 patch version number + `-beta.1`. In this case, we would assume `6.0.1` was the next version, so we'd create the version number: `6.0.1-beta.1`. Altogether, we'd be specifying: `dev-feat/SFT-123 as 6.0.1-beta.1`. + +Your final `composer.json` file might have something like this: + +```json {4} +"require": { + "craftcms/cms": "^5.0.0", + "vlucas/phpdotenv": "^5.4.0", + "solspace/craft-calendar": "dev-feat/SFT-123 as 6.0.1-beta.1", + "solspace/craft-freeform": "^5.0.0", +}, +``` + +:::info +If there are more unreleased changes to the repo in the future, you could change `-beta.1` to `-beta.2` and so on. For example, `dev-feat/SFT-123 as 6.0.1-beta.2`. +::: + +## Purchasing + + + + +Craft allows you to trial third-party plugins to see if they're right for your needs. We recommend **trying** any commercial plugin first before buying it. You can trial any plugin or Craft CMS itself by running your site from any domain [that Craft does not consider to be a public domain](https://craftcms.com/knowledge-base/how-craft-license-enforcement-works). + + + + +If this is your first time purchasing a third-party plugin, here's an overview of the purchasing process of plugins. You may purchase licenses for plugins either via the [Craft Plugin Store website](https://plugins.craftcms.com) or directly through the Craft Control Panel. For the latter, here is the process: + +1. Go to the _Plugins_ section of your Craft control panel (**Craft CP** → **Settings** → **Plugins**). +2. For the plugin(s) that need to be purchased, click the **Buy Now** button to add them to your cart. +3. Proceed to purchase the plugin directly inside your Craft control panel. If you think you'll need updates and product support beyond the first year, you can optionally pre-purchase renewal years. You can also purchase renewals later after expiry. +4. Once purchased, the current trial license key for the Calendar will become valid. These product keys can also be accessed and managed later on in your [Craft Console account](https://console.craftcms.com) by visiting the **Plugins** area. + +If you encounter any issues with licensing your plugin, please refer to the [Troubleshooting guide](#troubleshooting) below. + + + + +Renewals are not required to continue using Calendar past the one-year term, but they are required if you wish to update to newer versions of Calendar and receive official support from Solspace. Renewals can be set to automatic, or you may also purchase a renewal directly through the Craft Control Panel or via the [Craft Console website](https://console.craftcms.com/). + + + + +## Changing Editions + +If you wish to change the edition of Calendar from _Lite_ to _Pro_ (or _Pro_ to _Lite_ while trialing), simply visit the Plugin Store area in the Craft control panel and click on the **Try** button for the edition you wish to change to. If you've already purchased a copy of Calendar _Lite_ but wish to upgrade to the _Pro_ edition, you can do so for the price difference only ($100). + + + + +If you'd like to switch during the trial from _Lite_ to the _Pro_ edition, you can switch the edition 1 of 2 ways: + +- **From Project Config**: Open up your [Project Config](https://craftcms.com/docs/5.x/system/project-config.html) file (`/config/project/project.yaml`) and search for `calendar`. Where it says `edition: lite`, switch that to `edition: pro` and then approve the update inside the CP. +- **From CP**: Click on the _**LITE** / trial_ button beside Calendar's name and when it takes you to the Plugin Store page and click on the **Try** button for the _Pro_ edition. + +:::info +If using Craft's [allowAdminChanges](https://craftcms.com/docs/5.x/reference/config/general.html#allowadminchanges) config setting, be sure to temporarily set it to `true` in order to make changes to the edition (which can be switched back to `false` afterward). +::: + + + + + + +If, sometime after purchasing Calendar _Lite_, you decide that you need more features that are available in the _Lite_ or _Pro_ edition, you can switch at any time for the price difference (e.g. from Lite to Pro would be $100) rather than needing to purchase the _Pro_ edition at full price. We suggest you start by switching to a trial of the _Pro_ edition and then purchase it if it meets your needs. You can switch the edition 1 of 2 ways: + +- **From Project Config**: Open up your [Project Config](https://craftcms.com/docs/5.x/system/project-config.html) file (`/config/project/project.yaml`) and search for `calendar`. Where it says `edition: lite`, switch that to `edition: pro` and then approve the update inside the CP. +- **From CP**: Click on the _**LITE** / trial_ button beside Calendar's name and when it takes you to the Plugin Store page and click on the **Try** button for the _Pro_ edition. + +:::info +If using Craft's [allowAdminChanges](https://craftcms.com/docs/5.x/reference/config/general.html#allowadminchanges) config setting, be sure to temporarily set it to `true` in order to make changes to the edition (which can be switched back to `false` afterward). +::: + +Once you're ready to complete the purchase, you can visit the Cart inside your site's control panel: + + + + + + +## Troubleshooting + +Third-party plugin licenses are managed and validated entirely by Craft. Some issues may require that you contact the Craft Team directly if issues persist. The following troubleshooting tips account for the most common issues we've seen our customers report to us: + +
      + Error: 'This license is tied to another Craft install' + + If you receive the error `This license is tied to another Craft install. Visit id.craftcms.com to resolve.` it indicates that the license is tied to another install of Craft CMS. This is likely because either you purchased this under a different domain or subdomain, or something glitched in the process of purchasing the license. Regardless of what happened here, this can likely be resolved by: + + 1. Visit your [Craft Console account](https://console.craftcms.com/). + 2. Under **Licenses** → **Plugins**, look for the _Calendar_ (or affected plugin) license in the list and confirm it's tied to the correct Craft CMS license. If not, click into the license (e.g. `CRZ6`) and click on the _Detach from this Craft license_ button. This will release it from being attached to the wrong or orphaned Craft CMS license and allow you to enter it into the Craft install you're using. + + If you are moving an existing site to a new non-public domain from a different local hostname, you will need to clear your data caches from the **Clear Caches** tool on the **Settings** page before Craft realizes that the hostname has changed. + +
      +
      + Error: 'This license isn't allowed to run version X.X.X.' + + If you receive the error `This license isn't allowed to run version X.X.X.`, it indicates that you're using a version of the plugin that your license isn't eligible for, which in almost all cases would be a plugin license that expired/finished the 1-year term since the initial purchase. According to Craft's policy (out of Solspace's control), once the plugin license has expired, the current version you have installed is the maximum version you can have. The rationale behind this (according to Craft) is that if, for example, you were using Calendar 6.0.1 at the time of expiry, but 6.0.4 was available to you just before the license expiry date, if that 6.0.4 version was available to you indefinitely, one might update to that version months or years later and experience issues while upgrading, which could generate issues and support requests to the developer beyond that initial 1 year term. This is a fair statement and concern on Craft's part, in our opinion. Craft does send out 30-day notices reminding customers of plugin licenses nearing expiry, so it would be wise to consider squeezing in your final update(s) earlier in that 30-day window if you do not wish to renew your license for future updates beyond the initial 1-year term. + + > When a license expires, you can keep using the version that's currently installed. However, you won't be able to update it to newer versions until you've renewed the license. + + As for **_how_ this happened** in the first place, Craft's [CP updater](#update-from-the-control-panel) and their recommended built-in [_update_ command](#update-from-the-cli) feature will make sure that you never update to a plugin version you don't have access to. However, if you used [Composer](#update-via-composer-from-the-cli) to update, it bypasses all of Craft's license validation and you can get yourself into the situation where you now have a version that your license shouldn't have access to, which then generates the error inside the Craft CP. The only way to resolve this would be reverting back to the previous version (which is not always recommended, as it's possible plugin update migration(s) could have taken place, and reverting could break your install), or renew your license. Please feel free to reach out to us for further clarification and assistance if you're in a bind with this, and we'll do the best we can to help. + +
      +
      + Plugin shows it's 'Missing' + + If you have a plugin that shows as _Missing_, this is because you don't have the plugin installed and/or the plugin files are not in the Craft **vendor** folder, BUT you have a valid purchased Craft 3 license for the plugin tied to that Craft install. Depending on your scenario, you likely either have the issue of wanting the plugin to be available or not wanting it to show up there. + + If you purchased the plugin and are expecting it to show up for installation, what likely happened is that Craft or your server environment glitched and didn't correctly add the plugin dependency (files) to your Craft site's **vendor** folder (but knows that you have a valid purchase of it). If this is the case, you'll need to follow the [Installation Instructions](#installation) documentation above to install the plugin. + + If the above is not the case for you, and you don't want this license showing up on your Craft site, this can likely be resolved by: + + 1. Visit your [Craft Console account](https://console.craftcms.com/). + 2. Under **Licenses** → **Plugins**, look for the _Calendar_ (or affected plugin) license in the list and confirm it's tied to the correct Craft CMS license. If not, click into the license (e.g. `CRZ6`) and click on the _Detach from this Craft license_ button. This will release it from being attached to the wrong or orphaned Craft CMS license, and later use it on the correct/different Craft install. + +
      +
      + Can't purchase upgrade from Lite to Pro edition + + If you're currently using the _Lite_ edition of Calendar and are trying to purchase an upgrade to the _Pro_ edition, but it's not letting you (the **Add to Cart** button isn't showing), please ensure that the `allowUpdates` and `allowAdminChanges` [Craft General Config items](https://craftcms.com/docs/5.x/reference/config/general.html#allowadminchanges) are NOT set to `false`. At least enable them temporarily to allow this change to happen. + + ```php + 'allowUpdates' => true + 'allowAdminChanges' => true + ``` +
      diff --git a/craft-calendar_versioned_docs/version-v6/templates/_category_.json b/craft-calendar_versioned_docs/version-v6/templates/_category_.json new file mode 100644 index 00000000..5280edfe --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Templating", + "position": 7 +} diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/_category_.json b/craft-calendar_versioned_docs/version-v6/templates/objects/_category_.json new file mode 100644 index 00000000..876b3ee4 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Objects", + "position": 2 +} diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/calendar.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/calendar.mdx new file mode 100644 index 00000000..bb375c91 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/calendar.mdx @@ -0,0 +1,44 @@ +--- +title: Calendar +sidebar_position: 1 +description: Calendar object reference in Solspace Calendar 6.x templates for Craft CMS. +--- + +## Properties + +- `id` + - the calendar's unique ID +- `name` + - the calendar's name +- `handle` + - the calendar's handle +- `color` + - a hex color code, e.g. `#FF00FF` +- `lighterColor` + - a hex color made lighter by **20%** +- `darkerColor` + - a hex color made darker by **20%** +- `contrastColor` + - either `black` or `white`, depending on the darkness or lightness of `color` +- `icsUrl` + - displays the full ICS subscription URL that users can subscribe to in their calendaring system such as Apple Calendar or Google Calendar, if ICS sharing is enabled for this calendar (enabled inside _Calendars_ page of Calendar CP). +- `icsHash` + - displays the ICS subscription hash (not the full ICS URL) that for users to subscribe to calendars. + - if you wish to specify a certain site's translated version, include `site=mySiteHandle` in the URL path, like this: + ```twig showLineNumbers + {{ siteUrl }}index.php?p=actions/calendar/api/ics&site=mySiteHandle&hash={{ calendar.icsHash }} + ``` + +## Usage in Templates + +```twig showLineNumbers +{% set calendar = craft.calendar.calendar({ + handle: "holidays" +}) %} + +{% if calendar %} +
      + {{ calendar.name }} +
      +{% endif %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/date.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/date.mdx new file mode 100644 index 00000000..8fa0e6b1 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/date.mdx @@ -0,0 +1,63 @@ +--- +title: Date +sidebar_position: 5 +description: Date handling and object methods in Solspace Calendar 6.x templates. +--- + +# Date object + +## Properties + +- `year` + - Returns the 4 digit year +- `month` + - Returns an `int` from `1-12`, representing the month +- `day` + - Returns an `int` from `1-31` +- `hour` + - Returns an `int` from `0-23` +- `minute` + - Returns an `int` from `0-59` +- `second` + - Returns an `int` from `0-59` +- `timestamp` + - Returns a UNIX timestamp +- `weekStartsAt` + - Returns an `int` from `0-6` (`0` - **Sunday**, `6` - **Saturday**) +- `weekEndsAt` + - Same as above +- `dateString` + - Returns a `Y-m-d` string +- `dateTimeString` + - Returns a `Y-m-d H:i:s` string +- `timeString` + - Returns a `H:i:s` string +- `weekday` + - Returns a `boolean` result if the date is a weekday date +- `weekend` + - Returns a `boolean` result if the date is a weekend date +- `sunday` + - Returns `true` if the date is a **Sunday** + - Works for all week days `monday`, `tuesday`, `wednesday`, etc + +## Methods + +- `format` + - Format the date to PHP's [date formatting](http://php.net/manual/en/function.date.php) guidelines, e.g. - `event.startDate.format("l d, Y")` +- `eq` + - check if a date is equal to another date. + - `event.startDate.eq(event.endDate)` would return true if both dates would be equal +- `ne` + - check if the dates are not equal +- `gt` + - checks if a date is greater than the other date + - `event.startDate.gt(anotherEvent.startDate)` would return true only if `event.startDate` were greater than `anotherEvent.startDate` +- `gte` + - check for greater OR equal than +- `lt` + - check for less than +- `lte` + - less than OR equal +- `between` + - check if a date is between two other dates + - `event.startDate.between(month.startDate, month.endDate)` would return **true** if the `event.startDate` were between a given month range diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/day.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/day.mdx new file mode 100644 index 00000000..46866669 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/day.mdx @@ -0,0 +1,79 @@ +--- +title: Day +sidebar_position: 8 +description: Day object reference for calendar views in Solspace Calendar 6.x templates. +--- + +import { Photo } from '@site/src/components/utils'; + +# Day object + +A _Day_ object holds in itself a list of all [Events](./event.mdx) that fall into this day, as well as gives the possibility to iterate over [Hour object](./hour.mdx)'s that fall into the range of this **Day object**. + + + +## Properties + +- `date` + - A [Date object](./date.mdx) of the starting date of the event duration + - For a _Day_ object of **April 15, 2023**, this would return the [Date object](./date.mdx) of `2023-04-15 00:00:00` +- `startDate` + - Basically the same as the `date` property +- `endDate` + - The ending date of the _Day_ object's day, e.g - `2023-04-15 23:59:59` in this case +- `previousDate` + - Returns a [Date object](./date.mdx) of the previous day relative to the `date` property, e.g. `2023-04-14 00:00:00` in this case +- `nextDate` + - Returns a [Date object](./date.mdx) of the next day relative to the `date` property, e.g. `2023-05-16 00:00:00` in this case +- `events` + - Contains a list of [Events](./event.mdx) that fall into this _Day_ object's range +- `eventCount` + - The number of events in the `events` property + +## Methods + +- `dateRange(int before, int after)` + - Returns a list of [Date objects](./date.mdx) ranging `before` number of days before `date` and `after` number of days after `date` + - E.g. `day.dateRange(6, 6)` would return a list starting from `2023-04-09` and ending in `2023-04-21` assuming the _Day_ object's `date` is `2023-04-15` +- `containsDate(dateObject)` + - Returns **true** if the `dateObject` provided is within the _Day_ object's date range. Typically used for handling CSS and title behavior in Month view templates for events that span multiple days. + - E.g. `day.containsDate(event.startDateLocalized)` would return **true** if the _Day_ object would be **April 15, 2023**, and the `event.startDateLocalized` would be `2023-04-15 17:30:00`, but **false** if the `event.startDateLocalized` would be `2023-04-16 00:00:00` + +## Usage in Templates + +Iterate through the hours of the day + +```twig showLineNumbers +{% set day = craft.calendar.day({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for hour in day %} + {% for event in hour.events %} +
      + {{ event.title }} +
      + {% endfor %} +{% endfor %} +``` + +--- + +Iterate through all events in the day + +```twig showLineNumbers +{% set day = craft.calendar.day({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in day.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/duration.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/duration.mdx new file mode 100644 index 00000000..759ff117 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/duration.mdx @@ -0,0 +1,37 @@ +--- +title: Duration +sidebar_position: 4 +description: Duration object for events in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Duration object + +## Properties + +### `humanReadable` + +Returns a **human readable string** of the duration, e.g. - `2d 1h 15m`. + +### `years` + +Returns an `int` of the difference in **years**, e.g. if total duration is 2 years, 4 months and 7 days, this will parse as `2`. + +### `months` + +Returns an `int` difference in **months**, e.g. if total duration is 2 years, 4 months and 7 days, this will parse as `4`. + +### `days` + +Returns an `int` difference in **days**, , e.g. if total duration is 2 years, 3 months and 7 days, this will parse as `7`. Durations 1 month or longer will trigger `months` count and reset the days count back to `0` at each month interval. + +### `hours` + +Returns an `int` difference in **hours**, e.g. `8`. + +### `minutes` + +Returns an `int` difference in **minutes**, e.g. `22`. + +### `seconds` + +Returns an `int` difference in **seconds**, e.g. `52`. diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/event.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/event.mdx new file mode 100644 index 00000000..72dfe90b --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/event.mdx @@ -0,0 +1,132 @@ +--- +title: Event +sidebar_position: 2 +description: Event object reference and properties in Solspace Calendar 6.x templates for Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Event object + + + +## Properties + +- `id` + - The event's unique ID, which is also the element ID. +- `draftId` + - The event draft ID when viewing or saving an event draft. +- `siteId` + - The site ID for the event. +- `slug` + - The event's unique URL slug. +- `title` + - The event's title. +- `status` + - The event's status. +- `enabled` + - If the event is enabled. +- `authorId` + - The event's author ID. +- `author` + - The event's author. +- `startDate` + - a [Date object](./date.mdx). + - Can be formatted with `.format("l, F j, Y \\a\\t g:ia")` + - If you'd like to have dates translatable, use `startDateLocalized` instead and `format()` with `|date()` filter, e.g. `event.startDateLocalized|date("l, F j, Y g:ia")`. +- `endDate` + - a [Date object](./date.mdx). + - Can be formatted with `.format("l, F j, Y \\a\\t g:ia")` + - If you'd like to have dates translatable, use `endDateLocalized` instead and `format()` with `|date()` filter, e.g. `event.startDateLocalized|date("l, F j, Y g:ia")`. +- `duration` + - a [Duration object](./duration.mdx). +- `timezone` + - The timezone stored for the event. Calendar 6 uses this when normalizing recurrence and occurrence dates. +- `allDay` + - a `boolean` value. +- `multiDay` + - a `boolean` value. +- `repeating` + - a `boolean` value. +- `rrule` + - The **RFC RRULE/RSet** string used for repeating events and ICS exports. + - Calendar 6 normalizes `RRULE`, `RDATE`, and `EXDATE` lines when events are saved. +- `repeatType` + - The normalized repeat type, such as `NEVER`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`, or `CUSTOM`. +- `repeatEndType` + - The normalized repeat end type, such as `NEVER`, `AFTER`, or `ON_DATE`. +- `readableRepeatRule` + - a human readable string of the `rrule`. +- `simplifiedRepeatRule` + - a simplified version of the repeat rule (e.g. **Weekly**). +- `isCurrentlyHappening` + - Checks if the user's current time is between the event's start and end date. + - Based on the logged in user's locale, or otherwise the site's default timezone. +- `isHappeningOn` + - Checks if the specified date and time is between the event's start and end date, e.g: + ```twig showLineNumbers + {% if event.isHappeningOn('2023-03-07 4:30pm') %} Yes! {% endif %} + ``` + - Time has a default of `00:00:00`, so if not specified, only All Day events will evaluate to `true`. +- `calendar` + - a [Calendar object](./calendar.mdx). +- `exceptions` + - a list of exception models for recurring events. + - Exception models consist of these properties: + - `id` - the ID of the exception + - `eventId` - the ID of the parent event + - `date` - a `\DateTime` object of the exception date +- `occurrences` + - a list of [Occurrence objects](./occurrences.mdx) for repeating rules. +- `occurrenceCount` + - the total number of occurrence results. +- `url` + - the URL of the event, if available, generated from Event URL path setting for calendars. +- `uri` + - The URI of the event, if available, generated from Event URL path setting for calendars. + +You can also access any custom fields which you have added to events by directly calling their **handle** (the **handle** must not match any of the existing event properties). + +## Usage in Templates + +You can also access any custom fields which you have added to events by directly calling their **handle** (the **handle** must not match any of the existing event properties). If you had a field called _Event Description_ with a handle of **eventDescription** you would access it in the template like this: + +```twig showLineNumbers +{{ event.eventDescription }} +``` + +You could make sure such a property exists first, to prevent errors in case the field is deleted: + +```twig showLineNumbers +{% if event.eventDescription is defined %} + {{ event.eventDescription }} +{% endif %} +``` + +Let's use a Date method to check if our event's start date is before the current Day's date + +```twig showLineNumbers +{# Print out the Y-m-d of start date if start date is before the Day date #} + +{% if event.startDate.lt(day.date) %} + {{ event.startDate.dateString }} +{% endif %} +``` + +Now let's print out the duration of the event, which is the amount of time in months, days, hours, etc from the event's start date until its end date + +```twig showLineNumbers +{# Print out the duration string #} +{# An example output would be "1d 5h 30m" #} + +{{ event.duration.humanReadable }} + +{# Print out a custom message if the duration in days is 1 or more #} + +{% if event.duration.days >= 1 %} + Event spans for {{ event.duration.days }} days +{% endif %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/hour.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/hour.mdx new file mode 100644 index 00000000..85c3e26c --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/hour.mdx @@ -0,0 +1,53 @@ +--- +title: Hour +sidebar_position: 9 +description: Hour object reference for calendar views in Solspace Calendar 6.x templates. +--- + +# Hour object + +An _Hour_ object holds in itself a list of all [Events](./event.mdx) that fall into this hour. + +## Properties + +- `date` + - A [Date object](./date.mdx) of the starting date of the event duration + - For an _Hour_ object of **April 15, 2023 at 5pm**, this would return the [Date object](./date.mdx) of `2023-04-15 17:00:00` +- `startDate` + - Basically the same as the `date` property +- `endDate` + - The ending date of the _Hour_ object's hour, e.g - `2023-04-15 17:59:59` in this case +- `previousDate` + - Returns a [Date object](./date.mdx) of the previous hour relative to the `date` property, e.g. `2023-04-15 16:00:00` in this case +- `nextDate` + - Returns a [Date object](./date.mdx) of the next hour relative to the `date` property, e.g. `2023-05-15 18:00:00` in this case +- `events` + - Contains a list of [Events](./event.mdx) that fall into this _Hour_ object's range +- `eventCount` + - The number of events in the `events` property + +## Methods + +- `dateRange(int before, int after)` + - Returns a list of [Date objects](./date.mdx) ranging `before` number of hours before `date` and `after` number of hours after `date` + - E.g. `hour.dateRange(6, 6)` would return a list starting from `2023-04-15 11:00:00` and ending in `2023-04-15 23:00:00` assuming the _Day_ object's `date` is `2023-04-15 17:00:00` +- `containsDate(dateObject)` + - Returns **true** if the `dateObject` provided is within the _Hour_ object's date range + - E.g. `hour.containsDate(event.startDate)` would return **true** if the _Hour_ object would be **April 15, 2023 at 5pm**, and the `event.startDate` would be `2023-04-15 17:30:00`, but **false** if the `event.startDate` would be `2023-04-16 18:00:00` + +## Usage in Templates + +Iterate through all events within the current hour + +```twig showLineNumbers +{% set hour = craft.calendar.day({ + date: "now", + calendar: ["holidays", "sports"] +}) %} + +{% for event in hour.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/month.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/month.mdx new file mode 100644 index 00000000..45347149 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/month.mdx @@ -0,0 +1,98 @@ +--- +title: Month +sidebar_position: 6 +description: Month object reference for calendar views in Solspace Calendar 6.x templates. +--- + +import { Photo } from '@site/src/components/utils'; + +# Month object + +A _Month_ object holds in itself a list of all [Events](./event.mdx) that fall into this month, as well as gives the possibility to iterate over [Week object](./week.mdx)'s that fall into the range of this **Month object**. + + + +## Properties + +- `date` + - A [Date object](./date.mdx) of the starting date of the event duration + - For a _Month_ object of **April 2023**, this would return the [Date object](./date.mdx) of `2023-04-01` +- `startDate` + - Basically the same as the `date` property +- `endDate` + - The ending date of the _Month_ object's month, e.g - `2023-04-30` in this case +- `previousDate` + - Returns a [Date object](./date.mdx) of the previous month relative to the `date` property, e.g. `2023-03-01` in this case +- `nextDate` + - Returns a [Date object](./date.mdx) of the next month relative to the `date` property, e.g. `2023-05-01` in this case +- `events` + - Contains a list of [Events](./event.mdx) that fall into this _Month_ object's range +- `eventCount` + - The number of events in the `events` property + +## Methods + +- `dateRange(int before, int after)` + - Returns a list of [Date objects](./date.mdx) ranging `before` number of months before `date` and `after` number of months after `date` + - E.g. `month.dateRange(6, 6)` would return a list starting from `2015-10-01` and ending in `2023-10-01` +- `containsDate(dateObject)` + - Returns **true** if the `dateObject` provided is within the _Month_ object's date range + - E.g. `month.containsDate(event.startDate)` would return **true** if the _Month_ object would be **April 2023**, and the `event.startDate` would be `2023-04-15`, but **false** if the `event.startDate` would be `2023-03-31` + +## Usage in Templates + +Iterate through weeks and days of the month + +```twig showLineNumbers +{% set month = craft.calendar.month({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for week in month %} + {% for day in week %} + {% for event in day.events %} +
      + {{ event.title }} +
      + {% endfor %} + {% endfor %} +{% endfor %} +``` + +--- + +Iterate through all events in the month + +```twig showLineNumbers +{% set month = craft.calendar.month({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in month.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` + +--- + +Show only events which start in weekends + +```twig showLineNumbers +{% set month = craft.calendar.month({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in month.events if event.startDate.weekend %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/occurrences.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/occurrences.mdx new file mode 100644 index 00000000..ed425716 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/occurrences.mdx @@ -0,0 +1,91 @@ +--- +title: Occurrences +sidebar_position: 3 +description: Occurrence object for recurring events in Solspace Calendar 6.x templates. +--- + +# Occurrence object + +The _occurrence_ object represents one generated occurrence of a Calendar event. Calendar 6 stores generated occurrences in dedicated occurrence tables, which gives recurrence-heavy sites more reliable date range filtering and a stable occurrence key for each event/date combination. + +## Properties + +- `id` + - The stable occurrence key. Calendar builds this from the event ID and occurrence start date. +- `uid` + - The occurrence UID. +- `startDate` + - a [Date object](./date.mdx) in UTC. +- `startDateLocalized` + - a localized [Date object](./date.mdx). +- `endDate` + - a [Date object](./date.mdx) in UTC. +- `endDateLocalized` + - a localized [Date object](./date.mdx). +- `allDay` + - a `boolean` value. +- `event` + - the parent [Event object](./event.mdx). +- `calendar` + - the parent [Calendar object](./calendar.mdx). +- `dateCreated` + - a `\DateTime` object for when the occurrence row was generated. +- `dateUpdated` + - a `\DateTime` object for when the occurrence row was last updated. + +## Usage in Templates + +```twig showLineNumbers +{% set event = craft.calendar.events({ + id: craft.app.request.segment(2), +}).one() %} + +{% if event.repeating %} + +

      Upcoming Recurrences

      + + {% set occurrences = event.occurrences({ + rangeStart: 'today', + rangeEnd: '+6 months', + limit: 10, + }) %} + + {% if occurrences %} +
        + {% for occurrence in occurrences %} +
      • + {{ occurrence.startDate.format("l, F j, Y") }} + {% if occurrence.allDay %} + (all day) + {% else %} + at {{ occurrence.startDate.format("g:ia") }} + {% if occurrence.multiDay %} +
        {{ occurrence.endDate.format("l, F j, Y \\a\\t g:ia") }} + {% else %} + {{ occurrence.endDate.format("g:ia") }} + {% endif %} + {% endif %} +
        • + {% endfor %} +
      + {% else %} +

      No occurrences found for this timeframe.

      + {% endif %} + +{% endif %} +``` + +You can also access the parent event or calendar from each occurrence: + +```twig showLineNumbers +{% for occurrence in event.occurrences({ + rangeStart: 'today', + rangeEnd: '+3 months', +}) %} +
      +

      {{ occurrence.event.title }}

      +

      {{ occurrence.calendar.name }}

      + +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/objects/week.mdx b/craft-calendar_versioned_docs/version-v6/templates/objects/week.mdx new file mode 100644 index 00000000..98035dda --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/objects/week.mdx @@ -0,0 +1,89 @@ +--- +title: Week +sidebar_position: 7 +description: Week object reference for calendar views in Solspace Calendar 6.x templates. +--- + +# Week object + +A _Week_ object holds in itself a list of all [Events](./event.mdx) that fall into this week, as well as gives the possibility to iterate over [Day object](./day.mdx)'s that fall into the range of this **Week object**. + +## Properties + +- `date` + - A [Date object](./date.mdx) of the starting date of the event duration + - For a _Week_ object of **April 15, 2023** and week starting day of **Sunday**, this would return the [Date object](./date.mdx) of `2023-04-10` with the starting day of the week set to **Sunday** +- `startDate` + - Basically the same as the `date` property +- `endDate` + - The ending date of the _Week_ object's week, e.g - `2023-04-16` in this case +- `previousDate` + - Returns a [Date object](./date.mdx) of the previous week relative to the `date` property, e.g. `2023-04-03` in this case +- `nextDate` + - Returns a [Date object](./date.mdx) of the next week relative to the `date` property, e.g. `2023-05-17` in this case +- `events` + - Contains a list of [Events](./event.mdx) that fall into this _Week_ object's range +- `eventCount` + - The number of events in the `events` property + +## Methods + +- `dateRange(int before, int after)` + - Returns a list of [Date objects](./date.mdx) ranging `before` number of weeks before `date` and `after` number of weeks after `date` + - E.g. `week.dateRange(6, 6)` would return a list starting from `2023-02-28` and ending in `2023-05-22` +- `containsDate(dateObject)` + - Returns **true** if the `dateObject` provided is within the _Week_ object's date range + - E.g. `week.containsDate(event.startDate)` would return **true** if the _Week_ object would be **April 15, 2023** starting on Sunday, and the `event.startDate` would be `2023-04-10`, but **false** if the `event.startDate` would be `2023-04-09` + +## Usage in Templates + +Iterate through days of the week + +```twig showLineNumbers +{% set week = craft.calendar.week({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for day in week %} + {% for event in day.events %} +
      + {{ event.title }} +
      + {% endfor %} +{% endfor %} +``` + +--- + +Iterate through all events in the week + +```twig showLineNumbers +{% set week = craft.calendar.week({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in week.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` + +--- + +Show only events which start in weekdays + +```twig showLineNumbers +{% set week = craft.calendar.week({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in week.events if event.startDate.weekday %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/_category_.json b/craft-calendar_versioned_docs/version-v6/templates/queries/_category_.json new file mode 100644 index 00000000..e97d8185 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Queries", + "position": 1 +} diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/calendar.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/calendar.mdx new file mode 100644 index 00000000..71935ca3 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/calendar.mdx @@ -0,0 +1,34 @@ +--- +title: Calendar +sidebar_position: 1 +description: Calendar query methods and parameters in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Calendar Query + +The _calendar.calendar_ template query fetches a single calendar by its unique ID. + +## Parameters + +- `id` + - The unique calendar ID +- `name` + - The name of the calendar +- `handle` + - The handle for the calendar +- `color` + - a hex value of the color, e.g - `#FFFFFF` + +## Usage in Templates + +```twig showLineNumbers +{% set calendar = craft.calendar.calendar({ + handle: "holidays" +}) %} + +{% if calendar %} +
      + {{ calendar.name }} +
      +{% endif %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/calendars.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/calendars.mdx new file mode 100644 index 00000000..ba46ed32 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/calendars.mdx @@ -0,0 +1,44 @@ +--- +title: Calendars +sidebar_position: 2 +description: Calendars query for listing multiple calendars in Solspace Calendar 6.x templates. +--- + +# Calendars Query + +The _calendar.calendars_ template query fetches a list of calendars based on some or no criteria. + +## Parameters + +- `id` + - The unique calendar ID + - Can be passed as an array of ID's - `[1, 2, 3]` + - Use `"not 1,2,3"` to filter out calendars which **don't** have an ID of **1, 2 or 3** + - Use `"!= 3"` to filter out calendars which **don't** have an ID of **3** +- `name` + - same usage as listed above for `id` +- `handle` + - same usage as listed above for `id` +- `color` + - a hex value of the color, e.g - `#FFFFFF` +- `orderBy` + - Valid orderBy attributes are `id`, `name`, `handle` and `color` +- `sort` + - Options are `ASC` or `DESC` +- `limit` + - An `int` limiting the result count + +## Usage in Templates + +```twig showLineNumbers +{% set calendars = craft.calendar.calendars({ + orderBy: "name", + sort: "asc" +}) %} + +{% for calendar in calendars %} +
      + {{ calendar.name }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/day.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/day.mdx new file mode 100644 index 00000000..ea89435b --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/day.mdx @@ -0,0 +1,79 @@ +--- +title: Day +sidebar_position: 8 +description: Day query and calendar views in Solspace Calendar 6.x templates for Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Day Query + +The _calendar.day_ template query assembles a [Day object](../objects/day.mdx) containing its events and allows for iteration over it to access all [Hour objects](../objects/hour.mdx) contained within. + + + +## Parameters + +- `date` + - A date string representing the date for the day that should be compiled. + - `"march 15 2023"` is a valid `date` value + - `"2023-03-15"` would be valid and return the [Day object](../objects/day.mdx) for the day of **March 15, 2023** +- `calendar` + - Handle of the calendar, e.g. `"holidays"`, or an array of handles: `["holidays", "football"]`. + - Use `"not holidays"` to select all calendars EXCEPT the **Holidays** calendar +- `calendarId` + - An ID of the calendar, or array of ID's, e.g. `[1, 2, 3]` + - If you want to select all calendars EXCEPT the calendar with an ID of **1**, use `"not 1"` +- `allDay` + - Selects only events that are set to be **All Day** events went set to `true`. +- `authorId` + - Selects events from specific author ID's +- `limit` + - Supply an `int` to limit the amount of events returned +- `orderBy` + - Override default sort order by for the specified day with this parameter, e.g. `orderBy: "startDate ASC"` +- `status` + - By default, `live` is used, showing only enabled events + - Can be set to `disabled` to show disabled events + - Or `null` to show all events regardless of their status +- `search: "customField:myvalue*"` + - Works just like regular [Craft Searching](https://craftcms.com/docs/4.x/searching.html). + +## Usage in Templates + +Iterate through the hours of the day + +```twig showLineNumbers +{% set day = craft.calendar.day({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for hour in day %} + {% for event in hour.events %} +
      + {{ event.title }} +
      + {% endfor %} +{% endfor %} +``` + +--- + +Iterate through all events in the day + +```twig showLineNumbers +{% set day = craft.calendar.day({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in day.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/event.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/event.mdx new file mode 100644 index 00000000..88e39559 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/event.mdx @@ -0,0 +1,56 @@ +--- +title: Event +sidebar_position: 4 +description: Single Event query methods and properties in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Event Query + +The `craft.calendar.events()` element query fetches Calendar Event elements. To fetch a single event, pass the criteria you need and call `.one()`. + +:::warning Legacy query deprecated + +The old `craft.calendar.event()` helper is deprecated in Calendar 6. Use `craft.calendar.events(...).one()` for existing events, and use `craft.calendar.createEvent()` when you need a new event model for a front-end form. + +::: + +## Parameters + +The single event query supports the same criteria as the [Events Query](./events.mdx), including `id`, `slug`, `calendar`, `calendarId`, `siteId`, `status`, and date filters. + +## Usage in Templates + +```twig showLineNumbers +{% set event = craft.calendar.events({ + id: craft.app.request.segment(2), +}).one() %} + +
        +{% if event %} +
      • + {{ event.title }} - {{ event.startDate.format("l d, Y") }}
        + {{ event.eventDescription }} +
        • +{% endif %} +
      +``` + +For an event detail page that needs a specific recurrence date, query occurrences instead: + +```twig showLineNumbers +{% set occurrenceDate = null %} +{% if craft.app.request.segment(3) and craft.app.request.segment(4) and craft.app.request.segment(5) %} + {% set occurrenceDate = craft.app.request.segment(3)~"-"~craft.app.request.segment(4)~"-"~craft.app.request.segment(5) %} +{% endif %} + +{% set occurrence = craft.calendar.occurrences({ + event: craft.app.request.segment(2), + startsAfterOrAt: occurrenceDate, + startsBefore: occurrenceDate ? occurrenceDate|date_modify('+1 day')|date('Y-m-d') : null, +}).one() %} + +{% if occurrence %} +

      {{ occurrence.event.title }}

      +

      {{ occurrence.startDateLocalized|date('l, F j, Y g:ia') }}

      +{% endif %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/events.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/events.mdx new file mode 100644 index 00000000..867fe763 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/events.mdx @@ -0,0 +1,302 @@ +--- +title: Events +sidebar_position: 4 +description: Events query for retrieving multiple events in Solspace Calendar 6.x templates. +--- + +# Events Query + +The `craft.calendar.events()` template query fetches Calendar Event elements based on some or no criteria. In Calendar 6, generated recurring dates are handled by the separate `craft.calendar.occurrences()` query, which reads from Calendar's persisted occurrence tables. + +## Parameters + +- `rangeStart` + - Selects events that fall into a given date range. Defaults to no date (beginning of time) - if you wish to display events from long ago, we do recommend using a value like `6 months ago` or `5 years ago`, etc to avoid running into potential performance issues or quirkiness. A date range of `2023-01-01` to `2023-02-15` would show all events and their recurrences that occur between January 1, 2023 to February 15, 2023. A start range of `2023-01-01` with no end range would show all events and their recurrences that occur January 1, 2023 and beyond. + - Time ranges can be specified as 24hr or 12hr: + - `2023-01-01 16:30` or `2023-01-01 5:00 pm` + - Times consider any events with a duration that overlaps (even partially) with the time range specified. + - Used in conjunction with [rangeEnd](#range-end) parameter. + - Alternately, use one of the following instead to have a more precise timeframe (you may need to continue to use `rangeStart` and `rangeEnd` parameters if results are not reliable enough when using with recurring events): + - `startsAfter: "now"` + - `startsAfterOrAt: "now"` + - `startsBefore: "now"` + - `startsBeforeOrAt: "now"` +- `rangeEnd` + - Selects events that fall into a given date range. Defaults to no date (end of time) - if you wish to display events far into the future, we do recommend using a value like `+6 months` or `+5 years`, etc to avoid running into potential performance issues or quirkiness. A date range of `2023-01-01` to `2023-02-15` would show all events and their recurrences that occur between January 1, 2023 to February 15, 2023. An end range of `2023-02-15` with no start range would show all events and their recurrences that occur February 15, 2023 and earlier. + - Time ranges can be specified as 24hr or 12hr: + - `2023-01-01 16:30` or `2023-01-01 5:00 pm` + - Times consider any events with a duration that overlaps (even partially) with the time range specified. + - Used in conjunction with [rangeStart](#range-start) parameter. + - Alternately, use one of the following instead to have a more precise timeframe (you may need to continue to use `rangeStart` and `rangeEnd` parameters if results are not reliable enough when using with recurring events): + - `endsAfterOrAt: "now"` + - `endsAfter: "tomorrow"` + - `endsBefore: "now"` + - `endsBeforeOrAt: "now"` +- `calendar` + - Handle of the calendar, e.g. `"holidays"`, or an array of handles: `["holidays", "football"]`. + - Use `"not holidays"` to select all calendars EXCEPT the **Holidays** calendar +- `calendarId` + - An ID of the calendar, or array of ID's, e.g. `[1, 2, 3]` + - If you want to select all calendars EXCEPT the calendar with an ID of **1**, use `"not 1"` + - Exclude multiples with syntax like: `calendarId: ["and", "not 1", "not 2"]` +- `id` + - An event ID, or array of ID's, e.g. `[1, 2, 3]` + - If you want to select all events EXCEPT the event with an ID of **1**, use `"not 1"` +- `slug` + - An event slug, or array of slugs, e.g. `[event-one, event-two, event-three]` + - If you want to select all events EXCEPT the event with a slug of **event-two**, use `"not event-two"` +- `allDay` + - Selects only events that are set to be **All Day** events went set to `true`. +- `authorId` + - Selects events from specific author ID's +- `timezone` + - Selects events stored in one or more timezones, e.g. `"America/Los_Angeles"` or `["Europe/London", "America/New_York"]`. +- `limit` + - Supply an `int` to limit the amount of events returned +- `orderBy` + - Use any of the above keys (plus `RAND()`) to order by and include the `ASC` or `DESC` parameter in the string, e.g. `orderBy: "startDate ASC"` +- `status` + - By default, `live` is used, showing only enabled events + - Can be set to `disabled` to show disabled events + - Or `null` to show all events regardless of their status +- `search: "customField:myvalue*"` + - Works just like regular [Craft Searching](https://craftcms.com/docs/4.x/searching.html). + :::warning + There's currently a known issue where searches combined with `calendar` parameter will not work. Use `calendarId` instead for now. + ::: +- `relatedTo: event.id` + - Works just like regular [Craft Relations](https://craftcms.com/docs/4.x/relations.html#templating). + +## Methods + +- `groupedByMonth()` + - Allows you to group events by month and display a heading above each month. +- `groupedByWeek()` + - Allows you to group events by week and display a heading above each week. +- `groupedByDay()` + - Allows you to group events by day and display a heading above each day. + +See [Grouping Events by Month/Week/Day examples](#grouping-events-by-month-week-day) for more information. + +## Occurrence Query + +Use `craft.calendar.occurrences()` when you need generated recurrence results, date-range filtering across repeating events, or a specific occurrence of an event. + +### Occurrence Parameters + +- `event` + - An event ID, array of event IDs, or event criteria. +- `calendar` + - Handle of the calendar, e.g. `"holidays"`, or an array of handles: `["holidays", "football"]`. +- `calendarId` + - An ID of the calendar, or array of IDs, e.g. `[1, 2, 3]`. +- `site` / `siteId` + - The site handle or ID. +- `startsBefore`, `startsBeforeOrAt`, `startsAfter`, `startsAfterOrAt` + - Filters occurrence start dates. +- `endsBefore`, `endsBeforeOrAt`, `endsAfter`, `endsAfterOrAt` + - Filters occurrence end dates. +- `rangeStart`, `rangeEnd` + - Filters occurrences that overlap a date range. + +```twig showLineNumbers +{% set occurrences = craft.calendar.occurrences({ + calendar: 'holidays', + rangeStart: 'today', + rangeEnd: '+3 months', +}) %} + +{% for occurrence in occurrences %} +
      +

      {{ occurrence.event.title }}

      +

      {{ occurrence.startDateLocalized|date('M j, Y g:ia') }}

      +
      +{% endfor %} +``` + +## Usage in Templates + +```twig showLineNumbers +{# select only all day events #} +{% set events = craft.calendar.events({ + allDay: true +}) %} + +{% for event in events %} +
      + {{ event.title }} +
      +{% endfor %} +``` + +--- + +You can also access any custom fields which you have added to events by directly calling their **handle** (the **handle** must not match any of the existing event properties). If you had a field called _Event Description_ with a handle of **eventDescription** you would access it in the template like this: + +```twig showLineNumbers +{% set events = craft.calendar.events %} + +{% for event in events %} +
      + {{ event.title }} + + {# You can omit the "is defined" check if you're certain that you have that field #} + + {% if event.eventDescription is defined %} + {{ event.eventDescription }} + {% endif %} +
      +{% endfor %} +``` + +--- + +Let's use a Date method to check if our event's start date is before the current Day's date + +```twig showLineNumbers +{# Print out the Y-m-d of start date if start date is before the Day date #} + +{% set events = craft.calendar.events %} + +{% for event in events %} + {% if event.startDate.lt(day.date) %} + {{ event.startDate.dateString }} + {% endif %} +{% endfor %} +``` + +Now let's print out the duration of the event, which is the amount of time in months, days, hours, etc from the event's start date until its end date + +```twig showLineNumbers +{# + Print out the duration string. + An example output would be "1d 5h 30m" +#} + +{% set events = craft.calendar.events %} + +{% for event in events %} + {{ event.duration.humanReadable }} +{% endfor %} + +{# + Print out a custom message if the duration in days is 1 or more. + Please note that durations 1 month or longer will trigger 'months' + count and reset the days count back to '0' at each month interval). +#} + +{% for event in events %} + {% if event.duration.days >= 1 %} + Event spans for {{ event.duration.days }} days + {% endif %} +{% endfor %} +``` + +--- + +To paginate events, use Craft's [Pagination](https://craftcms.com/docs/4.x/dev/tags.html#paginate). Here's an example: + +```twig showLineNumbers +{% set eventOptions = {limit: 15} %} + +{% paginate craft.calendar.events(eventOptions) as pageInfo, events %} + +{% for event in events %} +
      + {{ event.title }} +
      +{% endfor %} + +{% if pageInfo.prevUrl %} + Previous Page +{% endif %} +{% if pageInfo.nextUrl %} + Next Page +{% endif %} +``` + +--- + +To display a list of parent events with their upcoming occurrences paired with them, your code might look something like this: + +```twig showLineNumbers +{% set events = craft.calendar.events().all() %} + +{% for event in events %} +
      + {{ event.title }} - {{ event.startDate.toDateTimeString }} + + {% set occurrences = craft.calendar.occurrences({ + event: event.id, + startsAfterOrAt: 'today', + }).all() %} + {% if occurrences %} +
        + {% for occurrence in occurrences %} +
      • + {{ occurrence.startDateLocalized|date('M j, Y g:ia') }} +
        • + {% endfor %} +
      + {% endif %} +
      +{% endfor %} +``` + +--- + +If you want to show a list of other events, and exclude the currently viewed event, your code might look something like this: + +```twig showLineNumbers +{% set currentEventId = craft.request.segment(3) %} +
        +{% for event in craft.calendar.events({ + id: 'not ' ~ currentEventId, + rangeStart: 'today', + rangeEnd: '1 month', + limit: 5 +}) %} +
      • [{{ event.id }}] {{ event.title }} {{ event.startDate }}
        • +{% endfor %} +
      +``` + +--- + +#### Grouping Events by Month/Week/Day + +If you want to group events by month/week/day, you can use this: + +```twig showLineNumbers +{% set eventOptions = { + rangeStart: "today", + rangeEnd: "2 months", +} %} + +{% for month in craft.calendar.events(eventOptions).groupedByMonth() %} +

      Month of {{ month.startDate.format("F, Y") }}

      +
        + {% for event in month.events %} +
      • {{ event.title }} - {{ event.startDate.toDateString() }}
        • + {% endfor %} +
      +{% endfor %} + +{% for week in craft.calendar.events(eventOptions).groupedByWeek() %} +

      Week of {{ week.startDate.format("F j, Y") }}

      +
        + {% for event in week.events %} +
      • {{ event.title }} - {{ event.startDate.toDateString() }}
        • + {% endfor %} +
      +{% endfor %} + +{% for day in craft.calendar.events(eventOptions).groupedByDay() %} +

      Day of {{ day.startDate.format("F j, Y") }}

      +
        + {% for event in day.events %} +
      • {{ event.title }} - {{ event.startDate.toDateString() }}
        • + {% endfor %} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/export.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/export.mdx new file mode 100644 index 00000000..877a21b2 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/export.mdx @@ -0,0 +1,60 @@ +--- +title: Export +sidebar_position: 10 +description: Export queries and iCal feeds in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Export Query + +The _calendar.export_ template query lets you export all or specific calendar events as an `ICS` formatted file. This will cause the user to receive a file download dialogue, and allow them to import the event(s) into a calendaring app like Apple Calendar or Google Calendar. + +:::info +Pass Calendar Event elements to the exporter. Calendar 6 uses each event's normalized RRULE/RSet data when generating the ICS feed. +::: + +## Parameters + +The _calendar.export_ template query is fairly simple in that it receives a list of events generated by the [Events query](./events.mdx). Additionally, there are 2 optional parameters available: + +- `site` + - Allows you to specify a certain site's translated version to be exported. Use the calendar's handle. +- `timezone` + - Allows you to simulate a localized timezone. By default, Calendar dates are stored as [floating timezones](https://tools.ietf.org/html/rfc5545#section-3.3.5), so an event with start time of `1pm` would have a "floating" time of `1pm` for `UTC±0`. If you specify `"America/New_York"` (`UTC-4`), the start time of the event will still show as `1pm`, but pretend to be on a **New York/UTC-4** timezone. If you then viewed this exported event in a timezone outside of `UTC-4` such as `UTC-5`, the start time would display as `12pm`. This feature is more-so available as a workaround for [Google Calendar not correctly supporting floating timezones](https://www.finalsitesupport.com/hc/en-us/articles/115000804047-When-displayed-via-a-Google-Calendar-event-times-are-incorrect). + - Specify the same format Craft does... `Region/City`, e.g. `timezone: "America/New_York"`. + - Warning: Dates/times will be will be localized (changed) for users **outside** of the specified timezone. + +```twig showLineNumbers +{{ craft.calendar.export(events, {site: "mySiteHandle", timezone: "America/New_York"}) }} +``` + +## Usage in Templates + +A basic example with floating timezones (the same dates/times forced for everyone, e.g. `6:30pm` is **6:30pm** regardless of which timezone you're in): + +```twig showLineNumbers +{%- set events = craft.calendar.events({ + calendarId: [1, 3, 5], + rangeStart: "1 year ago", + rangeEnd: "5 years", +}) -%} + +{%- header "Content-Type: application/octet-stream" -%} +{%- header "Content-Transfer-Encoding: binary" -%} + +{{- craft.calendar.export(events) -}} +``` + +An example where you can simulate a localized timezone that will be localized for users outside of the specified timezone (more-so as a workaround for [Google Calendar not correctly supporting floating timezones](https://www.finalsitesupport.com/hc/en-us/articles/115000804047-When-displayed-via-a-Google-Calendar-event-times-are-incorrect): + +```twig {11} showLineNumbers +{%- set events = craft.calendar.events({ + calendarId: [1, 3, 5], + rangeStart: "1 year ago", + rangeEnd: "5 years", +}) -%} + +{%- header "Content-Type: application/octet-stream" -%} +{%- header "Content-Transfer-Encoding: binary" -%} + +{{- craft.calendar.export(events, {timezone: "America/New_York"}) -}} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/hour.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/hour.mdx new file mode 100644 index 00000000..507821f0 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/hour.mdx @@ -0,0 +1,50 @@ +--- +title: Hour +sidebar_position: 9 +description: Hour query and calendar views in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Hour Query + +The _calendar.hour_ template query assembles an [Hour object](../objects/hour.mdx) containing its events. + +## Parameters + +- `date` + - A date string representing a date and hour for the hour that should be compiled. + - `"march 15 2023 5pm"` is a valid `date` value + - `"2023-03-01 17:33:11"` would be valid and return the [Hour object](../objects/hour.mdx) for the hour of 5pm on March 15, 2023 +- `calendar` + - Handle of the calendar, e.g. `"holidays"`, or an array of handles: `["holidays", "football"]`. + - Use `"not holidays"` to select all calendars EXCEPT the **Holidays** calendar +- `calendarId` + - An ID of the calendar, or array of ID's, e.g. `[1, 2, 3]` + - If you want to select all calendars EXCEPT the calendar with an ID of **1**, use `"not 1"` +- `allDay` + - Selects only events that are set to be **All Day** events went set to `true`. +- `authorId` + - Selects events from specific author ID's +- `limit` + - Supply an `int` to limit the amount of events returned +- `orderBy` + - Override default sort order by for each hour with this parameter, e.g. `orderBy: "startDate ASC"` +- `status` + - By default, `live` is used, showing only enabled events + - Can be set to `disabled` to show disabled events + - Or `null` to show all events regardless of their status +## Usage in Templates + +Iterate through all events within the current hour + +```twig showLineNumbers +{% set hour = craft.calendar.day({ + date: "now", + calendar: ["holidays", "sports"] +}) %} + +{% for event in hour.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/month.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/month.mdx new file mode 100644 index 00000000..1aacc469 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/month.mdx @@ -0,0 +1,108 @@ +--- +title: Month +sidebar_position: 5 +description: Month query and calendar views in Solspace Calendar 6.x templates for Craft CMS. +--- + +import { Photo } from '@site/src/components/utils'; + +# Month Query + +The _calendar.month_ template query assembles a [Month object](../objects/month.mdx) containing its events and allows for iteration over it to access all [Week objects](../objects/week.mdx) contained within, which in turn contain their respective [Day objects](../objects/day.mdx), which in turn contain their respective [Hour objects](../objects/hour.mdx). + + + +## Parameters + +- `date` + - A date string representing a date within the month that should be compiled. + - `"march 2023"` is a valid `date` value + - `"2023-03-01"` or even `"2023-03-15 12:33"` would be valid and return the [Month object](../objects/month.mdx) for **March 2023** +- `calendar` + - Handle of the calendar, e.g. `"holidays"`, or an array of handles: `["holidays", "football"]`. + - Use `"not holidays"` to select all calendars EXCEPT the **Holidays** calendar +- `calendarId` + - An ID of the calendar, or array of ID's, e.g. `[1, 2, 3]` + - If you want to select all calendars EXCEPT the calendar with an ID of **1**, use `"not 1"` +- `allDay` + - Selects only events that are set to be **All Day** events went set to `true`. +- `authorId` + - Selects events from specific author ID's +- `limit` + - Supply an `int` to limit the amount of events returned +- `orderBy` + - Override default sort order by for each day with this parameter, e.g. `orderBy: "startDate ASC"` +- `status` + - By default, `live` is used, showing only enabled events + - Can be set to `disabled` to show disabled events + - Or `null` to show all events regardless of their status +- `firstDay` + - An `int` value representing the first day of week. + - Defaults to the currently logged in user's first day of week. + - If user not logged in, it defaults to the global **First Day of Week** Craft setting + - Accepts `int` values from `0-6`, `0` being **Sunday**, `6` being **Saturday** +- `search: "customField:myvalue*"` + - Works just like regular [Craft Searching](https://craftcms.com/docs/4.x/searching.html). + :::warning + There's currently a known issue where searches combined with `calendar` parameter will not work. Use `calendarId` instead for now. + ::: +- `relatedTo: event.id` + - Works just like regular [Craft Relations](https://craftcms.com/docs/4.x/relations.html#templating). + +## Usage in Templates + +Iterate through weeks and days of the month + +```twig showLineNumbers +{% set month = craft.calendar.month({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for week in month %} + {% for day in week %} + {% for event in day.events %} +
      + {{ event.title }} +
      + {% endfor %} + {% endfor %} +{% endfor %} +``` + +--- + +Iterate through all events in the month + +```twig showLineNumbers +{% set month = craft.calendar.month({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in month.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` + +--- + +Show only events which start in weekends + +```twig showLineNumbers +{% set month = craft.calendar.month({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in month.events if event.startDate.weekend %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_docs/version-v6/templates/queries/week.mdx b/craft-calendar_versioned_docs/version-v6/templates/queries/week.mdx new file mode 100644 index 00000000..00f1c338 --- /dev/null +++ b/craft-calendar_versioned_docs/version-v6/templates/queries/week.mdx @@ -0,0 +1,94 @@ +--- +title: Week +sidebar_position: 6 +description: Week query and calendar views in Solspace Calendar 6.x templates for Craft CMS. +--- + +# Week Query + +The _calendar.week_ template query assembles a [Week object](../objects/week.mdx) containing its events and allows for iteration over it to access all [Day objects](../objects/day.mdx) contained within, which in turn contain their respective [Hour objects](../objects/hour.mdx). + +## Parameters + +- `date` + - A date string representing a date within the week that should be compiled. + - `"march 15 2023"` is a valid `date` value + - `"2023-03-10"` would be valid and return the [Week object](../objects/week.mdx) for the week containing **March 15, 2023** +- `calendar` + - Handle of the calendar, e.g. `"holidays"`, or an array of handles: `["holidays", "football"]`. + - Use `"not holidays"` to select all calendars EXCEPT the **Holidays** calendar +- `calendarId` + - An ID of the calendar, or array of ID's, e.g. `[1, 2, 3]` + - If you want to select all calendars EXCEPT the calendar with an ID of **1**, use `"not 1"` +- `allDay` + - Selects only events that are set to be **All Day** events went set to `true`. +- `authorId` + - Selects events from specific author ID's +- `limit` + - Supply an `int` to limit the amount of events returned +- `orderBy` + - Override default sort order by for each day with this parameter, e.g. `orderBy: "startDate ASC"` +- `status` + - By default, `live` is used, showing only enabled events + - Can be set to `disabled` to show disabled events + - Or `null` to show all events regardless of their status +- `firstDay` + - An `int` value representing the first day of week. + - Defaults to the currently logged in user's first day of week. + - If user not logged in, it defaults to the global **First Day of Week** Craft setting + - Accepts `int` values from `0-6`, `0` being **Sunday**, `6` being **Saturday** +- `search: "customField:myvalue*"` # + - Works just like regular [Craft Searching](https://craftcms.com/docs/4.x/searching.html). + +## Usage in Templates + +Iterate through days of the week + +```twig showLineNumbers +{% set week = craft.calendar.week({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for day in week %} + {% for event in day.events %} +
      + {{ event.title }} +
      + {% endfor %} +{% endfor %} +``` + +--- + +Iterate through all events in the week + +```twig showLineNumbers +{% set week = craft.calendar.week({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in week.events %} +
      + {{ event.title }} +
      +{% endfor %} +``` + +--- + +Show only events which start in weekdays + +```twig showLineNumbers +{% set week = craft.calendar.week({ + date: "today", + calendar: ["holidays", "sports"] +}) %} + +{% for event in week.events if event.startDate.weekday %} +
      + {{ event.title }} +
      +{% endfor %} +``` diff --git a/craft-calendar_versioned_sidebars/version-v6-sidebars.json b/craft-calendar_versioned_sidebars/version-v6-sidebars.json new file mode 100644 index 00000000..caea0c03 --- /dev/null +++ b/craft-calendar_versioned_sidebars/version-v6-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/craft-calendar_versions.json b/craft-calendar_versions.json index 732c7ddc..71cff5a0 100644 --- a/craft-calendar_versions.json +++ b/craft-calendar_versions.json @@ -1 +1 @@ -["v4", "v3", "v2", "v1"] +["v6", "v4", "v3", "v2", "v1"] diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 57e53f59..e7521495 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -224,6 +224,12 @@ const config: Config = { path: 'v5', badge: false, }, + v6: { + label: '6.x', + path: 'v6', + banner: 'unreleased', + badge: false, + }, v4: { label: '4.x', path: 'v4', diff --git a/src/theme/DocVersionBanner/index.tsx b/src/theme/DocVersionBanner/index.tsx index ad14364c..473d235e 100644 --- a/src/theme/DocVersionBanner/index.tsx +++ b/src/theme/DocVersionBanner/index.tsx @@ -41,7 +41,6 @@ function getCurrentProductName(): string { } function UnreleasedVersionLabel({ - siteTitle, versionMetadata, productName, }: BannerLabelComponentProps) { @@ -50,14 +49,11 @@ function UnreleasedVersionLabel({ id="theme.docs.versions.unreleasedVersionLabel" description="The label used to tell the user that they're browsing an unreleased doc version" values={{ - siteTitle, - versionLabel: {versionMetadata.label}, + versionLabel: versionMetadata.label, productName, }} > - { - 'This is unreleased documentation for {siteTitle} {versionLabel} version of {productName}.' - } + {'This is unreleased documentation for {productName} {versionLabel}.'} ); } diff --git a/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx b/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx index cdcaa5fb..ac535c11 100644 --- a/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx +++ b/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx @@ -22,6 +22,11 @@ const badgeObj = { ✓ Latest
), + Upcoming: ( +
+ Upcoming +
+ ), Retired: (
Retired @@ -68,7 +73,17 @@ export default function DocsVersionDropdownNavbarItem({ ); const versionBadgeList = versionData ? versionsBadge[versionData] : []; - const versionLinks = versions.map((version) => { + const getVersionOrder = (version: GlobalVersion) => { + const badgeIndex = versionBadgeList.findIndex( + (v) => v.version === version.name + ); + + return badgeIndex === -1 ? Number.MAX_SAFE_INTEGER : badgeIndex; + }; + + const versionLinks = [...versions].sort( + (a, b) => getVersionOrder(a) - getVersionOrder(b) + ).map((version) => { const versionDoc = activeDocContext.alternateDocVersions[version.name] ?? getVersionMainDoc(version); diff --git a/versionsBadge.json b/versionsBadge.json index dae571f2..411447a8 100644 --- a/versionsBadge.json +++ b/versionsBadge.json @@ -7,6 +7,7 @@ { "version": "v1", "badge": "Retired" } ], "/craft/calendar": [ + { "version": "v6", "badge": "Upcoming" }, { "version": "current", "badge": "Latest" }, { "version": "v4", "badge": "Retired" }, { "version": "v3", "badge": "Retired" },