Ajax framework

The Ajax framework is used to dynamically update parts of a page's HTML based on data from the server. Upon a specified event, such as a button click, a callback function is triggered which performs server-side logic and may return updated markup, which is then replaced on-the-fly with no page refresh necessary.

This framework creates a PHP macro language that allows the server to instruct JavaScript to perform actions on the client browser. When using links, it can be used with the #use-ajax class. The #use-ajax class can be used to bind the link to the Ajax framework. The route pointed by this link has to be set "type"="ajax", can return updated HTML or can also return a richer set of Ajax framework commands.

A complex ajax example

First we create a simple page where the ajax modification will work, and an ajax handler which will do the modifications:

function hook_ajaxexample_defineroute()
{
    $r = array();

    $r[] = ['path' => 'example/ajax',
            'callback' => 'page_ajaxexample', //the callback of the original page,
                                              //we will modify the content generated by
                                              //this function
        ];

    $r[] = ['path' => 'ajaxhandle/{direction}/{value}',
            'callback' => 'ajax_handler', //the callback of the ajax handler
            'type' => 'ajax', // tells the system to handle this as an ajax handler
        ];

    return $r;
}

The following codes generates the html content we can modify, and place the ajax links. The code will insert a div with change_this id. The ajax handler will change the content of this div.

function page_ajaxexample()
{
    ob_start();
    print "<h2>Simple ajax exmaple</h2>";
    print '<div id="change_this">'.counter_inner(55).'</div>';
    return ob_get_clean();
}

function counter_inner($value)
{
    ob_start();
    print l('Up',"ajaxhandle/up/$value",['class' => 'use-ajax']);
    print '<br/>';
    print "The value is $value";
    print '<br/>';
    print l('Down',"ajaxhandle/down/$value",['class' => 'use-ajax']);
    return ob_get_clean();
}

The code of the ajax handler. It is receive two url parameter which tells what to do. The ajax_add_html function is used to tell the ajax framework to replace the content of #change_this element's to the result of counter_inner($value).

function ajax_handler()
{
    par_def('direction','text4'  ,'url');
    par_def('value'    ,'number0','url');

    $value = par('value');
    if(par_is('direction','up'))
        ++$value;
    if(par_is('direction','down'))
        --$value;

    ajax_add_html('#change_this',counter_inner($value));
}

Start ajax requests

There are more ways in CodKep to start ajax calls and use ajax framework.

HTML link with use-ajax class

The easiest way to place an ajax call to the page is put a simple html link with the class use-ajax. The use-ajax marker will indicate to the ajax framework to handle link as CodKep ajax request. When the user click on this link an ajax request will be send to the server and the response will be processed by the CodKep's ajax framework.

  print l('Click me',"ajax_url/somefunction/$param",['class' => 'use-ajax']);

Set HTML form action to ajax

In case you generate a html form with CodKep's HtmlForm class, you can specify the submit action to ajax. The HtmlForm class has an action_ajax($ajaxurl) method which sets the submit url and type to ajax. The response of the specified ajax handler will be processed by CodKep's ajax framework.

  $myform = new HtmlForm('myform');
  $myform->input('text','name','');
  $myform->input('submit','ok','ok');
  $myform->action_ajax('myform_submit_ajax');
  print $myform->get();

Place a delayed ajax call

You can place a delayed ajax call to the generated page by calling this function:

place_delayed_ajax_call($ajax_url,$msec)
Returns a html code which submits an ajax call after a specified time.

Let's see and example how it's work:

function mypage()
{
    ob_start();
    print "<h1>My page<h2>";
    ...
    //This will start an ajax call to the "ajaxhandler_mypage" internal url after 1 second:
    print place_delayed_ajax_call('ajaxhandler_mypage',1000);
    return ob_get_clean();
}

Ajax handler

Every ajax call which made by CodKep's ajax framework have to be targeted to a CodKep ajax handler. A CodKep ajax handler is the callback function of an internal location which has "type"=>"ajax".

The ajax callback functions can take effect by the following functions:

Ajax commands

The following functions can used in ajax handlers to direct the ajax framework to do what we want. Summarizing, this functions should be used in ajax callbacks which has "type" => "ajax" in route definition. On the other hand they affect the client browsers page, without reloading the page.

Note: The commands of this functions is buffered and the buffer is only send when the callback is finished.

Note2: You can put more commands to the buffer. (by calling functions below) The commands will be executed that order they added.

ajax_reset()
Clears the ajax command buffer. All previous passed commands will erased.

ajax_add_html($selector,$content)
Invokes the jQuery.html method which replace the html content of the element specified by $selector parameter to the content of $content parameter.

ajax_add_val($selector,$value)
Invokes the jQuery.val method which set the value of the element specified by $selector parameter to the content of $value parameter.

ajax_add_css($selector,$css)
Invokes the jQuery.css method which sets the css of the element specified by $selector parameter to the content of $css parameter.

ajax_add_addclass($selector,$class)
Invokes the jQuery.addClass method which adds the $class class to the element specified by $selector parameter.

ajax_add_removeclass($selector,$class)
Invokes the jQuery.removeClass method which remove the $class class from the element specified by $selector parameter.

ajax_add_show($selector,$showparam)
Invokes the jQuery.show method which display the element specified by $selector parameter. The $showparam parameter passed to the jQuery show(). (This is a string or number determining how long the animation will run. Tipically "fast" or "slow" or a millisecond value)

ajax_add_hide($selector,$hideparam)
Invokes the jQuery.hide method which hide the element specified by $selector parameter. The $hideparam parameter passed to the jQuery hide(). (This is a string or number determining how long the animation will run. Typically "fast" or "slow" or a millisecond value)

ajax_add_toggle($selector,$param)
Invokes the jQuery.toggle method which hide or show the element specified by $selector parameter. The $param parameter passed to the jQuery toggle(). (This is a string or number determining how long the animation will run. Typically "fast" or "slow" or a millisecond value)

ajax_add_alert($message)
Invokes the javascript alert() function to show the $message message.

ajax_add_log($message)
Invokes the javascript console.log() function to place the $message log message to the browsers log area.

ajax_add_run($command,$arg = array())
Invokes the client side ajax framework to immediately run the $command named javascript function with $arg arguments.

ajax_add_delayed_ajaxcall($ajax_url,$msec)
Invokes the client side ajax framework to wait $msec millisecond then start a new ajax call to the $ajax_url url.

ajax_add_refresh()
Invokes the client browser to do a full page refresh. (On the current location: location.refresh() )

ajax_add_showol($content,$timeout = 0)
Invokes the ajax framework to show the $content html fragment as overlay popup until $timeout second.

ajax_add_goto($url)
Invokes the client browser to go to the $url url. (The $url parameter is passed to url() before processing)

Page generated in 0.0545 seconds.