===============================================
 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.