Hello World

Hello World - The beginner's guide

The vision of CalendarXP is to keep it simple outside while powerful inside. Most of the time, to get a calendar shown on your page is as simple as inserting the following tag to wherever you want, just like other HTML tags.

<iframe name="gToday:normal:agenda.js" id="gToday:normal:agenda.js" src="iflateng.htm" scrolling="no" frameborder="0"></iframe>

Yes, as you can tell from the HelloWorld demo, it's very simple and straightforward. We'll reference the above <iframe> tag as the calendar tag from now on.

If you want to support the outdated Netscape 4.x browser, you'll have to add 3 more tags - a <a> and a <img> tag in <iframe> and another <layer> tag at page bottom, as following.

... <iframe name="gToday:normal:agenda.js" id="gToday:normal:agenda.js" src="iflateng.htm" scrolling="no" frameborder="0"> <a name="_spacer"><img width=172 height=180></a></iframe> ... <layer name="gToday:normal:agenda.js" src="nflateng.htm" background="nflateng.htm"> </layer> </body> </html>

Now ensure you have the following files in the same directory where the iflateng.htm is located:

iflateng.htm & nflateng.htm - these are so-called engine files (nflateng.htm is for NN4 and only available in commercial edition).
"theme-name".js & "theme-name".css - these are theme files, e.g. normal.js & normal.css in above example.
plugins.js - plugins file. It could be empty if nothing needs to be plugged in, but MUST exist.
agenda.js - events & holiday definition file. It could be empty, but you should have it there unless you removed it from the name & id 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.

So now, where is the "Hello World"? - Simply append the following line to the agenda.js and click the date of Sep 23, 2002 in 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.

Calendar Tag - iFrame

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/iflateng.htm" or src="../../calendar/iflateng.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` default-month should be set in an array whose first element indicates the year and second one indicates the month, e.g. `"[2003,9]:normal"`; you may also use the predefined `gToday` variable to bring up the current month. theme-name denotes the name of the theme used to render the calendar. It should be prepended with the absolute web path if the theme files were not located together with the engine files, e.g. "gToday:/caltheme/normal". Note that you should not set any domain or protocol prefix before the path. agendar-file is the js file that defines all your agenda events and holidays. It should be prepended with the absolute path if the agenda file were not located together with the engine files, e.g. "gToday:normal:/events/agenda.js". It can also be set to share another calendar's agenda store, more detailed in "Setup agenda & holidays" tutorial. context-name declares the naming space of the calendar engine so that you can access the build-in calendar functions and variables via `context-name.function-or-variable` from your web page. It's NOT available for reference until the page is fully loaded. If it's omitted, you won't be able to reference anything inside the calendar from the container page. plugin-file is a javascript file that contains all plugin functions. We'll talk about it in details later. If omitted, the engine will try to use the `plugins.js` file in the directory where the engine files are located. charset indicates the character set used in the themes, plugins and agenda. e.g. GB2312, ISO-8859-1, etc. Note: The name and id of the <iframe> must be set to exactly the same.
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.
scrolling & frameborder	They should always be set to "no" and "0".

Calendar Tag - Layer

The <layer> tag is dedicated to support the Netscape 4.x browser. Only the name, src and background properties are required in the <layer> tag. The enclosed <a><img></a> works as a placeholder for the calendar. They are embraced by the <iframe> tag so as not to be parsed by other browsers. Please check the Rule#6 in "Netscape 4" tutorial for details.

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.

Summary

We now know that the calendar tag mentioned before actually says - show a calendar using the "normal" theme, initialize it with the current month and load with all agendas and holidays from agenda.js.

If you want a default selected day, you may set the gdSelect option in the theme. 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.

Exercise. What to do if I want to show a calendar default to next month using the supermini theme?

Solution. Simply change the name & id from "gToday:normal" to "[gToday[0],gToday[1]+1]:supermini".