[MKDoc-dev] Proposed event/calendar functionality

[Bruno Postle]

MKDoc is going to acquire what we call an 'Event Component', this 
email is an attempt to summarise the developments so-far.

Rationale
=========

MKDoc is 'document-centric', each document has a unique URI ending 
with a slash - The purpose is to _appear_ to be a hierarchical 
structure of directories much like a static web-site.

Permissions, versioning, template selection and all the actions in 
the yellow top tool-bar work at this coarse-grained document level.

One aspect of an MKDoc document is that it has a 'Body', this is 
content such as text, HTML or link 'components' serialised as XML 
and stored in the SQL database.

Depending on the choice of template and the components added, an 
MKDoc document can be many things: a document, photo album, links 
page, product for sale, news story, news headlines or several of 
these things all at the same time.

In addition to these existing ad-hoc types, we want to be able to 
make an MKDoc document an Event (in time) and later-on, a Place (in 
space).

Typical usage of an Event Component
-----------------------------------

Say a theatre is going to present a new production, they might 
create a document describing it:

  http://www.example.com/my-theatre/plays/twelfth-night/

All the usual MKDoc stuff can be added, such a sub-documents and 
photo components.  The audience categories might be set to 
'theatre', 'comedy', 'Elizabethan' and 'amateur'.

For each performance the editor must add an event-component, each 
specifying the start and stop times.

Elsewhere a calendar can be displayed, this will be customised to 
show only productions in the future matching a visitors audience 
preferences:

  http://www.example.com/my-theatre/programme/

..and the regular personalised email newsletters will list it as an 
upcoming event.

How is it going to work?
========================

Rather than trying to stuff this information into the document 
attributes, the plan is to create a new 'component type' that 
represents a 'time range' - This solves the potential problem of 
repeating-events requiring complex configuration rules - Under this 
model a repeating event simply has multiple 'time range' components.

Time Component
--------------

This will be stored in the document Body in the same way as existing 
components, though events need to be search-able, so a new SQL table 
is required:

  Component_TimeRange
  --------------------
  ID            Char
  Date_Start    TimeDate
  Date_Start_TZ Char
  Date_Stop     TimeDate
  Date_Stop_TZ  Char
  Title         Char

(I realise that this is missing the Document_ID, very important)

MKDoc-1.8 already has an unfinished skeleton of this arrangement 
with a flo::editor::TimeRange component and associated editor 
template: /resources/templates/editor/timerange/

Display rules
-------------

How this time-range component appears when a document is viewed is 
entirely up-to the template author, they could be invisible, listed 
at the bottom or trigger a blinking "Now on" banner.

Newsletter
----------

Currently a personalised newsletter gets sent out daily, weekly or 
monthly - If a user requests it and if they specify which 'audience 
categories' interest them - This lists all the documents added to 
the site during that period.

We propose adding-on to this - So a weekly newsletter would have a 
new section entitled 'events coming-up in the next week'.

Headlines
---------

Currently the headlines component is used to provide a personalised 
listing of relevant recent documents, typically this is used to 
create news-headlines pages.

We intend to calendar-ise this by adding a toggle to switch this 
display between 'recently added' and 'upcoming'.

That's it, any comments welcome, please send them to the mkdoc-dev 
list.

-- 
Bruno