modules/holidays/API.txt

<!-- $Id: API.txt,v 1.1 2008/01/06 12:03:33 mooffie Exp $ -->

<!--
          NOTE:
          This document is outdated. It only mentions the Jewish calendar.
		  But for the meantine it's better than nothing.
		  
		    -->

<h2>The API</h2>

<p>The most important part of the code is the <code>JewishCalendar</code> PHP class.
It contains the 'brain' that calculates the holidays. It is derived from
the base class <code>NativeCalendar</code>, so you should add also this to the
bundle. The rest of the code, including the GUI you see here, is
considered a demonstration of how to use this class and is appropriately
contained in files having 'demo' in their names (e.g. 'demo.php').</p>

<p>Here's a taste of the API:</p>

<pre>
require_once 'NativeCalendar.php';

$jcal = NativeCalendar::factory('Jewish'); // In the future there may be Drivers
                                           // for other calendars.

$jcal->settings(array(
  'language' => CAL_LANG_NATIVE, // Speak in Hebrew, not English.
  'diaspora' => FALSE,           // We don't live abroad.
  'eves'     => TRUE,            // Give us 'Erev Rosh HaShana' too.
));

// Let's print the holidays for the next 20 days.

$timestamp = time();

for ($n = 20; $n--; ) {
  print 'Holidays for '. date('Y-m-d', $timestamp) .":\n";
  foreach ($jcal->getHolidays($timestamp) as $holiday) {
    print "   $holiday[name]\n";
  } 
  $timestamp += 60*60*24; // Advance to the next day
}
</pre>

<p>The output of this snippet is:</p>

<pre>
Holidays for 2007-09-20:
Holidays for 2007-09-21:
   ערב יום הכיפורים
Holidays for 2007-09-22:
   יום הכיפורים
Holidays for 2007-09-23:
Holidays for 2007-09-24:
Holidays for 2007-09-25:
Holidays for 2007-09-26:
   ערב סוכות
Holidays for 2007-09-27:
   סוכות
Holidays for 2007-09-28:
   חול המועד סוכות
Holidays for 2007-09-29:
   חול המועד סוכות
Holidays for 2007-09-30:
   חול המועד סוכות
Holidays for 2007-10-01:
   חול המועד סוכות
Holidays for 2007-10-02:
   חול המועד סוכות
Holidays for 2007-10-03:
   הושענא רבה
Holidays for 2007-10-04:
   שמיני עצרת
&lrm;   שמחת תורה
Holidays for 2007-10-05:
Holidays for 2007-10-06:
Holidays for 2007-10-07:
Holidays for 2007-10-08:
Holidays for 2007-10-09:
</pre>

<p>Let's have another script...</p>

<pre>
// Print today's date:
print $jcal->getLongDate(time()) ."\n";

// Now in English:
$jcal->settings(array('language' => CAL_LANG_FOREIGN));
print $jcal->getLongDate(time()) ."\n";

// When did the first man land on the moon?
print $jcal->getLongDate('1969-07-20') ."\n";
</pre>

<p>...which outputs:</p>

<pre>
ח' תשרי ה'תשס"ח
8 Tishrei, 5768
5 Av, 5729
</pre>

<h2>Localization</h2>

<p>The calendar comes speaking in two languages: Hebrew and English. But
you can make it speak any other language. This is due to the fact that
all English strings --month names and holiday names-- are enveloped in a
special function. Mavens will recognize this as "the Gettext method of
localizing strings." I chose the name 't' for this function.</p>

<p>In some projects you'd use various <code>gettext</code> tools to
extract (see <a href="JewishCalendar.pot">JewishCalendar.pot</a>) and
translate the strings, but it's actually enough to implement a
simple-minded <code>t()</code> function in your script. Here's an
example:</p>

<pre>
require 'NativeCalendar.php';

$jcal = NativeCalendar::factory('Jewish'); // In da future they may be drivers
                                           // fo otha calendars.
$jcal->settings(array(
  'language' => CAL_LANG_FOREIGN,
  'diaspora' => TRUE,
));

function t($s) {
  static $table = array(
    'Tishrei' => 'Teeshre',
    'Erev Rosh HaShana' => 'Justa little bit before da start of da year.',
    'Rosh HaShana I' => 'Da start of da year.',
    'Rosh HaShana II' => 'Anotha start of da year, man. See? There be two.',
    'Yom Kippur' => "Da 'No TV' day.",
    'Tsom Gedalya' => 'Rememba poor Gedalya, OK?',
    'Sukkot' => "You's squizin' yo' TV inside this thingy a here.",
  );
  if (isset($table[$s])) {
    return $table[$s];
  } else {
    return $s;
  }
}

// Dig dis:
print $jcal->printCal(2007, 9);
</pre>

</div> <!-- LTR -->
1	<!-- $Id: API.txt,v 1.1 2008/01/06 12:03:33 mooffie Exp $ -->
2
3	<!--
4	NOTE:
5	This document is outdated. It only mentions the Jewish calendar.
6	But for the meantine it's better than nothing.
7
8	-->
9
10	<h2>The API</h2>
11
12	<p>The most important part of the code is the <code>JewishCalendar</code> PHP class.
13	It contains the 'brain' that calculates the holidays. It is derived from
14	the base class <code>NativeCalendar</code>, so you should add also this to the
15	bundle. The rest of the code, including the GUI you see here, is
16	considered a demonstration of how to use this class and is appropriately
17	contained in files having 'demo' in their names (e.g. 'demo.php').</p>
18
19	<p>Here's a taste of the API:</p>
20
21	<pre>
22	require_once 'NativeCalendar.php';
23
24	$jcal = NativeCalendar::factory('Jewish'); // In the future there may be Drivers
25	// for other calendars.
26
27	$jcal->settings(array(
28	'language' => CAL_LANG_NATIVE, // Speak in Hebrew, not English.
29	'diaspora' => FALSE, // We don't live abroad.
30	'eves' => TRUE, // Give us 'Erev Rosh HaShana' too.
31	));
32
33	// Let's print the holidays for the next 20 days.
34
35	$timestamp = time();
36
37	for ($n = 20; $n--; ) {
38	print 'Holidays for '. date('Y-m-d', $timestamp) .":\n";
39	foreach ($jcal->getHolidays($timestamp) as $holiday) {
40	print " $holiday[name]\n";
41	}
42	$timestamp += 606024; // Advance to the next day
43	}
44	</pre>
45
46	<p>The output of this snippet is:</p>
47
48	<pre>
49	Holidays for 2007-09-20:
50	Holidays for 2007-09-21:
51	ערב יום הכיפורים
52	Holidays for 2007-09-22:
53	יום הכיפורים
54	Holidays for 2007-09-23:
55	Holidays for 2007-09-24:
56	Holidays for 2007-09-25:
57	Holidays for 2007-09-26:
58	ערב סוכות
59	Holidays for 2007-09-27:
60	סוכות
61	Holidays for 2007-09-28:
62	חול המועד סוכות
63	Holidays for 2007-09-29:
64	חול המועד סוכות
65	Holidays for 2007-09-30:
66	חול המועד סוכות
67	Holidays for 2007-10-01:
68	חול המועד סוכות
69	Holidays for 2007-10-02:
70	חול המועד סוכות
71	Holidays for 2007-10-03:
72	הושענא רבה
73	Holidays for 2007-10-04:
74	שמיני עצרת
75	&lrm; שמחת תורה
76	Holidays for 2007-10-05:
77	Holidays for 2007-10-06:
78	Holidays for 2007-10-07:
79	Holidays for 2007-10-08:
80	Holidays for 2007-10-09:
81	</pre>
82
83	<p>Let's have another script...</p>
84
85	<pre>
86	// Print today's date:
87	print $jcal->getLongDate(time()) ."\n";
88
89	// Now in English:
90	$jcal->settings(array('language' => CAL_LANG_FOREIGN));
91	print $jcal->getLongDate(time()) ."\n";
92
93	// When did the first man land on the moon?
94	print $jcal->getLongDate('1969-07-20') ."\n";
95	</pre>
96
97	<p>...which outputs:</p>
98
99	<pre>
100	ח' תשרי ה'תשס"ח
101	8 Tishrei, 5768
102	5 Av, 5729
103	</pre>
104
105	<h2>Localization</h2>
106
107	<p>The calendar comes speaking in two languages: Hebrew and English. But
108	you can make it speak any other language. This is due to the fact that
109	all English strings --month names and holiday names-- are enveloped in a
110	special function. Mavens will recognize this as "the Gettext method of
111	localizing strings." I chose the name 't' for this function.</p>
112
113	<p>In some projects you'd use various <code>gettext</code> tools to
114	extract (see <a href="JewishCalendar.pot">JewishCalendar.pot</a>) and
115	translate the strings, but it's actually enough to implement a
116	simple-minded <code>t()</code> function in your script. Here's an
117	example:</p>
118
119	<pre>
120	require 'NativeCalendar.php';
121
122	$jcal = NativeCalendar::factory('Jewish'); // In da future they may be drivers
123	// fo otha calendars.
124	$jcal->settings(array(
125	'language' => CAL_LANG_FOREIGN,
126	'diaspora' => TRUE,
127	));
128
129	function t($s) {
130	static $table = array(
131	'Tishrei' => 'Teeshre',
132	'Erev Rosh HaShana' => 'Justa little bit before da start of da year.',
133	'Rosh HaShana I' => 'Da start of da year.',
134	'Rosh HaShana II' => 'Anotha start of da year, man. See? There be two.',
135	'Yom Kippur' => "Da 'No TV' day.",
136	'Tsom Gedalya' => 'Rememba poor Gedalya, OK?',
137	'Sukkot' => "You's squizin' yo' TV inside this thingy a here.",
138	);
139	if (isset($table[$s])) {
140	return $table[$s];
141	} else {
142	return $s;
143	}
144	}
145
146	// Dig dis:
147	print $jcal->printCal(2007, 9);
148	</pre>
149
150	</div> <!-- LTR -->