How JavaScript layer works in Agile Toolkit

Monday, April 26th, 2010|Beginner tips, Version 3|by Romans

Half year ago we have introduced jQuery / Chain into AModules3 (former name for Agile Toolkit). It allows us to clean up a lot of older code and at the same time give developers a way to do many new things in a flexible way.

How things were before?

When we designed AModules3, JavaScript (JS) wasn’t widely used yet. It wasn’t trendy too, so we tried not to relay on it too much. It was used in some rare occasions. Eventually need for javascript was higher and we started to collect a library.

Library was called amodules3.js. To rely on those functions form got support for “onclick”, and so did buttons. That was very clumsy.

To simplify access to javascript functions from PHP we have developed Ajax.php class with functions such as loadRegionURL, submitForm etc. This was widely used in projects in mid-2009.

New approach to JavaScript

All the JavaScript framework was redesigned. The new approach was meant to work only through IDs. Here is what we did:

  • added <…id=> to all view elements such as grid, form etc.
  • removed all inline javascript (onload, onclick, etc)
  • made jQuery mandatory for JavaScript support
  • all the interactions were done through binding $(…).click(). and so on.

So now when page or part of the page is being generated through render(), it also puts together list of js-actions to perform on those elements.

Basic approach and PHP integration.

We have added class jQuery_Chain which was implementing a layer of transparency between PHP and JavaScript by using __call handler. In shorts user could write $this->js()->any()->method()->calls(); to jQuery chain and they would be translated into a valid jQuery chain: $(..).any().method().calls().

Additionally this gave us layer of security because all the arguments are properly encoded through json. You can’t sneak a piece of JavaScript code through the argument.


Previous $this->ajax()->loadRegionURL() was implemented through such chain and javascript class atk4_univ. This is now identical to calling js()->univ()->loadRegionURL().

We introduced a way how JavaScript developers can add their own functions to univ() class thus giving a very easy way to add extra functions which can be easily called from within PHP. Some good examples of standard functions are

$button->js(‘click’)->univ()->dialogURL(‘Add new item’,$this->api->getDestinationURL(‘./add’));

but also a custom functions are quite useful:

$form->getElement(‘total’)->js(true)->univ()->bindTotalCalculation($form->getElement(‘vat’), $form->getElement(‘net’));


Any view element can use js() method to produce new JavaScript chain. First argument to the function is event when chain should be executed. js(true) would always be executed (but only!!) if element is visible. js() – default action will not execute chain automatically. Then you can use multitude of custom events such as js(‘click’), or js(‘hover’) or even js(‘my_own_event’), which you can execute for through jQuery trigger().


Each JavaScript chain produces a valid JavaScript code. Try doing echo on one. It’s automatically converted to string. But you can only have one chain. Sometimes you need to combine them. Second argument to js(,..) function will accept any javascript code. This is a good way to supply one chain to another.


return $button->js(‘click’,$j);

Resulting code will tell text to reload when button is clicked. You can also use chains to get values such as:

return $button->js(‘click’)->univ()->alert( $form->getElement(‘name’)->js()->val() );

Code above will display alert message containing current value of form field in it.

Two types of AJAX requests

Agile Toolkit do not burden developers with complex protocols. There are only two ways how AJAX requests are been passed.

  • regions – Request to load part of the page. Typically complimented by arguments such as cut_region, cut_object or cut_page. Region would contain valid piece of HTML code, but will also contain <script> tag which have to be properly executed by ajax function doing the request. atk4_load() and univ().page() would typically be sending this kind of request.
  • js-code – Those requests will ask for instructions. When you submit data to form, backend returns only the list of javascript instructions such as highlight fields with errors, or redirect user to other page. Requests are generated by form.submit(), univ().ajaxec(). Those requests will not contain any HTML and will simply evaluate the return. You will see argument $_GET['ajax'] passed in those requests.

You have to be aware what type of request you will be receiving. If you are supposed to return js-code you should do so through the following construction:

$js()->univ()->alert(‘thank you’)->page($this->api->getDestinationURL(‘page2′))->execute();

The final function execute() will echo the chain and will stop execution of PHP script. This is typically done to produce decision quickly and do not waste too much time on generating reply.

To be continued…

This is just an introduction to basics of JavaScript. Our new approach in Agile Toolkit provides many ways to further expand use of javascript. In my next post I will be looking at how you can integrate jQuery UI widgets with a single line of code.

1 Comment

Svetlozar Kondakov
Posted April 27, 20109:01 pm

Can’t wait for next step in this tutorial … it cleared a lot of things for me.