Differences

This shows you the differences between two versions of the page.

--- plugin:calendoku [2015-06-29 14:20] – 138.246.2.185
+++ plugin:calendoku [2023-03-07 02:51] (current) – 165.231.67.56
@@ Line 7: / Line 7: @@
 type       : Syntax
 lastupdate : 2014-11-05
-compatible : Hrun, Ponder Stibbons
+compatible : Elenor Of Tsort, Detritus, Hrun, Ponder Stibbons, !Igor
 depends    : bureaucracy
 conflicts  :
-similar    : gcalendar, icalendar, hcalendar, wikicalendar
+similar    : gcalendar, hcalendar, icalendar, wikicalendar
 tags       : calendar, date, ical, icalendar
@@ Line 28: / Line 28: @@
 :!: **External requirements:** This plugin requires the following additional components that must be installed separately:
-  * [[plugin:bureaucracy|bureaucracy plugin]] if you want to enter calendar entries directly.
+  * [[plugin:bureaucracy|Bureaucracy plugin]] if you want to enter calendar entries directly.
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.
+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
 Note that you need at least PHP 5.3.0 to use calendoku!
@@ Line 36: / Line 36: @@
 ===== Examples/Usage =====
-See the plugin in action on the [[https://www.komkon2.de/dokuwiki/doku.php?id=calendar:overview|events calendar]] of my page. The according pages on my site are ''calendar:template'', ''calendar:inputtemplate'' and ''calendar:newform''. In the [[#Walkthrough|Walkthrough section]], a complete guide on how to setup an example calendar is given.
+See the plugin in action on the [[https://www.tolledomain.ch/dokuwiki/doku.php?id=calendar:overview|events calendar]]  of my page FIXME. The according pages on my site are ''calendar:template'', ''calendar:inputtemplate'' and ''calendar:newform''. In the [[#Walkthrough|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.
@@ Line 42: / Line 42: @@
 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|Templating]] for how to use the templates.
+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|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 [[plugin:bureaucracy|bureaucracy plugin]] to handle that. A good form for that is given in [[#Bureaucracy Forms|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.
+The last important part about calendoku is the input. Since icalendar is unbearable to write directly, you should setup a form with the [[plugin:bureaucracy|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 =====
@@ Line 52: / Line 52: @@
 To setup a working calendar with entry form, do the following:
-   - Install the calendoku plugin
+   - Install the Calendoku Plugin
-   - Install the [[plugin:bureaucracy|bureaucracy plugin]]
+   - Install the [[plugin:bureaucracy|Bureaucracy plugin]]
    - [[#Configuration and Settings|Configure]] the namespaces. We use ''calendar'' as the namespace.
    - Configure the templates. We will use ''calendar:template'' for this.
@@ Line 64: / Line 64: @@
 ===== Templating =====
-To display a single calendar entry inside one of the designated namespaces, you have to use a template. Once specified (see [[#Configuration and Settings|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.
+To display a single calendar entry inside one of the designated namespaces, you have to use a template. Once specified (see [[#Configuration and Settings|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.
+On this page, you can also use ''%%@@DOKUWIKIICAL@@%%'' to link to the direct ical representation of the current page with a ''.ics'' ending.
 <code>
@@ Line 79: / Line 79: @@
 URL: @@URL@@
 </code>
 This is an easy example which will plainly show everything.
 You can also make more sophisticated templates, e.g.:
 <code>
 ===== [[@@URL@@|@@SUMMARRY@@]] =====
@@ Line 92: / Line 94: @@
 ===== Calendar Overviews =====
-To create an overview of the calendar files in one namespace, you have to use the
+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 ''%% %%''.
-<code>
-{{calendoku}}
-</code>
-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**'' |
+| 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'' |
@@ Line 150: / Line 148: @@
 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 [[devel:caching]].
+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 [[devel:caching]].
 ===== Bureaucracy Forms =====
-To have a nice form for entering new events, the [[plugin:bureaucracy|bureaucracy plugin]] is used. For using it properly, we need two things:
+To have a nice form for entering new events, the [[plugin:bureaucracy|Bureaucracy plugin]] is used. For using it properly, we need two things:
   * the form for entering the events
@@ Line 163: / Line 161: @@
 The form for entering the events could e.g. be:
-<code php bureaucracytemplate>
+<code php bureaucracytemplate.txt>
 <form>
 action template calendar:inputtemplate calendar: _
@@ Line 192: / Line 190: @@
 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 [[plugin:bureaucracy|bureaucracy plugin page]] for more information about how to setup forms.
+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 [[plugin:bureaucracy|Bureaucracy plugin page]] for more information about how to setup forms.
 ==== Templating the Forms ====
@@ Line 239: / Line 237: @@
 END:VCALENDAR
 </code>
 ===== Configuration and Settings =====
@@ Line 247: / Line 244: @@
   * 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 [[http://php.net/manual/en/function.date.php|PHP reference page]].
+  * the ''datetimeformat'' is the string used for displaying date/time combinations. You can see a reference on the [[phpfn>function.date|PHP reference page]].
-  * the ''dateformat'' is the string used for displaying dates. You can see a reference on the [[http://php.net/manual/en/function.date.php|PHP reference page]].
+  * the ''dateformat'' is the string used for displaying dates. You can see a reference on the [[phpfn>function.date|PHP reference page]].
-  * the ''timeformat'' is the string used for displaying times. You can see a reference on the [[http://php.net/manual/en/function.date.php|PHP reference page]].
+  * the ''timeformat'' is the string used for displaying times. You can see a reference on the [[phpfn>function.date|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 [[http://de1.php.net/manual/en/timezones.php|here]].
+  * the ''defaulttimezone'' option defines the standard timezone. Find a list of supported timezones [[http://www.php.net/manual/en/timezones.php|here]].
 ===== Development =====
@@ Line 288: / Line 285: @@
   * 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 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.
-I hope that might help somebody else.
+==== Date/Time bug and double substitution workaround ====
+Also I can confirm the trouble, and found the following workarounds:
+<code text termine>
+{{calendoku>
+  NAMESPACE=calendar>
+  FIELDDESCS=Start **Titel**>
+  FIELDS=@@DTSTART@@ @@SUMMARY@@>
+  START=0>
+}}
+</code>
+<code php newpage>
+<form>
+action template calendar:inputtemplate calendar: _
+fieldset "Termin"
+date "Startdate" @
+time "Starttime" @
+textbox "Summary" @
+textbox "Location" !
+textarea "Description" !
+submit
+</form>
+</code>
+<code text inputtemplate>
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:DokuWiki/calendoku//blub
+BEGIN:VEVENT
+CREATED:%Y%m%dT%H%M%S
+DTSTAMP:20170906T194907
+LAST-MODIFIED:20170906T194907
+DTSTART:@DATE(##Startdate## ##Starttime##,%%Y%%m%%dT%%H%%M%%S)@
+SUMMARY:##Summary##
+LOCATION:##Location|-##
+DESCRIPTION:##Description|-##
+END:VEVENT
+END:VCALENDAR
+</code>
+<code text template>
+**Start:** @@DTSTART@@\\
+**Titel:** @@SUMMARY@@\\
+**Ort:** @@LOCATION@@\\
+**Description:**\\
+@@DESCRIPTION@@
+</code>
+**Details**:
+See [[plugin:bureaucracy|Bureaucracy Plugin]] "Creating Templates":
+As placeholder, marker ''##'' can be used instead of ''@@''. This does not have the double expansion problem and replacing with ''@@@@@@'' or ''@@@@'' on every edit is superflous.
+Conversion of the date/time values can be specified with double escaped strftime format tags, ''@DATE(<datetime>,%%x)@''
+If the placeholder has a ''|'', the subsequent part is the default value if none was entered, instead of leaving the placeholder name. This is in particular important for ''DTEND'' to keep period calculations working.
+See [[plugin:bureaucracy|Bureaucracy Plugin]] "Fields", "Constraints and Defaults":
+There is also a ''time'' datatype allowing ''HH:MM:SS'', seconds part and leading 0 optional.
+trailing ''!'' makes the value optional, trailing ''@'' makes the value part of the filename if present, trailing ''='' allows to provide a default value, also number constraints possible.
+**Bug description**:
+Actually there is a double bug.
+This is independent of using the ''time'' datatype, or composing hour/minute/second by individual ''number'' values.
+[[plugin:bureaucracy|Bureaucracy Plugin]] somehow combines adjacent date time values ''YYYY/mm/dd HH:MM:SS'' to a single ''YYYYmmDDTHHMMSS'' value, but with non 0 hour/minute/second having three digits, while [[plugin:calendoku|Calendoku Plugin]] correctly assumes two digits and parses only the leading 6 time digits, which leads to a wrong time.
+On alternatively using ''YYYY/mm/dd HH:MM'' the values are left as is, but then [[plugin:calendoku|Calendoku Plugin]] parses the format wrongly, in particular subtracting an offset from the year.
+Helmut 2017/09/07
+==== Suggestions ====
+  - Any chance of having icons or differential formatting based on some category variable at some point in the future?
+  - 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.
-Any chance of having icons or differential formatting based on some category variable at some point in the future?
-----
-When using bureaucracy plugin, the date is usually given as yyyy-mm-dd and time as hh:mm. However, ics standard is something like yyyymmddThhmm. I had to change a bit of the bureaucracy code to make it work. Otherwise date and time can get very strange and differ quite a bit. Maybe you you should adapt your ical parser to include those expressions.