Documentation

Ajax Lessons

Do not install this package on a real C5 site. Use it on a development site to help learn about AJAX.

This package is a learning experience, providing lesson examples of opening AJAX dialogs and exchanging AJAX data from a block, in Add, Edit and View. Examples are boiled down to a minimum to illustrate how they work (or dont).

Exchanging data between the browser and server using AJAX, or popping up a dialog using AJAX, from Concrete 5 is both straightforward and confusing. Straightforward because, once you boil it down to the basics, there is not much to it. Complicated because Concrete5 provides 3 slightly different ways of declaring AJAX action handlers:

  1. A public function beginning "action_" in a block controller
  2. A php script in a block's "tools" subfolder
  3. A php script in a package's "tools" subfolder

Which works best depends a lot on how you want to organise your package and in what context you want to use the AJAX transaction. Most importantly, a function beginning "action_" in the block controller will not work if you need to do AJAX within the block's Add dialog because the bID does not exist until after the Add has completed, so the C5 dispatcher is unable to route such an AJAX request.

Rather than get bored and confused reading about all the various combinations and permutations, install this package on a development site and explore the behaviour of the blocks during Add, Edit and View:

  1. AJAX Data Lessons - uses 3 AJAX methods to send data from the browser to the C5 server and show the returned html.
  2. AJAX Dialog Lessons - uses 3 AJAX methods to load a C5 browser dialog from the C5 server.

AJAX is often combined with other JavaScript functionality, so in the dialog lessons we attempt to execute JavaScript from various places in various ways and using scripts declared in various sources, summarising success in a table.

You will see that some script locations and methods of executing the JavaScript work reliably, as designed by C5, whereas others may work incidentally, but cannot be relied on. You will also see erratic results when JavaScript is not within a jQuery $().ready() event.

For JavaScript to execute in the View, the script can be in any of:

  1. The php file
  2. view.js
  3. Any .js file in the /js/ folder

But if you want to use JavaScript in a dialog loaded from the view, it will only execute reliably if it is called from JavaScript in a <script> section of the php.

Within an Add or Edit dialog, the reliable choices are limited to:

  1. The php file
  2. Auto.js

Again, JavaScript in any of these sources will only execute reliably within a dialog if it is called from JavaScript in a <script> section of the php.

More importantly, any other means of executing JavaScript, while they will occasionally work, that is merely a coincidence and cannot be relied on.

As with the AJAX actions, rather than list all the permutations and combinations here, use the AJAX Dialog Lessons block to explore the various contexts and understand where the JavaScript can be loaded from and executed from within your design.

See https://www.concrete5.org/documentation/how-tos/developers/javascript-jquery-and-concrete5/ for some detailed theory.