DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:davcal

davcal Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" yes
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Add a synchronisable Calendar to DokuWiki

Last updated on
2022-08-04
Provides
Syntax
Repository
Source
Requires
sqlite

FIXME Look for new maintainer - Would be nice if someone could take on this plugin and develop it further!
However, any help with a javascript update is welcome!
FIXME

New repository

The original authors repository https://gitlab.aboehler.at/dokuwiki/davcal/ is cloned to https://github.com/dokufreaks/dokuwiki-plugin-davcal

Pull requests are welcome.

DAVCal provides

  • Integration of a graphical calendar
  • Optionally, provides tabular output
  • Synchronisation URL via CalDAV and ICS feed
  • Calendar is automatically shared based on ACL
  • Together with webdavclient, can act as a CalDAV Client

Requirements

  • You need the sqlite PlugIn
  • You need at least PHP 5.4 (required by the underlying DAV library), including the PHP XML module (php-xml1))
  • CalDAV synchronisation requires
    • User accounts, an anonymous synchronisation is impossible
    • An auth plugin which provides password checking

Installation

Make sure that the sqlite PlugIn is installed. PDO SQLite support is required for the CalDAV server to function properly.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Examples/Usage

This plugin enables you to embed a Calendar within a WikiPage. The calendar is rendered using fullcalendar.js and makes use of AJAX/jQuery requests. Thus, it is only reliably rendered within your web browser. You can, however, also display a (read-only) table with events in your calendar. This table doesn't need JavaScript.

To add a simple calendar to a page, use the syntax {{davcal>}}.

Be aware that only one calendar per page is possible. However, you can aggregate multiple calendars into one.

Syntax

There are a few syntax elements that control certain settings of your calendar:

{{davcal>name=Test Calendar,description=My first Wiki Calendar,color=red,view=agendaWeek}}

The key 'name' allows you to specify a name, which will be reflected in the DAV interface, the same is true for the description. You can define the calendar color with the key 'color'.

The default view can be specified using the key 'view'. Valid options are 'agendaDay', 'agendaWeek', 'basicDay', 'basicWeek', 'listDay', 'listWeek', listMonth', 'listYear' and 'month'. If none or an invalid value is given, 'month' will be assumed.

It is also possible to reference one or more existing calendars on a page. This page must not have an own calendar. In this case, the settings 'name' and 'description' have no effect. Instead, you need to specify the ids of the linked pages:

{{davcal>id=calendars:mycalendar:start,id=calendars:othercalendar}}

This displays the calendars of the pages calendars:mycalendar:start and calendars:othercalendar, no matter what the current page is.

You can overrule the 'color' here, but the effect is limited to this instance only. Otherwise, the color information is taken from the linked calendar. Be aware that this setting is cached: If you change the color of the linked calendar, you might need to add ?purge=true to the page including the changed calendar in order to update the color information.

In order to display a table with events, the syntax is slightly different:

{{davcaltable>id=calendars:mycalendar:start,id=calendars:othercalendar,startdate=2015-10-20,numdays=30,dateformat=Y-m-d,calname=true,onlystart=true,sort=asc,timezone=Europe/Vienna,nolocation}}

This creates tabular output and starts from 2015/10/20 (startdate=2015-10-20, this date format is required!), displays up to 30 days (numdays=30), formats the events as Y-m-d (dateformat=Y-m-d) and displays only the column 'At' instead of 'From' and 'To' (onlystart=true). Events are sorted in ascending order (sort=asc) and their time is converted to the timezone 'Europe/Vienna' (timezone=Europe/Vienna). It is also possible to define the date relative to the current date: startdate=today-30 means 30 days ago, startdate=today+1 means tomorrow. If you omit the timezone, 'UTC' is assumed. The field 'Location' is hidden ( nolocation), but the calendar name is displayed (calname=true).

If you want to get all events up to and including today, you can do the following:

{{davcaltable>id=calendars:mycalendar:start,startdate=today+1,numdays=0,startisend=true}}

The following table lists all options for davcal>:

Option Possible Values Description
name Any name you like Give the calendar a sensible name
description Give the calendar a description; will not be displayed
id Any other wiki page Specify the ID of another wiki page to aggregate its calendar here; can be defined multiple times
color Any color definition, either red or green or an HTML code like #3a87ad; can be defined multiple times and always refers to the previous id definition
settings hide/show Specify hide to remove the Settings/Sync link below the calendar
view month, basicDay, basicWeek, agendaWeek, agendaDay, listDay, listWeek, listMonth, listYear Specify the default view of the graphical calendar
forcetimezone Any timezone supported by PHP Force the display of the calendar events in a given timezone, overruling global and user preferences
forcetimeformat lang, 12h, 24h Force the display of the calendar events in a given time format, overriding global and user preferences
fcoptions Anything supported by fullcalendar Pass additional options to the underlying “fullcalendar” widget. Check the fullcalendar documentation for possible options. Example: fcoptions=startTime:15:00:00;scrollTime:16:00:00 starts the weekly view at 3pm and scrolls to 4pm by default. You need a “:” to separate key and value and a “;” to separate the individual options.

The table below lists all options for davcaltable>

Option Possible Values Description
id Any other wiki page Specify the ID of another wiki page to aggregate its calendar here; can be defined multiple times
startdate today, today-#/today+# where # is a number of days or a date of the form Y-m-d Determine the start date of the tabular output, defaults to today
startisend true, on Treat the start date as end date to get events up to or before this date. Defaults to false
numdays any number Display this many days in the tabular output, defaults to 30
dateformat any date() time format Use this date format when creating the tabular output, defaults to Y-m-d H:i
alldayformat any date() time format Use this date format when creating the tabular output for all day events, default o Y-m-d
onlystart true, on Specify this option to show only the column 'At' instead of the columns 'From' and 'To'. Defaults to false
sort asc or desc Sort the events in ascending or descending order (by start date). Defaults to desc
timezone Any timezone supported by PHP Specify the timezone the events should be displayed in. Defaults probably to UTC, depending on your server configuration.
nolocation not specified If specified, the field 'Location' is hidden.
calname true, on Set this to true or on to add a column with the calendar name the event is saved in. The default is false.

Settings

The admin can specify default settings for all calendars (timezone, week numbers, …) in the settings panel. Users can override the settings on a per-user basis by clicking on the link 'Settings/Sync'. The admin can also disable this button in the admin settings.

Nginx usage

Since .ics url are a bit weird, the following hack is required to make them work:

location ~ ^/lib/plugins/davcal/ics.php/(.*)$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param REDIRECT_STATUS 200;
    fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;

    fastcgi_split_path_info ^(.+\.php)(.*)$;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
}

Also, CalDAV requires a similar code block for nginx.

location ~ ^/lib/plugins/davcal/calenderserver.php/(.*)$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param REDIRECT_STATUS 200;
    fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;

    fastcgi_split_path_info ^(.+\.php)(.*)$;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
}

Also, the caret (^) might need to be removed from the location line to get either block to work in some nginx configurations. Also, the path to the PHP FPM sock might need adjusted.

Synchronization (Client Mode)

The plugin webdavclient provides the client synchronisation component for davcal. Add webdavclient to your installation and configure a new connection in the Admin setup. Note the ID of the newly configured connection.

Then, add a calendar with id=webdav://7 to connect to the WebDAV connection number 7. A full call to davcal could look like this:

{{davcal>id=webdav://7}}

This also works with davcaltable, the full davcal option set is supported. If the calendar is set read/write in the WebDAV connection setup, you can even modify and delete events.

Synchronization (Server Mode)

The synchronization backend is provided by SabreDAV. If you click on Settings/Sync below a calendar, a CalDAV URL as well as a Private URL is displayed. Synchronization can be disabled in the admin settings.

CalDAV

The CalDAV URL allows you to synchronize your calendar via CalDAV, but requires authentication. Use your DokuWiki login credentials. This only works on password-based authentication backends (obviously), but provides a convenient two-way sync. The URL is only displayed for logged-in users.

For MacOS/iOS, use the iOS sync URL provided.

The Private URL allows you to subscribe to calendar changes using a public URL, not requiring authentication. This URL is shared for all users who have access to this calendar.

Auto Discovery

This does not work on certain MacOS/iOS versions.
MacOS X 10.6 Snow Leopard does not work
MacOS X 10.11 El Capitan works properly

If you have access to the configuration of your webserver, you can use the auto-discovery feature. In this case, you need to redirect the file .well-known/caldav to your DAVCal installation.

For the following example, let's assume you have DokuWiki installed at http://www.example.com/dokuwiki. Thus, your CalDAV server is at http://www.example.com/dokuwiki/lib/plugins/davcal/calendarserver.php. For autodiscovery to work, you need to omit the remaining parts of the Sync URL, only the path to calendarserver.php is required.

If you have Apache, create the file /.htaccess in the root directory of the web server and add the following line:

Redirect 301 /.well-known/caldav /dokuwiki/lib/plugins/davcal/calendarserver.php

Then you can point your CalDAV sync client to http://www.example.com, provide login credentials and all your accessible calendars should be available.

Auto Discovery (MacOS)

MacOS/iOS, at least certain versions, require the principal URL for auto discovery to work. The clients seem to send requests for .well-known, but do not succeed in getting the calendars.

Instead, use the provided iOS sync URL and paste that into your MacOS/iOS calendar. All calendars you have access to should be automatically discovered and available.

Sharing

By default, the calendar is accessible for synchronization to all users who have at least read rights on the page it is attached to. If the user has only read rights, the calendar is read-only, if the user has more powerful rights, the calendar is also accessible for writing.

Clients

DAVCal is tested with the following CalDAV clients:

  • Thunderbird (recent version, Arch Linux)
  • DAVDroid (recent version, Android 5)
  • Calendar (MacOS X El Capitan)
  • Evolution (Debian)

Deleting/Moving of Calendar

It is currently not possible to entirely delete or move a calendar. However, when the reference to a calendar is deleted via the Syntax option, the calendar is disabled. Synchronization is disabled for this calendar, but the calendar objects are retained. As soon as you restore an old version of the page, the calendar is enabled again and the objects are back.

An admin component for completely deleting calendars is currently WiP.

Language Support

DavCAL currently supports the languages

  • Dutch (nl)
  • English (en)
  • French (fr)
  • German (de and de-informal)
  • Russian (ru)

If you would like to provide translations, don't hesitate to contact me or open a task at https://github.com/dokufreaks/dokuwiki-plugin-davcal.

Limitations

  • The time format in the “Edit Event” dialog is fixed
  • You cannot edit recurring events
  • You cannot move an event from one calendar to another if you display multiple calendars

Tips & Tricks

DAVCal stores all its data in a SQLite database managed by the SQLite plugin. However, sometimes it is handy to understand the database format and to perform operations on the database.

The raw database file can be found in the DokuWiki-folder at data/meta/davcal.sqlite3. It can be edited using a command line tool or the SQLite interface in the DokuWiki admin area.

Listing/deleting calendar objects older than...

It is possible to get a list of all calendar entries older than, in this example 20th September, 2017 at 10AM, using the query: SELECT calendardata FROM calendarobjects WHERE datetime(lastoccurence, 'unixepoch') < '2017-09-20 10:00:00';.

In order to delete the entries, replace the query by DELETE FROM calendarobjects WHERE datetime(lastoccurence, 'unixepoch') < '2017-09-20 10:00:00';. You could even automate this task by creating a cron job.

Development

Change Log

Known Bugs and Issues

ToDo/Wish List

1)
openSUSE users add the packages php5-dom, php5-xmlwriter, php5-xmlreader and php5-mbstring
plugin/davcal.txt · Last modified: 2024-02-08 09:03 by LMS23

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki