Code Manual (ver 1)

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 [[Code Manual|this page]].

== Downloads and Examples ==

'''Download''':
* Code: [http://praytimes.org/code/v1/js/PrayTime.js PrayTime.js] (ver 1.2.1, see [[Code ChangeLog|changes log]])
* License: [http://www.gnu.org/licenses/gpl.html GNU General Public License, version 3]

'''Examples''': 
* A simple example: [http://praytimes.org/code/v1/js/examples/simple.htm simple.htm]
* Monthly timetable: [http://praytimes.org/code/v1/js/examples/monthly.htm monthly.htm]
* Yearly prayer times: [http://praytimes.org/code/v1/js/examples/yearly.htm 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 <code>getPrayerTimes</code>) 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:

:<code>'''getPrayerTimes''' (date, latitude, longitude, timeZone)</code>
:<code>'''getDatePrayerTimes''' (year, month, day, latitude, longitude, timeZone)</code> 

The parameter <code>date</code> specifies the date for which prayer times are calculated. You can use <code>new Date()</code> to specify today. <code>latitude</code> and <code>longitude</code> specify the coordinates of the location for which the times are calculated, and <code>timeZone</code> specifies the time offset of the location with respect to the GMT. <code>getDatePrayerTimes</code> is the same as <code>getPrayerTimes</code>, 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 [[Calculation#Definitions|here]] for the definition of the times).

<blockquote>
'''Notes''':
* Daylight saving is included in <code>timeZone</code>. Therefore, you must add +1 to the base time offset if daylight saving is observed in the given date.
* If <code>timeZone</code> 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|formatting functions]].
</blockquote> 

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

:<code>'''setCalcMethod''' (method)</code>

<code>method</code> can be any of the followings:

{| class="wikitable" style="margin: 1em 2.25em 0;"
!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, Leva Research Institute, Qum
|}

More information on the above calculation methods is provided [[Calculation Methods|here]].

<u>'''Example'''</u>

  prayTime.setCalcMethod(prayTime.MWL);

== Asr Method ==

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

:<code>setAsrMethod(method)</code>

The available values for <code>method</code> are listed in the table below:

{| class="wikitable" style="margin: 1em 2.25em 0;"
!Method
!Description  ([[Calculation#Asr|more info]])
|-
| Standard || Shafii, Maliki, Jafari and Hanbali (shadow factor = 1)
|-
| Hanafi || Hanafi school of thought (shadow factor = 2)
|}

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

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

:<code>'''setFajrAngle'''(angle)</code>
:<code>'''setMaghribAngle'''(angle)</code>
:<code>'''setIshaAngle'''(angle)</code>

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 <code>prayTime.setFajrAngle(17)</code>.

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

:<code>'''setDhuhrMinutes'''(minutes)</code>
:<code>'''setMaghribMinutes'''(minutes)</code>
:<code>'''setIshaMinutes'''(minutes)</code>

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

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

:<code>'''setHLAdjustMethod'''(method)</code>

The available values for <code>method</code> are listed in the table below:

{| class="wikitable" style="margin: 1em 2.25em 0;"
!Method
!Description  ([[Calculation#Higher_Latitudes|more info]])
|-
| None || No adjustments
|-
| MidNight || The middle of the night method
|-
| OneSeventh || The 1/7th of the night method
|-
| AngleBased || The angle-based method (recommended)
|}

The descriptions for the above methods can be found [[Calculation#Higher_Latitudes|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:

:<code>'''setTimeFormat'''(timeFormat)</code>

The available values for <code>timeFormat</code> are listed in the table below:

{| class="wikitable" style="margin: 1em 2.25em 0;"
!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 &nbsp; || 4:45
|-
| Float || Floating point number || 16.75
|}

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

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

:<code>'''floatToTime24'''(time)</code>
:<code>'''floatToTime12'''(time)</code>
:<code>'''floatToTime12NS'''(time)</code>

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


[[Category:Code]]