{"id":20583740,"url":"https://github.com/mzur/kirby-calendar-plugin","last_synced_at":"2025-04-14T20:31:39.682Z","repository":{"id":47170177,"uuid":"6163697","full_name":"mzur/kirby-calendar-plugin","owner":"mzur","description":"A plugin for the Kirby CMS to easily implement an event calendar.","archived":false,"fork":false,"pushed_at":"2024-05-14T12:38:16.000Z","size":89,"stargazers_count":101,"open_issues_count":2,"forks_count":9,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-28T08:42:15.208Z","etag":null,"topics":["calendar","event-calendar","kirby","kirby-plugin","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mzur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mzur","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"custom":"https://www.paypal.me/drmzur"}},"created_at":"2012-10-10T20:13:34.000Z","updated_at":"2025-03-02T18:15:30.000Z","dependencies_parsed_at":"2024-05-14T13:59:25.777Z","dependency_job_id":null,"html_url":"https://github.com/mzur/kirby-calendar-plugin","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzur%2Fkirby-calendar-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzur%2Fkirby-calendar-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzur%2Fkirby-calendar-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mzur%2Fkirby-calendar-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mzur","download_url":"https://codeload.github.com/mzur/kirby-calendar-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248955646,"owners_count":21189203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","event-calendar","kirby","kirby-plugin","php"],"created_at":"2024-11-16T06:43:32.191Z","updated_at":"2025-04-14T20:31:39.659Z","avatar_url":"https://github.com/mzur.png","language":"PHP","funding_links":["https://github.com/sponsors/mzur","https://www.paypal.me/drmzur"],"categories":[],"sub_categories":[],"readme":"# kirby-calendar-plugin\n\nA plugin for the [Kirby CMS](http://getkirby.com) to easily implement an event calendar.\n\n\n## Installation\n\n1. [Download](https://github.com/mzur/kirby-calendar-plugin/archive/refs/heads/master.zip) this repository and extract the directory to `site/plugins/`.\n\n2. Make sure you have the language support of Kirby activated (even, if you only want to support one language).\n\nFor more information on the multi language support of Kirby, see [the docs](https://getkirby.com/docs/guide/languages/introduction).\n\n## Usage\n\nMaking this plugin work involves three steps: providing the calendar data, setting up the calendar object and displaying the calendar as a snippet.\n\n### Calendar data\n\nYou provide the calendar data as you provide any content in Kirby; as a data field of the page. For example take the page `content/calendar/calendar.en.txt`:\n\n```txt\nTitle: Calendar\n\n----\n\nCalendar: \n-\n  summary: My Event\n  _begin_date: 12/14/2014\n  _begin_time: 10:00\n  _end_date: 12/14/2014\n  _end_time: 15:00\n- \n  summary: My supercool event for the whole day\n  description: This wil be a nice event!\n  _begin_date: 10/01/2014\n```\n\nThe `Calendar` field contains all events as a [structure](https://getkirby.com/docs/reference/panel/fields/structure). Each event has several own fields, too, but of them only  `_begin_date` is mandatory (see [event-fields](#event-fields)).  You can define as many other fields as you like.\n\n### Calendar object\n\nNow let's get to the `calendar` template. Setting up the calendar object is really simple; you only have to do this:\n\n```php\n\u003c?php $calendar = new Mzur\\KirbyCalendar\\Calendar($page-\u003ecalendar()-\u003eyaml()); ?\u003e\n```\n### Calendar snippet\n\nTo produce any output, you have to use a calendar snippet. This enables you to print even multiple different versions of the same calendar in the same template! You can use one of the [snippets provided by this plugin](#snippets) or make your own.\n\nTypical usage of a snippet looks like this (here we use the [`table`](#table) snippet provided by the plugin):\n\n```php\n\u003c?php\n   snippet('calendar-table', [\n      'calendar' =\u003e $calendar,\n      'fields' =\u003e [\n         'summary' =\u003e t('title'),\n         'description' =\u003e t('description')\n      ]\n   ]);\n?\u003e\n```\n\nThere are two variables we are passing along to the snippet here: `$calendar` is the calendar object we created in the previous step and `$fields` is an associative array of all the event fields that should be displayed in this snippet. The keys of this array are the keys of the event fields specified in the calendar data; the values specify how these fields should be displayed (in this case it depends on the language of the site).\n\nSo this is basically it. If you followed the instructions correctly, you should see the calendar printed on the page.\n\n### Panel\n\nThe calendar data is formatted to work perfectly with a [structure field](https://getkirby.com/docs/reference/panel/fields/structure). Here is an example blueprint:\n\n```yaml\ntitle: Events\npreset: page\nfields:\n   title:\n      label: Title\n      type:  text\n      readonly: true\n   events:\n      label: Events\n      type: structure\n      sortBy: _begin_date asc\n      fields:\n         _begin_date:\n            label: Start date\n            type: date\n            display: DD.MM.YYYY\n            required: true\n         _begin_time:\n            label: Start time\n            type: time\n            interval: 15\n            required: true\n         _end_date:\n            label: End date\n            type: date\n            display: DD.MM.YYYY\n            required: true\n         _end_time:\n            label: End time\n            type: time\n            interval: 15\n            required: true\n         summary:\n            label: Title\n            type: text\n            required: true\n```\n\n## Localisation\n\nThe plugin is designed to fully support localisation, thus requiring Kirby's language support to be enabled.\n\n### Language variables\n\nThe provided language files contain some language variables used by the plugin internally, by the default snippets or in this example.\n\n- `calendar-time-format`: The formatting string of the date of an event (without a time).\n- `calendar-full-time-format`: The formatting string of the date and time of an event.\n- `calendar-month-format`: The formatting string of a month.\n- `calendar-no-entry`: The message printed when there are no events to display.\n\nSee [here](http://php.net/manual/en/function.strftime.php) for more information on time formatting strings.\n\n### Timezone\n\nBy default the plugin uses the uses the timezone of the server it is running on. The correct timezone is essential for correct `datetime` attributes or iCal output, for example. To set the timezone manually you can use [`data_default_timezone_set`](http://php.net/manual/en/function.date-default-timezone-set.php) in the header snippet of your site like this:\n\n```php\n\u003c?php date_default_timezone_set('Europe/Berlin'); ?\u003e\n```\n\n### Locale\n\nThe locale is set by Kirby's language configuration. So if you've set up everything correctly, it should work without problems.\n\n## Event fields\n\nEvents can have arbitrary fields. However there are the special fields for this plugin marked by a `_`-prefix:\n\n- `_begin_date`: The only **mandatory** field specifying the date, the event begins.\n- `_begin_time`: The time of the day the event begins.\n- `_end_date`: The date the event ends.\n- `_end_time`: The time of the day the event ends.\n\nThe behavior with different combinations of these fields is the following:\n\n- only `_begin_date` given: The event lasts the whole day.\n\n- `_begin_date` and `_begin_time` given: The event lasts from the given time until midnight (12 am) of the following day.\n\n- `_begin_date` and `_end_time` given: The event lasts from midnight until the given time of the day.\n\n- `_begin_date` and `_end_date` given: The event lasts from mindnight of the beginning day until midnight of the day after the ending day.\n\n## Functions\n\nThere are two classes you can work with, `Mzur\\KirbyCalendar\\Calendar` and `Mzur\\KirbyCalendar\\Event`.\n\n### Calendar class\n\nThe `Mzur\\KirbyCalendar\\Calendar` class has the following functions:\n\n#### getAllEvents()\n\nReturns an array of all the events of this calendar, including the past events.\n\n#### getEvents()\n\nReturns an array of all future events of this calendar.\n\n#### getEventFields()\n\nReturns an array of all the event fields occurring in the events of this calendar.\n\n### Event class\n\nThe `Mzur\\KirbyCalendar\\Event` class has the following functions:\n\n#### getBeginTimestamp()\n\nReturns the UNIX timestamp in seconds for the beginning of this event.\n\n#### getBeginDate()\n\nReturns the [PHP date array](http://php.net/manual/en/function.getdate.php) of the beginning of this event.\n\n#### getBeginStr()\n\nReturns the formatted string of the beginning of this event. Formatting is done according to the language configuration of Kirby. If the event was given a time, the `calendar-full-time-format` is used, `calendar-time-format` otherwise.\n\n#### getBeginHtml($languageCode = 'en')\n\nReturns the formatted string of the beginning of this event as a `time` element with `datetime` attribute. Formatting is based on the passed language code.\n\n#### getEndTimestamp()\n\nReturns the UNIX timestamp in seconds for the ending of this event.\n\n#### getEndDate()\n\nReturns the [PHP date array](http://php.net/manual/en/function.getdate.php) of the ending of this event.\n\n#### getEndStr()\n\nReturns the formatted string of the ending of this event. Formatting is done according to the language configuration of Kirby. If the event was given a time, the `calendar-full-time-format` is used, `calendar-time-format` otherwise.\n\n#### getEndHtml($languageCode = 'en')\n\nReturns the formatted string of the ending of this event as a `time` element with `datetime` attribute. Formatting is based on the passed language code.\n\n#### getFieldKeys()\n\nReturns all field keys of this event that have no `_`-prefix.\n\n#### getField($key)\n\nReturns the content of the field or an empty string if it doesn't exist in this event.\n\n`$key`: The event field key whose value should be returned.\n\n#### isPast()\n\nReturns `true` if this event is past at the current time, `false` otherwise.\n\n#### hasEnd()\n\nReturns `true` if the event was given an ending date or time, `false` otherwise.\n\n## Snippets\n\nThere are a few default calendar snippets provided by this plugin. You can find them in the `snippets` directory of this repo. Of course you can customize them to your needs or write ones on your own!\n\n### table\n\nDisplays all events (including the past ones) as a table. Only the event fields given in `$fields` are displayed. `$fields` specify the column labels as well. Example output:\n\n```html\n\n\u003ctable class=\"calendar\"\u003e\n   \u003cthead\u003e\n      \u003ctr\u003e\n         \u003cth\u003eDate\u003c/th\u003e\n         \u003cth\u003eTitle\u003c/th\u003e\n         \u003cth\u003eDescription\u003c/th\u003e\n      \u003c/tr\u003e\n   \u003c/thead\u003e\n   \u003ctbody\u003e\n      \u003ctr class=\"month past\"\u003e\n         \u003ctd colspan=\"3\"\u003eOctober 2014\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr class=\"event past\"\u003e\n         \u003ctd\u003e\u003ctime datetime=\"2014-10-01T00:00:00Z\"\u003e01\u003c/time\u003e\u003c/td\u003e\n         \u003ctd\u003eMy supercool event for the whole day\u003c/td\u003e\n         \u003ctd\u003eThis wil be a nice event!\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr class=\"month\"\u003e\n         \u003ctd colspan=\"3\"\u003eDecember 2014\u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr class=\"event\"\u003e\n         \u003ctd\u003e\u003ctime datetime=\"2014-12-14T10:00:00Z\"\u003e14 10:00:00 AM\u003c/time\u003e to \u003ctime datetime=\"2014-12-15T23:45:00Z\"\u003e15 11:45:00 PM\u003c/time\u003e\u003c/td\u003e\n         \u003ctd\u003eEvent\u003c/td\u003e\n         \u003ctd\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n   \u003c/tbody\u003e\n\u003c/table\u003e\n```\n\n### div\n\nDisplays all events (including the past ones) as a div layout. Only the event fields given in `$fields` are displayed. `$fields` specify the column labels as well. Example output:\n\n```html\n\u003csection class=\"calendar\"\u003e\n   \u003cdiv class=\"row head\"\u003e\n      \u003cdiv class=\"item\"\u003eDate\u003c/div\u003e\n      \u003cdiv class=\"item\"\u003eTitle\u003c/div\u003e\n      \u003cdiv class=\"item\"\u003eDescription\u003c/div\u003e\n   \u003c/div\u003e\n   \u003cdiv class=\"row month past\"\u003e\n      \u003cdiv class=\"item\"\u003eOctober 2014\u003c/div\u003e\n   \u003c/div\u003e\n   \u003cdiv class=\"row event past\"\u003e\n      \u003cdiv class=\"item date\"\u003e\u003ctime datetime=\"2014-10-01T00:00:00Z\"\u003e01\u003c/time\u003e\u003c/div\u003e\n      \u003cdiv class=\"item\"\u003eMy supercool event for the whole day\u003c/div\u003e\n      \u003cdiv class=\"item\"\u003eThis wil be a nice event!\u003c/div\u003e\n   \u003c/div\u003e\n   \u003cdiv class=\"row month\"\u003e\n      \u003cdiv class=\"item\"\u003eDecember 2014\u003c/div\u003e\n   \u003c/div\u003e\n   \u003cdiv class=\"row event\"\u003e\n      \u003cdiv class=\"item date\"\u003e\u003ctime datetime=\"2014-12-14T10:00:00Z\"\u003e14 10:00:00 AM\u003c/time\u003e to \u003ctime datetime=\"2014-12-15T23:45:00Z\"\u003e15 11:45:00 PM\u003c/time\u003e\u003c/div\u003e\n      \u003cdiv class=\"item\"\u003eEvent\u003c/div\u003e\n      \u003cdiv class=\"item\"\u003e\u003c/div\u003e\n   \u003c/div\u003e\n\u003c/section\u003e\n```\n\n### ical\n\nDisplays all events (including the past ones) in iCal format. This is very useful to provide iCal export of your calendar. It only includes the `summary`, `description` and `location` event fields. Be sure to set the header of your iCal-export template like this:\n\n```php\n\u003c?php header('Content-type: text/calendar'); ?\u003e\n```\n\nExample output:\n\n```ical\nBEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//http://example.com//Kirby Calendar Plugin//EN\nMETHOD:PUBLISH\nBEGIN:VEVENT\nDTSTART:20141001T000000Z\nDTEND:20141002T000000Z\nSUMMARY:My supercool event for the whole day\nDESCRIPTION:This wil be a nice event!\nLOCATION:\nEND:VEVENT\nBEGIN:VEVENT\nDTSTART:20141214T100000Z\nDTEND:20141215T234500Z\nSUMMARY:Event\nDESCRIPTION:\nLOCATION:\nEND:VEVENT\nEND:VCALENDAR\n```\n\n### teaser\n\nDisplays a set number of future events as a list. The number of events to display is specified in `$items`. The event fields to display are specified in `$fields`. Example output:\n\n```html\n\u003cul class=\"teaser\"\u003e\n   \u003cli\u003e\u003cstrong\u003e\u003ctime datetime=\"2014-12-14T10:00:00Z\"\u003e14 10:00:00 AM\u003c/time\u003e\u003c/strong\u003e Event\u003c/li\u003e\n\u003c/ul\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmzur%2Fkirby-calendar-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmzur%2Fkirby-calendar-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmzur%2Fkirby-calendar-plugin/lists"}