djangocms-events

Events and calendar with ics import for django CMS

Installation, required libraries and settings

You can install this package with

pip install djangocms-events

or from the git repository with

pip install git+https://github.com/MacLake/djangocms-events.git

or add djangocms-events or

djangocms-events @ git+https://github.com/MacLake/djangocms-events.git

to your requirements.

Python packages

This package uses sekizai, which is required by django CMS anyway.

The description of events can be formatted text and is saved in a QuillField, so django-quill-editor is required.

In the templates for event lists and detail view easy-thumbnails is used. This requires an entry in INSTALLED_APPS in your project settings:

INSTALLED_APPS: list[str] = [
    ...
    'sekizai',
    'easy_thumbnails',
    'django_quill',
    'djangocms_events',
]

and a definition for the thumbnail sizes:

THUMBNAIL_ALIASES: dict[str, dict[str, dict[str, any]]] = {
    '':
        {
            'event-list': {
                'size': (600, 300),
                'crop': True,
                'upscale': True
            },
            'event-detail': {
                'size': (600, 300),
                'crop': False,
                'upscale': True
            },
        }
}

The following settings are optional:

DJANGOCMS_EVENTS_SHOW_CALENDAR_MONTH_WEEK_DAY_CONTROL: bool = False
DJANGOCMS_EVENTS_PAGINATE_BY: int = 100
DJANGOCMS_EVENTS_NR_INITIALLY_SHOWN: int = 5
DJANGOCMS_EVENTS_CORNER_LABELS: bool = True

With DJANGOCMS_EVENTS_SHOW_CALENDAR_MONTH_WEEK_DAY_CONTROL you can choose if the control for switching between month, week and day view in the calendar is shown or hidden. If it’s not set, it will be shown. DJANGOCMS_EVENTS_PAGINATE_BY sets the number of events per page in the events list and defaults to 100. With setting DJANGOCMS_EVENTS_NR_INITIALLY_SHOWN to a number that is smaller than the number of events per page, only this number of events will be shown on the overview, the rest will be hidden in an accordion, otherwise no events will be hidden. With DJANGOCMS_EVENTS_CORNER_LABELS: bool = True corner labels in pictures of calendar lists (app hook or plug-in) indicate the corresponding calendar by its colour.

JavaScript frontend libraries

The frontend uses the framework Fomantic UI in general and especially for modal overlays and optionally an accordion. In its current version it needs jQuery which is also used for event handling. Ajax requests for getting the content of event details are done with htmx. These libraries are included in the webpack bundle djangocms_events/static/djangocms_events/webpack/index.bundle.js. In case you already have one or more of these libraries in your CMS base template, so that you don’t need this bundle, or you want to adopt the templates to integrate it into your website, you can override the templates by copying them to your project and modify them. You might want to build your own webpack bundle based on assets/src/index.js. If you do, you should rename index in entry in webpack.config.js in order to avoid a name conflict with the shipped bundle and link your own bundle.

Short instruction for building the webpack bundles: Clone this repo and enter it in a shell.

npm install
npx webpack

The second bundle djangocms_events/static/djangocms_events/webpack/calendar.bundle.js is used for the calendar view in the apphook page and the calendar plug-in.

Usage

After installing and configuring the package you can integrate it in django CMS as a webhook page in the advanced settings of a CMS page.

You can edit events in the Django admin or import an ICS file. In either case first create a calendar in the admin. If you want to import an ICS file available in the Internet, enter its URL, otherwise leave this field empty. You can import events after having checked the “publish” field in the calendar by applying an admin action or by calling a URL for importing the events e.g. in a cron job or in a browser where you will get a table of the imported events. The URL for importing all events of all published calendars is the URL of your apphook page plus import_calendars or import_calendars_future_events for just importing events in the future.

On the apphook page you can see a calendar and a list of the events. The default view shows only events of the current and future months in the calendar and future events in the list, because calendars with thousands of events in the past take much more time to render, even with pagination. With a menu you can also go to pages with the past or all events.

In addition, there are plug-ins for event lists and calendar views. You can choose which calendars, i.e. groups of events will be shown. In the event list plug-in you can choose how many events are being shown, and if there are not enough future events, you can choose to fill up the list with recent events, so the list won’t look too empty in that case.

Integrated libraries

Name	Used for	License
jquery	Needed for Fomantic UI, event handling	MIT license
Fomantic UI	frontend library	MIT license
htmx	Ajax requests for detail views	BSD-2-Clause license
Toast UI Calendar	JS calendar	MIT License