===============================================
 How to show custom event sources in Kronolith
===============================================

(`Also posted on Stack Overflow`_)

.. _`Also posted on Stack Overflow`: http://stackoverflow.com/questions/1808104/how-to-show-custom-events-to-a-kronolith-calendar

You can do this by implementing the listTimeObjects and listTimeObjectCategories API calls. `Nag`_ (task list) and `Whups`_ (ticket tracking) do it this way. If you are using the Git version, you can use `TimeObjects`_, which wraps everything up in a nice class.

.. _`Nag`: http://www.horde.org/nag/
.. _`Whups`: http://www.horde.org/whups/
.. _`TimeObjects`: http://theupstairsroom.com/93

Kronolith calls these functions in initialize() (when filling $all_external_calendars) and listEvents(). It searches all APIs for this function, so you can register it with your own prefix.

*timeObject* is a generic name for "things that can be shown on a calendar", like events, task due dates, ... A *timeObjectCategory* is a group of *timeObjects*, which can be enabled or disabled in a group by the user. (In the default layout: using the panel in the upper-right corner of the calendar view, "Calendars".)

Your implementation for listTimeObjectCategories should return an array, with a category id as the key, and the user-visible name as the value.

listTimeObjects is called with the currently selected categories (an array of id's), and a start and end date. These dates might already be Horde_Date objects (to be sure, convert them again: $start = new Horde_Date($start)).

You should return an array of *timeObjects* that belong to these categories and fall in the specified time range. The keys are event id's, the values are arrays with values for the following keys:

* id

* title

* description

* start (Horde_Date or timestamp)

* end (Horde_Date or timestamp)

* category (Horde category, not timeobject category)

* params

If you register the show API call, this will be used for creating the link to the *timeObject* detail.