The Simple Events Plugin is an extension for Grav CMS. It lets you add a simple list of events to your site. If you'd like something more advanced, check out the Events plugin which has a calendar, geolocation, options for repeating events and more. This plugin really is for a simple list of events with no extra pages for them, and all added manually.
Installing the Simple Events plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.
To install the plugin via the GPM, through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:
bin/gpm install simple-events
This will install the Simple Events plugin into your /user/plugins-directory within Grav. Its files can be found under /your/site/grav/user/plugins/simple-events.
To install the plugin manually, download the zip-version of this repository and unzip it under /your/site/grav/user/plugins. Then rename the folder to simple-events. You can find these files on GitHub or via GetGrav.org.
You should now have all the plugin files under
/your/site/grav/user/plugins/simple-events
If you use the Admin Plugin, you can install the plugin directly by browsing the Plugins-menu and clicking on the Add button.
Before configuring this plugin, you should copy the user/plugins/simple-events/simple-events.yaml to user/config/plugins/simple-events.yaml and only edit that copy.
Here is the default configuration and an explanation of available options:
enabled: true
delete_old: false # enable to delete past events automatically
unpublish_old: true # disable to keep past events in your list
unpublish_day: start
unpublish_time: '00:00'
use_location: false # shows an extra text field in admin for use in templates
use_links: false # turn on options in admin to add a link to (part of) the title
link_options:
- PLUGIN_SIMPLE_EVENTS.NONE
use_regions: false # enable to group events in the list by regions
regions: null
# see below on how to configure links and regionsNote that if you use the Admin Plugin, a file with your configuration named simple-events.yaml will be saved in the user/config/plugins/-folder once the configuration is saved in the Admin.
Once the plugin is enabled, you have two extra template options: Events and Event. Create a new page that you want to display your events list on, and give it the template Events. Then create child pages with the template Event, define a collection in the frontmatter of the parent page and they will automatically be listed on the parent page.
A simple frontmatter collection example:
content:
items: '@self.children'
order:
by: header.start
dir: asc
filter:
published: true
type: 'event'Note that if you use the Admin plugin, you will find the ordering options under the Events tab of that page, and the collection will be created for you upon saving.
You can (and probably want to) modify the appearance of the list by copying
user/plugins/simple-events/templates/events.html.twig to [theme folder]/templates/events.html.twig, and then making any changes in that copy. I have included some code to help with making the dates multilingual, if you can't make something work, feel free to create an issue for the plugin!
If you just want a very simple list of events, the end date, regions, location and link fields of the Event page type are completely optional. If you would like to use any of these, turn them on in the plugin options (see above). The location field is really just a text field that you can use for any information you'd like to style differently in your template, it does not have to be a location (but this is likely to see a lot of use). For links and regions, additional configuration is needed.
If you wish to be able to link your event text or a part of it to another page or another website, make a list of available links under the plugin's configuration options or directly in the config file like so:
link_options:
0: '- nothing -'
'path/to/page': 'Example'
'http://www.example.com': 'External example'You can then put part of your event text in square brackets [] and select what you wish to link this to. (This is an option I made for my clients, if you can create links in all the regular ways, you will likely not need this.)
You can sort your events into regions if you like: just create a list of regions in the plugin settings and enable the regions (in Admin), or put an array into your user/config/plugins/simple-events.yaml like so:
regions:
london: 'London area'
paris: 'Paris and surroundings'
germany: 'Somewhere in the backwaters of Germany'
use_regions: trueThen add one of these to each of your events, either via the Admin interface or by putting region: paris or similar in the event page frontmatter. Whatever you have put as the region's name will appear as a headline in between your list of events, and they will be sorted by how you sorted that list of regions.
If you'd like to put a list of events as part of a page somewhere, do the following:
- add a collection of the events you'd like to list to that page's frontmatter
- then put
{% include 'partials/eventslist.html.twig' %}wherever you would like the list to appear - set
process: twig: truefor that page (in the Advanced tab in Admin) - do any customisations in a copy of that file and put that in your theme's
templates/partialsfolder
You can also add taxonomy tags to your events and then use them in the page collection as a filter, for example if you have different types of events.
This plugin was initially sponsored by a German nonprofit organisation. As soon as the English version of their website is online, I shall link them here!
I would also like to thank @pamtbaau, whose expertise has greatly contributed to this plugin.
- add option to delete past events (or do it automatically)
- make use of Grav's built-in unpublish_date field
- support for categories in events template
- support for types in events template