List Types

A list type is a type of list (yeah ok, that’s a bit asinine, but really what do you call this thing? it is more than a template, or a format ….. )

skip the background… tell me how to specify which fields to show in each list

Each shortcode has a default list type associated with it, all set up ready to go.

To specify another list type in the shortcode :

[events listtype=2]

For testing or prototyping purposes, when looking at a calendar page, you can also add ?listtype=n (or & if already have a ? in the url) to the url to see what another list type would look like. eg: http://test.icalevents.com/agenda/?listtype=12

Simple and Customisable?

I like simple but clever code,  code that is generic, resuable, multi-purpose. However this can be a double edged sword:

  • the more generic a tool is, the harder it can be to understand how to use it
  • the more flexible and customisable, the more complex it can be to setup

In this case, I tried to provide simplicity and flexibility.

  • To make it simple, there are a variety of pre-defined list types that are either usable as they are, or hopefully not too far from what you want.
  • To make it flexible, one can customise these or define new ones.  One can choose or customise:
    • the type of html to be produced around the content (tables, lists etc)
    • different date, time, month formats (localised)
    • select exactly which event fields you want in which order and with what html before and after (only displayed if field has data)
    • define own headings
    • define some grouping of events
    • choose ical components from the ics file… yes you could use this to just show “freebusy” info (if available in the ical file)
    • define default maximum days and events
  • To make it simple you can define a common list that meets your needs, and then
  • To make it flexible, you can override some of these settings in the shortcode and in the query string.  This also allows one to play around a but more easily.
  • To make it simple, there is some pre-defined “pretty printing”. For example, if you decide to print the RRULE (ics speak for the repeating rule), it will turn it into human speak eg: Daily on every Monday, Friday, Saturday. I challenge you to find a repeating rule that it cannot cope with!
  • To make it flexible, there is a before and after html for each field, and each field has a css class assigned, so you can style your list or calendar anyway you like.

Listing Events Configuration:

Some of the configuration is fairly obvious (I hope) and each upgrade usually has a bit more inline help.  The most complex part is possibly the Specify Fields to show for each list type:

Specify fields to show

This section currently shows:

  • almost all the possible fields that could appear in an ics file, grouped as the ics spec groups them.  These are in UPPERCASE.  For example: SUMMARY (the ics term)  is the title of the event.
  • lowercase fields are additional derived fields that I have added.  For example subscribeevent, if included will give you a link to the ics file for that event (only in amr-events for now), so that users may subscribe to just that event, not the whole calendar)
List type - fields to show

List type – fields to show

Column and Order

Assume you have chosen the html style of a table.  Then hopefully column is obvious?  Except of course for column 0 (zero) – that means “do not show”.  If not using the table html style, then think of a column as a means to group  the data for an event. Say description and location in one ‘column’ and dates, times etc in another.

The order you assign to a field determines the order or sequence within the column or group.

What does column and order mean when working with a calendar box?

I mentioned re-usable code?  Well using the list type code that was already there meant that I could offer great flexibility in defining the content of your box calendar and how it should be displayed.

The defaults provided (in conjunction with the default css) use two ‘columns’:

  • the first ‘column’ – visible immediately, maybe for the event title and date and time?
  • the second ‘column’ – only visible on hover over the event.  You can put whatever you like here – maybe the description?

To make it flexible and still give valid HTML, div’s are used within the table cells.  Any other html structure could result in invalid HTML if the you added your onw html.

You can define your own css of course to alter the behaviour, or (if you must), add some javascript.

Peek into the html behind day events

Grouping