Architectural Overview
======================

Design goals
------------

The development of plone.app.event was done with following design goals in mind:

  [a] Encapsulation and independence: All event related code should reside in a separate package (split into other packages, where appropriate). Plone should be least depend on plone.app.event. Best would be that one can deinstall this feature completely.

  [b] Dexterity support: plone.app.event should provide Dexterity behaviors, which can be used in Dexterity type.

  [c] Standards compliance: the iCalendar / `RFC5545 <http://tools.ietf.org/html/rfc5545>`_ standard is wonderful flexible, so plone.app.event should provide support for it by allowing ical exports. This is also available for the current ATContentType based implementation, but plone.app.event aims to improve it. A future goal is to support CalDAV also.

  [d] Recurring events support based on the RFC5545 standard.

  [e] A modern dateinput widget.

  [f] Features like whole-day-events.

  [g] Timezone support.

Encapsulation and independence: plone.app.event provides the Dexterity behaviors.  The calendar and event portlets were moved from plone.app.portlets into plone.app.event, where they belong semantically - thus improving encapsulation and independence and reducing interwoven dependencies.  The calendar portlet was completely refactored. The functionality of the CalendarTool (portal_calendar) was reimplenented. Important settings from the calendar-controlpanel are now available in the event configlet. Since the calendar portlet was the only consumer of the CalendarTool, the CalendarTool, the calendar controlpanel and the dependency to Products.CMFCalendar can be dropped. The new plone.app.widgets package implements z3cform based widgets, so the old datetime widget can be dropped. Python-dateutil provides recurrence calculations based on the RFC5545 standard - plone.formwidget.recurrence provides a awidget for recurrence and Products.DateRecurringIndex an appropriate index as a drop-in replacement for Zope's DateIndex. The iCalendar package was improved and is now used for plone.app.event to provide icalendar serialization. The timezone support is based on the pytz package. Plone now haves a portal timezone, User timezones and every event can define another timezone, if wished. User timezones are planned. Whole day events get their starttime set to 0:00 and endtime set to 23:59:59 - that's should be feasible in most cases (excluding any scientific events...).


Packages
--------


plone.app.event
~~~~~~~~~~~~~~~

Github: https://github.com/plone/plone.app.event

The "dx" submodule provides Dexterity behaviors (some granular ones). Like in the "at" submodule, ical, recurrence and generic event accessor adapters as well as some event subscribers are provided.

Both subpackages are only loaded, if the neccassary features are installed.

plone.app.event does not depend on CMFCalendar and the portal_calendar tool any more. Plone core's only consumer of this package was the calendar portlet anyways, which was completely rewritten.

base.py provides some basic event related functionality. Many of them need a context in order to get the correct timezone.

The "browser" submodule provides the new "event" controlpanel (the "calendar" controlpanel can be dropped, since we do not need CMFCalendar any more). The settings are stored in plone.registry.  The event view is generic to ATEvent and DX based event types.

The ical submodule provides adapters and views for export and import to and from icalendar resources.

The locales directory which holds locale files.

In the portlets subpackage there are portlet_calendar (a complete rewrite) and portlet_events, both from plone.app.portlets, where only BBB imports exist, so that existing installations do not break.

The tests are all ported to plone.app.testing.


plone.event
~~~~~~~~~~~

Github: https://github.com/plone/plone.event

Date/time related utilities, recurrence calculations based on python-dateutil.


plone.formwidget.recurrence
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Github: https://github.com/plone/plone.formwidget.recurrence

Recurrence widget based on jquery.recurrenceinput.js. Supports complex recurrence rules with exclusion and inclusion dates, automatically updated occurrences display within the widget and a nicely formatted string which explains the recurrence rule.  The recurrence rule is stored as a RFC5545/icalendar compatible recurrence string.


Products.DateRecurringIndex
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Github: https://github.com/collective/Products.DateRecurringIndex

A drop-in replacement for Zope's DateIndex with support for recurring events.  Each recurrence gets an index entry.


icalendar
~~~~~~~~~

Github: https://github.com/collective/icalendar

icalendar parser/generator framework.


Other, external packages
------------------------

plone.app.eventindex
~~~~~~~~~~~~~~~~~~~~

Github: https://github.com/regebro/plone.app.eventindex

A possible alternative to Products.DateRecurringindex, which supports late indexing and which does not have problems with unlimited occurrences. This eventindex is currently not used by plone.app.event.


Python-dateutil
~~~~~~~~~~~~~~~

Documentation: http://labix.org/python-dateutil
Repository: https://launchpad.net/dateutil

Useful extensions to the standard Python datetime features. plone.app.event uses it mainly for recurrence calculations.


Pytz
~~~~

Documentation: http://pytz.sourceforge.net/
Pypi page: https://pypi.python.org/pypi/pytz/

World timezone definitions, modern and historical. Based on the Olson database.
