CakePHP: BehaviourJS Helper

cake_logoI made this Helper because i always used Behaviour in all my projects before i recently joined the cakePHP community. Now while the AJAX Helper is nice and the Javascript Helper too, there was one huge problem: The inline-Javascript. BehaviourJS makes use of CSS Selectors to attach events - and this all as a layer instead of creating inline code.

First argument why to use it is that it makes it possible for you to let your site gracefully degrade to clients. Second is that you can attach the same Javascript to many elements at once by just adding one line of code!

Selector Magic

As an example:
Lets say you have a list of links.. a menu, for that matter. You wrap it around a div with the id=menu.

HTML:
  1. <div id="menu">
  2. <a href="pages/test">example</a>
  3. <a href="pages/test">example</a>
  4. <a href="pages/test">example</a>
  5. </div>

Now with the BehaviourHelper you can attach javascript to all of them like this:

PHP:
  1. <?php $behaviour->addRule('#menu a', 'onmouseover', "new Effect.Highlight('element')"; ?>

If you now hover over the links their background will highlight.. or jump around..whatever you want to do =)
You can use all available "on"-EventHandlers.

Form Input example

Lets say you have to validate Form Inputs while there are being typed or changed..
You could add a className "required" to them and start a validation with - again - one line of code:

PHP:
  1. <?php $behaviour->addAjaxRule('input.required', 'onchange', array('url'=>'/users/formvalidator',    'update'=>'errormsg')); ?>

This saves you hours! ;D

How it works

Now the outsourcing of the javascript is a bit tricky but i hope it is still convinient enough for you. Be aware that i am into Cake for just 3 days so i dont know all stuff around it.

For stacking up all Rules, defined in all views, i am writing to a js file located in the /tmp/ folder of your app folder.

To actually get it into your <head> part of the layout, i am using a second PHP file which is located in your webroot/js folder. That file reads the content of the js which should be around that time and then spits out the temp-content.

Installation

copy behaviour.js to [app]/webroot/js/
copy behaviourRules.php to [app]/webroot/js/
copy behaviour.php to [app]/views/helper/

put 'Behaviour' into your $helper array, like so:

PHP:
  1. var $helper = array('Behaviour');

put this into the head section of your layout:

PHP:
  1. <?php echo $javascript->link('prototype'); ?>
  2. <?php echo $javascript->link('behaviour'); ?>
  3. <?php echo $behaviour->linkRulesJS(); ?>

And thats it ..

Of course your [app]/tmp/ folder needs to
writable for this whole thing to work.

METHOD: addAjaxRule()

This creates a Ajax.Request or Ajax.Updater Rule based upon the first two arguments. It uses the Ajax Helper, so for all possible options refer to the AjaxHelper Manual.

Note: If you leave out $options['update'] the Ajax Call will become a Request.

$behaviour->addAjaxRule($target, $event, $options, [$returnFalse])
  • @param string $target - This can be a html-tagname, a id, a classname or a combination of all, like "li.listclass" or "a.menu". For id: "pre#myid"
  • @param string $event - This is the event handler. For example: "onsubmit" or "onkeydown"
  • @param array $options - Array with the AjaxHelper options for building an Prototype Ajax Function
  • @param boolean $returnFalse - If 'false' the call will not "return false;". Generally not a good idea but just in case, here you can control this

METHOD: addRule()

This is for simple Javascript. For example if you are using the Scriptaculous Effects in your application.

Note: Don't append the last semi-colon.

$behaviour->addRule('a#hidemenu', 'onclick', "Element.toggle('menu')");
  • @param string $target - This can be a html-tagname, a id, a classname or a combination of all, like "li.listclass" or "a.menu". For id: "pre#myid"
  • @param string $event - This is the event handler. For example: "onsubmit" or "onkeydown"
  • @param string $script - Any javscript you want..
  • @param boolean $returnFalse - If 'false' the call will not "return false;". Generally not a good idea but just in case, here you can control this.

More examples

Fun with Forms.

PHP:
  1. <?php echo $html->input('test/bla', array('class'=>'required')); ?><br />
  2. <?php echo $html->input('test/bla', array('class'=>'required')); ?><br />
  3. <?php echo $html->input('test/bla', array('class'=>'required')); ?><br />
  4. <?php echo $html->input('test/bla'); ?><br />
  5. <?php echo $html->input('test/bla'); ?><br />
  6.  
  7. <?php $behaviour->addRule('input.required', 'onchange',
  8.              "new Effect.Highlight(element)"); ?>

Note: To the highlight function i pass "element". Element is the javascript variable for the current html element. ;)

Note 2: To actually call Effect.[whatever..] you have to link up with scriptaculous.js first!

License

Since i am using a Behaviour Library from Ben Nolan which provides it as BSD licensed i will do so too with this Helper. All files are BSD licensed. ;-)

Download

You can always download the latest version at cakeforge.org
http://cakeforge.org/projects/behaviourhelper/

I hope you enjoy this one.
Comments welcome!