The CalendarPage is the heart of the Joyous application.


Users can display the calendar in a Monthly, Weekly, or List View. (The default view is set in the Settings tab.)

The first day of the week used, Sunday or Monday, depends upon your Django format localization or FIRST_DAY_OF_WEEK setting. This can be over-ridden using the JOYOUS_FIRST_DAY_OF_WEEK setting.

There are actually multiple list views

  • All upcoming events
  • All past events
  • and a “secret” all events of a day - unless there’s only one - in which case it just redirects straight to that event


How a calendar is displayed or exported depends upon the path and query string of the URL used to access it. Consider a calendar with the slug /events/:

/events/ Default view of the calendar - set as a per-calendar property.
/events/month/ Monthly view.
/events/week/ Weekly view.
/events/day/ Day list view.
/events/upcoming/ List of upcoming events.
/events/past/ List of past events.
/events/?view=list Specified (list|weekly|monthly) view of the calendar.
/events/2017/ Default view of the calendar for 2017
/events/2017/?view=weekly Specified view for 2017.
/events/2018/Apr/ Monthly view for April 2018.
/events/2018/5/ Monthly view for May 2018.
/events/2018/W2/ Weekly view for Week 2 of 2018.
/events/2018/6/18/ Day list view for the 18th of June 2018.
/events/?format=ical Export as an iCal file.
/events/?format=rss Export as a RSS feed.



A CalendarPage displays all the events in the same Wagtail Site as itself.

If that isn’t what you want, then have a look at GeneralCalendarPage or SpecificCalendarPage.


Displays all the events in the database ignoring site boundaries. See GeneralCalendarPage.

GeneralCalendarPage is disabled by default. Use GeneralCalendarPage.is_creatable = True to enable it.


Displays only those events which are children of itself. See SpecificCalendarPage.

SpecificCalendarPage is disabled by default. Use SpecificCalendarPage.is_creatable = True to enable it.

Derive your own

If you would like some other kind of event selection you can derive your own version of CalendarPage.

Have a look at the source-code of the CalendarPages classes if you would like some other kind of event selection. The methods _getEventsOnDay, _getEventsByDay, _getEventsByWeek, _getUpcomingEvents, and _getPastEvents determine what events are displayed. The methods _getEventFromUid and _getAllEvents are for import and export.


Holidays are a property of the CalendarPage.

If the JOYOUS_HOLIDAYS setting is set then it is used to select holidays from python-holidays. But it is also possible to add other holiday sources (e.g. from workalendar or just a simple dict) via register. And to add individual days via add.

For example:
from datetime import date
from workalendar.america import Ontario

CalendarPage.holidays.add(date(2019,4,29), "HAPPY HAPPY")

It would also be possible to derieve different Calendar models and give them different sets of holidays. Holidays for CalendarPage are determined programmatically, but a derieved Calendar model could choose to change this, e.g. store the holidays in the database so that different pages of the same model could have different holidays.