Serving up actions as AJAX with jQuery in a few simple steps

Since this tutorial was missing and some people on IRC have been asking questions about when there will be jQuery support in the ajax/javascript helper I decided to write this. I find that helpers are used for generating HTML markup, you don’t see a helper for CSS as it shouldn’t be mixed with inline markup and frankly, the same goes for Javascript.

I like to apply Javascript (especially through the power of jQuery CSS selectors) as a stylesheet to my work to improve versatility. But even if you just want to figure out how to do a basic ajax call with jQuery and Cake here’s the steps you need:

1. Attach jQuery Library
2. Turn on the RequestHandler Component
3. Create and style a div (overlay) in the view to use for ajax populating
4. Choose an action to trigger the AJAX
5. Throw in the jQuery code

Step 1
Throw this in your layout:

echo $javascript->link('http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js');

Step 2
Throw this in your controller of question (or app_controller for all-around ajaxy goodness):

var $components = array('RequestHandler');

Cake will now automatically detect the AJAX headers sent by jQuery and will return the actions with the same views you coded for normal use except now with the ajax layout (by default empty).

Step 3
Add this to your layout or the action you plan to use AJAX in for overlays or population content with:

<div id="overlayer" style="display:none"></div>

Preferably without the initial inline CSS of course

Step 4
The html link we will magically transform with the ‘js-ajax’ class because Javascript just plain shouldn’t be inline:

<?php echo $html->link('Demo', array('controller'=>'posts','action'=>'view',$id), array('class'=>'js-ajax')); ?>

Step 5
Notice how we simply use our class to hijack a perfectly normally working link with it’s already present information to serve up as AJAX? In addition we have the overlayer div fade in on callback so it runs after the ajax loads instead of at the same time. You may want to make some thinking icon appear first as this occasionally takes a second or two.

$('a.js-ajax').click(function() {
    $('#overlayer').load(
        $(this).attr('href')
    , function () {
        $(this).fadeIn(300);
    });
    return false;
});

Want to have a close button on an overlay window on all ajax? You should probably put it in the layout.

<a href="#close" title="Close Overaly" class="close">Close</a>
 
jQuery:
$('#overlayer a.close').click(function () {
    $('#overlayer').fadeOut(300);
    return false;
});

Using TinyMCE with CakePHP

What is TinyMCE?
TinyMCE is a WYSIWYG editor by Moxiecode that you can find here. Its very fast to load (much faster than FCKEditor last time i’ve tried, which is quite a long time ago now, I must admit…), easy to setup and configure. It isn’t as powerful as FCKEditor in terms of text processing, but if all you need is a small WYSIWYG editor to get clean (X)HTML, TinyMCE is your boy.

Installation
First step, of course, is to download TinyMCE. At the time of writing, latest version is 3.2.4.1 and has been for a few months. 3.2.4.1 is very stable. Once downloaded, unpack TinyMCE, and copy just the tinymce/jscripts/tiny_mce folder in /webroot/js. You don’t need the rest of the archive (documentation, examples, etc.) on your webserver.

Configuration
Next step is to implement it in Cake. Its very easy. First, we need to add this to the layout(s) that will be used on the page(s) that will have the editor. Of course, you need to add the javascript helper to your $helpers array in your controller(s) :

PHP Snippet

<?php 
if(isset($javascript)):
    ...
    echo $javascript->link('tiny_mce/tiny_mce.js');
    ...
endif;
?>

Then, for each page that will have a TinyMCE editor, you’ll have to add to the top of the view file :

HTML

<script type="text/javascript">
    tinyMCE.init({
        theme : "simple",
        mode : "textareas",
        convert_urls : false
    });
</script>

By default, there are 2 themes with TinyMCE : ’simple’ and ‘advanced’. You specify the one you want to use on your page with the theme parameter. You can create your own themes or modify the existing ones in the webroot/js/tiny_mce/themes folder. The mode parameter is set here to ‘textareas’, meaning that all textareas of the page will be replaced by TinyMCE editors of the same size. If this behaviour doesn’t satisfy you, check the documentation. The last parameter, convert_urls, is set to false so that TinyMCE doesn’t try to process URLs for images or links.

There are loads of other parameters (All documented here) to customize the way the editor will work. For example, the file_browser_callback allows you to give a js callback function or method to call a custom file browser for the image insertion popup dialog.

If you want to change the way the text in the editor appears, each theme has a css/editor_content.css file that you can modify to match your site’s styles.