Calendar:Dev Guide

2008-07-04T17:28:12Z

Jamescat: /* Alarms */

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



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

Help:Calculation

2008-07-04T17:26:45Z

Jamescat: /* Without putting the result on the page */

The software does not allow calculations, but one can use a [[piped link]] to a calculation with Google's calculator, with the label as answer, to demonstrate the numbers used in the computation. This way one can check for consistency, see the result with a higher accuracy, and also conveniently update the result.

E.g., in the case of the population density in the [[w:Netherlands|Netherlands]]:

<nowiki>[[google:16318199/33883|482/km²]]</nowiki>, giving [[google:16318199/33883|482/km²]].

With a suitable browser the evaluated expression pops up, so the link is useful even without following it.

Suppose that someone updates the population figure but not the density, than the next person can see that the density is not based on the latest figure, replace the first number, press Preview, follow the link, copy the new result to the link label, and save. Thus the update requires a minimum of effort.

Unfortunately, the result 482 has to be entered manually and consistency is not automatically maintained.

==Without putting the result on the page==

Alternatively, the user has to follow the link to see the result. Using [[template:popd]] is convenient and there is no redundancy, hence no worry about consistency:

<nowiki>{{popd|16318199|33883}}</nowiki> gives:

{{popd|16318199|33883}}

MozillaWiki - User contributions [en]

Calendar:Dev Guide

Help:Calculation