Documentation for the Textpattern plugin smd_calendar by Stef Dawson follows this short message from our sponsor ;-)

smd_calendar

Render a calendar with one or more articles as events on each day. Useful for gig guides, “what’s on” or scheduling apps.

Features

Full-size / mini calendar by month, with ISO week support
Nav: next/prev month or month/year dropdown. Year range can be from first/last article or +/- N years
One article = one event, native to TXP: posted date = the date it appears in the calendar (overrideable)
Filter events by cat / section / author / status / time / expiry
Specify event frequency in custom field (1 week / 10 days / 3 months / etc)
Custom fields for in/exclusions (dates on which an event is (re)scheduled/cancelled/omitted)
Multi-day spanned events based on article expiry
Display future, expired or sticky events
Holidays per-calendar
Pass each event to a form/container. Spanned and/or recurring events can be sent to a separate form. Cell format also customisable
Conditional tests for flags and dates so you can build your own logic
Table-, row-, cell-, and event-level classes for indicating different scenarios
Tags to display recurring events; event/calendar characteristics; or the current date/time

Installation / Uninstallation

Requires Textpattern 4.4.1+

Download the plugin from either textpattern.org, or the software page, paste the code into the TXP Admin->Plugins pane, install and enable the plugin. Create any needed custom fields. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To uninstall, delete from the Admin->Plugins page.

Naming convention

The core of the plugin is the smd_calendar tag, which renders a standard calendar. Each cell contains one or more events that occur on that day. Before diving into the tags here are the basics:

*calid% : you may put more than one calendar on a page: each can be uniquely referenced with a calendar ID so they may be controlled independently
*event% : an article. Any article written in the given section(s) will appear on the calendar as long as its expiry hasn’t been met. More than one event may appear in each cell
*event flag% : events can either be standard, they can recur, they can span multiple days, dates can be unscheduled or omitted from the calendar, or extra dates can be added
*cell flag% : a series of flags are used to label each cell according to what it contains. Cells can either be empty (i.e. no date: the filler cells at the start/end of the month), they can be a regular day (no flag), they can contain an event, or may be a holiday

Flags provide information about the cell / event — and can be tested with the conditional tag — while the corresponding class names are just there for your CSS use.

When assigned as classes, flags always take the ‘class’ prefix (i.e. the 1st item given in smd_calendar’s classprefixes attribute) — whether they appear at the event or cell levels. The only classes that take the optional 2nd ‘event’ prefix are the fields you specify in the eventclasses attribute.

Standard cells and events

The following cumulative naming rules apply:

Normal (day) cells don’t have a class assigned to them unless you specify one with cellclass
Any cell that contains an event (of any type) is flagged as an event
Any cell that falls on a holiday is given the flag hols
The current day is given the flag today

A single event (aka article) with a Posted date will be flagged standard, unless it recurs or spans more than one day.

Recurring events

If you have nominated a field as your stepfield you may enter a comma-separated list of frequencies at which the event is to repeat. The format of the repetition is number interval, e.g. 4 weeks or 10 days or 6 months. The plugin will do its best to figure out what you mean. See date input formats for more.

A few points:

second tuesday will show an event every 2nd Tuesday from the start date (i.e. fortnightly)
second tuesday ?month ?year will substitute the current month and year in first, and then calculate the date, resulting in the event only recurring on the 2nd Tuesday of each month. You must use both ?month and ?year if you choose this type of date or your event won’t appear
20 ?month will show the event on the 20th of every month
things like first thursday or last friday or this tuesday don’t need the ?month or ?year because they can only occur monthly, and will only show the event on the given day of the month

If you can find a use for it, you may specify multiple frequencies, for example 3 days, 1 week. That means you would see the event on the 1st day, then the 3rd, 6th, 7th, 9th, 12th, 14th, 15th, 18th, 21st, 24th… days thereafter. Note that the event only occurs once on the 21st day even though the two frequencies clash.

Recur rules:

The repetition will continue forever¹ unless you specify an expiry time
The very first event of a recurring set will be flagged with recurfirst
Each following cell that contains a recurring event will be flagged with recur
Both flags are applied to the event as classes using the class prefix
Repeated events may be cancelled or omitted on a per-date basis

¹ ‘forever’ is limited to 99999 recurrences per event, or 274 years’ worth of daily events. Either UNIX will run out of dates or PHP will run out of memory long before you reach this limit :-)

Multi-day (spanned) events

Any event that has:

a start date
an expiry date that is a day or more later than the start date, and
does not have any repetition in its stepfield

is flagged as a multi. By default the first event is displayed in full and each ‘continuation’ event is shown only as a right arrow in subsequent cells. Events may span months or years and the plugin figures everything out using flag rules:

The first cell of a spanned set is multifirst
The last cell is multilast
Every other cell is a multi except if the event rolls over into the next month. In that case, the entry on the 1st of the month is a multiprev to indicate it belongs to a previous event
If the 1st day of the month is the last day of the event, the multiprev is dropped in favour of multilast

Switch off spanning completely with showspanned="0". Events that have an expiry then become standard events.

‘Continuation’ cells may be processed with a separate form (spanform). If you choose not to use a spanform, the standard form or container will be used and you will have to distinguish between the different multi flags yourself using the conditional tag.

You can also cancel or omit days of a spanned event in the same manner as you do with recurring events, except you cannot cancel the first day; you should move the event start date and apologise!

Cancelling and omitting events

Plans change and you may find that a gig has to be cancelled. Perhaps you advertise a weekly boot fair but the field is waterlogged one week. No problem: nominate a skipfield in your smd_calendar tag and enter the date of the cancelled event.

Or you might run a theatre web site that has a three-week production performance on weeknights only. Instead of setting up three separate events — one for each week — nominate an omitfield and list the dates on which the performance does not air. Omitted dates will not, under any circumstances, appear on the calendar and they override cancelled dates/holidays. If cellplus mode is used, you will however see a cell flag labelled omit (plus class prefix) in case you do wish to style such cells.

To specify the dates in either field, use any acceptable date format, but derivatives of dd-monthname-yyyy or monthname-dd-yyyy are the most unambiguous to avoid problems (e.g. is 1/5 Jan 5th or May 1st). You can specify as many cancellations or omissions as you like; comma-separate each one. You may also specify ranges of dates to omit/cancel by using the notation start date => end date.

By default, cancelled events will not appear on the calendar. If you use showskipped="1" the event will appear in the cell as normal and the cancel flag will apply to the event (and cell if you choose) so you may detect/style it.

Extra dates

When events are cancelled you may elect to reschedule the event on a different date instead of having to create a new event with identical details. Use the extrafield to simply add it to the calendar on its new day. You might also use this feature if you have a recurring event on the 1st of every month but for some reason you have to move one of the events a day or two. Simply cancel the offending date and add the new date using extrafield.

The list of dates can be in any standard date format (including date ranges using start => end). They will be added to the calendar and flagged as extra. Also see the extrastrict attribute.

If your original event spans more than one day, you may elect to schedule the entire block again. Add a ‘+’ after any date you wish to repeat in its entirety, e.g. 2009-Mar-12+, 2009-Jun-18+, 2009-Feb-19 would copy the entire event block to March and June, but only the 1st date to Feb 19th. Events/cells are flagged as both extra and multi where applicable.

Notes:

if you schedule an extra event on a day that already contains the same event (perhaps on a spanned or recurring date) you may see two identical events on the same day. Try and avoid this, unless it’s your intended behaviour
date ranges and the ‘+’ syntax are mutually exlcusive on any date (e.g. 2009-Mar-10+ => 2009-Mar-15 is illegal)

Holidays

Public holidays need not be a nuisance to your events. Give the plugin a holiday list and it’ll make sure any recurring or multi events are not scheduled on those days. Standard one-off events are permitted by default because you might want to organise a special event on that day, though you can forbid those too if you wish.

The list of dates you specify can be entered directly in a string in the holidays attribute or in a <txp:variable />:

<txp:variable name="nat_hols"
     value="Dec 25, 26 Dec, 31/Dec, Jan-1,
        May 4 2009, 2009-08-31" />
<txp:smd_calendar holidays="txpvar:nat_hols" />

That list shows some of the variety and breadth of formats the plugin allows. There are more. Note that the events without a year occur on the same date every year, whereas the ones with a year will only occur on that specific date.

Once your dates are defined you can control which events are allowed to fall on those dates via holidayflags. Combining that attribute, showspanned, showskipped and the forms — along with the conditional tag — can give a wide variety of ways to display events and cells.

Holiday cells are given the flag hols, and any event that is not specifically permitted by the holidayflags is automatically assigned a cancel flag if it falls on one of the days. Omitted dates will, however, cause the cancel flag to be removed.

Tag: `<txp:smd_calendar>`

Put this tag wherever you want your calendar to appear. Use the following attributes to control its output. The default value is unset unless stated otherwise.

Display attributes

size

Calendar size. Options:

large

small

The small is more geared towards a minical, although functionally there isn’t much between them

Default: large

firstday

First day of the week to show in the calendar. 0=Sunday, 1=Monday … 6=Saturday

Default: 0

dayformat

Way in which day names are rendered. Options:

ABBR shows abbreviated day names; Mon, Tue, Wed, etc

FULL uses full names

Any valid strftime() codes. Locale-specific names are returned

A comma-separated list of custom day names surrounded by {} brackets

Example, for two-letter German weekdays: dayformat="{So,Mo,Di,Mi,Do,Fr,Sa}". The first day in the list must represent Sunday or things will break

Default: ABBR

monthformat

Way in which the month names are rendered. Options:

FULL shows full month names

ABBR uses abbreviated names

Any valid strftime() codes. Locale-specific names are returned

A comma-separated list of custom month names surrounded by {} brackets

Example, for single-letter month names: monthformat="{J,F,M,A,M,J,J,A,S,O,N,D}". The first month in the list must represent January or things will break

Default: FULL

select

Use a select dropdown for rapid access to weeks, months or years instead of fixed names. Choose one or more of:

week

month

year

Note: week and month are mutually exclusive

You may also specify up to two extra arguments, separated by : chars. These add text in front of and behind the week/month/year, respectively

Example: select="week:WEEK#, year:<:>" displays a select list with entries like this: WEEK#15 <2009>

selectbtn

Add a dedicated submit button to week/month/year select lists. Specify the text you wish to appear on the button. It will have the CSS class name smd_cal_input

Default: unset (i.e. auto-submit on select list change)

isoweeks

Show ISO week numbers as a column at the start of the calendar. Any text in this attribute enables the feature, and becomes the heading of the ISO week column

You may change the default week number in each cell by adding a comma and some text; whatever you enter will be put in each ISO week cell. Use the following replacement codes in your markup to insert the relevant info:

{week}

{month}

{year}

{isoyear}

Example: isoweeks="wk, #{week}" will put ‘wk’ at the top of the column and something like #24, #25, #26… beneath it. If the first item is omitted, there will be no column heading

Note that if this feature is enabled, firstday will be forced to start on a Monday as governed by the ISO specification

navarrow

Comma-separated pair of items you want to appear as prev/next arrows in the calendar

Default: <, >

caption

Add a caption to the calendar

summary

Add a summary to the calendar

Filter attributes

time

Which events to display. Options:

any

past

future

today

Default: any

expired

Hide or show expired events. Options:

unset (use the TXP Preference ‘Publish expired articles’)

0 (hide)

1 (show)

status

Events in this status list are published on the calendar. Options:

live

sticky

Default: live

category

Filter events by this list of categories. Use SMD_UNCAT for uncategorised events

subcats

Consider sub-categories. Choose a numeric nesting level to consider, or the word all

section

Filter events by this list of sections

author

Filter events by this list of author login names

realname

Filter events by this list of author Real Names (note: may add one extra query)

showall

If your calendar appears on the front page of your site and you have not used the section attribute, then:

0: only shows events from sections marked with On front page

1: shows all events from all sections

Default: 0

month

Start the calendar on this month from 1 (Jan) to 12 (Dec). Normal calendar navigation overrides this value

If static is used, this month becomes the only one you may view

If unset, and no m= value appears on the URL line, the current month is used

week

Start the calendar during the month containing this ISO week (from 1 to 53)

Ignored if static or one of the calendar navigation controls is used

If a w= value appears on the URL line, the given week overrides any month value

year

Start the calendar at this 4-digit year. Normal calendar navigation overrides this value

If static is used, this year becomes the only one you may view

If unset, and no y= value appears on the URL line, the current year is used

static

Force the calendar to be fixed to one month/year (i.e. no navigation). Month and year decided by attributes month and year or, if omitted, the current date will be used

Form attributes

form: Use the given TXP form to process each event; If the smd_calendar tag is used as a container it will be used in preference to the form; If neither are used, a default is used (Large: hyperlinked article title, Small: empty event)
spanform: Display spanned events differently to standard events; they usually use the same form/container; If neither are specified, a right-arrow will be used to indicate continuation of the previous day’s event; Note: the first day of a spanned set is not passed to the spanform; only continuation cells are passed to it
recurform: Display recurring events differently to standard events; Note: the first event of a recurring set is not passed to recurform
cellform (only on large calendars): Use if you wish to build each cell entirely from scratch; There are some replacement variables you can use to insert dynamic pieces of information in your cells; Note: you cannot use TXP article or plugin tags in the Form
headerform: Use if you wish to build the header yourself; There are some replacement variables you can use to insert dynamic pieces of information in your header

Field-based attributes (custom fields or other article fields)

stepfield

ID of a field within which an event may be told to repeat

Note: it is the field’s ID not its name, so for custom fields you must use custom_1 or custom_2 etc

Without this attribute, no recurring events may be defined

omitfield

ID (not name) of a field that contains a list of dates on which this event is to be omitted

skipfield

ID (not name) of a field that contains a list of dates on which this event is cancelled

extrafield

ID (not name) of a field from which a list of additional event dates may be given; the same event details will be copied to the new day(s)

extrastrict

Control visibility of extra dates on the calendar. Options:

0: extrafield dates automatically appear on the calendar

1: restrict new dates from appearing after the event’s expiry date

Default: 0

showskipped

Control visibility of cancelled events on the calendar. Options:

0 (hide)

1 (show)

Default: 0

showspanned

Control visibility of spanned events on the calendar. Options:

0 (hide)

1 (show)

Default: 1

datefields

IDs (not names) of up to two fields from which posted and expiry date stamps may be read. Comma-separate the field names; the first will be used as the Posted date and the second as the Expiry

If either is omitted or mangled, the article’s “real” posted/expiry date will be used instead

If the expiry date occurs before the start date, your datefields will be ignored and a warning will be issued

Config attributes

holidays

List of dates that are decreed as holidays

May be deferred to a <txp:variable />, in which case define your list in a named variable and use holidays="txpvar:my_var_name" to read them into the plugin

holidayflags

Permit certain event flags to be scheduled on holidays. List one or more of:

standard

recur

multi

Default: standard

id

HTML ID to apply to the table that holds the calendar. This becomes the value of the URL variable calid

Use this if you have more than one calendar on a page and wish to control them separately via the URL vars

navid

HTML ID to apply to the prev/next/month/year navigation form

yearwidth

A comma-separated list that specifies how many years your calendar spans. Visitors will not be permitted to navigate (next/prev) the calendar outside this range. Options:

0: use the earliest (posted) event as the earliest year, and the latest (modified or posted, whichever is greater) event as the latest year

any other single number expands the range equally in past & future directions

any pair of numbers subtracts the first from the earliest event and adds the second number of whole years to the latest event

adding c to either value causes the current year to be used instead of the earliest or latest event

Example: yearwidth="2,4c" subtracts 2 years from the earliest event and adds 4 whole years to today’s date

Default: 0

remap

When dealing with multiple calendars on a page it is often beneficial to use different names for w=, m= or y= in the URL so you can navigate calendars individually. This attribute enables you to rename the w, m, & y variable to any name specified after a colon (:)

Example: remap="w:wk, y:yr"

linkposted (only on small calendars)

Each cell that contains an event flag of the given type(s) will have its day number linked to the event’s true start date instead of the cell’s date. This allows you to always link to a valid article/event

Note that if more than one event occurs in the cell, the link will only be to the first event the plugin finds

Example: if you have a weekly event that starts on the 20th December 2008, setting linkposted="recur" will cause the link to be date=2008-12-20 every week. Without linkposted, the dates would be 2008-12-20, 2008-12-27, 2009-01-03, and so on

Default: recur, multi, multiprev, multilast (i.e. any recurring or spanned event)

maintain

Keep track of this comma-separated list of variables in the URL when navigating the calendar using the next/prev or month/year select lists. If you wish to maintain state yourself or do something exotic, empty this attribute first to avoid weirdness. Options:

calid

section

Style attributes

classlevels

Each flagged event can be given a CSS class based on its flag name(s). Classes can be applied to events, cells, or both. You may also promote (i.e. copy) all event classes that occur in a day to the cell itself so you can style the cell based on the events it contains. Options:

event

cell

cellplus (for copying unique event classes to the containing cell)

Note you should not use cell and cellplus together because the latter overrides the former

Default: cell, event

classprefixes

Comma-separated list of up to two prefixes to apply to your class names. The first prefix is applied to cell-level classes (and flags) and the second prefix is applied to event classes (see eventclasses)

If you only specify one prefix, it will be used for both. If you use classprefixes="" then no prefixes will be used at all

Default: smd_cal_, smd_cal_ev_

class

Class name of the calendar table itself

Default: unset

rowclass

Class name of each table row

Default: unset

cellclass

Class name of each table cell

Default: unset

emptyclass

Class name of any cells that don’t contain a day number (i.e. the blank cells at the start & end of a month)

Default: empty

isoweekclass

Class name of each cell containing an ISO week

Default: week

navclass

Class name of the prev/next month nav arrows. If a comma-separated list is used, the first item will be the name of the class of the previous month, the 2nd item of the next month. If a single value is used, both class names will be the same

Default: navprev, navnext

myclass

Class name of both the month and year in the calendar header (either the <span> or <select> tags). If mywraptag is used, the class is applied to the wraptag instead

Default: unset

eventclasses

Comma-separated list of items to add as classes to each event. Each are prefixed with the event prefix

Example: eventclasses="ID, AuthorID, custom_5" would add three classes to each event corresponding to the event’s ID, its author (login) name and the contents of custom_5

If you use cellplus, these classes will be copied to the cell level. Some special names exist: category adds both Category1 and Category2 (if set); gcat will add the current ‘global’ category (if filtering by category); author adds the author ID (if filtering by author); section adds the current section

Default: category

eventwraptag

HTML tag, without brackets, to wrap each event with

Default: span

mywraptag

HTML tag, without brackets, to wrap around both month + year dropdown select lists and submit button

Default: unset

Using a `cellform` with replacement variables

If you don’t like the layout of the default cell, you can do it yourself with the cellform attribute. The cells are generated last, so by the time the plugin reaches this attribute, all events have already been processed by any of your forms/containers. Thus you can’t use TXP article or plugin tags.

To build your own cells you often need information such as the events that fall on a particular day; or the week, month or day numbers, etc. So you may also insert any of the following replacements to have the relevant value inserted among your markup:

{day} / {dayzeros} : day of the week (1-31 / 01-31)
{weekday} : weekday in the local language, or from your dayformat list
{weekdayfull} or {weekdayabbr} : weekday in the local language
{week} : ISO week number (01-53)
{month} / {monthzeros} : month number (1-12 / 01-12)
{monthname} : month name in the local language, or from your monthformat list
{monthnamefull} or {monthnameabbr} : month name in the local language
{year} : 4-digit year
{shortyear} : 2-digit year
{isoyear} : 4 digit ISO year
{shortisoyear} : 2 digit ISO year
{evid} : event (article) ID
{events} : all events for the day
{standard} : only standard events
{recurfirst} / {recur} : various recurring events
{allrecur} : all recurring events for the day
{multifirst} / {multi} / {multiprev} / {multilast} : various multi events
{allmulti} : all multi events for the day
{cancel} : only cancelled events
{extra} : only extra events

Using a `headerform`

You can create your own header if you wish and employ any of the following replacements in the markup:

{firstday} : current weekday (as a number from 0 to 6)
{daynames} : comma-separated day names
{isoweekhead} : ISO week heading
{week} : ISO week
{month} : month
{year} : year
{isoyear} : ISO year

Differences between large and small calendars

cellform cannot be used on a small calendar
By default, no event descriptions are placed in the small calendar. You can add them yourself if you wish using a form/container
The only thing rendered in a small calendar cell is the hyperlinked date and any flags so you can style the boxes
classlevels are ignored: everything is automatically assigned at the cell level (i.e. cellplus is set)
eventclasses are still honoured if you wish to use a form to process them yourself
The small calendar outputs year-month-day-title or messy permlinks only

Tag: `<txp:smd_if_cal>`

This conditional tag allows you — inside your container/forms — to test certain conditions of the current event/cell. For enhanced conditional checking (perhaps in conjunction with smd_cal_now), consider the smd_if plugin. The default value is unset unless stated otherwise.

Attributes

flag

The cell or event flag(s) you want to test, each separated by a comma. List one or more of:

event

standard

recurfirst

recur

multifirst

multi

multilast

multiprev

cancel

omit

extra

hols

today

SMD_ANY (will trigger if the cell or event contains any of the above)

calid

The calendar ID you wish to check for a match

year

The year the current cell falls in

isoyear

The ISO year the current cell falls in

month

The month number (1-12) that the current cell falls in

week

The ISO week number that the current cell falls in

day

The day number the current cell falls in

logic

Method of combining the nominated tests. Options:

or: tag will trigger if at least one of the tests is true

and: tag will only trigger if all the tests are true

Default: or

‘And’ logic is useful for checking if the cell is of a certain type AND is later than the 15th of the month, for example.

Rudimentary comparators can be applied to the (iso)year, month, week and day attributes. Normally the value you supply will be tested for an exact match but if you prefix it with one of the following character sequences then the behaviour changes:

> tests if attribute is greater than the given value (e.g. year=">2008")
>= tests if attribute is greater than or equal to the given value (e.g. month=">=7")
< tests if attribute is less than the given value
<= tests if attribute is less than or equal to the given value
! tests if attribute is not the given value (e.g. day="!15")

Tag: `<txp:smd_cal_info>`

Inside your smd_calendar container/forms, use this tag to output certain information about the current event.

Attributes

type

Comma-separated list of types of information you want to display. Options:

flag

calid

(iso)year

month

week

day

s (current section)

Tag: `<txp:smd_cal_class>`

Inside your smd_calendat container/forms, use this tag to add a list of classes to the current cell/event. Very useful if building cells yourself because inside a conditional tag you could add particular class names based on some value in a cell.

Attributes

name: Comma-separated list of classnames to add to the current cell/event. These are not subject to any classprefixes so will always appear exactly as you write them; Default: unset

Tag: `<txp:smd_cal_now>`

Return the current date/time, formatted however you please. Useful for extracting parts of the current system timestamp to compare things via other conditional plugins or the <txp:smd_if_cal> tag.

Attributes

format

The way you want the date/time represented. Use any valid strftime() string. Has full Windows support, even for those values where strftime() indicates otherwise

Default: the date format set in Basic Preferences.

now

If you don’t want the time to be ‘now’ you can state what time ‘now’ is! Use any standard date/time format

You may also use the codes ?day, ?month or ?year in your time string which will do one of two things:

replace the codes with the URL parameters d=, m= or y=, if they are being used

use the current day, month or year (i.e. the parts of today’s date)

Default: now! (the time at which you call the tag)

offset

An offset into the future that you wish to apply to now

Example: 2 months. See Example 6 for a practical application of this attribute

gmt

Return either:

0: local time according to the time zone set in Basic Prefs

1: GMT time

Default: 0

lang

An ISO language code that formats time strings suitable for the specified language (or locale) as defined by ISO 639

Default: unset (i.e. use the value as stated in TXP prefs)

Tag: `<txp:smd_article_event>`

When you create recurring events, they really only exist once as a single article; the repetition is a trick. Thus the built-in article tags only show the single, real articles.

This tag — similar in function to <txp:article_custom /> — allows you to list recurring articles as if they were ‘real’ articles in the database. They don’t become real articles, they are just listed as such.

Inside the tag’s form or container you can use all existing article tags to display any information you like about each ‘virtual’ article. The default value is unset unless stated otherwise.

Identical attributes to smd_calendar:

stepfield
skipfield
omitfield
extrafield
datefields
section
category
author
realname
status
time
expired

Other attributes

id

Restrict events to this list of article IDs

custom

Specify your own comma-separated list of custom field clauses to the query. Separate each field from its (optional) operator and clause with a colon (alterable via param_delim).

Example: custom="custom_3:like:Lion%, custom_6:Chessington" would add AND custom_3 like 'Lion%' AND custom_6='Chessington' to the database query.

param_delim

Alter the separator character(s) between field-clause items in the custom attribute.

Default: colon (:)

type

Comma-separated list of event types to display. Options:

standard

recur

multi

Default: standard, recur, multi

allspanned

Control display of spanned events:

0: any event that has a start date in the past will be omitted from the list

1: display remaining days from spanned events that began in the past

Example: use allspanned="1" if you are listing remaining performance dates from a Broadway show’s schedule that started some months ago.

Default: 0

month

Only show events that occur in the given YYYY-mm

from

Only show events with Posted dated beginning after this start date. Can be any valid date format

to

Only show events with Posted dates up to this end date. Can be any valid date format

sort

Order the events by this column (case-sensitive) and sort direction (asc or desc)

Default: Posted asc

form

Pass each matching event to the given TXP form. Note that using a container overrides this attribute, and if you specify neither a form nor container, you will see a list of article Posted dates

paging

Unlike article_custom, events from the smd_article_event tag may be paged using <txp:older /> and <txp:newer />. But if you wish to show an event list on the same page as a standard article list, the older/newer tags will navigate both lists simultaneously. Under this circumstance you may need to turn paging off (0). Options:

0 (off)

1 (on)

Default: 1

offset

Begin displaying events from this numeric position, instead of from the start of the list of events

Default: 0

limit

Inly show this many events maximum per page, i.e. the number of events to display, whether they come from one ‘real’ article or many

Default: 10

eventlimit

Only show this many events maximum per event

Example: if you have a weekly repeated event that lasts for four months and you set eventlimit="6" you will only see a maximum of 6 events from every article containing repetition. The range (start and end date) is determined by other plugin attributes

Default: 10

pageby

Esoteric paging feature, identical to <txp:article />

Default: same as limit

pgonly

Set to 1 to perform the paging action without displaying anything. Probably useless

wraptag

The HTML tag, without brackets, to wrap the list in

break

The HTML tag to separate each item with

class

The CSS class to apply to the wraptag

The smd_article_event tag process

It is worth noting that this tag executes in 3-phases:

Pre-filter: all events that match type, category, section, author, status, id, and expired are extracted
Time-filter: any “time-based” attributes are then applied to the above list. At this point, any extrafield, stepfield, omitfield, or skipfield are calculated to find repeated dates (up to as many as eventlimit allows or the calculation exceeds the event’s expiry time). The attributes time, month, from, and to are used to refine the filtration here
Output: whatever the previous phases have left behind is subject to any paging, offset and limit you may have specified, then wrapped and displayed

Tag: `<txp:smd_event_info>`

Identical tag to <txp:smd_calinfo /> but for use inside <txp:smd_article_event />.

Examples

Example 1: basic calendar

You have the entire arsenal of TXP tags available to you in a calendar. Thus you can set the article’s start and end dates to the same day and set the start and end times to indicate the start and end of the event. You can then use standard <txp:posted /> or <txp:expires /> tags with various format strings to render the event’s criteria.

Similarly you can use any other TXP tags to show as much or as little detail as you like in the calendar cell.

<txp:smd_calendar section="events">
<div>
   Event: <txp:permlink><txp:title /></txp:permlink>
   <br /><txp:excerpt />
</div>
<div class="evtime">
   Start: <txp:posted format="%H:%M" />
</div>
<div class="evtime">
   End: <txp:expires format="%H:%M" />
</div>
</txp:smd_calendar>

Example 2: conditional calendar

Using the conditional tag you can take action if certain events contain particular flags. This example also shows a completely useless manner of employing <txp:smd_cal_now />.

Time is: <txp:smd_cal_now format="%T" />
<txp:smd_calendar form="evform"
     stepfield="custom_3" skipfield="custom_6"
     spanform="multis" />

In form evform:

<txp:smd_if_cal flag="recur">
  <txp:permlink>(RECUR)</txp:permlink>
<txp:else />
   <txp:permlink><txp:title /></txp:permlink>
   <txp:smd_if_cal flag="multifirst">
      <span class="right">&laquo;--</span>
   </txp:smd_if_cal>
   <txp:smd_if_cal flag="recurfirst">
      <span>One of many...</span>
   </txp:smd_if_cal>
</txp:smd_if_cal>

And in form multis:

<txp:smd_if_cal flag="multi, multiprev">
   <txp:permlink>--&raquo;--</txp:permlink>
</txp:smd_if_cal>
<txp:smd_if_cal flag="multilast">
   <txp:permlink>
      <span class="left">--&raquo;</span> END <txp:title />
   </txp:permlink>
</txp:smd_if_cal>

Notice that multifirst is tested inside the same form as standard events. This is because only continuation spanned cells are passed to the spanform; the first event of a spanned group is just like any standard event. Similarly, if you had been using recurform the first event of the recurring set would be processed in the usual form/container and every subsequent event would be passed to the dedicated form.

Example 3: classes

You could use the calendar tags to output various pieces of flag information to build your own class names. This example also demonstrates the html attribute of <txp:smd_cal_info /> to build up a query string that is passed along with an event’s category1 when a visitor clicks the anchor.

This allows your site visitors to filter events by category while retaining the ability to show the calendar for the current month/year and section they are viewing instead of dropping back to the current month/year like other calendar systems often do.

<txp:smd_calendar isoweeks="WEEK#"
     yearwidth="0,2" select="year, month"
     stepfield="custom_1" skipfield="custom_2"
     showskipped="1" expired="1">
   <span class="<txp:smd_cal_info join=" cal_" />">
      <txp:permlink><txp:title /></txp:permlink>
      <a href="?c=<txp:category1
         />&<txp:smd_cal_info type="s, year,
         month, calid" html="1" join_prefix=""
         />"><txp:category1 title="1" /></a>
   </span>
</txp:smd_calendar>

What is also useful about the <txp:smd_cal_info /> tag is that if a particular value is not set it will not be included in the output.

Example 4: upcoming events

List the next 5 upcoming — recurring — events, plus any standard and spanned events, formatting them as a definition list.

<h2>Upcoming Events</h2>
<txp:smd_article_event stepfield="custom_1"
     wraptag="dl" time="future" eventlimit="5">
   <txp:if_different>
     <dt><txp:posted format="%B %Y" /></dt>
   </txp:if_different>
   <dd>
      <txp:permlink><txp:title/></txp:permlink>
      <txp:posted />
   </dd>
</txp:smd_article_event>

If you add pagination tags you can flip through all the events; they will be displayed 10 at a time on each page (if you want to keep track of which page you are on as you flip through a calendar that is in a sidebar, add pg to the maintain attribute in your calendar).

Note the hyperlinked title shown here will jump to the ‘real’ article (the first date in the recurring set) when clicked, not to an article with a date matching the recurrence.

If you wanted to allow people to book an event, try this in your hyperlinked individual article:

<txp:if_individual_article>
 <txp:article limit="1">
  <h3><txp:title /></h3>
  <txp:body />
  <p>Please choose a date to book:</p>
  <select>
  <txp:smd_article_event stepfield="custom_1"
    type="recur" id='<txp:article_id />'>
    <option
     value='<txp:posted format="%G-%m-%d"/>'>
      <txp:posted format="%m %d, $G" />
    </option>
  </txp:smd_article_event>
  </select>
 </txp:article>
</txp:if_individual_article>

With some cunning you could even add the ‘virtual’ date that they chose in your original smd_article_event list and pass it as a URL variable to your individual article where you could read the value and pre-select the date in the select list for the vistor.

Example 5: iCal synchronisation

How about being able to output your events in iCal format so other people can sync their calendars to yours? Put this in a new Page template in its own Section:

BEGIN:VCALENDAR
VERSION:2.0
X-WR-CALNAME:Gigs Calendar
PRODID:-//Apple Computer, Inc//iCal 1.5//EN
X-WR-TIMEZONE:Europe/London
<txp:smd_article_event form="icsitem" time="any"
section="gigs" limit="1000">
 BEGIN:VEVENT
 DTSTART:<txp:posted format="%Y%m%dT%H%i%s" />
 DTEND:<txp:expires format="%Y%m%dT%H%i%s" />
 SUMMARY:<txp:title />
 END:VEVENT
</txp:smd_article_event>
END:VCALENDAR

That will output an iCal-formatted gig list (repeated or otherwise). If you got freaky with it and added some conditional logic inside the template you could even read in URL variables and plug them in. Thus you could link to it directly off the calendar itself, pass in the section, category or event info and have a customised iCal stream pumped out of Textpattern.

Thanks to woof for bringing the original David Emery article to my attention.

Example 6: redefining now

Using the now and offset attributes of <txp:smd_cal_now /> you can effectively set ‘now’ to be any time you like and make calculations based on a particular date.

Plugging the ?month and ?year codes in allows you to make <txp:smd_article_event /> track the calendar. So you can automatically show only the events that occur in the month the visitor is browsing via the calendar:

<txp:smd_calendar stepfield="custom_1" />
<h2>Events this month</h2>
<txp:smd_article_event stepfield="custom_1"
     from='<txp:smd_cal_now now="01-?month-?year" />'
     to='<txp:smd_cal_now now="?month-?year"
        offset="1 month" />' time="any" wraptag="ul">
<li><txp:permlink><b><txp:title/></b></txp:permlink></li>
</txp:smd_article_event>

Author / credits

Stef Dawson. Jointly funded by generous donators: mrdale, woof, jakob, renobird and joebaich. Originally based on mdp_calendar. All props to the original author, and of course the class upon which the calendar is based.

Source code

If you’d rather frolic in the raw code halls, you’ll need to step into the view source page.

Legacy software

If, for some inexplicable reason, you need last century's version of a plugin, it can probably be found on the plugin archive page.

Experimental software

If you’re feeling brave, or fancy skateboarding into volcanos, you can test out some of my beta code. It can be found on the plugin beta page.

Put this in your diary and smoke it

smd_calendar

Features

Installation / Uninstallation

Naming convention

Standard cells and events

Recurring events

Multi-day (spanned) events

Cancelling and omitting events

Extra dates

Holidays

Tag: <txp:smd_calendar>

Display attributes

Filter attributes

Form attributes

Field-based attributes (custom fields or other article fields)

Config attributes

Style attributes

Using a cellform with replacement variables

Using a headerform

Differences between large and small calendars

Tag: <txp:smd_if_cal>

Attributes

Tag: <txp:smd_cal_info>

Attributes

Tag: <txp:smd_cal_class>

Attributes

Tag: <txp:smd_cal_now>

Attributes

Tag: <txp:smd_article_event>

Identical attributes to smd_calendar:

Other attributes

The smd_article_event tag process

Tag: <txp:smd_event_info>

Examples

Example 1: basic calendar

Example 2: conditional calendar

Example 3: classes

Example 4: upcoming events

Example 5: iCal synchronisation

Example 6: redefining now

Author / credits

Source code

Legacy software

Experimental software

Textpattern plugin links

Tag: `<txp:smd_calendar>`

Using a `cellform` with replacement variables

Using a `headerform`

Tag: `<txp:smd_if_cal>`

Tag: `<txp:smd_cal_info>`

Tag: `<txp:smd_cal_class>`

Tag: `<txp:smd_cal_now>`

Tag: `<txp:smd_article_event>`

Tag: `<txp:smd_event_info>`