PrayTimes.org

Code Manual

From Pray Times

(Difference between revisions)
m (→Adjusting Parameters)
m (→Tuning Times)
 
(30 intermediate revisions not shown)
Line 1: Line 1:
-
PrayTimes is a small program providing a set of handy functions to calculate prayer times for any date and location, based on a variety of calculation methods currently used in Muslim communities.  
+
Pray Times provides a set of handy functions to calculate prayer times for any location around the world, based on a variety of calculation methods currently used in Muslim communities.  
-
PrayTimes is originally written in JavaScript. This manual provides information on how to use PrayTimes on a web-page or JavaScript-based widget to compute prayer times for any given time and location.
+
The code is originally written in JavaScript. This manual provides information on how to use the code on a web-page or a JavaScript-based application to display prayer times.
-
 
+
== Downloads and Examples ==
-
== Download and Examples ==
+
'''Download''':
'''Download''':
-
*Latest release: [http://praytimes.org/code/js/prayTimes.js prayTimes.js] (ver 2.0)
+
* Code: [http://praytimes.org/code/v2/js/PrayTimes.js PrayTimes.js] (3 KB, minified and gzipped)
-
*License: [http://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0 Unported]  
+
* Version: 2.3 (see [[Code ChangeLog|changes log]])
 +
* License: [http://www.gnu.org/licenses/lgpl.html GNU LGPL v3]
'''Examples''':  
'''Examples''':  
-
* A simple example: [http://praytimes.org/code/js/examples/simple.htm simple.htm]
+
* A simple example: [http://praytimes.org/code/v2/js/examples/simple.htm simple.htm]
-
* Monthly timetable: [http://praytimes.org/code/js/examples/monthly.htm monthly.htm]
+
* Monthly timetable: [http://praytimes.org/code/v2/js/examples/monthly.htm monthly.htm]
-
* Yearly prayer times: [http://praytimes.org/code/js/examples/yearly.htm yearly.htm]
+
* Yearly prayer times: [http://praytimes.org/code/v2/js/examples/yearly.htm yearly.htm]
 +
 
 +
'''See Also''':
 +
* Older Version: [[Code Manual (ver 1)| Version 1]]
 +
* [[Code|Code in Other Languages]] (Python, PHP, Java, Objective-C, C#, etc.)
== General Usage ==
== General Usage ==
Line 20: Line 24:
The first step for using PrayTimes in a web-page or widget is to include it using a line like this:
The first step for using PrayTimes in a web-page or widget is to include it using a line like this:
-
   <script type="text/javascript" src="prayTimes.js"></script>  
+
   <script type="text/javascript" src="PrayTimes.js"></script>  
-
After including prayTimes.js, an object named prayTimes is created and is ready to use.  
+
After including PrayTimes.js, an object named prayTimes 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:
-
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:
+
   prayTimes.getTimes(new Date(), [43, -80], -5);
   prayTimes.getTimes(new Date(), [43, -80], -5);
Line 45: Line 48:
; coordinates: Specifies the coordinates of the input location as a triple <code>[latitude, longitude, elevation]</code>. Latitude is a real number between -90 and 90, longitude is between -180 and 180, and elevation is a positive number, specifying the height in meters with respect to the surrounding terrain. The elevation parameter is optional. Examples of valid coordinates are <code>[-43.2, 80.6]</code> and <code>[12.5, -25.8, 300]</code>.
; coordinates: Specifies the coordinates of the input location as a triple <code>[latitude, longitude, elevation]</code>. Latitude is a real number between -90 and 90, longitude is between -180 and 180, and elevation is a positive number, specifying the height in meters with respect to the surrounding terrain. The elevation parameter is optional. Examples of valid coordinates are <code>[-43.2, 80.6]</code> and <code>[12.5, -25.8, 300]</code>.
-
; timezone: The difference to Greenwich time (GMT) in hours.
+
; timezone: The difference to Greenwich time (GMT) in hours. If omitted or set to 'auto', <code>timezone</code> is extracted from the system.
-
; dst: Daylight Saving Time: 1 if date is in daylight saving time, 0 otherwise. If omitted, <code>dst</code> is assumed to be 0.
+
; dst: Daylight Saving Time: 1 if date is in daylight saving time, 0 otherwise. If omitted or set to 'auto', <code>dst</code> is extracted from the system.
; format: Output time format, according to the following table:
; format: Output time format, according to the following table:
Line 67: Line 70:
<u>'''Return Value'''</u>
<u>'''Return Value'''</u>
-
<code>getTimes</code> return an associative array containing 9 prayer times (See [[calculation| here]] for the list of times and their definition.) Each time can be accessed thorough its name. For example, if the output of <code>getTimes</code> function is stored in an object <code>times</code>, the time for sunrise can be accessed through <code>times.sunrise</code>.  
+
<code>getTimes</code> return an associative array containing 9 prayer times (see [[calculation| here]] for the list of times and their definition). Each time can be accessed thorough its name. For example, if the output of <code>getTimes</code> function is stored in an object <code>times</code>, the time for sunrise can be accessed through <code>times.sunrise</code>.  
<u>'''Example'''</u>
<u>'''Example'''</u>
Line 93: Line 96:
| Egypt || Egyptian General Authority of Survey
| Egypt || Egyptian General Authority of Survey
|-
|-
-
| Makkah || Umm al-Qura, Makkah
+
| Makkah || Umm al-Qura University, Makkah
|-
|-
| Karachi || University of Islamic Sciences, Karachi
| Karachi || University of Islamic Sciences, Karachi
-
|-
 
-
| Jafari || Shia Ithna Ashari (Ja`fari)
 
|-
|-
| Tehran || Institute of Geophysics, University of Tehran
| Tehran || Institute of Geophysics, University of Tehran
 +
|-
 +
| Jafari || Shia Ithna Ashari (Ja`fari)
|}
|}
-
More information on the above calculation methods is provided [[Calculation#Fajr_and_Isha|here]].
+
More information on the above calculation methods is provided [[Calculation Methods|here]].
Line 122: Line 125:
!Values
!Values
!Description
!Description
-
!Example  &nbsp;
+
!Sample Value
|-
|-
| rowspan="2" | imsak  
| rowspan="2" | imsak  
Line 131: Line 134:
| fajr || degrees || twilight angle || 15
| fajr || degrees || twilight angle || 15
|-
|-
-
| zuhr || minutes || minutes after mid-day || 1 min
+
| dhuhr || minutes || minutes after mid-day || 1 min
|-
|-
| rowspan="2" | asr
| rowspan="2" | asr
Line 172: Line 175:
!Description
!Description
|-
|-
-
| Standard || The middle of Sunset to Sunrise
+
| Standard || The mean time from Sunset to Sunrise
|-
|-
-
| Jafari || The middle of Maghrib to Fajr
+
| Jafari || The mean time from Maghrib to Fajr
|}
|}
Line 190: Line 193:
| OneSeventh || The 1/7th of the night method
| OneSeventh || The 1/7th of the night method
|-
|-
-
| AngleBased || The adaptive angle-based method
+
| AngleBased || The angle-based method (recommended)
|}
|}
Line 196: Line 199:
<u>'''Example'''</u>
<u>'''Example'''</u>
-
   prayTimes.adjust( {fajr: 16, zuhr: '5 min', asr: 'Hanafi', isha: 15} );
+
   prayTimes.adjust( {fajr: 16, dhuhr: '5 min', asr: 'Hanafi', isha: 15} );
-
 
+
== Tuning Times ==
== Tuning Times ==
Line 205: Line 207:
:<code>'''tune''' (offsets)</code>
:<code>'''tune''' (offsets)</code>
-
<code>offsets</code> is an associative array containing time offsets in minutes for each prayer time.  
+
where <code>offsets</code> is an associative array containing time offsets in minutes for each prayer time.  
Line 211: Line 213:
   prayTimes.tune( {sunrise: -1, sunset: 3.5} );
   prayTimes.tune( {sunrise: -1, sunset: 3.5} );
 +
 +
<blockquote>
 +
'''Notes''':
 +
* By default, PrayTimes rounds minutes to the nearest values. To round a specific time up, you can tune it by&nbsp;+0.5 minutes, and to round it down, you can tune it by&nbsp;-0.5 minutes.
 +
* Tuning is the last step after calculating step, and thus, it has no effect on the calculation parameters. For example, if Isha is set to be 90 minutes after sunset, tuning sunset by 5 minutes will not push Isha forward.
 +
</blockquote>
-
; Note 1.: By default, PrayTimes rounds minutes to the nearest values. To round a specific time up, you can tune it by&nbsp;+0.5, and to round it down, you can tune it by&nbsp;-0.5 minutes.
+
[[Category:Code]]
-
; Note 2.: Tuning is the last step after calculating step, and thus, it has no effect on the calculation parameters. For example, if Isha is set to be 90 minutes after sunset, tuning sunset by 5 minutes will not push Isha forward.
+

Latest revision as of 02:18, 11 May 2011

Pray Times provides a set of handy functions to calculate prayer times for any location around the world, based on a variety of calculation methods currently used in Muslim communities.

The code is originally written in JavaScript. This manual provides information on how to use the code on a web-page or a JavaScript-based application to display prayer times.

Contents

Downloads and Examples

Download:

Examples:

See Also:

General Usage

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

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

After including PrayTimes.js, an object named prayTimes 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: 

 prayTimes.getTimes(new Date(), [43, -80], -5);

There are several functions for adjusting calculation parameters. For example, we can call the following function (before calling getTimes) to change the calculation method to ISNA: 

 prayTimes.setMethod('ISNA');

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

Get Prayer Times

The following function is used to retrieve prayer times for a given date and location:

getTimes (date, coordinates, timezone, dst, format)

The input parameters are described below:

date
The date for which prayer times are calculated. You can use new Date() to specify today. Date can be also entered as a triple [year, month, day]. For example, [2009, 2, 26] specifies February 26, 2009.
coordinates
Specifies the coordinates of the input location as a triple [latitude, longitude, elevation]. Latitude is a real number between -90 and 90, longitude is between -180 and 180, and elevation is a positive number, specifying the height in meters with respect to the surrounding terrain. The elevation parameter is optional. Examples of valid coordinates are [-43.2, 80.6] and [12.5, -25.8, 300].
timezone
The difference to Greenwich time (GMT) in hours. If omitted or set to 'auto', timezone is extracted from the system.
dst
Daylight Saving Time: 1 if date is in daylight saving time, 0 otherwise. If omitted or set to 'auto', dst is extracted from the system.
format
Output time format, according to the following table:
Format Description Example
24h 24-hour time format 16:45
12h 12-hour time format 4:45 pm
12hNS 12-hour format with no suffix   4:45
Float Floating point number 16.75

Return Value

getTimes return an associative array containing 9 prayer times (see here for the list of times and their definition). Each time can be accessed thorough its name. For example, if the output of getTimes function is stored in an object times, the time for sunrise can be accessed through times.sunrise.

Example 

 var times = prayTimes.getTimes(new Date(), [43, -80], -5);
 document.write('Sunrise : '+ times.sunrise)

Set Calculation Method

There are several conventions for calculating prayer times. The default convention used in PrayTimes is Muslim World League. You can change the calculation method using the following function:

setMethod (method)

method can be any of the followings:

Method Description
MWL Muslim World League
ISNA Islamic Society of North America
Egypt Egyptian General Authority of Survey
Makkah Umm al-Qura University, Makkah
Karachi University of Islamic Sciences, Karachi
Tehran Institute of Geophysics, University of Tehran
Jafari Shia Ithna Ashari (Ja`fari)


More information on the above calculation methods is provided here.


Example 

 prayTimes.setMethod('Makkah');

Adjusting Parameters

The calculating parameters can be adjusted using the following function:

adjust (parameters)

parameters is an associative array composed of any number of the following parameters:

Parameter Values Description Sample Value
imsak degrees   twilight angle 18
minutes minutes before fajr 10 min
fajr degrees twilight angle 15
dhuhr minutes minutes after mid-day 1 min
asr method asr juristic method; see the table below Standard
factor shadow length factor for realizing asr 1.7
maghrib degrees twilight angle 4
minutes minutes after sunset 15 min
isha degrees twilight angle 18
minutes minutes after maghrib 90 min
midnight method midnight method; see the table below Standard
highLats method higher latitudes adjustment; see below None


asr methods
Method Description (more info)
Standard Shafii, Maliki, Jafari and Hanbali (shadow factor = 1)
Hanafi Hanafi school of tought (shadow factor = 2)


midnight methods
Method Description
Standard The mean time from Sunset to Sunrise
Jafari The mean time from Maghrib to Fajr


higher latitudes methods
Method Description (more info)
None No adjustments
NightMiddle The middle of the night method
OneSeventh The 1/7th of the night method
AngleBased The angle-based method (recommended)


Example 

 prayTimes.adjust( {fajr: 16, dhuhr: '5 min', asr: 'Hanafi', isha: 15} );

Tuning Times

You can further tune calculated prayer times (for precaution) using the following function:

tune (offsets)

where offsets is an associative array containing time offsets in minutes for each prayer time.


Example 

 prayTimes.tune( {sunrise: -1, sunset: 3.5} );
Notes:
  • By default, PrayTimes rounds minutes to the nearest values. To round a specific time up, you can tune it by +0.5 minutes, and to round it down, you can tune it by -0.5 minutes.
  • Tuning is the last step after calculating step, and thus, it has no effect on the calculation parameters. For example, if Isha is set to be 90 minutes after sunset, tuning sunset by 5 minutes will not push Isha forward.
Retrieved from "http://praytimes.org/wiki/Code_Manual"
Personal tools