phpBB

Development Wiki

JavaScript Function.phpbb.ajaxify

From phpBB Development Wiki

Revision as of 17:01, 22 October 2011 by Callumacrae (Talk | contribs)

This code is not yet merged into the core, do not try to use it.

phpbb.ajaxify –– automatically makes a link or form use AJAX instead of loading an entire page.

Description

  1. function phpbb.ajaxify ( options [, refresh [, callback ]] )

The function automatically makes a link or form use AJAX instead of loading an entire page. It supports both normal links and links that would link to a page which calls confirm_box, detecting which type of link it is without the developer having to tell it. It also supports forms. This function is generally called automatically for links and forms with the data-ajax attribute set.

Parameters

Parameter Usage
options Either array containing options for the function, or a string to be used as the selector. If it is an object, it will look for the following properties and ignore the rest:
Property Description
selector A string to be used as the selector, or a jQuery HTML element.
exception (optional) A function that will be called and can cancel the function and make the link or form perform normally (load a new page). See "Exceptions" below for information such as parameters.

refresh (optional, default is false) If the board sends us back REFRESH_DATA, should it be acted upon? This can be either a boolean value (true or false), or a function. If it is a function, the function will be called with the parameter being the URL of the ajax request, and then if the function returns true, it will refresh the page.
callback (optional, default is false) Callback to be called on completion of the event (eg the user has pressed yes in the confirm_box and the HTTP request has been sent and replied to successfully). See "Callbacks" below for more information such as parameters.


Callbacks

The callback option specifies the name of a function that has been added to the list of callbacks using phpbb.add_ajax_callback, which will be called on successful completion of the event.

The callback will not be called if the user presses "No" on the confirm_box.

It is sent two parameters, and the element can be accessed using "this":

  1. function callback ( data , action )
Parameter Usage
data The data that was returned by the server.
action If a form, this parameter will be the value of the action that was sent.


Exceptions

Exceptions are given to the function using the options array (see above), and are called when an ajaxified link or form is clicked or submitted. It can cancel the functions and make the link or form perform normally (load a new page). It is sent two parameters, and the element can be accessed using "this":

  1. function exception ( action , data )
Parameter Usage
action If a form, this parameter will be the value of the "action" element.
data If a form, this parameter will be the data that would be sent as the AJAX request.

If it returns true, then the ajax request will be cancelled and the page will load as if phpbb.ajaxify was never called. If it returns false, then phpbb.ajaxify will continue normally.


data-ajax

Unless the style author has removed the code that calls this (which can be found below), any element with the data-ajax attribute set will automatically be ajaxified. If data-ajax is set to true, then no callback will be sent, but any other value will be sent as the name of the callback to be called. If data-ajax is set to false, then it will be ignored entirely.

data-refresh

On elements with data-ajax set, data-refresh will be used as the refresh value. It can only be true or false - it cannot be a function.

The Code

$('[data-ajax]').each(function() {
	var $this = $(this);
	var fn = ($this.data('ajax') !== 'true') ? $this.data('ajax') : null;
	phpbb.ajaxify({selector: this}, $this.data('refresh') !== undefined, fn);
});

Examples

An element which will be ajaxified with no callback:

<a href="page.php?action=delete" data-ajax="true">Delete</a>

An element which will be ajaxified with a callback:

<a href="page.php?action=delete" data-ajax="delete">Delete</a>

An element which will be ajaxified with a callback, which will then refresh the page:

<a href="page.php?action=delete" data-ajax="delete" data-refresh="true">Delete</a>

Examples

AJAXifying a simple link

The two following code examples do exactly the same thing:

<a href="page.php?action=delete" data-ajax="true">Delete</a>

<a href="page.php?action=delete" class="ajax_delete">Delete</a>
<script>
    phpbb.ajaxify('.ajax_delete');
</script>

Using callbacks

The following code example will remove the link when it is clicked.

<a href="page.php?action=delete" class="ajax_delete">Delete</a>
<script>
    phpbb.add_ajax_callback('deleted', function() {
        $(this).href('#').text('Deleted');
    });
    phpbb.ajaxify('.ajax_delete', false, 'deleted');
</script>

Using exceptions

The following code example will force the link to act normally if data attribute ajax-override is set to true.

<a href="page.php?action=delete" class="ajax_delete">Delete</a>
<script>
    phpbb.ajaxify({
        selector: '.ajax_delete',
        exception: function() {
            return $(this).data('ajax-override');
        }
    });
</script>