### Hello World - The beginner's guide

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)"`><span `class="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)

- ipopeng.htm & npopeng.htm - these are so-called engine files (npopeng.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 that MUST exist. It could be empty if nothing needs to be plugged in.
- agenda.js - events & holiday definition file. It could be empty, but you should have it unless it's not defined in 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.

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.

#### Date Format

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.

#### 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/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` 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. It determines which month to show up when there is no pre-selected date (the `gdSelect` theme option is set to [0,0,0]) and the value in the form field is empty or invalid. 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, 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 omitted, the engine will create one named "gfPop". 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.
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".

#### Calendar Tag - Layer

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.

#### Calendar Trigger - fPopCalendar() function

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. ) `[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]`, e.g. [[2000,10,15],[2020,10,15]]. 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]`, e.g. [[2000,10,15],[2020,10,15],[2000,10]] 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. e.g. [[2000,10,15],[2020,10,15],[2000,10],[2003,10,10],[2003,10,11]] This is a very useful and powerful feature to constrain the date range dynamically. It's optional but should be at least set to `null` if other params behind it were used.
posLayerId | The name of the layer tag that contains the localizer tag. It's optional but should be at least set to `null` if other params behind it were used. 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.

#### Summary

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.

Copyright© 2003-2007 Idemfactor Solutions, Inc. All rights reserved.