View source for Calendar:Dev Guide

<small>[[Calendar:Home Page|<< Back to Calendar Home Page]]</small>

{{Outdated}}

This page is a work in progress.  It is eventually meant to replace the old Developer's Guide at http://www.mozilla.org/projects/calendar/dev_guide.html

== Introduction ==
The Sunbird and Lightning code-bases can be roughly divided into the 'Front End', which corresponds to the XUL and js files that the user directly interacts with, and the 'Back End', which consists mainly of XPCOM components.

As is often the case with software code, the actual code is usually the best resource.  There are a fair number of comments throughout the code that can help explain in greater detail what is going on.  This page is merely meant to give a "bird's eye" view of the code-base, to help provide entry points for searches.

= Folder Structure =
All of the calendar-specific code lives in the [http://lxr.mozilla.org/mozilla/source/calendar/ calendar/] directory of the mozilla source tree.  Within there:
*[http://lxr.mozilla.org/mozilla/source/calendar/base/ base/] is meant to contain all of the files that are shared by both Lightning and Sunbird.  This rule is not strictly followed at this time though.
**[http://lxr.mozilla.org/mozilla/source/calendar/base/content/ base/content/] contains shared front-end code.
**[http://lxr.mozilla.org/mozilla/source/calendar/base/public/ base/public/] contains IDL files for all calendar-specific interfaces.
**[http://lxr.mozilla.org/mozilla/source/calendar/base/src/ base/src/] contains the actual code for all XPCOM components.
*[http://lxr.mozilla.org/mozilla/source/calendar/import-export/ import-export/] contains implementations of the [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calIImportExport.idl import and export interfaces].
*[http://lxr.mozilla.org/mozilla/source/calendar/lightning/ lightning/] contains files specific to Lighting.
*[http://lxr.mozilla.org/mozilla/source/calendar/locales/ locales/] contains the en-US strings. Alternative locales live in the /l10n repository.
*[http://lxr.mozilla.org/mozilla/source/calendar/providers/ providers/] See the Providers section of this document.
*[http://lxr.mozilla.org/mozilla/source/calendar/resources/ resources/] is the original front-end directory.  Many front-end files live here.
*[http://lxr.mozilla.org/mozilla/source/calendar/sunbird/ sunbird/] Sunbird specific files.

= Front End =
Start-up points: The front-end code in Sunbird begins to be called with the calendarInit() function in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendar.js calendar.js].  In Lightning, the ltnOnLoad() function in [http://lxr.mozilla.org/mozilla/source/calendar/lightning/content/messenger-overlay-sidebar.js messenger-overlay-sidebar.js] is registered as an onload listener.  Note that backend components (especially the alarm-service) begin much earlier in the startup process.
== Calendar Management ==
Note: See also the backend Providers section for information on what actually makes up a calendar object.

See also the backend [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calICalendarManager.idl calCalendarManager interface].
==== Sunbird ====
Within Sunbird, all of the calendars that the user subscribes to are placed in a listbox within a tab in the upper-left of the display (as specified in [http://lxr.mozilla.org/mozilla/source/calendar/sunbird/base/content/calendar.xul calendar.xul]).  The code that builds this listbox, as well as other related code (such as the code that controls calendar colors) may be found in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarManagement.js calendarManagement.js].

==== Lightning ====
Within Lightning, all of the calendars that the user subscribes to are placed in a tree in the tabbox in the lower left of the display, as specified in [http://lxr.mozilla.org/mozilla/source/calendar/lightning/content/messenger-overlay-sidebar.xul messenger-overlay-siderbar.xul]).  The equivalent of Sunbird's calendarManagement.js is [http://lxr.mozilla.org/mozilla/source/calendar/lightning/content/calendar-management.js calendar-management.js].

==== Shared UI ====
Both Sunbird and Lightning use the Calendar Creation Wizard to provide the user with a way to create and subscribe to new calendars.  It is defined in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarCreation.xul calendarCreation.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarCreation.js calendarCreation.js].

Both Sunbird and Lightning use the Calendar Properties dialog to allow the user to modify an existing calendar.  It is defined in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarProperties.xul calendarProperties.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarProperties.js calendarProperties.js].

== Task Lists ==
The current status of the task lists is under review.

== Event Lists ==
The current status of the event lists (agenda-tree vs. unifinder) is under review.

== The Views ==
==== Shared UI ====
Both Sunbird and Lightning use a deck to display a series of views.  Each of these views implements the [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calIDecoratedView.idl calIDecoratedView Interface].  Each of these decorated views inherits from [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-decorated-base.xml calendar-decorated-base.xml]  Within each of these decorated views is an embedded [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calICalendarView.idl calICalendarView] object.
{| 
| Decorated View || Embedded View 
|- 
| [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-decorated-month-view.xml calendar-decorated-month-view.xml] || [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-month-view.xml calendar-month-view.xml]
|- 
| [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-decorated-multiweek-view.xml calendar-decorated-multiweek-view.xml] || [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-month-view.xml calendar-month-view.xml]
|- 
| [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-decorated-week-view.xml calendar-decorated-week-view.xml] || [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-multiday-view.xml calendar-multiday-view.xml]
|- 
| [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-decorated-day-view.xml calendar-decorated-day-view.xml] || [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-multiday-view.xml calendar-multiday-view.xml]
|}
Note: Only Sunbird implements the Multiweek view.

Navigation (next/prev) is controlled within the actual xml files.  Switching of views, and interaction with exterior code is controlled (temporarily) in Sunbird by [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarWindow.js calendarWindow.js] and in Lighting by parts of [http://lxr.mozilla.org/mozilla/source/calendar/lightning/content/messenger-overlay-sidebar.js messenger-overlay-sidebar.js]
== Dialogs ==
The main dialog that users interact with is the event/task creation/modification dialog.  This dialog is currently under review.  Both Sunbird and Lightning offer publish dialogs as well, and these too are under review

==== Shared UI ====
Sunbird and Lightning share the event/task dialog. The dialog is defined in [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-event-dialog.xul calendar-event-dialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-event-dialog.js calendar-event-dialog.js].  It also relies on code in [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-item-editing.js calendar-item-editing.js].

Sunbird and Lightning share the publishing dialog. The dialog is defined in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/publishDialog.xul publishDialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/publishDialog.js publishDialog.js].  It also relies on code in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/publish.js publish.js]

==== Sunbird ====
Sunbird also offers a goToDate dialog ([http://lxr.mozilla.org/mozilla/source/calendar/resources/content/goToDateDialog.xul goToDateDialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/goToDateDialog.js goToDateDialog.js]) and a printing dialog ([http://lxr.mozilla.org/mozilla/source/calendar/resources/content/printDialog.xul printDialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/printDialog.js printDialog.js]).  Printing also relies on [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calPrintEngine.xul calPrintEngine.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calPrintEngine.js calPrintEngine.js] for actual print-previews.

==== Lightning ====
None.


See also the backend section on 'Events/Tasks'

== Preferences ==
==== Sunbird ====
The files controlling Sunbird's preferences are all in the [http://lxr.mozilla.org/mozilla/source/calendar/base/content/preferences/ calendar/base/content/preferences/] folder.

==== Lighting ====
Lightning overlays a prefpane directly into Thunderbird's prefwindow.  This prefpane is defined in [http://lxr.mozilla.org/mozilla/source/calendar/lightning/content/lightning-preferences.xul lightning-preferences.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/lightning/content/lightning-preferences.js lightning-preferences.js]

== Alarms ==
<strike>The alarm system is currently undergoing a rewrite in [https://bugzilla.mozilla.org/show_bug.cgi?id=298358 Bug 298358].</strike>

The referenced bug is no longer active, as it has been marked resolved.

<!-- Can someone "in the know" please replace this section with more current information on where to find the current pieces of the alarm system... with at least roughly the level of detail in other similar sections of this page? Thanks! -->

== Other useful files ==
The [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarUtils.js calendarUtils.js] file contains many common functions used in both Sunbird and Lightning.  It also contains the code for guessing the system timezone that the user is in.  Sunbird additionally offers a [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/applicationUtil.js applicationUtil.js] file that controls Sunbird specific utilities, such as opening the Extension/Theme managers.

= Back End =
The back-end of Lightning and Sunbird consists largely of a series of XPCOM components that have been designed specifically for calendar-related purposes.  In most cases, these components implement a specific interface defined in an IDL file.  All of these interface definitions reside in [http://lxr.mozilla.org/mozilla/source/calendar/base/public/ public/] and contain substantial documentation on their use and implementation.  The back end  is entirely shared between all calendar applications and extensions. 

== SQLite ==
Sunbird/Lightning are now using the new [http://developer.mozilla.org/en/docs/mozStorage mozStorage] system to keep track of the majority of user-entered information.  There are several tables stored in the database.  The tables concerning calendar locations and preferences are defined [http://lxr.mozilla.org/mozilla/source/calendar/base/src/calCalendarManager.js#119 here] and those concerning events in individual calendars are defined [http://lxr.mozilla.org/mozilla/source/calendar/providers/storage/calStorageCalendar.js#1922 here].

== Providers ==
There are currently 3 types of calendars that are available to the user, and 5 back-end types to support these.  Each of these calendar types must implement the [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calICalendarProvider.idl calICalendarProvider interface].  Then, individual instances of a [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calICalendar.idl calICalendar] object are created for each calendar the user subscribes to.

*Local Calendars use the mozStorage (sqLite) system.  They are defined in [http://lxr.mozilla.org/mozilla/source/calendar/providers/storage/calStorageCalendar.js calStorageCalendar.js].

*ICS (called "remote webdav" in the UI) calendars are defined in [http://lxr.mozilla.org/mozilla/source/calendar/providers/ics/calICSCalendar.js calICSCalendar.js]  They rely heavily on the [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calIICSService.idl calIICSService].  With every ICS calendar a [http://lxr.mozilla.org/mozilla/source/calendar/providers/memory/calMemoryCalendar.js calMemeoryCalendar] is also created, to help improve speed.  ICS Calendars are built on top of the [http://lxr.mozilla.org/mozilla/source/calendar/libical/ libical.] component, which handles the lowest level parsing of ICS files.  All interactions with libical should go through calICSService.

*Caldav (called "remote caldav" in the UI) calendars are defined in [http://lxr.mozilla.org/mozilla/source/calendar/providers/caldav/calDavCalendar.js calDavCalendar.js].

Additionally, there is a special calendar type that has been created to reduce complexity the front-end code.  Rarely will the front end code interact with any of these calendars directly.  Instead, the calendar-management system will add and remove calendars from a [http://lxr.mozilla.org/mozilla/source/calendar/providers/composite/calCompositeCalendar.js calCompositeCalendar].  This calendar contains a collection of all the active ("check-marked") calendars.  Asking it for events will return all events in all active calendars that meet the criteria specified.

== Events/Tasks ==
Events are defined in the [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calIEvent.idl calIEvent interface] and tasks similarly defined in the [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calITodo.idl calITodo interface].  Each of these inherits from [http://lxr.mozilla.org/mozilla/source/calendar/base/public/calIItemBase.idl calIItemBase].

Additionally, events and tasks rely on the majority of other interfaces defined.

== Build System ==
The build system is magic.  Don't ask too many questions about it.  Hopefully XULRunner will simplify things.
=== Filling .jars ===
During the build process, the jar.mn file in each  directory of the calendar/ source is read.  Files referenced in there are added to the appropriate jar.  The syntax is fairly self-explanatory.  Note, however, that whenever you wish to add new files to the code, you must add an appropriate line to the relevant jar.mn file.
=== Registering Components ===
(someone check me on this)
Sunbird and Lighting only define 1 'real' component, in [http://lxr.mozilla.org/mozilla/source/calendar/base/src/calItemModule.js calItemModule.js].  This module then creates on-the-fly factories for most of the other components used.  To add a new component, you should add it to the array of components defined there.  See the patch on [https://bugzilla.mozilla.org/show_bug.cgi?id=298358 Bug 298358] for an example of how to do this.  Note that you'll also need to modify the jar.mn file for lightning, so that the component file can be added to the .xpi.

[[category:calendar|Dev Guide]]