Skip to content
This plugin provides Calendar Events for Grav CMS
PHP HTML CSS CoffeeScript JavaScript Shell
Branch: master
Clone or download
Pull request Compare This branch is 70 commits ahead of kalebheitzman:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Revised templates and css while using the Quark theme Aug 16, 2019
blueprints added exceptions Dec 20, 2016
classes Merged bugfix from u01jmg3/ics-parser#238 (comment) Oct 5, 2019
coffee updated calendar styles Dec 22, 2016
scss Revised templates and css while using the Quark theme Aug 16, 2019
templates Revised templates and css while using the Quark theme Aug 16, 2019
tests/units added atoum testing Oct 2, 2016
vendor Update dependencies Oct 5, 2019
.gitignore better gulp workflow Dec 22, 2016
.travis.yml updated travis Oct 2, 2016
CHANGELOG.md Merged bugfix from u01jmg3/ics-parser#238 (comment) Oct 5, 2019
LICENSE updated license Oct 2, 2016
README.md Some minimal changes Sep 4, 2019
blueprints.yaml Merged bugfix from u01jmg3/ics-parser#238 (comment) Oct 5, 2019
bower.json updated templates Sep 21, 2016
composer.json Updated dependencies Aug 15, 2019
composer.lock Update dependencies Oct 5, 2019
events.php
events.yaml readme update Oct 2, 2016
gulpfile.js
languages.yaml Added German translations Aug 15, 2019
package.json better gulp workflow Dec 22, 2016
phpdocs.sh moved phpdocs generated docs outside of plugin Oct 3, 2016

README.md

Events Plugin for Grav CMS

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.

Installation

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.

Translations

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.

Taxonomy

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'.

iCalendar file support

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.

How it works

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.

Specifying dates and times

The event.start: and event.end: dates can be specified using m/d/y or d-m-y formats along with times.

Repeating dates

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

Event frontmatter example

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'

Collection frontmatter examples

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 ]

Collection twig examples

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|date('F j, Y') }}
            </time>
        </li>
    {% endfor %}
</ul>

DateTools Plugin

Be sure to checkout the DateTools Plugin. This plugin uses DateTools to filter date ranges on collection in twig templates.

Todo/Issues

  • 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.
  • dates in the sidebar are not being translated, yet
You can’t perform that action at this time.