mka_ical – Help

Display ical calendars as event lists

mka_ical is a Textpattern plugin for displaying events from an iCal URL (e.g. Google Calendar) or ics file using a standard or user-definable template.

It’s also possible to specify a folder or a Textpattern category for images referenced in the feed. The image is drawn from the title of the event and the name of the image.

Tags

Tag: mka_ical

Inserts a public calendar from an ics url or file, or a googlemail account. Can be used as a standalone or as a container tag.

The following attributes are available:

url (string, default: "", required)
Url of the ICS file

googlemail
GoogleMail address. The user’s public google calendar will automatically be referenced.

limit (int, default: 0, optional)
Defines how many events are shown. Defaults to 0 (= all)

pastevents (boolean, default: FALSE, optional)
Display past events

html_id (string, default: icalevents, optional)
Sets the html id for the event list

class
Sets the CSS class for the event list

details (boolean, default: TRUE, optional)
Display the details

cachingtime (int, default: 30 (minutes), optional)
Duration that local cache file persists

form (string, default: none, optional)
Name of txp form to use to format each event item

fmttime (string, default: %H:%M, optional)
Format string for the time

fmtdate (string, default: %d.%m.%Y, optional)
Format string for the date

img (boolean, default: FALSE)
Display an image for each date (requires following attributes)

imgfolder (string, default: images, optional)
Image folder

defaultimg (string, default: none.gif, optional)
Default image

Tag: mka_if_first_event

Use as a container tag. The tag will execute the contained statements if the displayed event is the first in the currently displayed calendar.

Tag: mka_if_last_event

Use as a container tag. The tag will execute the contained statements if the displayed event is the last in the currently displayed calendar.

Tag: mka_if_different

Use as a container tag. The tag will execute the contained statements when the value of the contained statement differs from the preceding value for that contained statement.

If additionally processing the {placeholder} values, e.g. with mka_format_date, set the key attribute to a name of your choosing. See Example 4.

Attribute:

key (string, default: empty, optional)
A name for your if_different instance.

Tag: mka_format_date

Use as a container tag around an existing date, time or datetime placeholder. The tag will reformat the date or time output according to a specified format.

Attribute:

format (date parameter, default: empty)
Use the date formatting parameters of strftime to define the date and/or time format.

Note: The fmtdate and fmttime attributes of mka_ical control how the placeholders {start_date}, {end_date} and {start_time} and {endtime} are formatted for the entire calendar. This tag allows you to override the date or time format.

Placeholder variables

; {date}
: Date (format according to “fmtdate” and “fmttime” attributes)
; {start_datetime}
: Start datetime in %Y-%m-%d %H:%M format
; {start_date}
: Start date (format according to “fmtdate” attribute)
; {start_time}
: Start time (format according to “fmttime” attribute)
; {end_datetime}
: End datetime in %Y-%m-%d %H:%M format
; {end_date}
: End date (format according to “fmtdate” attribute)
; {end_time}
: End time (format according to “fmttime” attribute)
; {duration}
: Duration (formatted as days:hours:minutes:seconds)
; {title}
: Title (ics summary entry)
; {description}
: Description
; {location}
: Location/venue
; {uid}
: Event unique ID
; {imagesrc}
: Link to image
; {imageid}
: ID# of image (when using images from categories)

Examples

Example 1 (using a public Google Calendar)

<txp:mka_ical googlemail="YOURADDRESSNAME@googlemail.com" />

• googlemail: Your GoogleMail address or name.

Example 2 (using a custom url and additional options)

<txp:mka_ical url="https://domain.com/url-of-ics-file/calendar.ics"
    pastevents="1" img="1" imgfolder="images/events/" defaultimg="none.gif" />

• url: URL of a calendar file
• pastevents: [0,1] Show past events?
• limit: [0,1,2,3,4,…] Show only X events
• img: [0,1] Show images?
• imgfolder: Where are the images?
• defaultimg: Name of the default image

Example 3 (mka_ical as a container tag)

<txp:mka_ical wraptag="" break=""
    googlemail="YOURADDRESSNAME@googlemail.com">
    <div class="h-event"> <!-- microdata h-event -->
    <h1 class="p-name">{title}</h1>
    <p class="h-event__meta">
    From <time class="dt-start" datetime="{start_datetime}">{start_date} {start_time}</time>
        to <time class="dt-end" datetime="{end_datetime}">{end_time}</time>
        at <span class="p-location">{location}</span>
    </p>
    <img class="event-img" src="{imagesrc}" border="0" align="left">
    <p class="p-summary">{description}</p>
    <a class="u-url" href="{event_url}">More information</a>
    </div>
</txp:mka_ical>

Example 4 (“Month year” headings using mka_if_different and mka_format_date)

<txp:mka_ical url="calendar.ics" wraptag="" break="">
    <txp:mka_if_different key="month_year"><h2><txp:mka_format_date format="%B %Y">{start_date}</txp:mka_format_date></h2></txp:mka_if_different>
    <div class="h-event">
        <p class="h-event__meta">
            <time class="dt-start" datetime="{start_datetime}">{start_date}</time> –
            <time class="dt-end" datetime="{end_datetime}">{end_time}</time>,
            <span class="p-location">{location}</span>
        </p>
        <txp:evaluate wraptag="p" class="description">{description}</txp:evaluate>
    </div>
</txp:mka_ical>

Standard output

<span class="date">{date}</span>
<span class="title">{title}</span>
<span class="description">{description}</span>

Changelog

• 0.7.0 – Textpattern v4.7 and php 7 compatibility (jools-r)
  • Plugin cleanup and reconfiguration for rah_blobin/plugin compiler
  • Inclusion of updated ical parser library (php5.6+ compatibility) in plugin
  • Updated google calendar URL
  • New ‘mka_if_first_event’ tag
  • New ‘mka_if_last_event’ tag
  • New ‘mka_if_different’ tag
  • New ‘mka_format_date’ tag
  • Tag registration for Txp 4.6+
  • Updated help
  • Additional replacement placeholders
  • Attribute ‘cssid’ renamed to ‘html_id’ in line with other txp tags (cssid still accepted for now)
  • New ‘googlemaildomain’ attribute if using just google username but need to use ‘gmail’ rather than ‘googlemail’ (default setting)
  • Cached json file now located in /tmp folder (as defined in prefs), not /files
• 0.6.3 – Debug details removed (Martin Kozianka)
• 0.6.2 – Output the date with strftime. Resolve: error when displaying without image (Martin Kozianka)
• 0.6.1 – First public version (Martin Kozianka)

Credits

This plugin was originally the work of Martin Kozianka (kozianka.de) and has since been updated to work with Textpattern 4.7+.

It makes use of the ICal parsing library TKr/intouch-iCalendar which is a fork of intouch-iCalendar which is in turn based on SG-iCalendar by Morten Fangel.