DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:calendoku

calendoku Plugin

Compatible with DokuWiki

  • 2017-02-19 "Frusterick Manners" unknown
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes

plugin Integrates a calendar to DokuWiki

Last updated on
2014-11-05
Provides
Syntax
Repository
Source
Requires
bureaucracy

IMPORTANT

:!: Calendoku is still considered a beta or late alpha. Bugs are probable, and it will have very rough edges. Do not install it on production machines unless you already tested that it works! :!:

Installation

:!: External requirements: This plugin requires the following additional components that must be installed separately:

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Note that you need at least PHP 5.3.0 to use calendoku!

Examples/Usage

See the plugin in action on the events calendar of my page. The according pages on my site are calendar:template, calendar:inputtemplate and calendar:newform. In the Walkthrough section, a complete guide on how to setup an example calendar is given.

In calendoku, much of the work is based on namespaces. A “calendar” for calendoku is simply a namespace which (also) has icalendar pages in it. On my page, this is the “calendar:” namespace.

In this namespace, you just insert the icalendar files directly as the pages. It is important that the pages start and end exactly with the icalendar content, i.e. no trailing newlines or spaces!

You have to configure a template which is used for rendering icalendar files. Otherwise, the user would just see bare icalendar, which is not really readable. Then, for every namespace you configured to be handled by calendoku, if calendoku finds an icalendar page, it will attempt to render it and replace it with the template. See Templating for how to use the templates.

You can also create overviews of the calendars. For this, the calendoku command is used. With that, you can define the fields of the calendar that shall be shown. See Calendar Overviews on how that is done.

The last important part about calendoku is the input. Since icalendar is unbearable to write directly, you should setup a form with the Bureaucracy plugin to handle that. A good form for that is given in Bureaucracy Forms. Note that this is not strictly necessary, but nonetheless recommended. You could also have a calendar where you only insert the ical files you get from somewhere else.

Walk-Through

To setup a working calendar with entry form, do the following:

  1. Install the Calendoku Plugin
  2. Install the Bureaucracy plugin
  3. Configure the namespaces. We use calendar as the namespace.
  4. Configure the templates. We will use calendar:template for this.
  5. Add a template. Take one from Templating and save it as calendar:template.
  6. Add an input template. Take the one from Entering Events and save it as calendar:inputtemplate.
  7. Add an input form. Just take the code from Templating the Forms and save it as calendar:newpage.
  8. Add an overview. Take one example from Calendar Overviews and save it as calendar:overview.
  9. Enter events through the page calendar:newpage. Then, refresh the overview (unfortunately, this is still required), e.g. open it, change one character, and save it again.

Templating

To display a single calendar entry inside one of the designated namespaces, you have to use a template. Once specified (see Configuration), you write a normal DokuWiki page which contains placeholders which are replaced by the fields from an entry. As a placeholder, you just take the name of the icalendar field and surround it by @@, e.g. @@DTSTART@@ to set the start value.

On this page, you can also use @@DOKUWIKIICAL@@ to link to the direct ical representation of the current page with a .ics ending.

Title: @@SUMMARY@@

From: @@DTSTART@@

Till: @@DTEND@@

Description: @@DESCRIPTION@@

URL: @@URL@@

This is an easy example which will plainly show everything.

You can also make more sophisticated templates, e.g.:

===== [[@@URL@@|@@SUMMARRY@@]] =====

From @@DTSTART@@ to @@DTEND@@ at @@LOCATION@@.

@@DESCRIPTION@@

Calendar Overviews

To create an overview of the calendar files in one namespace, you have to use the {{calendoku}} command. You have to specify attributes to actually make it useful. Attributes are separated by > signs, and the attributes are separated from its values by = signs, and for lists of values, they are separated by spaces. To write a space inside a field which allows more than one value, escape it by a backslash, i.e., write \ instead of .

The following attributes are available:

Attribute Meaning Example
NAMESPACE Specifies the namespaces in which to search for calendar entries. NAMESPACE=calendar
FIELDS Specifies the fields to show. They can also be formatted to format all entries of the table. For FIELDS, there is still a replacing going on, and the fields are enclosed by @@. This way, you can also define links inside fields. One special term to use is DOKUWIKILINK, which will link the DokuWiki page the event is described on, the other special term is DOKUWIKIICAL, which will link directly to the .ics download of the DokuWiki page. FIELDS=DTSTART DTEND SUMMARY
FIELDDESCS Specifies the table headers for the fields, in the same order. Formatting can also be applied. FIELDDESCS=Start Ende Titel
START Specifies the start of the calendar. If you enter CURRENT, then no events ending earlier than the current date are displayed. If you enter 0, then all events are displayed. Otherwise, use the usual Y-m-d H:i format, though more are possible (for those interested, see the function guessDateTime() in calendoku/helper.php). START=2014-09-04 15:43
END Specifies the end of the calendar. If you enter CURRENT, then only events ending earlier than the current date are displayed. If you enter 0, then all events are displayed (i.e. END is infinity). Otherwise, use the usual Y-m-d H:i format, though more are possible (for those interested, see the function guessDateTime() in calendoku/helper.php). END=2020-01-01

Examples:

{{calendoku>
  NAMESPACE=calendar>
  FIELDS=@@DTSTART@@ @@DTEND@@ @@SUMMARY@@
  FIELDDESCS=Start Ende **Titel**
  START=0>
  END=CURRENT>
}}

This example will show all entries from the calendar namespace which were up to now. This is a good example to make an archive of events.

{{calendoku>
  NAMESPACE=calendar>
  FIELDS=@@DTSTART@@ @@DTEND@@ [[@@DOKUWIKILINK@@|@@SUMMARY@@]] [[@@URL@@|external]]
  FIELDDESCS=Start Ende **Titel** Extern
}}

This example will show all entries from the calendar namespace. The title will always be linked to the actual DokuWiki page, while the “external” field will link to the given URL.

{{calendoku>
  NAMESPACE=calendar>
  FIELDS=DTSTART DTEND SUMMARY
  FIELDDESCS=Start Ende **Titel**
  START=2010-01-01>
  END=2015-01-01>
}}

This example will show all entries which were in the years 2010-2014.

:!: Note that the overview will be cached, and it should be. Collecting the calendar takes a lot of resources, and you should do it only when required. If you added a new event, you should call the overview page with

&purge=true

or

?purge=true

attached, so the page cache will be flushed. E.g., flushing the cache for a site http://example.org/calendar would be http://example.org/calendar?purge=true or for http://example.org/doku.php?id=calendar&purge=true, as described in caching.

Bureaucracy Forms

To have a nice form for entering new events, the Bureaucracy plugin is used. For using it properly, we need two things:

  • the form for entering the events
  • the template for making those data an icalendar files

Entering Events

The form for entering the events could e.g. be:

bureaucracytemplate.txt
<form>
action template calendar:inputtemplate calendar: _
 
fieldset
 
textbox "Summary" @
textbox "Location"
textbox "URL"
textbox "Comment"
textarea "Description"
 
fieldset "Start date"
date "Start date" @
select "Start hour" "-|0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23" @
select "Start minute" "-|0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59" @
 
fieldset "End date"
date "End date" @
select "End hour" "-|0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23" @
select "End minute" "-|0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59" @
 
fieldset
submit
</form>

This will create a form which enables you to enter an event happening somewhere, along with a description, a summary, beginning and end. If the minute or hour of an date is set to “-”, then these fields will not be used at all and the date will have a DATE value (i.e., in future, no time is shown for them).

As a template, calendar:inputtemplate is taken, and new events will be created with the summary, the start date and the end date in their name. See the Bureaucracy plugin page for more information about how to setup forms.

Templating the Forms

The second part is the input template for the bureaucracy form. It includes the primary information which is also contained in the form.

inputtemplate
BEGIN:VCALENDAR
VERSION:2.0
PRODID:DokuWiki/calendoku//blub
BEGIN:VEVENT
CREATED:%Y%m%dT%H%M%S
DTSTAMP:
LAST-MODIFIED:
DTSTART:@@@@@@Start date@@@@ @@@@Start hour@@@@:@@@@Start minute@@@@@@
DTEND:@@@@@@End date@@@@ @@@@End hour@@@@:@@@@End minute@@@@@@
SUMMARY:@@@@@@Summary@@@@@@
DESCRIPTION:@@@@@@Description@@@@@@
URL:@@@@@@URL@@@@@@
COMMENT:@@@@@@Comment@@@@@@
END:VEVENT
END:VCALENDAR

Note that this template must already be an icalendar file. The reparsing of calendoku to make the form a real icalendar file also uses @@ to denote the fields which shall be reparsed. This means that for every parsed file, you have to insert four @ signs. In case of dates where several entries from the form are entered, you have to write the @ for calendoku only in the beginning and end of the line, but for the tags used for bureaucracy, you have to enter them as well. Look at the DTSTART line for an example.

Further, note that since calendoku won't know anything about the input templates used by some bureaucracy forms, it will render this page already. Thus, where you have four @ signs, you have to insert six if you have the input template in a namespace declared as a calendar, such that it is rendered to four @ signs. The above input template already contains the right number of @s.

This means, if you put your template outside the calendar namespace, you would need this template here:

inputtemplate
BEGIN:VCALENDAR
VERSION:2.0
PRODID:DokuWiki/calendoku//blub
BEGIN:VEVENT
CREATED:%Y%m%dT%H%M%S
DTSTAMP:
LAST-MODIFIED:
DTSTART:@@@@Start date@@ @@Start hour@@:@@Start minute@@@@
DTEND:@@@@End date@@ @@End hour@@:@@End minute@@@@
SUMMARY:@@@@Summary@@@@
DESCRIPTION:@@@@Description@@@@
URL:@@@@URL@@@@
COMMENT:@@@@Comment@@@@
END:VEVENT
END:VCALENDAR

Configuration and Settings

There are seven configuration options which are crucial for calendoku:

  • the icaltemplates option defines the space-separated templates which are used for showing the entries. You can define either a global one (without a namespace) or single ones which are used for the namespaces they are in. E.g., template calendar:template would use the page calendar:template for all pages in the calendar namespace, but for all others the template page.
  • the icalnamespaces option defines the space-separated namespaces which are considered for calendar entries. Entries outside these namespaces are not rendered, but rather just given out as plain text.
  • the datetimeformat is the string used for displaying date/time combinations. You can see a reference on the PHP reference page.
  • the dateformat is the string used for displaying dates. You can see a reference on the PHP reference page.
  • the timeformat is the string used for displaying times. You can see a reference on the PHP reference page.
  • the showlocaltime decides whether you want to treat timezones or not. If this option is not set, then all timezone additions are ignored, and every date is considered to be the local one. If it is set, you *must* also set the defaulttimezone option or leave it empty!
  • the defaulttimezone option defines the standard timezone. Find a list of supported timezones here.

Development

Change Log

You can find the whole release history on the plugin website.

Last update: 2014-11-05: Fifth release a. Fix some major bugs for timezone handling.

Known Bugs and Issues

There is a bug tracker online. Please note you have to log in anonymous (go to Login page, click �~@~\Fill out captcha�~@~]) before you can commit bugs. Also, you can write me an e-mail and I will enter the bug to the bug tracker.

FIXME Pictures should be added so you know what is happening.

ToDo/Wish List

In the end, I want to have a fully-fledged calendar. Of course some things are not possible with DokuWiki, but this is less than you might think.

So, what I want to implement at some point:

  • Render more components in a sensible way. Currently, only VEVENT is handled.
  • Add more calendar views. Currently, only a vertical table is handled. Views I want to have:
    • a short overview which just shows the summary in a box and has a nice JS so when you hover it, you see more details
    • the usual seven-column calendar view you usually have for calendars
    • a horizontal table
  • be able to use the CLASSes and CATEGORYes of ical, e.g., group entries by them in the overview
  • have a repository of nice templates and plugin:bureaucracy forms to use.

FAQ

Discussion

Took me a while to get working, but I seem to be there now. Nice. I think some things in the walkthrough section are not quite right.

  • Not all attributes in the overview examples end with >
  • I struggled to get the right number of @s in the input template. In the end I moved this into another namespace.
  • I was struggling to get the dates and times to show correctly. Modified my input template to create YYYYMMDDTHHMMSS date-times, and configured calendoku to write date-time as I wanted and to write date as YYYYMMDD (so that I got that date-time structure.
    I hope that might help somebody else.

Suggestions

  1. Any chance of having icons or differential formatting based on some category variable at some point in the future?
  2. Is it possible to supply a tool to parse a multi-event ical (*.ics) file for adding to a calendoku calendar? For example, I have calendars from elsewhere (football fixtures, work appointments) that I'd like to include. This would also work well with a category label/formatting.
plugin/calendoku.txt · Last modified: 2017-01-23 23:22 by 77.109.185.27