Introduction

If you want to integrate your external calendar system into DPCalendar, then you have to write a plugin for the dpcalendar group. A good starting point for a DPCalendar plugin is the hello world example on Github plugin. Basically we fire the three events which are described below to gather the event data. It is recommended to inherit your plugin class from the DPCalendarPlugin class.

If you are new to Joomla plugin development, consider to read the DPCalendar joomla events article.

DPCalendarPlugin class

The DPCalendarPlugin class (located at /administrator/components/com_dpcalendar/libraries/dpcalendar/DPCalendar/Plugin/DPCalendarPlugin.php) provides some convenient helper functions to integrate your calendar data easily into DPCalendar. It comes out of the box with caching support and id management. It is highly recommended to extend your plugin class from the DPCalendar plugin.

The main function is getContent() where you can return an Ical string. Everything else will be managed then by the base plugin class.

Events

onCalendarsFetch

Description
Event to fetch additional calendars. It is recommended to extend DPCalendarPlugin and implement the abstract function fetchCalendars.

Parameters

1. calendarId (optional)
   If only a single calendar should be fetched.

Return value
An array containing calendars (see DPCalendarPlugin::createCalendar).

onEventsFetch

Description
Fetches a list of events. It is recommended to extend DPCalendarPlugin and implement the abstract function fetchEvents.

Parameters

1. calendarId The calendar where the events should come from.
2. startDate
   The start date of the date range where the events should be. A Date object is given.
3. endDate
   The end date of the date range where the events should be. A Date object is given.
4. options
   A JRegistry object to get some additional parameters.

Return value
An array containing events (see DPCalendarPlugin::createEvent).

onEventFetch

Description
Fetches a single event. It is recommended to extend DPCalendarPlugin and implement the abstract function fetchEvent.

Parameters

1. eventId The event ID.

Return value
A single event (see DPCalendarPlugin::createEvent).

onEventsSync

Description
When events are synced for database caching.

Parameters

1. plugin The plugin to sync.
2. calendarIds The calendars ids to sync.

Return value
Nothing.

onEventSave

Description
When an external event is saved. Is primarily used fo the specific event plugin to save it's own event.

Parameters

1. data The event data to save.

Return value
The new event id.

onEventDelete

Description
When an external event is deleted. Is primarily used fo the specific event plugin to delete it's own event.

Parameters

1. id The event id to delete.

Return value
Nothing.

onCalendarAfterDelete

Description
When an external calendar is deleted.

Parameters

1. calendar The calendar instance.

Return value
Nothing.

onDPCalendarDoAction

Description
Triggered from a callback url. Can be used for example on OAuth token fetch, when a redirect is performed to the provider site for proper authntication.

Parameters

1. action The action which is performed.
2. plugin The plugin name.

Return value
Nothing.

Example

We have a Github repository with a simple hello world example. You can download from there the install able file under the release section or clone the repository. A DPCalendar plugin must have a manifest XML and a PHP file, optional is a language folder which contains the translation files. The structure of the installed zip file must be

plg_dpcalendar_helloworld
--- helloworld.xml
--- helloworld.php
--- index.html
--- language
--- ---- en-GB
--- ---- ---- en-GB.plg_dpcalendar_helloworld.ini
--- ---- ---- en-GB.plg_dpcalendar_helloworld.sys.ini

Manifest (dpcalendar_helloworld.xml) The manifest file describes the plugin and delivers Joomla the necessary information during installation. An example is shown below.

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.9" type="plugin" group="dpcalendar" method="upgrade">
    <name>plg_dpcalendar_helloworld</name>
    <author>Digital Peak</author>
    <creationDate>Aug 2018</creationDate>
    <copyright>(C) 2018 Digital Peak GmbH. <https://www.digital-peak.com>
    </copyright>
    <license>https://www.gnu.org/licenses/gpl-3.0.html GNU/GPL</license>
    <authorEmail>info@digital-peak.com</authorEmail>
    <authorUrl>joomla.digital-peak.com</authorUrl>
    <version>7.0.0</version>
    <description>PLG_DPCALENDAR_HELLOWORLD_XML_DESCRIPTION</description>
    <files>
        <filename plugin="helloworld">helloworld.php</filename>
        <folder>language</folder>
    </files>
    <config>
        <fields name="params"
                addfieldpath="/administrator/components/com_dpcalendar/models/fields">
            <fieldset name="basic">
                <field name="ext" type="extcalendar" plugin="helloworld" label="" description=""/>
            </fieldset>
            <fieldset name="advanced">
                <fieldset name="advanced">
                    <field name="cache" type="list" default="1"
                           label="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_LABEL" description="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_DESC">
                        <option value="1">PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_JOOMLA</option>
                        <option value="2">PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_DB</option>
                        <option value="0">PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_NEVER</option>
                    </field>
                    <field name="cache_time" type="text" default="900" showon="cache:1"
                           label="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_TIME_LABEL"
                           description="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_TIME_DESC"/>
                    <field name="sync_start" type="text" default="-3 year" showon="cache:2"
                           label="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_SYNC_START_LABEL"
                           description="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_SYNC_START_DESC"/>
                    <field name="sync_end" type="text" default="+3 year" showon="cache:2"
                           label="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_SYNC_END_LABEL"
                           description="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_SYNC_END_DESC"/>
                    <field name="sync_steps" type="text" default="1 year" showon="cache:2"
                           label="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_SYNC_STEPS_LABEL"
                           description="PLG_DPCALENDAR_HELLOWORLD_FIELD_CACHING_SYNC_STEPS_DESC"/>
                </fieldset>
            </fieldset>
        </fields>
    </config>
</extension>

The file /administrator/components/com_dpcalendar/libraries/dpcalendar/DPCalendar/Plugin/DPCalendarPlugin.php can be used as base class to create the PHP file. Here is an example how it is recommended to implement a DPCalendar plugin.

<?php
/**
 * @package    DPCalendar
 * @copyright  Copyright (C) 2018 Digital Peak GmbH. <https://www.digital-peak.com>
 * @license    https://www.gnu.org/licenses/gpl-3.0.html GNU/GPL
 */defined('_JEXEC') or die();use Joomla\CMS\Date\Date;
use Joomla\Registry\Registry;class PlgDPCalendarHelloworld extends \DPCalendar\Plugin\DPCalendarPlugin
{    protected $identifier = 'hw';    protected function getContent ($calendarId, Date $startDate = null, Date $endDate = null, Registry $options)
    {
        $start = DPCalendarHelper::getDate();
        $start->modify('+1 day');        $end = clone $start;
        $end->modify('+2 hour');        $buffer = "BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//DPCalendar
BEGIN:VEVENT
UID:sdfsf8erhklf89zrjklh890hoih89
DTSTAMP:20140714T170000Z
ORGANIZER;CN=John Doe:MAILTO:john.doe@example.com
DTSTART:" . $start->format('Ymd\THis\Z') . "
DTEND:" . $end->format('Ymd\THis\Z') . "
SUMMARY:Demo Hello world event
DESCRIPTION:This is a demo event in the hello world DPCalendar plugin.
LOCATION:New York
END:VEVENT
END:VCALENDAR";
        return $buffer;
    }
}