As the summer winds down here in beautiful, increasingly overcast Washington state, I have to face certain facts.  Fact: if I don’t get that stationary trainer set up, I’m not going to ride my bicycle this winter.  Fact: I really, really need a haircut.  Fact: I’m not going to implement the ‘due date’ functionality in my homework hand-in web application by the time school starts again in two weeks.  This last fact is sad, but not tragic, especially since I got other Really Important Stuff done this summer.  And I got figured out how to use jQuery with a calendar sort of control/widget, starting with choosing a date (or time) picker for my web app.

To be clear, my motivation is that I want a a DHTML date/time picker that will make my otherwise plain old input form that much better.  There’s no AJAX involved here, just DHTML interactive goodness.  I’m going to use the jQuery / jQuery UI stuff because it’s easy to use, elegant, and because I’m planning on using it for other things, in the future.  I’ll be continuing to use CakePHP for the backend, since it’s ‘convention over configuration’ approach is refreshingly XML-free, their MVC abstraction is clean, and their ORM implementation is quickly and easily used.

After much fiddling, I’ve decided on one date/time picker control to use.  I’ve also found some strategies for trying this stuff out.  So I’ll start by talking through the strategies, then I’ll talk about the contenders, then finally I’ll call out the winner.  If I have time, I’ll walk you through using the winner in my next post (which will include nitty-gritty details like the exact CakePHP code you’ll need to use   )

Suggested strategy for deciding on a UI widget/control:

In general, this seemed to work well:

1. Find a widget
   This is the ‘Google around for it’ stage.  You’re just looking for options at this point.
2. Look through the control’s home page, paying special attention to the demo page
   The home page will help make it clear how polished/full-featured the control is.  It should contain a link to a page that contains clear documentation for all the options, and the documentation should contain code samples.  Especially for projects run by individuals, sample code is crucial for figuring out how the author expects you to use it.

   You really, really want to find a ‘demo page’, which shows off the UI widget.  Not only will this let you quickly get a feel for how the widget works, but will serve as a complete, working example for the ‘copy locally’ step (#4, below).

3. Repeat the above steps until you find something that you like
   ‘Nuff said
4. Copy the demo page into a local directory & make sure it works
   The local directory can either be something in the file system, or something that’s served up by a web server that you’ve got control over.  XAMPP is perfect for this step.

   The real goal here is to make sure that you’ve got everything working, so that when you go to integrate it into CakePHP, you’ve got a working copy to compare your Cake-ified version to.  This is especially useful if you’re making local copies of the various libraries & files that the control depends on.

   This step can also be useful to make sure that you can make the control appear (and behave) the way you want, before investing time to Cake-ify it.

5. Cake-ify it
   First get the UI part to work, then verify that you can get the data you need back to the server (back to the Cake controller).  Then, and only then, should you fiddle with the control’s options extensively.

Having outlined my suggested strategy for figuring out which control you want, let’s look at the options that I found.  These aren’t the only options, but these are the ones that I found, that seemed to work well.

The Contenders:

Cake’s default date/time picker

Figure 1: Cake’s default control(s) for a DATETIME field

While not actually jQuery based, I figured that I’d point this out just because of how quick-and-easy this is to program.  It’s built into Cake (obviously), and so you don’t have to do much for this to work.  Just use the FormHelper’s input method on a database field that’s a DATETIME, and Cake takes care of the rest. 

Cake auto-magically provides the user with a collection of drop-down menus that let the user safely pick out the date and time, as shown in Figure #1.

If you’ve got something that doesn’t need to be AJAX-y, this is an option worth considering, simply because of how fast, easy, and reliable it is.

jQuery’s Datepicker

Home Page: http://docs.jquery.com/UI/Datepicker

Demo Page: http://jqueryui.com/demos/datepicker/ 
(there’s another demo in the home page, too)

  
Figure 2: The jQuery UI’s Datepicker control

This is the only date/time picker that’s a standard part of the jQuery UI, so it’s easy to get your hands on, easily documented, and you can get CDN-hosting benefits.  The upside of this is that it’s really nicely done – solid documentation, full-featured, and easy to use.  As you can see in Figure 2, above, Datepicker supports the jQuery UI ThemeRoller custom themes, slide-out visual effects, and such nice perks as having the widget ‘output’ a differently formatted string into another form field (in this case it’s outputting "Thursday, 17 December, 2009" into the text input field on the right).  

The major downside is that this control only allows the user to pick the date.  If you want to pick the time as well, you’re on your own – there aren’t any time-picking widgets in the standard jQuery UI.  So the Datepicker widget is a great choice if you’ve got a DATE field in your (MySQL) database, and want the user to have a slick, calendar-based way of picking a date.

A word of warning: You’ll need to watch the format – the default format for the Datepicker isn’t the exact same as the MySQL DATE format, which will cause problems for CakePHP.  You’ll need to use one of the format parameters to make sure that the Datepicker widget puts a properly formatted string into the text field, so that Cake can auto-convert it).

An aside: what if you want to use the Datepicker as part of a solution?

Let’s say that we want the user to be able to pick both the date AND the time.  One option would be to use a separate DATE and TIME field in the database, and have each one nicely tied to a single jQuery widget.  This will make the UI fairly straightforward, but will then complicate later queries.  If we’re interested in determining if the student’s homework submission is late, we’d have to do convoluted queries like "An assignment is be late if it was handed in after the due DATE, or if it was handed in on the due DATE and after the TIME it is due").  Questions like ‘How many days late is the submitted homework’ should be even more fun

Luckily , MySQL provides both DATETIME and TIMESTAMP data types – they appear to be pretty much identical (which clearly indicates that I just haven’t researched the differences enough   ).  They can be compared directly, and there are PHP routines for dealing with DateTimes (http://us.php.net/manual/en/class.datetime.php), so using a single DATETIME in the database layer, and multiple input fields in the UI layer, seems like a reasonable approach.

The jQuery Datepicker doesn’t do anything with time, but we’ve got a couple of options.  The worst option is to set up the Datepicker’s format string to include an arbitrary, unchanging time (e.g., "12:00:00"), but if we’re going to do that, then why waste the space & effort on recording the time at all? 

If we’re not going to hard-code a time into the field, then we’ll have to ask the user for for the time using a separate widget.  We can do this using two separate widgets in the UI layer.  The question then becomes "Where should I merge those two separate fields into the single DATETIME field?  In JavaScript (on the web page), or in PHP (in the Cake controller method)?"  A friend who’s been doing web programming for a while says that doing such merging work in PHP (in the controller method) is the way to go.  Thinking about it, I agree with him, mostly because using JavaScript to manipulate the automatically generated Cake input form fields seems brittle.  The various arrays (mostly $this->data) in the controller seem much more stable.  For example, the documentation clearly defines the format used, and this definition is so fundamental to how Cake works that it would be a major, breaking change for them to alter it.  An added bonus for putting this ‘merging’ logic into the controller is that the UI can display anything you want, so long as your controller code can parse the fields, then merge and reformat the fields into a single, properly formatted DATETIME string that Cake’s model code is expecting.

So if you’re going to use the jQuery UI’s Datepicker widget to let your users pick the date/time, then you’ll probably want to have a second field that will allow them to pick the time, and then merge these two fields into one DATETIME in the Cake controller method.

timepickr

Home Page: http://haineault.com/media/jquery/ui-timepickr/page/

Demo Page: (at the top of the home page)

Figure 3: The timepickr widget

This widget only picks out the time – there’s no support for picking out the date.  I’m only  mentioning this control at all in case you want to use the approach of providing a Datepicker to pick the date, and something like this timepickr to pick the time.

As you can see in Figure 3, above, the widget is a tad odd.  Essentially, you click on the field ( "{suffix}", in this case), and then the first row of numbers pops out beneath it.  You then choose the hour ("06", in Figure 3) by moving your mouse over it, and the next row pops out.  You then select the minutes ( "30" ), and finally AM/PM (unless you’re using a 24 hour timepickr). 

It’s a really nice interface, actually – not one I would have thought of, but once you use it a couple times, it works really well.

dtpicker

Home Page: http://code.google.com/p/jquery-dtpicker/

Demo Page: http://jquery-dtpicker.vndv.com/

 Figure 4: The dtpicker widget

This is the first combined date and time picker widget that I found.  It’s very similar to the timepickr control, in the sense that you click on the input form (in Figure 4, above, I clicked on the text field under the "event" label), and it displays the first column of choices – the years, in the above figure.  Once you move the mouse over a year, it lets you pick the month ( "March" ), then a range of days ("20-29"), then a specific day ( "22" ), then an hour ( "09:" ), then a minute ( "20 ).  It’s a slick interface, and I liked it.  I could quickly and easily pick out the date and time that I wanted, especially after the timepickr widget familiarized me with how this style of widget worked.

There are two reasons that I didn’t go with with widget.  First, I wanted something that looks like a calendar, since this will be used to pick out due dates for homework assignments.  It’s invaluable to see how far apart dues are, visually, so that it’s clear how much time (a week?  two weeks?) the students will have to work on any given project.  Secondly, this widget doesn’t appear to play nicely with Cake’s CSS ‘out of the box’.

A word of warning: Watch out for the type of the input field that you attach the dtpicker to.  The dtpicker doesn’t appear to work when attached to a text input (e.g., <input type="text">), but instead you must attach it to one of the custom "date" input types that it requires (e.g., <input type="date">)

dyndatetime

Home Page: http://code.google.com/p/dyndatetime/

Demo Page: http://www.mechanicalmarksy.com/hosted/toolman/dyndatetime/example.html

Figure 5: The dyndatetime widget

As you can see in Figure 5, above, the dyndatetime widget looks like a calendar with a space for time at the bottom.  You activate it by clicking on something (in this case, the button labeled ‘PICKER", but you can attach it to the text field instead).  The widget then appears on the screen, and you can pick the time, then pick the date.  The time picker isn’t entirely intuitive (you can SHIFT+Click to increase the hour/minute individually, or you can click-and-hold on the hour (or minute), and then drag the mouse left or right to adjust the time), but once you figure it out, it works pretty well.

The Winner: dynDateTime

dyndatetime, based on the based on Dynarch date time calendar, is what I’m going to use.  It looks pretty slick, seems to work well, and will produce a single field that contains both date and time. 

It seems to be reasonably full-featured, including things like formatting the input field one way, and then formatting another field in a different way.  This will make it easy to have a field that Cake’s server-side code will use to automatically populate the DATETIME database field. 

There’s also a bunch of pre-fab .CSS and language options, too, so you can customize how it looks, or which language you’ll be using it with.  Speaking of which, dyndatetime’s CSS plays pretty well (but not perfectly) with Cake’s default CSS, which is nice.  Generally, there are lots of nice options (http://code.google.com/p/dyndatetime/wiki/Home), and the date/time formatting that can both support MySQL’s DATETIME, and more human-readable formats.

I am looking at using jQuery and AJAX as a means of making some of my forms in my StudentTracker© web app more streamlined.  Currently, I’m dynamically creating forms so that all the students’ assignments are listed on a single page, no matter how many assignments there are.  By putting each item into a separate form element (i.e., one text field for the student-visible name, another for the number of points it’s worth, etc, etc), I can allow the user (me!   ) to edit each one directly and in-place, without having to visit a separate page for each assignment.  This approach works well, even in spite of the ‘reload the entire page after each edit’ workflow that StudentTracker’s non-AJAX pages use.  The problem is that if I wanted to use, say, jQuery to create a rich user experience, it seems like I’d need a way to generate some JavaScript code per element, in order to do things like send AJAX messages back to the server when a form element gets changed. 

After thinking about it for a while, I’m not so sure that’s true.  I think that for my situation, not only will it be possible to use jQuery to handle a bunch of different elements individually, but it will actually be better to go with that approach.  I say this with the confidence of one who hasn’t actually tried it yet

That said, I was playing around with both CakePHP and some simple jQuery, and thinking that if I could use (Cake)PHP to write jQuery code directly into my JavaScript file then I could dynamically generate some JavaScript to go with my dynamically generated form.  Specifically, I wanted the PHP page that generated the JavaScript to have access to all the PHP variables that I have defined in my Cake view.  I also wanted to do so using an approach that could be reused within the Cake controller, if I chose.

After thinking about it, I’ve come up with a fun, clever, very very hack-y way to do it.  It’s so much fun, in fact, that I’m posting it here, even though I think I’ve got a better way to accomplish my original goal .

Side-note: If all you want to do is execute PHP code in your JavaScript file, then you can rename the webroot/js/…/foo.js file to be foo.js.php, and CakePHP will correctly interpret the code first as a normal PHP file.  You’ll need to link to foo.js.php (instead of foo.js), but except for that change, the browser will interpret that file as a JavaScript file.

The problem I have with this solution is that you can’t get to anything from the original context – any local variables in your view (or helpers that your controller defined, etc) will be UNAVAILABLE in the JavaScript-generating PHP file. 

This is because the .js.php file is separate from your controller/view files, which means that the browser needs to make a separate request to the web server to retrieve the JavaScript file – by the time the JS is being served up, the original controller/view methods have long since finished!

I started by asking myself "What about using PHP’s include function?"

include will open a file, pull it’s contents into the current .PHP page, and then evaluate the file’s contents, which is exactly what we want.  What’s also very handy is that the include code will be evaluated as if it really had been pasted into that line, including having access to all the local variables available at the time that include is called.  Incidentally, include with also drop back out of ‘PHP mode’, and into ‘HTML mode’, which we also want.  This mode switch will mean that include will basically ignore anything that’s not wrapped in <?php ?> tags, which is perfect.

At first blush, this seems like it should solve the problem easily and elegantly – we can pull the .js file into the view/controller, and evaluate all the (Cake)PHP elements in the file with full access to the view’s local variables.

But include this doesn’t quite work, because it will (effectively) paste the included (JavaScript) code directly into the controller/view method.  Instead, what we want is to have include do it’s work, and then have it hand us a string that contains results of that work (i.e., the evaluated contents of the included file).

Luckily for us, the PHP manual page spells out how to do exactly this.  We can use output buffering to include the file, then put that into a string.  My code below is basically a simple variation on http://us3.php.net/manual/en/function.include.php – specifically the "Example #6 Using output buffering to include a PHP file into a string"

I said to myself "Let’s put this logic into a function and call it!"

The code that I got from the PHP manual wasn’t the most tricky thing in the world, but it wasn’t really something I wanted to have littered throughout my CakePHP code.  So putting this into a function is a natural and normal way to place it into a well-understood and reusable package.

The only problem is that if we call include from a function, then all of that function’s local variables will be in scope, and so we won’t be able to access the controller/view’s variables.

I told myself that I’d finally found a fun reason to use PHP’s eval function!

The basic approach is to define a string that is valid PHP code for including the JavaScript file.  The output buffering goes into this block, too, but I’m going to leave most of the error-checking/input massaging out of this example to keep things simple.  When PHP’s eval is called on the block, then it will execute the ‘include’ statement, in the context of the eval line.

Because the code runs in the context of the eval line, we should should be clear any variables that we create (or stomp on) will still exist after the call to eval is done.  (By ’stomp on’, I mean ‘overwrite’.)  Because of this, we shouldn’t create local variables (or stomp on existing variables) in the script that we’ll be evaluating.   We can achieve this by creating a CakePHP helper, having the controller import that helper, and then using instance variables on that helper object instead of local variables.  In order to make that work, we’ll need to have a variable that contains the name of the helper. 

Thus, the final product: the JavascriptEval helper, with instance variables that’ll substitute for parameters and return values (and locals, if I had any).  The code for the helper (and example files to demonstrate the use of the helper) are listed below; if you want a .ZIP file that contains all of these files, you can find it at http://panitzco.com/Files/JavascriptEval_Demo.zip.  All the files in the .ZIP should be set up so that you can extract it into your /app/ directory, and everything will end up where it needs to go. 

You’ll notice that all the action is in the script that the constructor assigns to evalScript, using a heredoc.  Within the script, we check and see if $name_of_javascript_eval_object is defined, and if not, then we assign it a name that should typically work for view code (i.e,. in .CTP files).  Next we check if scriptToEvaluate has been set (it must be set to a file underneath the /app/webroot/js/ directory).  Following that, we assume the file’s name refers to something in the /app/webroot/js/ directory, and so we pre-pend /app/webroot/js/ to the provided script name.  If that file doesn’t exist, then we stop, otherwise we go ahead and include it.

Note the clever use of variable variables to allow someone to re-use this script in, say, a controller, by setting name_of_javascript_eval_object to be something other than the default javascriptEval.  This does mean that we’re creating a local variable in the scope that wants to do the include, but name_of_javascript_eval_object seems like a sufficiently unique name that I just go ahead & create it without checking.  if you wanted to, you could check that it doesn’t already exist and/or unset it before the script ends.

Here’s an example that uses this:

Controller file:

Other than adding the new JavascriptEval class and the core JavaScript class to the helpers array, this really doesn’t do much.

This does a couple of quick unit tests on the provided helper.  It makes sure that the script will detect a missing filename, an incorrect filename, and that it will function correctly when given a correct filename.  Note that the core of this (the ‘typical usage’) boils down to three key steps:

1. Set the scriptToEvaluate field to the relative path of the file within /app/webroot/js/.
2. Use PHP’s eval function on the scriptToEvaluate field
3. Retrieve the scriptResults field, and then use the core JavaScript helper to put the evaluated script into the head of the document.

Note that because the helper assumes that we’ll be using it in a view, we do not need to set the name_of_javascript_eval_object variable. 

This basically contains a bunch of small tests, in order to demonstrate what you can do with this helper.  When you actually use this helper yourself, you’d want to replace the contents of this file with the JavaScript that you want to dynamically generate using (Cake)PHP. 

The first alert confirms that the JavaScript is loading correctly.  We then use PHP to generate a JavaScript string that we’ll use later on.

We then get into the really useful/interesting stuff – since the view imported the Sanitize class, we can use it here.  Similarly, we can use the helpers that the view has access to, such as the $javascript helper.

Following all that, we have an ultra-simple use of jQuery (which I talked about in my prior post)

A better way?

My original motivation for doing this was being able to create JavaScript code that could deal with dynamically created forms.  For example, I might want to create a single page that contains a list of all the assignments the students will do in a term, with a bit of JavaScript/jQuery attached to each item, so that each and every item can have it’s own rich interface (for example, having each item include a datepicker control).

In retrospect, I think that it’s possible (and better) to write the jQuery code so that it will attach event handlers to all of the UI elements (possibly by ‘tagging’ each one with a CSS class), and then just use that one, single, cache-able, normal JavaScript file instead of dynamically generating code for each client.

Still, the above hack is pretty darn cool, and was fun to try out

I’d love to hear if this post helped you out, if you’ve got further questions, or if you’ve got feedback on my blog.

It’s summer time, which means I finally have large(-ish) blocks of free time again.  Of course, with great time comes a great desire to accomplish something satisfying, so naturally I’m thinking about sprucing up my StudentTracker© web app.  I wrote the CakePHP-based version last summer, so that my students could submit their homework online this past year.  It’s worked well, but there’s always that extra something that I want to add to it

One feature that I didn’t quite get to last summer was having due dates for assignments.  This was left out partly because of time constraints, and partly because I realized that I’d hit that stage where “I can always add more features/fiddle with it needlessly!!”, so I stopped working on it.  On top of that, I had tried to use CakePHP’s nascent support for Prototype-based AJAX.  I could never quite get AJAX to work well, owing mostly to the lack of documentation for that (apparently) new feature.  That, plus the odd implementation that I found daunting (it appeared to detect changes in the selection of a drop-down menu using polling).

Of course, having taught for years I am comfortable managing due dates manually.  I tell the students when stuff is due in class, send out email notifying them of changes via the class’s Google Group, etc, etc.

But during this past year, I realized that I really did want to have that due date feature.  Not because it could auto-ding my students, but because it could provide each student with a personalized ‘TODO’ list.  Since StudentTracker knows which assignments each student has handed in, it could use the due-date information to produce a list of assignments that each student still needed to do.  I’d like to continue managing due dates myself so that consistently hard-working students who occasionally get a bit behind don’t get penalized.  StudentTracker can then tell each student what that student still needs to do.

The first step in adding this functionality is to create a way for the instructor to enter due dates for assignments, obviously.  The problem with doing this using normal HTML forms is that entering dates is a bit tricky.  Forcing the user to enter the month/day/year is awkward, and it’s easy to make mistakes.  Plus, when you’re looking to enter the due dates for 20 or more items for each of three classes, this gets real old, real fast.  Think about it – if you want to assign a due date to each of four homework assignments, and their allowed revisions, and the 10 weekly warm-up exercises, and the mid-term and final exams, and possibly the daily, 2-point ‘Are you paying attention?’ quizzes,  you can easily pile up 20-30 due dates per course that you’re teaching.  Multiply that by the number of classes you need to teach to fill out your load (three, in my case), and you can see how entering month/day/year gets tedious.

Thus, my immediate goal is to incorporate a ‘date picker’ UI widget into my web app.

After looking around for a while, I decided to use the jQuery UI’s Datepicker, because it looks nice, seems functional, and because I’ve heard a lot of good things about jQuery.  Plus, jQuery has a FullCalendar plugin that will allow me to (eventually) provide a calendar-based view of all the assignments, along with a drag-and-drop mechanism for changing due dates.  But that, along with my scheme for defining ‘relative due dates’ (to make it easier to move assignments to a new quarter), are topics for future posts.

In this post I’ll talk about how the very basics of using jQuery with CakePHP.  But just the uber-basics of using the jQuery library, and not the jQuery UI.  I’m assuming that you’ve both used jQuery a bit, and that you’ve used CakePHP a bit.  If you want help with their of those technologies on their own, you should search the web for tutorials on them.

Let’s go through the above steps in more detail.

1. Create your normal CakePHP pages

Figure 1: Directory structure

You’ll need to create all the normal CakePHP classes, so you’ll need to create a file that contains your Controller, and a file that contains your View.  For this simple demonstration we’re going to leave out the ‘Model’, but adding that in won’t be difficult.

On the right, you can see a picture of the files, and where they go.  I’ve decided to make the web page that you’ll visit available at http://localhost/Demos/demo/jQueryDemo/, so the controller must therefore be placed in a file named demo_controller.php (in the app/controllers folder).

The contents of the controller file are pretty straightforward, and are included in this post below.  The only tricky parts are setting the $uses field to be an empty array (so that Cake does not try to use any particular model for this model-free controller), and adding the JavaScript helper in the jQueryDemo action (rather than to the entire controller).  You could easily add the JavaScript helper to the entire controller, but if you’re only using it in a limited subset of the actions, then only adding that helper where it’s used prevent clutter.

Just in case it’s useful, I’m also providing a .ZIP file that contains all the files I discuss in this post.  It’s set up so that you should be able to extract this into your app directory, and have the files and folders appear in the correct place.

You’ll notice (in the above code) I want the name of the action to be jQueryDemo, so I’ll need to create a file named j_query_demo.ctp (in the app/views folder).  The contents of this file is a little bit more interesting, as we’ll explore in the next step

2. Link to jQuery

At this point, you’ve got a couple of options.  You can either link to Google’s copy (and thus take advantage of their Content Delivery Network – CDN), or else link to your own, local copy.  Using Google’s copy is easier, but you then rely upon them continuing to provide these files.  Using your local copy means that you don’t need to worry about the files disappearing/changing versions/etc, but then you have to supply them to anyone who visits your site (and thus pay for that bandwidth).

http://encosia.com/2008/12/10/3-reasons-why-you-should-let-google-host-jquery-for-you/ makes a pretty compelling argument that one ought to use Google’s CDN for internet-facing apps, and local copies for LAN-based apps, but you can choose whichever you feel is best for your app.  I’m guessing that linking to Google’s copy and downloading a local backup copy for yourself is probably the best way to go.

We’ll look at what we’ve got here in the <?php ?> element.  Everything else in the file is straight HTML, which we’ll use later on in the jQuery code that we write. (Alternately, you could use Cake to generate some of this HTML, but the overall process is the same)

2a: Link to jQuery (Google’s copy)

This is pretty straightforward.  We’ll use the JavaScript helper that we pulled in back in the controller to link to Google’s copy.  That second ‘false’ parameter says NOT to put the code here (i.e., not to inline it), but instead to put it in the <head> of the document.

The second $javascript->link will create a link to our jQuery code, which (because we’re writing it ourselves) must reside locally.

2b: Link to jQuery (your own, local copy)

This is a tad more involved, just because you need to obtain your own copy of jQuery, and then install it into the app/webroot/js directory somewhere.  The upside is that you don’t have to worry about Google’s copy going away, or changing (such as when the ‘latest’ version changes to something newer), plus this will work if you’re going to deploy your app onto a LAN that might not be connected to the internet.

You can get yourself a copy of the core jQuery library at: http://docs.jquery.com/Downloading_jQuery

I recommend creating a app/webroot/js/jquery folder, just to keep the jQuery libraries (such as the jQuery UI) separated from all your other JavaScript.  You can see this depicted in Figure 1, above.  We’ll use the JavaScript helper that we pulled in back in the controller to link to our copy, as you can see in the code listed below.  That second ‘false’ parameter says NOT to put the code here (i.e., not to inline it), but instead to put it in the <head> of the document.

The second $javascript->link will create a link to our jQuery code, which (because we’re writing it ourselves) must reside locally.

3. Create your own JavaScript file in the app/webroot/js directory, and link to it

The last thing to do is to create a JavaScript file that contains all your jQuery-based code.  In order to use this with Cake’s JavaScript helper, you should put it in the app/webroot/js folder, probably in a sub-folder named for your controller.  In Figure 1 (above) I put the jQueryDemo.js file into the folder app/webroot/js/demo, since the controller is named DemoController.

Remember that we linked to this file in the view (.ctp) file using the line:

    echo $javascript->link(’demo/jQueryDemo’, false);

At this point, we’ve done all the heavy Cake lifting, and from here, it’s all just using jQuery to do what we want.  If you read through a tutorial like http://docs.jquery.com/Tutorials:Getting_Started_with_jQuery, you’ll be up and running with jQuery (and now CakePHP!).  Here’s a quick, commented tour through the jQueryDemo.js file:

4. You’re now off and running with jQuery and CakePHP!

Load up the page, and you’ll see something like:

Once you’ve clicked on the alert box, the top line of text will change and you’ll see something like:

Click that link a couple of times, and you’ll see the bottom line of text update, like so:

I’d love to hear if this post helped you out, if you’ve got further questions, or if you’ve got feedback on my blog.