This new version comes as a result of many hours of coding work by Ian Tyndall along with contributions from Andrew Reutter and others in the prototype community. A big thanks to everyone who contributed to this version, especially Ian.

For this release, we’ve set up a new project website at http://scal.fieldguidetoprogrammers.com. The new site is packed with documentation and live examples of scal v0.2 in action.

At this point, there will be no further development or changes for v0.1. Also, I’ll be changing over all of the scal links on this site to point to pages on the new project sub-domain.

Strange bits of code, tricks and tips about Drupal and WordPress, along with other fluff will continue to appear in this space from time to time. However, most of my energy will be spent working on a complete waste of time new novel.

Happy Coding!

I chose Google’s project hosting because it was quick and easy. They have a nice wiki too and simple issue tracker too.

Scal’s svn repository

If you are interested in joining the project, drop me an email with your Google account. Of course, anyone can checkout the code with anonymous access. Just click on the source tab once you hop over to the project page.

The latest version of scal (v0.2) is in the trunk. v0.1 is archived under branches.

The latest version of scal cleans up the code tremendously. We have Ian Tyndall to thank for the vast majority of these changes. Thomas Walpole also contributed some great prototype knowledge to the early development of this version.

Props aside, when you start cleaning up messy code, you end up finding a lot of ways to do things better. That’s a nice way of saying that Ian’s trimmed the fat from scal.

The latest version of scal is not 100% backwards compatible with the old version. In fact, you may wonder if there is anything left of the old scal when you look under the hood.

That said, I know many people have built custom styles for scal. This is the one area where everything ought to work as before (though there are two minor changes to the main css file to deal with cell border issues).

Changes

Here is a brief summary of the upcoming changes. It is not exhaustive. New documentation is being written along with samples and a nice unit test suite.

CSS:

Removed border for dayselected classes (scal and googleblue). That’s it.

Properties:

selecteddate – Replaced/merged with currentdate (this was always a bit confusing, the docs even say so)

Public Methods:

buildCalendar – No longer needed. Instantiating the scal class now builds the calendar.
getCalendar – Redundant function.
openCalendar – Replaced by toggleCalendar
closeCalendar – Ditto
showCalendar – Ditto, plus it was a bit redundant

Private Methods:

prevmonth – Replaced by _switchMonth (up/down)
nextmonth – Replaced by _switchMonth (up/down)

Methods Untouched:

setCurrentDate(date)
updateDayValue(week,day,value)

Download

While in pre-release, scal v0.2 is only available here as a zip archive. This includes the new unit tests along with the scal code and styles. Please feel free to post comments here about the latest version.

scal_0.2.zip

I am in the process of adapting it for use on the iPhone. I’ve done two things:

1) Hammered out the attached css. The css comes pretty darn close to emulating the look
and feel of the calendar app on iPhone, without using any images. In
safari, you even get the drop shadows, though the Safari
implementation on iPhone, lamely enough, does not support the entirety
of webkit.

The one presentation aspect I was unable to duplicate without diving
into your Javascript was that the calendar app on iPhone always
highlights the current day, even if it is not the selected day. Were
you to modify scal.js to assign a specific class name to the current
day, I would be able to do so. I think it has applicability beyond the
iPhone.

2) Made _very_ minor changes to scal.js to remove the dependency on
Scriptaculous. If you change lines 141 and 142 to read:

this.openeffect = this.options.openeffect || function(e)
{$(e).style.display = ‘block’;};
this.closeeffect = this.options.closeeffect || function(e)
{$(e).style.display = ‘none’;};

then I believe your code would work just fine without including
Scriptaculous. On a mobile device, every byte counts, and with your
durations set to 0 the effect is no different than using Appear/Fade.
I would go so far as to recommend this change in your default codebase
- people can still use effects if they want to pass them in, but don’t
need Scriptaculous if they don’t want effects. There might, of
course, be implications I’m not considering, but I just made the
change to get past the fact that Appear was not defined; I am not
using open/close links on my calendar anyway.

I think adding a style class to the current day is a fantastic idea. I’m going to include that in the next release.

Andrew’s style is in the current scal.css. I’ve renamed it “iphonic”, to remove any chance Apple might see this as a confusing use of their trademarks. To see it in action, just check out the front page of the site. I’ve added iphonic as a style option in the tester.

Also, as Andrew notes above, the switch out for Scriptaculous open and closing may or may not work. More testing needs to happen in this area, but from a design standpoint I’d like to abstract scal from Scriptaculous a bit. Nothing against Scriptaculous. I just think the control would benefit from having Scriptaculous as an add-on and not a requirement.

scal test page

I have a number of little functions I work with when I’m trying out new scal additions. Over time, I’ll add them to the “suite”, but for the moment at least there is a nice tester without my mugshot floating in the background.

I recently picked up scal and started putting it to use. During this, I’ve made some minor enhancements that you might be interested in.

I’ve removed the dependency on Builder and replaced it with the functionality of the new dom builder from prototype 1.6.0_rc1.

I’ve added destroy functionality to remove the observables when the calendar is closed.

Besides this, I only made minor performance/syntax enhancements.

Minor enhancements? There are 40 differences between these two versions of scal and Ian is responsible for the lot. A big thanks!

You know, it’s funny how these things happen. Just two days ago I read this post on Kangax’s website:

Refactoring with Prototype

I’m not surprised to see prototype code that sucks. Been there, done that (and I’m sure still doing it) – nobody is perfect. What surprises me though is how ridiculous some explanations (of writing crappy code) sound. “I don’t really know javascript. I do PHP professionally” is my favorite. Don’t get me wrong, I understand that experience and deep understanding of language is essential for writing smarter code. It could be a real challenge to wrap your mind around some of the dynamic concepts of such languages as javascript. That I can understand. What I don’t understand, though, is how people don’t follow some of the fundamental principles of programming. Do we really need to know javascript to prevent repetition, unnecessary constructions or poor optimization? I seriously doubt it

Kangax goes on to give a clinic on prototype/javascript. And as Kangax has gently suggested I clean up scal, I hang my head in shame that Ian had to come to the rescue before I could get to it.

About 50 people a day wander in here and check out scal. I know a few are using it as I’ve had comments via email, so I’m inspired to dig in and keep hacking away at this control. I hope everyone finds it useful.

Important note about scal v0.1b8:

Prototype v1.6.0_rc1 is REQUIRED. You won’t get far with the previous release of prototype (as you might expect from Ian’s comments).

Since I’ve already developed a calendar control using the Prototype js and scriptaculous frameworks, I have the basic materials I need to build the widget.

Before you begin, you might want to take a look at the Dashboard Widget Tutorial on Apple’s Developer site. I found it helpful, though ultimately I wanted to dig into the code. You probably do to, so let’s take a look at the structure of a Widget.

The Widget Structure

Any widgets you’ve installed on your system are stored in ~/Library/Widgets. If you look at that directory in the Finder, you will see something like this:

The Widget application file is an archive, just like most Mac applications. This means you can open it up and see what’s going on under the hood. You can also hack it if you want (customize menus, images, even code in some places). This is one of the hallmarks of the MacOS and OSX. Well, maybe that’s a bit strong. Let’s just say the feature has been around for awhile and it’s kinda cool.

To reveal the contents of the widget, right click on the icon and choose “Show Package Contents”. This will open the archive as a folder and show you all the goodies inside.

[TIP] If you are a TextMate user, you can just drag the icon of the widget onto TextMate. This will launch a new project using the Widget’s folder and give you easy editing access to all of files inside the Widget.

The basic structure of a Widget is pretty simple. You have index.html, info.plist, a couple of png image files, and a stylesheet. The images are used by Dashboard to show placement when you add the Widget and as an icon in the list of Widgets. The plist file holds the base information about the control (name, size, etc). The index.html file is of course where the action takes place.

The screenshot above shows a lot of files in addition to the basic four. Don’t be scared. These files are just the support files for prototype and scriptaculous and my calendar control (scal).

Scal Widget

Download Scal Widget (ZIP)

Once you’ve downloaded and expanded the ZIP archive, you can double-click the Scal.wdgt file to install the control in Dashboard. However, as I said above, you could also right click on the icon and choose “Show Package Contents” to open the widget as a folder. Lastly, I set up Scal to use the “dashblack” theme, so if nothing else you can see how not-close my CSS is to Apple’s.

samplecal = new scal('samplecal',updateyear,{titleformat:'mmmm yyyy',closebutton:'X',dayheadlength:2,weekdaystart:0});
// note that updateyear does not appear in quotes.
// This means that scal will call a function in my
// code named updateyear() when someone clicks on a cell.

function updateyear(){
   $('samplecal_value').update( samplecal.selecteddate.format('mmmm dd, yyyy'));
};

// Here is the sample update function.  I have a div in my HTML called samplecal_value.
// The updateyear() function, updates that value with the selecteddate property of the
// samplecal object (which is a Javascript Date object).

The format function above is actually an addition I made to the Date object. This is already included in scal.js.

As noted in the source, I borrowed this function from Hector Rivas’s article at http://www.codeproject.com/jscript/dateformat.asp. I’ve reproduced that here so that you can see the various formats available to you when constructing your Date format.

Date.prototype.format = function(f)
	{
	    if (!this.valueOf())
	        return ' ';

	    var d = this;

	    return f.replace(/(yyyy|mmmm|mmm|mm|dddd|ddd|dd|hh|nn|ss|a\/p)/gi,
	        function($1)
	        {
	            switch ($1.toLowerCase())
	            {
	            case 'yyyy': return d.getFullYear();
	            case 'mmmm': return scalmonthnames[d.getMonth()];
	            case 'mmm':  return (scalmonthnames[d.getMonth()]).substr(0, 3);
	            case 'mm':   return (d.getMonth() + 1);
	            case 'dddd': return scaldaynames[d.getDay()];
	            case 'ddd':  return scaldaynames[d.getDay()].substr(0, 3);
	            case 'dd':   return d.getDate();
	            case 'hh':   return ((h = d.getHours() % 12) ? h : 12);
	            case 'nn':   return d.getMinutes();
	            case 'ss':   return d.getSeconds();
	            case 'a/p':  return d.getHours() < 12 ? 'a' : 'p';
	            }
	        }
	    );
	};

I do not recommend using the planner when you are using a compressed calendar style (i.e. one that does not show the day cell). Of the sample styles, iscal is probably the best to use.

Below is a basic usage example I sent back to the suggester in email. Enjoy!

> I really liked your idea about adding events to scal. The static
> building of the calendar each month is a bit of a drag. So, I’ve
> added a new “planner” property that automatically sets the DayValue
> for a cell. You probably noticed the updateDayValue function in the
> list. The new function is called setPlannerValue. This function
> ties a bit of text to a particular day, and if we are displaying that
> month at the moment the day cell is filled in accordingly.

> Here’s how it might look using the sample code on
> http://www.fieldguidetoprogrammers.com:

samplecal = new scal('samplecal',updateyear,{titleformat:'mmmm yyyy',closebutton:'X',dayheadlength:2,weekdaystart:0});
// new code
samplecal.setPlannerValue(2007,8,28,"Here be dragons!");
// end new code
samplecal.showCalendar();

> Doing this would cause the text “Here be dragons!” to show up in the
> day cell for 8/28/2007. If you skipped off to September or November
> and then came back to August 2007, “Here be dragons!” would appear
> accordingly on the 28th.

> You could also pass in styled HTML instead of plain text, so this
> should cover your color coded bar idea too (which is a good one). I
> suspect that your styled HTML could also contain some nifty code to
> flash a pop-up on mouseover that would enable you to expand the event
> information. That seems like it would be easy to do with scriptaculous.