Code Manual (ver 1)

From Pray Times

Latest revision as of 05:53, 17 March 2011

This manual describes how Pray Time JavaScript code (version 1) can be used on a web-page or application. For a newer version of the code (version 2), please see this page.

Downloads and Examples

Download:

• Code: PrayTime.js (ver 1.2, see changes log)
• License: GNU General Public License, version 3

Examples:

• A simple example: simple.htm
• Monthly timetable: monthly.htm
• Yearly prayer times: yearly.htm

General Usage

The first step for using PrayTime in a web-page or widget is to include it using a line like this:

 <script type="text/javascript" src="PrayTime.js"></script> 

After including prayTime.js, an object named prayTime is created and is ready to use. We can immediately get the prayer times (using the default settings) from this object. For example, to get today's prayer times for a location with latitude 43, longitude -80 and time zone -5, we can call:

 prayTime.getPrayerTimes(new Date(), 43, -80, -5);

There are several functions to adjust various prayer times calculation parameters. For example, we can call the following function (before calling getPrayerTimes) to change the calculation method to ISNA:

 prayTime.setCalcMethod(prayTime.ISNA); 

Details of the functions available in PrayTime along with their description are provided below.

Get Prayer Times

There are two main functions for retrieving prayer times for a given time and location:

getPrayerTimes (date, latitude, longitude, timeZone)

getDatePrayerTimes (year, month, day, latitude, longitude, timeZone)

The parameter date specifies the date for which prayer times are calculated. You can use new Date() to specify today. latitude and longitude specify the coordinates of the location for which the times are calculated, and timeZone specifies the time offset of the location with respect to the GMT. getDatePrayerTimes is the same as getPrayerTimes, except that instead of receiving a Date object as the first parameter, it receives the date as a triple of <year, month, day>.

Both functions return an array of size 7 containing the times <Fajr, Sunrise, Dhuhr, Asr, Sunset, Maghrib, Isha> for the given date and location (see here for the definition of the times).

Notes:

• Daylight saving is included in timeZone. Therefore, you must add +1 to the base time offset if daylight saving is observed in the given date.
• If timeZone is omitted (or is set to 'auto') during calling the above two functions, prayTime will detect the time-zone (including daylight saving) automatically from the browser.
• You can change the format of the times returned by the above functions using formatting functions.

Set Calculation Method

There are several conventions for calculating prayer times. The default convention used in PrayTime is Jafari (Ithna Ashari). You can change the calculation method using the following function:

setCalcMethod (method)

method can be any of the followings:

More information on the above calculation methods is provided here.

Example

 prayTime.setCalcMethod(prayTime.MWL);

Asr Method

The juristic method for computing Asr can be set using the following functions:

setAsrMethod(method)

The available values for method are listed in the table below:

The default juristic method used in PrayTime is Standard. You can change it to Hanafi by calling prayTime.setAsrMethod(prayTime.Hanafi).

Adjusting Functions

Apart from the general functions available for determining the calculation methods, one can also adjust calculating parameters using the following set of function:

setFajrAngle(angle)

setMaghribAngle(angle)

setIshaAngle(angle)

The angle parameter defines the twilight angle (in degrees) that should be used to calculate the corresponding time. For example, to set the Fajr twilight angle to 17 degrees, one can call prayTime.setFajrAngle(17).

There are also a set of functions for adjusting the times by defining the time differences in minutes:

setDhuhrMinutes(minutes)

setMaghribMinutes(minutes)

setIshaMinutes(minutes)

In setDhuhrMinutes function, minutes specifies the time difference between mid-day and Dhuhr. In setMaghribMinutes function, minutes specifies the time difference between Sunset and Maghrib. In setIshaMinutes function, minutes specifies how many minutes after Maghrib should be considered as Isha. For example, to set Maghrib as 15 minutes after Sunset, we can use prayTime.setMaghribMinutes(15).

Adjustment for Higher Latitudes

In locations at higher latitude, twilight may persist throughout the night during some months of the year. Several solutions for this problem has been implemented in PrayTime that can be set using the following function:

setHLAdjustMethod(method)

The available values for method are listed in the table below:

The descriptions for the above methods can be found here. The default method used in PrayTime is MidNight.

Formatting Functions

The default time format used to output prayer times in calculating functions is 24-hour format. The time format can be changed using the following function:

setTimeFormat(timeFormat)

The available values for timeFormat are listed in the table below:

For example, to change the output format from 24-hour to 12-hour, it suffices to call prayTime.setTimeFormat(prayTime.Time12).

If the times are maintained in floating points, the following functions can be used to change them to other time formats:

floatToTime24(time)

floatToTime12(time)

floatToTime12NS(time)

For example, calling the function prayTime.floatToTime12(15.2) returns the string 3:12 pm.