|
|
|
|
A Brief History of the JavaScript Event CalendarThe core concept of displaying a single month's calendar on-demand, in an HTML table, with embedded events, came from a JavaScript example that I found on the 'net. It was limited to the 12 months of the current calendar year, allowed you to step a single month at a time (no jumping directly to a month), had the JavaScript source code embedded in the current HTML page, and was rather difficult to maintain events (it required editing an array of strings, one for each month, with each event description preceded by the day number and a delimiter character). I undertook a major re-write of the original code, including the following:
Meanwhile, because I was working on a calendar for my synagogue, I began to search for ways to easily include Jewish holidays and other information in the calendar. I didn't want to build that functionality into the JavaScript code; it made more sense to me to include them in the event list. The challenge was to find a way to automatically generate an event list containing Jewish holidays etc. Again, I found what I needed on the 'net: a marvelous Jewish calendar utility. It produces an ASCII list of dates and event descriptions. so I wrote a simple filter (available on my download page) to translate the list into JavaScript calls to the DefineEvent( ) function. It would then be easy to copy and paste these calls into my HTML page, or better yet, simply save t hem as a .JS file and reference it from my calendar page.
How to Use the Calendar ScriptYou will need to add two small things to your HTML page, and you'll have a fully functional calendar. The first addition is a directive to include the external JavaScript program that does all of the work. Just add the following to your HTML file. It can go anywhere BEFORE the point where you want to display the calendar. It does NOT need to be between the <html> and </html> tags, so if you wish you can conveniently place it at the VERY TOP of your HTML file.
(You need to have the CALENDAR.JS program on the web server, in the directory where your HTML file is. You can get the CALENDAR.JS file from my download page.) Then, at the exact location where you want the calendar to appear, include the following:
The first line indicates the beginning of an in-line JavaScript program. The second line is a tricky way to make sure that older versions of browsers (that don't understand JavaScript) don't "blow up"; they'll simply ignore the rest of the script. The third line is the important one: it displays the calendar. The fourth line is another trick for "Java-impaired" browsers, and the fifth line ends the script program. By calling the Calendar( ) function without first defining any events, and without overriding any of the default configuration settings, you get a calendar with the following characteristics:
(To actually see how this looks, study my first example.)
How the Calendar Knows What Month to DisplayWhen you display the calendar it shows the current month. When you click on one of the hyperlinks (to step to the previous month, to the next month, or to jump to any month in the drop-down list), that month is displayed. It is important to understand how this works. The Calendar( ) function defined in the CALENDAR.JS file examines the URL string for the current page. If it finds a querystring value in the form ?YYYYMM it will display that month. Otherwise, it will display the current month. The hyperlinks simply direct the client browser back to the current page, with an explicit month in the URL string. For example, if your page is called "mycalendar.html," and your web site lives under "www.mydomain.com," a user who visits http://www.mydomain.com/mycalendar.html will see the calendar for the current month. Clicking on a hyperlink for, say, February 2003 will redirect the client's browser to http://www.mydomain.com/mycalendar.html?200302. It is important to be aware of this, especially if you need to include other values in the URL string.
How to Define EventsThe CALENDAR.JS file that you include in your HTML page contains a function called DefineEvent( ) that you can call in your page prior to calling Calendar( ) to display the calendar. For example, I can include my birthday and my anniversary for 2003 as follows:
Notice that you call DefineEvent( ) for each event, passing in the parameters as defined above. You can define the events in any order you wish. The event description can include embedded HTML tags for formatting. For example, you can set the font size, color, or other attributes (bold, blink, etc.). Don't forget to use a closing </> tag for each tag that you use! If you wish, you can include a hyperlink and/or an image. The hyperlink URL and image path will be relative to the current HTML page, so if you like to keep your images in a special subdirectory, remember to include the subdirectory in the image reference. Recall that the default behavior of the calendar is to allow access to January - December of the current year. Each time you add an event, the range is automatically expanded to include the month in which the event occurs. Thus, if the code above is processed anytime during 2002, the resulting range will be January 2002 - November 2003. If it is processed anytime during 2004, the resulting range will be July 2003 - December 2004. And if it processed anytime during 2003, the resulting range will remain January 2003 - December 2003. (It is easy to override the range after you have defined the events.) (To actually see how this looks, study my second example.)
How to Use External Files to Define EventsIf you have a lot of events, and you regularly maintain/update the list, and would rather NOT edit your HTML code each time you need to make a change, you can easily put all of your event definitions in a separate file. In fact, you can use MULTIPLE external files, one for each type of event. For example, on my synagogue's web page, I set up two event files, one containing the "standard" Jewish holidays etc., and the other containing specific events for my synagogue. To illustrate the point, here are abbreviated versions:
To include all of the events in these two external files, use the following lines in your HTML page:
(To actually see how this looks, study my third example.)
How to Override the Default Configuration SettingsIn addition to containing all of the source code for the Calendar( ) and DefineEvent( ) functions, the CALENDAR.JS file defines several variables and initializes them to default values. By overriding these defaults just before you call Calendar( ), you can alter the appearance of the calendar to suit you tastes.
(For an illustration, study my second example.)
How to Use the JEC.EXE FilterIf you have a large number of events to define, the syntax of the DefineEvent( ) function can become tedious. You can download my filter program that transforms a plain ASCII list of events into a series of calls to DefineEvent( ). JEC is a DOS program (no, really; I'm not kidding!) that reads "standard input" and writes "standard output." The input is a series of events, one per line, in the following format:
JEC produces output as a series of calls to DefineEvent( ), one per line, in the following format:
For example:
If you have this information in a file (for example, EVENTS.TXT) and you tell JEC to process the file, it will produce the following output:
You can use the DOS command syntax to have JEC automatically write this information to a file. For example, the following command runs JEC, taking its input from a file called EVENTS.TXT and writing its output to a file called EVENTS.JS:
At this point you could edit the EVENTS.JS file if desired, to add hyperlinks and/or images in the DefineEvent( ) calls.
How to Create Events with the HEBCAL ProgramThe JEC filter program is very useful if you are using Danny Sadinoff's Hebcal Program to generate events from the Jewish calendar. The default output format of HEBCAL happens to be the exact input format for which JEC was designed. For example, running HEBCAL with the following syntax:
produces the following results:
Using the DOS "pipe" command syntax, you can send the output from HEBCAL directly into JEC, and from there save it in a file called, for example, HEVENTS.JS:
The HEVENTS.JS file would contain:
HEBCAL accepts various command line options (refer to the HEBCAL documentation); any options that you specify will affect the selection of events that are passed through JEC. For example, you can choose to suppress or include Rosh Chodesh, candlelighting times, standard holidays, yahrzeits, etc. Using these tools, it is possible to take much of the manual editing out of the process of creating the calendar. You can be even more creative; for example, run one pass of HEBCAL and JEC to produce a file of standard holidays, and a separate pass to produce just the candlelighting times (in a separate file!). Then edit the .JS file containing the candlelighting times, and use global search and replace to insert a candlesticks image reference, width, and height on all of the lines (replacing the "", 0, 0 at the end of each line). Then run a third pass to produce just the names of the parshiyoth, and again use global search and replace to insert a Torah scroll image reference! By creating separate JS files using HEBCAL and JEC, you can let your editor do more of the work for you.
CreditsAlthough I was not able to find a ready-made calendar that was EXACTLY what I was looking for, I did stumble across an EXCELLENT first draft, along with a large number of other free JavaScript samples, on a site called Cut-n-Paste JavaScript. (Unfortunately, that site is no longer available.) Tackling the arcane details of the Jewish calendar and its relationship to the Gregorian calendar that rules our lives was something I hoped to avoid. Just when I thought I would have to dive into the code, I found a tremendous implementation - Danny Sadinoff's Hebcal Program. Among its other versatile features, this remarkable little program can generate a list of events paired with their Gregorian dates. The events include the Jewish holidays, Rosh Chodesh, days of the omer, names of the parshiyoth, Shabbat, havdalah, and holiday candlelighting times (based on your location), as well as yahrzeits. By default it generates the dates for the current year, but it can be directed to do any year or any month or even any individual day. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
