Developing AJAX Templates

Content block example

To see how simple it is to create a Blcoks by AJAX template for most blocks, here is the regular concrete5 content block. First, the non-ajax standard block template is:

<?php 
defined('C5_EXECUTE') or die("Access Denied.");
$content = $controller->getContent();
print $content;

The Blocks by AJAX template is:

<?php 
defined('C5_EXECUTE') or die("Access Denied."); $c = Page::getCurrentPage(); $blkah = Loader::Helper('blocks_by_ajax','jl_blocks_by_ajax'); if($blkah->regular_block($bID) ) { if($c->isEditMode()) { echo $blkah->edit_mode_marker(); } $content = $controller->getContent(); echo $content; } else { echo $blkah->ajax_loader($bID, $c->getCollectionID()); }

In more detail

Before developing a template, first check the Blocks by AJAX forum and see if a template is already available.

Next, try the block in a  Universal Content Puller block, Stack Randomizer block or Global Areas block with a with a 'blocks_by_ajax' template. This will confirm that the block is actually loadable by AJAX and you are not wasting your time developing a custom template.

To create a 'blocks_by_ajax' template for a block, copy the view.php and any view.css for the block to:

  • /siteroot/blocks/the_block_name/templates/blocks_by_ajax/view.php

and (if there is a view.css file)

  • /siteroot/blocks/the_block_name/templates/blocks_by_ajax/view.css

Now edit the view.php of your newly created template and wrap the original content as shown below, making sure to keep the line ...defined('C5_EXECUTE') or die... at the top.

<?php defined('C5_EXECUTE') or die("Access Denied.");
$c = Page::getCurrentPage();
$blkah = Loader::Helper('blocks_by_ajax','jl_blocks_by_ajax');
if($blkah->regular_block($bID) ) {
  if($c->isEditMode()) {
    echo $blkah->edit_mode_marker();
   }
   /*
   ORIGINAL BLOCK CONTENT HERE
   */
} else {
  echo $blkah->ajax_loader($bID, $c->getCollectionID());
}

Starter templates where you can simply insert your block content are included with the Blocks by AJAX addon package. There is a regualr starter template and a package starter template for addon developers to use if they want to ship a Blocks by AJAX template with their addon.

You will obviously have to close and open php sections about the original content if that is needed - it all depends on how the original block view is coded.

If you want to be more sophisticated, the important things to remember are:

$blkah->regular_block($bID) 

Returns true if the usual block view needs to be rendered and false when the $blkah->ajax_loader() needs to be rendered.

$blkah->edit_mode_marker() 

Returns html to insert a marker in edit mode.

$blkah->ajax_loader($bID, $c->getCollectionID()) 

Returns html and script to set up an ajax load for the block.

None of these methods actually renders the html. You need to echo their output to the page. There are examples of this in the templates supplied.

If you prefer the logic to be the other way round,

$blkah->ajax_block($bID) 

Returns the inverse of $blkah->regular_block($bID).

When you have created and tested a 'blocks_by_ajax' template for a block, please post it on the forum for others to benefit. With your permission, I may even add it to the distribution package.

If you are an addon or theme developer, feel free to add Blocks by AJAX compatible block templates to your addon package or theme package.

More advanced templates

Within any template, the call to ajax_loader() takes a number of parameters. By default, these are:

function ajax_loader($bID, $cID, $throbber='show', $load_method = 'on_visible', $delay = 100){};

$bID and $cID are the usual Concrete5 bock and collection (page) identities.

If you don't want a $throbber to show, you can change $throbber to 'hide'. If you want a different throbber, you can change it to the path of an alternative throbber image, or to an html fragment. You can also override the throbber globally (see Global Configuration below).

The $load_method defaults to 'on_visible', but will accept any of the values:

  • 'on_visible' - ajax load started when the containing dom becomes visible.
  • 'when_visible' - as 'on_visible'.
  • 'delay' - after a delay (in milliseconds) after document ready.
  • 'on_event' - when the 'blocks_by_ajax' event is triggered on this block (for developers)
  • 'now' - ajax load started when document ready.
  • 'immediate' - as 'now'.

The $delay parameter is used with the 'delay' $load_method to set an absolute delay, and is also used with the 'on_visible' $load_method to control a polling loop.

'on_event' For Developers

As a developer, if you use the 'on_event' $load_method, it is up to you to trigger the JavaScript event 'blocks_by_ajax' on the containing div of the AJAX loader. For jQuery selection this will have an id of:

'blocks_by_ajax_'.$bID

And a class of:

'blocks_by_ajax'

Beware that the $bID will change as a block is edited, so the safest option is to trigger with jQuery like:

$('#your_wrapper_id .blocks_by_ajax').trigger('blocks_by_ajax');

If you are doing all this within a Blocks by AJAX template, you can use the helper methods id_for_dom($bID) and bclass_for_dom($bID) to get the id and the class assigned to  the containing div of the AJAX loader.

The html and script generated by the BlocksByAjaxHelper will normally be replaced by the AJAX loaded block. If you need to repeatedly trigger 'blocks_by_ajax' to repeatedly re-load the block, you can change:

$blkah->ajax_loader(.....);

to 

$blkah->repeatable_ajax_loader(.....);

The parameters are identical, though only the 'on_event' value for $load_method actually makes sense. This will preserve the script after the ajax content is loaded, so you can trigger it again to re-load the content as many times as you want.

For example, with a little bit of javascript you can use this form to repeatedly update a block at a timed interval or in response to another event on the page.

JavaScript Events Triggered

For JavaScript and jQuery developers, Blocks by AJAX triggers browser JavaScript events on the loading of each block, again on the dom element:

'blocks_by_ajax_'.$bID

The events triggered are:

  • blocks_by_ajax_start - when AJAX loading starts.
  • blocks_by_ajax_fail - if AJAX loading fails.
  • blocks_by_ajax_retry - when AJAX loading is retried following a failure.
  • blocks_by_ajax_success - upon sucessful completion.

Concrete5 Events Triggered

When a block is loaded by AJAX, the Blocks by AJAX tool triggers the Concrete5 events:

  • on_blocks_by_ajax_before_block
  • on_blocks_by_ajax_after_block

Both have the $bID and $cID as parameters and any scalar response returned by the event handler will be echoed before and after the block output.

Global Configuration

Blocks by AJAX an be configured globally by adding definintions to the config/site.php file:

  • BLOCKS_BY_AJAX_DEAFAULT_THROBBER - The global 'throbber' image. Set this to the url or an html fragment for an alternate throbber image. Set this to 'legacy' to show a legacy throbber as in versions prior to v1.1.
  • BLOCKS_BY_AJAX_DEAFAULT_DELAY - The global default delay and polling interval, defaults to 100ms.
  • BLOCKS_BY_AJAX_RETRIES - The number of retries made should AJAX loading fail. Defaults to 3.
  • BLOCKS_BY_AJAX_USE_REPEATABLE_LOADER - When 'true' forces the repeatable loader to be used globally.
  • BLOCKS_BY_AJAX_SET_DEBUG - When 'true' outputs a verbose trail to the developer console for template debelopers.
  • BLOCKS_BY_AJAX_DEAFAULT_LOAD_METHOD - use to globally override the load method parameter.

Last updated: over a year ago