Agile Toolkit news

library updates, tips, information and more

How JS layer works in ATK

Half year ago we have introduced jQuery / Chain into amodules3. 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 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 JS 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 JS 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 JS 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 JS 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 JS 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 JS 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 JS chain produces a valid JS 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

ATK 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 JS. Our new approach in ATK 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.


April 26, 2010 - Posted by | Beginner tips, Version 3


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

    Comment by Svetlozar Kondakov | April 27, 2010 | Reply

  2. […] post continues to explain how to use JS most efficiently in ATK. Read first part […]

    Pingback by How to extend JS in ATK | Agile Toolkit news | July 29, 2010 | Reply

  3. […] If you dont have the knowledge of installing the scripts you want on your website, SiteDuct offers fast script installation service. Read More… […]

    Pingback by Script installation service | September 18, 2012 | Reply

  4. […] Details […]

    Pingback by Fix My Website | February 11, 2013 | Reply

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s