289
edits
Changes
First cut at a new dev-guide
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/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/resources/content/calendar.xul calendar.xul]). The code the 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]. The previously used [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarManager.js calendarManager.js] is now obsolete and not packaged with any current builds. It will likely be removed from CVS soon.
==== 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].
The files [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/localCalDialog.xul lcoalCalDialog.xul], [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/localCalDialog.js lcoalCalDialog.js], [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/serverDialog.xul serverDialog.xul], and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/serverDialog.js serverDialog.js] which were used for these tasks in Sunbird 0.2 are now obsolete.
== 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
==== Sunbird ====
Sunbird's current event/task dialog is defined in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/eventDialog.xul eventDialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/eventDialog.js eventDialog.js]
The publishing 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 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 ====
Lightning's event/task 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].
Lightning's publish dialog lives in [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-publish-dialog.xul calendar-publish-dialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-publish-dialog.js calendar-publish-dialog.js]. At the time of this writing, its functionality is suspect.
==== Shared UI ====
None yet. It is hoped to soon unite the publish dialogs, and implement the goToDate dialog in Lightning.
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/resources/content/pref/ pref/] folder. The files [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/pref/prefBird.xul prefBird.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/pref/prefBirdOverly.xul prefBirdOverlay.xul] correspond to preferences that were used in the calendar.xpi, which is no longer supported.
==== 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 ==
The alarm system is currently undergoing a rewrite in [https://bugzilla.mozilla.org/show_bug.cgi?id=298358 Bug 298358].
== 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.
== 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.
= Potential Pitfalls =
One of the most confusing aspects of the Sunbird code is often the fact that there are actually two calendar.xul files. One can be found at [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendar.xul resources/content/calendar.xul] and the other at [http://lxr.mozilla.org/mozilla/source/calendar/sunbird/base/content/calendar.xul sunbird/base/content/calendar.xul]. This is a vestige of the original sharing of code between Sunbird and the calendar extension. The Sunbird build process uses the calendar.xul in the sunbird/ folder. When making changes to one calendar.xul, please make changes to the other. It's still theoretically possible to build the calendar extension, and we'd like to keep this possibility around as long as possible.
== 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/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/resources/content/calendar.xul calendar.xul]). The code the 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]. The previously used [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendarManager.js calendarManager.js] is now obsolete and not packaged with any current builds. It will likely be removed from CVS soon.
==== 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].
The files [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/localCalDialog.xul lcoalCalDialog.xul], [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/localCalDialog.js lcoalCalDialog.js], [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/serverDialog.xul serverDialog.xul], and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/serverDialog.js serverDialog.js] which were used for these tasks in Sunbird 0.2 are now obsolete.
== 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
==== Sunbird ====
Sunbird's current event/task dialog is defined in [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/eventDialog.xul eventDialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/eventDialog.js eventDialog.js]
The publishing 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 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 ====
Lightning's event/task 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].
Lightning's publish dialog lives in [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-publish-dialog.xul calendar-publish-dialog.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/base/content/calendar-publish-dialog.js calendar-publish-dialog.js]. At the time of this writing, its functionality is suspect.
==== Shared UI ====
None yet. It is hoped to soon unite the publish dialogs, and implement the goToDate dialog in Lightning.
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/resources/content/pref/ pref/] folder. The files [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/pref/prefBird.xul prefBird.xul] and [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/pref/prefBirdOverly.xul prefBirdOverlay.xul] correspond to preferences that were used in the calendar.xpi, which is no longer supported.
==== 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 ==
The alarm system is currently undergoing a rewrite in [https://bugzilla.mozilla.org/show_bug.cgi?id=298358 Bug 298358].
== 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.
== 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.
= Potential Pitfalls =
One of the most confusing aspects of the Sunbird code is often the fact that there are actually two calendar.xul files. One can be found at [http://lxr.mozilla.org/mozilla/source/calendar/resources/content/calendar.xul resources/content/calendar.xul] and the other at [http://lxr.mozilla.org/mozilla/source/calendar/sunbird/base/content/calendar.xul sunbird/base/content/calendar.xul]. This is a vestige of the original sharing of code between Sunbird and the calendar extension. The Sunbird build process uses the calendar.xul in the sunbird/ folder. When making changes to one calendar.xul, please make changes to the other. It's still theoretically possible to build the calendar extension, and we'd like to keep this possibility around as long as possible.
