The vision of CalendarXP is to keep it simple outside while powerful inside. Most of the time, to implement a date picker on your page is as simple as appending the following tags to the bottom of your page, just above the </body> tag.
<iframe name="gToday:normal:agenda.js" id="gToday:normal:agenda.js"
src="ipopeng.htm" scrolling="no" frameborder="0"
style="visibility:visible; z-index:999; position:absolute; top:-500px; left:-500px;">
<LAYER name="gToday:normal:agenda.js" src="npopeng.htm"background="npopeng.htm"> </LAYER>
</iframe>
It consists of 2 tags: <iframe> and <layer>, but we take them all together as a whole unit - the calendar tag. NOTE that the <layer> tag is for Netscape 4.x only and you can remove it if you don't need to support this outdated browser.
Then call the gfPop.fPopCalendar()
from the onclick event of the triggering button or image. For example,
<a onclick="if(self.gfPop)gfPop.fPopCalendar(document.demoform.dc);return false;"href="javascript:void(0)"><spanclass="PopcalTrigger">pop me</span></a>
The document.demoform.dc is the form field in which you want
to put the selected date. It can be a text field, a hidden field, a textarea
or even a button, as long as it has a value property. gfPop is the default engine context (or naming space) which can be changed in name & id, more on this later. The "if(self.gfPop)" part is used to guarantee that the calendar won't get called untill it's been fully loaded.
The PopcalTrigger is a marker (you don't need to define it in any css file, it's just a marker) used to identify the trigger element so as to allow the engine show up the calendar when you click on it and hide the calendar when you click elsewhere. It's optional if you use onclick event to trigger the calendar. More details can be found in FAQ - Why the calendar doesn't show up after I chose to use the onmousedown event instead of onclick to trigger the calendar?
Finally, ensure you have the following files in the same directory: (or in other directory specified by the src property of the calendar tag)
We always suggest you put all calendar related files into a separate directory and set the src of the calendar tags to reference them. This makes them more like a self-contained component and is easy for you to maintain in future.
Where is the "Hello World"? - Please append the following line to
the agenda.js and select the date of Sep 23, 2002 from the calendar... Voila!
fAddEvent(2002,9,23, "Hello World!", "alert('Hello World!')", "#87ceeb", "dodgerblue");
Sometimes you may want to redirect the current page to another URL upon any click against a specific date, and we have pre-defined a popup() call in plugins.js to help you:
fAddEvent(2002,9,23, "Hello World!", "popup('http://www.calendarxp.net','_top')", "#87ceeb", "dodgerblue");
Of course, you may use '_blank' as the 2nd parameter for the popup() call so as to pop up a new window instead of redirecting. In addition, numbered values like "#87ceeb" can be used anywhere that accepts literal color names.
The format of the selected date is controlled by the following theme options in the "theme-name".js file.
var gsSplit="."; // separator of date string.
var giDatePos=0; // date format sequence 0: D-M-Y ; 1: M-D-Y; 2: Y-M-D
var gbPadZero=true; // whether to pad the digits with 0 in the left when less than 10.
var giMonthMode=3; // month format 0: digits ; 1: full name from gMonths; >2: abbreviated month name in specified length.
var gbShortYear=false; // year format true: 2-digits; false: 4-digits
The above setting is equal to "DD.MMM.YYYY". In case you need very special format, you may declare fFormatInput and fParseInput plugin functions in the plugins.js to achieve whatever format you like. There is an example detailed in FAQ.
The <iframe> of the calendar tag is the main calendar engine for all supported browsers except NN4. It has the following important properties:
| Property Name | Description |
|---|---|
| src | Loading the script engine "iflateng.htm". You may specify either an absolute path or a relative one here, e.g. src="/calendar/ipopeng.htm" or src="../../calendar/ipopeng.htm", any will do. NOTE: all relative paths set in the following name & id are relative to this src location instead of the container page!! Therefore you don't need to set any path in the name & id if you have all calendar files in one folder. |
| name & id | "default-month:theme-name[:agenda-file[:context-name[:plugin-file[:charset]]]]" -- [] indicates optional
|
| width & height | They are the default initial width and height of the calendar panel. You don't have to specify them most of time. However, the built-in auto-resize function might not work on some certain browser, in which case you may set the width and height manually to be exact the size you need. |
| style | It must have at least the following properties specified: " visibility:visible;
z-index:999; position:absolute; top:-500px; left:-500px;"You shouldn't modify them unless you know what you are doing. |
| scrolling & frameborder | They should always be set to "no" and "0". |
The <layer> of the calendar tag is the engine dedicated to support Netscape 4.x. You may leave
it out if your website doesn't need to support NN4. Only the name, src and background properties are required in the <layer> tag. They are embraced by the
<iframe> tag so as not to be parsed by other browsers.
One important note here is that the src and background properties must be exactly the same - this is a workaround for a bug of NN4.
To show up the calendar, you need to call the fPopCalendar()
with a proper context-name, usually "gfPop". This function has 4 important
parameters that will help you to manipulate the date-picking:
gfPop.fPopCalendar(dateCtrl [,dateRange [,posLayerId [,posCtrl [,posOffset]]]]) -- [] indicates optional
| Parameter | Description |
|---|---|
| dateCtrl | The reference of the form field that stores the selected date. It doesn't have to be a form element. Any object with a "name" and "value" property can be passed in. The name of this object is requried because the engine needs it to identify the corresponding NN4 localizer. |
| dateRange | dateRange is an array in the following format: ( [] is the array operands here. )
This is a very useful and powerful feature to constrain the date
range dynamically. It's optional but should be at least set to |
| posLayerId | The name of the layer tag that contains the localizer tag. It's
optional but should be at least set to You'll need to specify it when the localizer of your date field is located within a <layer>, <ilayer> or any positioned <div> tags in NN4. You'll also need it if your date field is within an <iframe> and you want to pop the calendar outside the frame. (check the CrossFrameDemo) Remember whenever you deal with an <iframe> tag, you must set the name and id of it to be exactly the same. |
| posCtrl | The reference of the localizer tag. The engine will position the calendar right below it. It's optional and if you don't specify one, the engine will take the dateCtrl as the localizer. Note this parameter is designed for browsers other than NN4. The localizer for NN4 will be detailed in the Working with Netscape 4 tutorial. |
| posOffset | An array that overrides the gPosOffset theme option. The engine will position the calendar using the specified offset value. It's optional and if you don't specify one, the engine will use gPosOffset in the theme definition file. This array has a format of [x-offset, y-offset, isFixedPositioning]. Positive values of x-offset and y-offset will make the calendar position lower and righter to the default popup location according to posCtrl or dateCtrl. And if isFixedPositioning is set to true, the default location will be ignored and the calendar will be shown absolutely at position (x-offset,y-offset). |
e.g.
gfPop.fPopCalendar(document.myform.mydate,[[1997,1,1],[2020,12,25],[2003,9]], null,document.getElementById("localizerIE"),[15,10,false]);
This interprets to - using document.myform.mydate as the date input field, using date range started from January 1, 1997 to December 25, 2020 and set the safe month to September 2003, popping up the calendar under the html tag whose id is "localizerIE" and offseting it 15 pixels righter and 10 pixels lower.
We now know that the code in the upmost HelloWorld example actually says - popping up a calendar under the
document.demoform.dc form field using the "normal"
theme, initialize it with the current month and load it with all agendas and holidays
from agenda.js. After a date is picked, it will
be set to the value property of form field document.demoform.dc.
If you want a default selected day, simply set it with appropriate format in the textfield and the calendar will parse and show it up visually. For options like first-day-of-week, colors, fonts and sizes, please take a look at the "Working with themes" tutorial. There are more than 60 options that can be used to control the look and feel of the calendar, all self-documented in the theme files.