This is an events plugin for Grav CMS 1.1.5+.
Create single and repeating events using event: frontmatter on any page you choose. The Events Plugin provides templates for calendar, events, and event views and supports creating events via the Admin plugin.
View our related Pages Repo to see how Calendar, Events, and Event pages are properly created.
From the root of your Grav install.
$ bin/gpm install events
You can also install this plugin from the Admin plugin using the plugins search feature.
Date translations can be enabled by setting date_format.translate to true in the config. They use the official Grav translation files, so if your language is missing, don't hesitate to contribute upstream.
Events creates a few different taxonomy types and adds them programatically to Grav. You do not need to specify them in a config file as they are automatically inserted into the system based off of event frontmatter on event pages.
Currently, the following taxonomies are created and available for building page collections:
'@taxonomy.event_repeat' with params [M,T,W,R,F,S,U] When using this taxonomy, be sure to separate your repeat rules with a comma. When adding them to event.repeat: MTWRFSU do not separate the rules with a comma.
'@taxonomy.event_freq' with params [daily, weekly, monthly, yearly].
'@taxonomy.type' with param 'event'.
Events supports the import of events from one or more *.ics file(s). On saving the settings in the admin panel it will create a user defined folder for the events. This folder will contain a subfolder for each year with a subfolder and an event.md file for each event.
Events can also handle multi-language *.ics files. At the moment it supports summary, description and location in different languages. See example definitions at https://icalendar.org/iCalendar-RFC-5545/3-2-10-language.html. Although it would technically work, it's not recommended to use locales (en-GB, de-DE, etc.), but only languages (en, de, etc.).
The path to *.ics file(s) must be specified in the admin interface under iCalendar files. The path(s) may be relative (local) or absolute (local or remote). A line must not contain more than one path. The exact location doesn't matter, so you can choose any accessible directory.
Events parses all of your markdown files for event: frontmatter and then automagically assigns taxonomies to your events based on whether they repeat through the week and through what intervals. This lets you build powerful collections based on the event_freq: and event_repeat: intervals. This lets you create custom displays. For example, if you want to build a list of all events that happen on Mondays you can filter on '@taxonomy.event_repeat':['M'] or pull out your Weekly events by filtering on '@taxonomy.event_freq':'weekly'.
It also adds any page found with event frontmatter to ''@taxonomy.type': 'event'. This allows you to build collections based on this taxonomy type.
The date: of a page will be set to event.start: automatically if not specified. This allows you to order your events by date using the order: paramater for collections.
If the event is a repeating event, pages will be added to the pages collection with the correct dates and times for use throughout the rest of a Grav site. Each virtual page is given a unique path with a 6 character tokenized suffix. The URL generated is safe to copy and paste on other sites and will go back to the specific reoccurring or repeating date of the event.
The event.start: and event.end: dates can be specified using m/d/y or d-m-y formats along with times.
This plugin supports creating repeating events using event.repeat:,
event.freq:, and event.until:.
event.repeat: specifies what days you would like for your event to repeat horizontally across a calendar. This can be for Monday through Sunday as specified by MTWRFSU. (Monday, Tuesday, Wednesday, ThuRsday, Friday, Saturday, SUnday).
event.freq: can be set to daily, weekly, monthly, or yearly.
event.until: is a date and time specification like 01/01/2016 12:00am
You can edit the front matter of your pages or use the Admin plugin with the supplied blueprints to update event information. If you use the Admin plugin, coordinates will automatically be geo-decoded from address that you enter.
event:
start: '01/01/2015 6:00pm'
end: '01/01/2015 7:00pm'
repeat: 'MTWRFSU'
freq: weekly
until: '01/01/2020'
location: 'Raleigh, NC'
coordinates: '35.7795897, -78.6381787'A collection of weekend events.
collection:
@items:
@taxonomy.type: 'event'
@taxonomy.event_repeat: [S, U]A collection of weekly events.
collection:
@items:
@taxonomy.type: 'event'
@taxonomy.event_freq: 'weekly'A collection of featured events.
collection:
@items:
@taxonomy.type: 'event'
@taxonomy.category: [ featured ]A collection of weekend events with a dateRange using the DateTools Plugin. Note the use of limit for pagination. This plugin uses Grav's Pagination Plugin automatically if it is enabled.
{% set events =
page.collection({
'items': {
'@taxonomy': {
'type': 'event',
'event_repeat': ['S','U']
}
},
'dateRange': {
'start': datetools.startOfWeek,
'end': datetools.endOfWeek
},
'order': {
'by': 'date',
'dir': 'asc'
},
'limit': 10
})
%}
<ul>
{% for event in events %}
<li>
<a href="{{ event.url }}">{{ event.title }}</a>
<time class="dt-start" datetime="{{ event.header.event.start|date('c') }}">
{{ event.header.event.start|td(null, 'F j, Y') }}
</time>
</li>
{% endfor %}
</ul>
Be sure to checkout the DateTools Plugin. This plugin uses DateTools to filter date ranges on collection in twig templates.
- properly implement recurring events. Currently the ics-parser has an issue with recurring events (#196 & #231). As a workaround a folder for each occurence of an event is created and the folders are prefixed with month and day.
- the last recurring event may be missing due to an issue in the ics-parser (#238). To work around this the according event in the ics file should last one recurrence longer.