Hello World - The beginner's guide

The vision of CalendarXP is to keep it simple outside while powerful inside. Most of the time, all you need to get a beautiful calendar on your page is to append the following tags to the bottom of your page.

<iframe width=174 height=189
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 3 HTML tags: <iframe>, <ilayer> and <layer>, but we take them together as a whole unit - the calendar tag.

How to summon it then? Well, just call the gfPop.fPopCalendar() from anywhere of your page. For example,

<a href="javascript:void(0)" onclick="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.

Where is the Hello World then? Yeah, please append the following line to the agenda.js and select the date of Sep 23, 2002 from the calendar.

fAddEvent(2002,9,23, "Hello World!", "alert('Hello World!')", "#87ceeb", "dodgerblue");

You may use numbered values like "#87ceeb" instead of literal names to specify the colors.

Calendar Tag - IFrame

The <iframe> of the calendar tag is the main calendar engine with support for all supported browsers except NN4.(NN4 will simply skip this tag and go for the <layer> tag directly.) It has the following important properties:

Property Name Description
src Loading the script engine "ipopeng.htm". You may also specify absolute path here.
name & id "default-month:theme-name[:agenda-file[:context-name[:plugin-file]]]".
  • default-month should be set in an array like [year, month]; or you may use the predefined gToday variable to bring up the current month. It determines which month to show up when there is no date selected or the date field is empty.
  • theme-name denotes the name of the theme used to render the calendar; It should be prepended with absolute path if the theme files are not placed together with the engine file.
  • agendar-file is the js file that defines all your agenda events and holidays. It should be prepended with absolute path if the agenda file is not placed together with the engine file. It can also be set to share another calendar's agenda store, detailed in setup agenda & holidays tutorial. It's optional.
  • context-name declares the naming space of the calendar engine so that you can access the build-in calendar functions & variables using context-name.function-or-variable from your page. If you don't specify, the engine will by default create one called "gfPop".
  • plugin-file is the js file that contains all plugin functions. We'll talk about it in details later. If not specified, the engine will try to use the plugins.js file sitting together with the engine file.
Note: The name and id of <iframe> must be exactly the same.
width & height The default width and height of calendar panel in pixels. They are set for browsers that don't support iframe resizing, like IE4 and Opera. They are deprecated! You don't need them any more.
style It must have at least the following properties "visibility:visible; z-index:999; position:absolute; left:-500px; top:0px;"
These properties are mandatorily set and you shouldn't change unless you know what you are doing.
scrolling & frameborder They should always be set to "no" and "0".

Calendar Tag - Layer

The <layer> of the calendar tag is the Netscape 4 engine. You may leave it out if your website doesn't need to support NN4. Only "src" and "name" properties are required in the <layer> tag, and they have the same meaning as the ones in <iframe>. It is embraced by the <iframe> tag so that it won't be parsed by other browsers.

Calendar Trigger - fPopCalendar() function

To show up the calendar, you need to call the fPopCalendar() with proper context-name, usually "gfPop". This function has 4 important parameters that will help you to manipulate the date:

gfPop.fPopCalendar(dateCtrl [,dateRange [,posLayerId [,posCtrl]]]);

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:

[RangeBeginDate,RangeEndDate,SafeMonth,DisabledDate1,DisabledDate2,...]

  • RangeBeginDate, RangeEndDate denote the valid date range. Dates fall out of this range will be disabled. They should be set in an array format like [year,month,day].
  • SafeMonth is the month to be shown when the default-month of the calendar tag falls out of the valid range. If you don't specify it or if itself falls out of the valid range, the calendar will refuse to popup and give you a warning message. It should be set in an array format like [year,month].
  • DisabledDate# is the other dates within the valid range that you want to disable. You may have as many as you like. Each of them should be set an array format like [year,month,day]. They are optional.

This is a very useful and powerful feature to constrain the valid date range on-the-fly.

posLayerId

The name of the layer tag that contains the localizer tag. It's optional. You'll need to specify it when the localizer of your date field is located within a <layer> or <ilayer> tags. You'll also need it if your date field is within an <iframe> and you want to pop the calendar across the frame border(above the iframe).

Please check out the CrossFrame demo for details. And 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. 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.

 

Summary

We now know that the preceding sample actually says - pop a calendar under the document.demoform.dc form field using the "normal" theme, initialized by the current month and loaded with all agendas and holidays from agenda.js. After picking a date, the selected date will be set to the value property of document.demoform.dc.

Please see Hello World Demo for a live demo.


Copyright © 2001-2003 CalendarXP.net, Liming Weng