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; left:-500px; top:0px;">
<LAYER name="gToday:normal:agenda.js" src="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.
Then call the gfPop.fPopCalendar()
from the onclick event of the triggering button or image. For example,
<a href="javascript:void(0)" onclick="if(self.gfPop)gfPop.fPopCalendar(document.demoform.dc);return false;">pop me</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. The "if(self.gfPop)" part is used to bypass the call if the engine hasn't been fully loaded when user clicks on it.
NOTE: If you want to use an ASP.NET text box control to serve as the date field, you may need to reference it using document.forms[0].textbox_id instead of document.demoform.dc. Because in ASP.NET the form name is generated dynamically in the server end and the name of the generated html <input> tag is actually the id attribute defined in <asp:TextBox> tag.
Finally, ensure you have the following files in the same directory: (or in other directory specified by the src property of the calendar tag)
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're looking for redirecting the current page to another URL upon any click against the specific date. The solution is actually closer than it appears - we have pre-defined a popup() call in plugins.js that can help you right away:
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. |
| name & id | "default-month:theme-name[:agenda-file[:context-name[:plugin-file]]]" -- [] 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; left:-500px; top:0px;"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 "src" and "name" properties are required in the <layer> tag, and they have the same meaning as the ones in <iframe>. They are embraced by the <iframe> tag so as not to be parsed by other browsers.
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.