Drost-Tenfelde.de

Personal website of Jannes Drost-Tenfelde, resident bass trombone player at Cologne Concert Brass and Brass Band Merum

User Tools

Site Tools


Sidebar

General

Upcoming Events

  • CCB: Open Air
    28 September 2014 10:00-17:00

    Location: Rondorf

Music

Media

IT

Additional

dokuwiki:plugins:icalendar

iCalendar Plugin

This plugin allows you to display events from iCalendar in your website as html. It was initially based on the icalevents plugin by Robert Rackl.

The plugin reads the *.ics file from a URL and parses it into DokuWiki using pre-defined Templates from the configuration.

Added Features

Version 1.4:

  • Added extendable 'showAs' parameter, which allows users to add their own templates.
  • Altered templates to allow DokuWiki Syntax, rather than HTML.
  • Added default, list and table templates.
  • Fixed 'previewDays' issue.
  • Improved behavior of the 'sort' parameter.

Version 1.3:

  • Added parameter 'sort', which allows the entries to be sorted in reverse order.

Version 1.2:

  • Fixed timezones for reoccuring events.

Version 1.1:

  • Optional link to VEVENT, so that other users can add it to their calendar.
  • Event descriptions may now contain DokuWiki syntax.

Version 1.0:

  • Number of preview days is now optional.
  • Dates are now displayed using the local timezone settings of the server.
  • An optional 'to' date can be set to display events up until a cetain date.
  • A maximum number of entries to display can be set.
  • The events can now be displayed in two alternate ways, using a listed format or an extended view format (see configuration_and_settings).
  • Displays re-occuring events.
  • Allow external and internal links in events to link to external or internal pages using the [[ExternalPage]] or [[ExternalPage|Description]] tags. (See Features)
  • Automatically parses contents of an internal page into the event description using the [InternalPage] tag. (See Features)

Instalation

  • Extract the archive into your lib/plugins directory. Make sure the files are put into a directory called iCalendar.
  • Done! You are now ready to use iCalendar.

Examples/Usage

  • {{iCalendar>http://host/myCalendar.ics}} 1)
  • {{iCalendar>http://host/myCalendar.ics#from=today&previewDays=30}} 2)
  • {{iCalEvents>http://host/myCalendar.ics#from=01/01/2011&previewDays=30}} 3)
  • {{iCalendar>http://host/myCalendar.ics#from=today}} 4)
  • {{iCalendar>http://host/myCalendar.ics#to=today}} 5)
  • {{iCalendar>http://host/myCalendar.ics#from=today&numberOfEntries=5}} 6)
  • {{iCalendar>http://host/myCalendar.ics#sort=DESC}} 7)
  • {{iCalendar>http://host/myCalendar.ics#showAs=list}} 8)

Demonstration

Syntax

{{iCalendar>icsUrl#key=value&..&key=value}}
icsUrl the location of the ics file required
key the parameter key to set optional
value the parameter value to set optional

Multiple key=value parameters can be set using the & as a seperator.

Available parameters:

Key Type Comments Requirement Version
from date Date from which the events should be displayed. Format is DD/MM/YYYY. The value 'today' is also valid. optional all
to date Date until which the events should be displayed. Format is DD/MM/YYYY. The value 'today' is also valid. optional all
previewDays number Number of days starting at the from date to display. optional all
numberOfEntries number Number of entries to display optional all
showEndDates onoff Determines if the end date/time should be shown. If an event covers more than one day, the end date is shown by default. Values: 0 for off, 1 for on. Default: 0. optional all
includeLink onoff Adds an iCalendar link to the summary of the event. By opening the link, users may add the complete event to their own calendar. Values: 0 for off, 1 for on. Default: 0 optional Deprecated since version 1.4
showAsList onoff Uses alternate listHTML display formatting if set to 1. Uses the default viewHTML code if set to 0 or not specified optional Deprecated since version 1.4
sort string Default: ASC. If you set this parameter to DESC, the entries will be sorted in reverse order, from highest date downto the lowest. Parameter exists since Version 1.3. optional Version 1.3
showAs string Default: default. Allows the user to display the events using a template defined in the configuration parameters. Currently available: default, list, table. The user can add more templates by editing the default.php and metadata.php files in the conf/ directory. optional Version 1.4

Configuration and Settings

Key Type Comments Requirement Version
dformat date Formatting of the event date (See Format) required all
tformat date Formatting of the event time (See Format) required Version 1.1
listHTML string Template for displaying events as a list. The list view can be enabled using the Syntax parameter 'showAsList'. required Deprecated since Version 1.3
viewHTML string Default template for displaying events. required Deprecated since Version 1.3
default string Default template for displaying events. Previously viewHTML. required Version 1.4
list string Template for displaying events as a listview. Previously listHTML. optional Version 1.4
table string Template for displaying events as a table. optional Version 1.4

Entry templates

Version 1.4 and later

The user may add their own configuration parameters for their entry templates. The appropriate configuration parameter for the template can be set via the syntax parameter showAs.

In order to make a new template, for example one that displays all entries as an unsorted list, the configuration files must be changed as follows:

conf/metadata.php

If you wish to alter your self-created template in the administration panel, you must setup the metadata for this parameter.

Example:

$meta['unsortedlist'] = array('');

conf/default.php

If you wish to set a default setting for the newly created parameter, you can set it up in default.php. This is optional, you can also use the administration panel to setup the configuration parameter.

$conf['unsortedlist'] = '  * {date}: {summary} ';

showAs

Once the configuration parameter has been added, you can use it in the plugin syntax:

{{iCalendar>http://host/myCalendar.ics#showAs=unsortedlist}}

Version 1.3 and before

Using the configuration parameters listHTML and viewHTML alternate HTML templates may be configured to display the events. The templates used for these parameters are plain HTML containing specific tags that will be interpreted by the plugin.

Template tags

The templates, which can be configured in conf/default.php, or via the administraton panel, is parsed using the following tags:

Tag Comments
{summary} Will display the event's title
{summary_link} Will display the event's title, including a link to the according VEVENT, which can be opened to include in your own iCalendar. (Since Version 1.4)
{date} Will display the event date. The date format can be configured in the conf/default.php file
{location} Will display the event location
{location_link} Will display the event location with a link to GoogleMaps
{description} Will display the event description. If the [InternalPage] tag is included in the event description, the contents of the provided InternalPage will be inserted over the tag.

Examples v1.4 and later

default

===== {date}: {summary} =====

**Location**: {location_link}\\\\
{description}

list

====== {date}: {summary} ======
**<sup>Location: {location}</sup>**\\
{description}

Examples v1.3 and before

viewHTML:

<h2>{summary}</h2><p><small><strong>{date}</strong></small><br /><br /><b>Location</b>: {location}<br /><br />{description}


listHTML:

<p><small><b>{date}</b></small><br/><b>{summary}</b><br/>{description}</p>

Development

Change Log

  • 2011-11-14 Version 1.4
    • Added extendable 'showAs' parameter, which allows users to add their own templates.
    • Altered templates to allow DokuWiki Syntax.
    • Added default, list and table templates.
    • Fixed 'previewDays' issue.
    • Improved behavior of the 'sort' parameter.
  • 2011-11-09 Version 1.3
    • Added reverse sorting of entries
  • 2011-11-06 Version 1.2
    • Minor bugfixes
    • Timezone fix for reoccuring events.
  • 2011-10-09 Hotfix
    • Added hotfix, since p_render was called without the third parameter, which gave warnings. Should be fixed now.
  • 2011-10-04 Version 1.1
    • Minor bugfixes
    • Event descriptions can now contain DokuWiki syntax, for Example [[URL|Description]].
    • Added 'includeLink' syntax parameter, which adds a link to the summary with the original VEVENT. By clicking the link, users are able to add the event to their own .ics calendar.
    • Added 'tformat' configuration parameter, where the time format can be configured.
  • 2011-09-29 Version 1.0
    • Initial release

Known Bugs and Issues

  • When there is an url in the calendar event, the plugin renders it wrong. Sometimes it converts the slashes after http: to italic slashes. So the url is wrong and everything after http: is italic. The strange thing is, that this doesnt happen with every url.
    • If you wish to use URL's in your calendar event, please use the DokuWiki Syntax [[URL]]. I use standard DokuWiki functionality to turn the event description into HTML. The Syntax // is used for Italic by DokuWiki, so that could be the cause of the problem. Good luck! JDT
      • This works great thanks for the tip.
  • Maybe I found another bug: when I set a repeating event in Google Calendar, the plugin shows the time incorrect by 1 hour. When i set a normal event, the time is allright.
    • Thanks. Ok, I have found the timezone error, it seems that the DTSTART and DTEND times for repeating events have a different timezone than the normal events. I have now added the support for the TZID elements within DTSTART and DTEND which defines those individual timezones. I released Version 1.2 to this end, since many people currently use Version 1.1 and timezones are always a bit fiddly. I will look into reoccurring events more in the upcoming days, since the plugin currently only regards individual VEVENTs, but does not regard a single VEVENT being used for multiple events.JDT

ToDo/Wish List

  • Support for reoccurring events.JDT

FAQ

  • Why did you make a new plugin, rather than adjust the existing icalevents plugin ?
    • Well, initially, I thought it would be best to change the existing plugin to fix a few bus here and there, but as I got along, I found more and more things I wanted in the plugin, such as dynamically being able to adjust the presentation and adding new parameters. Whilst the icalevents plugin covers my basic needs, which is loading *.ics files and turning them into HTML, I did not want to start making loads of patches to the existing plugin, but rather have the option of altering the complete functionality.

Discussion

Implemented in Version 1.3

  1. Thanks for your work. Would it be possible to add an option to display the latest calendar entry on top and the oldest one at the bottom?
    • Hi there. I have added a new parameter 'sort' in Version 1.3, which you can set to DESC to sort in reverse order. I hope meets your requirement. JDT
      • Perfect, thank you very much.

Implemented in Version 1.4

  1. 'previewDays' is not working for me. Using this command: {{iCalendar>http://obfuscated.my/icalfile#from=today&previewDays=30&showAsList=1}} I get all events from today through next year(Dec 2012). This is a calendar of holidays, so all events are 'all day events' (in case that's relevant). The calendar is stored in a Kerio Connect mail server. -MJM
  2. I'd love to be able to display the output in a table, or using multiple options - perhaps by expanding 'showAsList' into a generic 'showAs' directive: &showAs=table, &showAs=list, &showAs=day &showAs=week, &showAs=month, &showAs=year (or &showAs=planner, or &showAs=gantt). -MJM
  3. I'd like to be able to specify wiki formatting as well as HTML in the template configurations, eg | {date} | {location} | {summary} (({description})) | (with the objective being to show a table with date, location and summary, with the description included as a footnote/mouse tip). -MJM
    • This has now been implemented in Version 1.4. You can now use DokuWiki syntax for your templates. If you wish to use HTML, you can use the
      <html></html>

      tags. JDT

Files

Here is a list of the files currently used in the plugin.

Source Code
syntax.php Contains the main plugin code
vevent.php Code to download an event as .ics file
functions.php Support functionality
Support
plugin.info.txt Plugin information
Configuration
conf/metadata.php Metadata settings
conf/default.php Default settings
Language
lang/en/lang.php English language file

Demonstration

1) Displays all events in the calendar
2) Displays all events in the calendar as of today until 30 days in the future
3) Displays all events in the calendar as of 01/01/2011 until 31/01/2001
4) Displays all events as of today
5) Displays all events until today
6) Displays the next 5 events after today
7) Sorts the events from newest date to oldest date
8) Shows the events using the configuration parameter 'list'
dokuwiki/plugins/icalendar.txt · Last modified: 2013/01/22 22:40 (external edit)

Page Tools