README

PopCalendar 0.7 Beta (March 15, 2007)

Introduction:

PopCalendar is a flexable JavaScript calendar. In this release, some JavaScript
is required to make use of the calendar. However, in future releases, additional
classes will be provided to simplify common uses of the calendar. PopCalendar 
gets it's name from it's original purpouse, which was having a calendar that
"popped" out of a text input to simplify inputting a date. To create a more
modular component, the calendar has been seperated from the "popping" script into
it's own object. Future releases will include the popping script as well.

Use:

To use popCalendar, upload the popcalendar.js script to your server and include
it in the HTML like this:

<script src="[/path/to/]popcalendar.js" type="text/javascript"></script>

Where [/path/to/] is the optional path if popcalendar.js is not in the same
directory as the current page.

To include a calendar on the page, do this:

<div id="calholder"></div>
<script>
popCalendar.build('calholder');
</script> 

The first argument to popCalendar.build is the ID of the element containing the
calendar. Usually, this should be a <div>. Anything in this element will be
removed. This is useful if you want to create a static calendar on the server,
and use popCalendar to replace it with a dynamic calendar on the client. 

Part of the flexibility of popCalendar is that it has no inline styles - all of
the styles are controlled by CSS. As a result, the calendar will look very plain
without some styling. You can add this to the HTML file to add the default 
styling to the calendar:

<link rel="stylesheet" type="text/css" href="[/path/to/]popcalendar.css" />

The calendar will now look a bit nicer, but it is still not useful. To make the
calendar useful, you can set a function that acts as an event handler when a new
date is selected on the calendar. For example, you could set up an alert that
gives the new date:

replace this:
popCalendar.build('calholder');

with this:
popCalendar.build('calholder', {onchange: function(a){alert(a);}});

This sets the onchange event handler to a new anonymous function which alerts it's
first perimiter. You could also do something more useful, like send the user to
another page depending on the date. For example, in a WordPress blog, you can find
articles by a particular date with a URL like this:
<http://www.paulbutler.org/archives/2007/02/17/>. With popCalendar, we can easily
create a calendar to send us to the posts for each date.

replace this:
popCalendar.build('calholder', {onchange: function(a){alert(a);}});

with this:
function dateUrl(date){
	document.location = "http://www.paulbutler.org/archives/"+date.getFullYear()+"/"+
		(date.getMonth()+1)+"/"+date.getDate()+"/";
	return false;
}
popCalendar.build('calholder', {onchange: dateUrl});

Note that the function returns false. This prevents the new date from being 
highlighted. Since a new URL will be opened anyway, there is no point in changing
the selected date.

Also, note that the function is passed without a pair of brackets. The result is that
the function is passed, not the result of the function.

Several other arguments may be passed to the calendar, which I will explain further
in future documentation.

popCalendar.build returns a new object representing the calendar just built. Some of
the methods and properties of the object are:

selectDate(date) - selects the date given to be highlighted on the calendar
selectedDay - gets the selected day's date object. Do not set this, use selectDate
instead.

License:

Copyright © 2007 Paul Butler <http://www.paulbutler.org/>

This software is provided 'as-is', without any express or implied warranty.
In no event will the authors be held liable for any damages arising from 
the use of this software.

Permission is granted to anyone to use this software for any purpose, 
including commercial applications, and to alter it and redistribute it 
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not 
claim that you wrote the original software. If you use this software in a 
product, an acknowledgment in the product documentation would be appreciated 
but is not required.

2. Altered source versions must be plainly marked as such, and must not be 
misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

A link to http://www.paulbutler.org/ where the project is hosted would be
appreciated, but is not required.