phpBB

Development Wiki

JavaScript Function.phpbb.ajaxify

From phpBB Development Wiki

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 )

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.
filter (optional) A function that will be called before the AJAX request is sent, if it returns true, the AJAX request is made, on false it is skipped.
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.


Filters

Filters 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 receives the form data as an argument, and the element can be accessed using "this":

  1. function filter ( data )
Parameter Usage
data If a form, this parameter will be the data that would be sent as the AJAX request.

If it returns false, then the ajax request will be cancelled and the page will load as if phpbb.ajaxify was never called. If it returns true, 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),
		ajax = $this.attr('data-ajax');

	if (ajax !== 'false') {
		var fn = (ajax !== 'true') ? ajax : null;
		phpbb.ajaxify({
			selector: this,
			refresh: $this.attr('data-refresh') !== undefined,
			callback: fn
		});
	}
});


Special JSON parameters

If the server responds with a JSON response there are a number of parameters that trigger special behaviour:

  • S_CONFIRM_ACTION: If this key is set on the JSON response, a confirm form will be displayed in an overlay. It will use MESSAGE_TEXT for the text, S_HIDDEN_FIELDS for the hidden fields (this is raw HTML), S_CONFIRM_ACTION as the target URL and YES_VALUE as the label of the confirm button.
  • MESSAGE_TITLE: If S_CONFIRM_ACTION is not set, but this is, a alert box with MESSAGE_TITLE as the title and MESSAGE_TEXT as the text are displayed.
  • REFRESH_DATA: If this is supplied, the user will be redirected (client-side) to REFRESH_DATA.url after REFRESH_DATA.time seconds. Optionally a refresh option can be supplied to the initial phpbb.ajaxify call, which can be a function converting the URL to a boolean, or a boolean directly. Depending on the value of refresh, the refresh will actually happen, or not.