Creating and managing calendars

[Discourse]

This guide explains how to create and manage calendars in Discourse using the Calendar (and Event) plugin.

Required user level: All users

Calendars are a powerful feature in Discourse that allow you to organize and display events within your community. This guide will walk you through the process of creating calendars, adding events, and managing them effectively.

Summary

• Enable the Calendar plugin
• Create a calendar in a topic or category
• Add events to your calendar
• Manage calendar options and settings
• Use the holiday calendar feature

Enabling the Calendar plugin

Before you can create calendars, ensure that the “Calendar (and Event)” plugin is enabled on your Discourse instance. For more details on enabling the plugin and its related settings, refer to the Discourse Calendar and Event plugin documentation.

Creating a calendar

Topic calendar

To embed a calendar in a topic:

1. Create a new topic or edit the first post of an existing topic
2. Add the following code on separate lines:

   [calendar]
   [/calendar]
   

3. Publish or update the post

Monday is considered the first day of the week in Discourse calendars, regardless of the viewer’s locale settings. This is currently not configurable.

Category calendar

To create a category-wide calendar:

1. Go to /admin/site_settings/category/discourse_calendar?filter=plugin=discourse-calendar
2. In the “calendar categories” setting, add an entry with the following format:

   categoryId=123;postId=4949;tzPicker;defaultView=month
   

   • Replace 123 with your category ID (found in the URL when viewing the category)
   • Replace 4949 with the post ID of the category description (found by appending .json to the “About category” topic URL)
3. Add the category ID to the “events calendar categories” setting
4. Optionally, set “discourse post event allowed on groups” to control which groups can add events

Adding items to a calendar

Topic calendar

To add an event to a topic calendar:

1. Reply to the topic containing the calendar
2. Use the Insert Date function in the composer to add a date or date range
3. Add a description above the date
4. Submit the reply

The event will appear in the calendar after reloading the topic.

Category calendar

To add an event to a category calendar:

1. Create a new topic in the category
2. Click the gear button and select “Create event”
3. Fill in the event details and publish

The event will appear on the category calendar.

Calendar options

You can customize your calendar using various options:

Option	Example	Description
Hide weekends	weekends="false"	Hides Saturday and Sunday
Hide specific days	hiddenDays="1,2"	Hides Monday and Tuesday (use 0-6 for Sunday-Saturday)
Set default view	defaultView="basicWeek"	Options: month, basicWeek, listNextYear
Ignore timezones	fullDay="true"	Treats all events as full-day events

Example usage:

[calendar weekends="false" hiddenDays="1,2" defaultView="basicWeek" fullDay="true"]
[/calendar]

Removing calendar items

Calendar items cam be removed in these ways:

• Expired calendar items can be automatically removed using the “delete expired event posts after” setting
• Use topic timers to auto-delete replies
• Manually delete posts as needed

Holiday calendar

The holiday calendar is a special feature for managing site staff holidays:

1. Create a topic with a calendar in the first post
2. Set the “holiday calendar topic id” to the ID of this topic
3. Replies to this topic will be treated as vacation time for the posting user
4. Vacation entries are automatically and randomly colored
5. An emoji (default: ) appears next to vacationing users’ names in user cards and @mentions
6. Optionally, include locale-specific holidays for users by enabling “calendar automatic holidays enabled”

FAQs

Q: Why do some events appear to span multiple days?
A: The calendar is always in UTC. Use the “all day event start time” and “all day event end time” settings to adjust for timezone differences.

Q: Can I control the colors of holiday calendar entries?
A: Currently, it’s not possible to control the colors of holiday calendar entries or get colored entries in regular calendars.

Q: How do I display past events in a list view?
A: There’s currently a bug when using defaultView=listNextYear that causes the initial view to be empty. As a workaround, users need to switch to monthly view, go back one month, and then return to list view to see past events.

Additional resources

• Discourse Calendar (and Event)
• Creating and managing events

Last edited by @hugh 2024-07-02T09:35:06Z

Last checked by @hugh 2024-07-02T09:35:23Z

Check document

Perform check on document:

[hellekin]

I have a hard time understanding how to create a calendar so that it displays in a category, and what to do to fill it once it’s there. For topics, it is quite straightforward, but the category case is more obscure. Can someone give an example?

[hellekin]

Create a Category Calendar

The difference between a topic calendar and a category calendar is that the former uses from a specific topic response, and displays the calendar in the topic itself, while the latter uses in any topic of the configured category, and displays the events calendar in the category.

1. Enable the calendar plugin

In /admin/site_settings/category/discourse_calendar?filter=plugin%3Adiscourse-calendar → calendar categories:

You want something like: categoryId=123;postId=4949;tzPicker;defaultView=month

• categoryId is easy to find: it’s the number in the URL when you click the #category

• postId can be found like this: go to the category description (the “About category” pinned topic) and append .json to the URL: the postId is at the beginning of the JSON file.

• Review the discourse-calendar documentation for available options.

• Add the category (numbered 123 in our example) to events calendar categories

You may want to set discourse post event allowed on groups to include the groups you want to be able to add events.

2. Create an event

You can create a new topic in category 123 and (from the gear button).

The event will then appear on the category calendar.

[jrgong]

Is there any way to display not the upcoming events, but the ones in the past year? We would like to make use of the plugin for our journal section and list all past entries in the first post.

When using this snippet below, the event list is initially empty. Only when going back to monthly view, going one month back and going back to list view, it works

[calendar defaultView=listNextYear fullDay=true]
[/calendar]

See bug in action:

[Heliosurge (Dan DeMontmorency)]

I am interested in this function as well.

I wonder if there might also be some data explorer scripts to go along calender searching