nuts and bolts of cakephp

Actually the main focus of this post will be how to creatively use JavaScript and Session::setFlash() to make your app a little more sexy.
(Slightly tweaked to use CakePHP 1.3, although there is nothing special here that you couldn’t do with other versions of cake).

First, I wanted to point out an awesome little library, called jQuery Tools, which comes with a set of really nice widgets, a whopping 5KB in size and its own CDN for easy loading.

To proceed further let’s consider an Articles Controller, where we are adding a new article.

This is something that you should’ve seen at least a few hundred times…

<?php
class ArticlesController extends AppController {
 public function add() {
    if (!empty($this->data)) {
        if($this->Article->save($this->data)) {
          $this->Session->setFlash('Article saved!', 'modal', array('class' => 'modal success'));
        } else {
          $this->Session->setFlash('Article was not saved!', 'modal', array('class' => 'modal problem'));
        }
     }
  }
}
?>

Here we are using a pretty standard approach to write a message to the session by using $this->Session->setFlash().
What usually happens then, is a redirect to some other place where the message is displayed.
In our case the message will be displayed in the same view, using a nice-looking modal/dialog.
Another point to note, is that once the message is displayed to the user, we’ll automatically hide it (let’s say after three seconds).
To further extend the app you might consider disabling (or converting to plain-text) the form fields, and possibly displaying an “Edit” link… though these features are brewing in my app, I thought it would be too much to cover in one example.

Alright, now that we are looking at our familiar add() action, let’s see what tweaks we should do achieve the desired goals listed above.

In our layout, we’ll need to load both the jQuery and jQuery Tools libraries.

This is a snippet to do so using the existing CDN’s (and in CakePHP 1.3 style):

<?php echo $this->Html->script(array('https://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js',
                                         'https://cdn.jquerytools.org/1.1.2/jquery.tools.min.js')); ?>

$this->Html->script() replaced CakePHP 1.2 approach of using $javascript->link(), the rest should be pretty obvious.

Next, let’s consider the view for our add() action:

<?php $this->Session->flash(); ?>
<?php
    echo $this->Form->create();
    echo $this->Form->input('Article.title');
    echo $this->Form->input('Article.body');
    echo $this->Form->end('Add Aricle');
?>

One thing you’ll notice is the way helpers are referenced in CakePHP 1.3… while $form->input() still works, the approach above is “safer” and more consistent. (Take a look here for more details).

Let’s get back to this line of code for a second…

$this->Session->setFlash('Article saved!', 'modal', array('class' => 'modal success'));

The main difference in CakePHP 1.3, is that modal, the second param, represents an element (unlike a layout in previous versions).
Therefore for this setup to work properly you’ll need to create app/views/elements/modal.ctp

Let’s see what it looks like:

<div id="flash-message" class="<?php echo $class; ?>"> <?php echo $message; ?> </div>

$message is replaced by whatever we place in the first argument to the setFlash() method (which happens to be “Article saved!”, in our case).
As you’ve probably guessed $class gets replaced with the appropriate value from the array of passed params.

Now, if we have successfully saved the article the add.ctp view gets re-displayed with our message showing up and the element rendered. (This all happens automagically by using $this->Session->flash()).
This could be already fine in itself, but it’s just not sexy enough… so we add a little jQuery and jQuery Tools magic to make things a little more fun.

$(document).ready(function() { 
   //with this approach you can assign the jQuery Tools API to be used later
  //otherwise you could use a standard one-liner:
  //$('#flash-message').expose().load();
   var flashMessage = $('#flash-message').expose({api: true}); 
   //now that we have a direct access to the API through the "flashMessage" object
   //we can call the jQuery Tools methods
   //such as load(), which is required to show/expose our modal
   flashMessage.load();
   //now that the modal is displayed we can create a simple way to automatically
   //remove it after 3 seconds
   flashMessage.onLoad(function() {
     setTimeout(function() {
          flashMessage.close();
          $('#flash-message').slideUp(500);
      }, 3000);
   });
});

By including this script we will achieve exactly what our goals are. Display the message in a nice modal/overlay fashion, wait 3 seconds and then auto-hide the message from the user and make our page act as before again.
If you care, please take a look at the comments in the code, to see some nice features of jQuery Tools, i.e. the ability to access any tool’s API. (Please refer to jQuery Tools site for more details).
Overall, we are just relying on the jQuery goodness and overriding our boring flash() behavior, with something quite a bit more interesting.

Well, there you have it, aimed with these tools you are ready to bake sexy CakePHP 1.3 apps ;)

P.S.

Just a little CSS for the modal:

.modal {
   width: 350px;
   padding: 60px;
   margin: 50px 50px;
  }
  .success {
    border: 1px solid #004000;
  }
  .problem {
    border: 1px solid #800000;
  }