phpBB

Development Wiki

Difference between revisions of "Using AJAX"

From phpBB Development Wiki

(More info added to ==Ajax events== to be more specific and to prevent misunderstandings.)
(document forms)
Line 17: Line 17:
  
 
Optionally you can add the '''data-refresh="true"''' attribute, which will refresh the page after the action is complete. While this can be useful, you should try to use ajax events whenever possible.
 
Optionally you can add the '''data-refresh="true"''' attribute, which will refresh the page after the action is complete. While this can be useful, you should try to use ajax events whenever possible.
 +
 +
==Forms==
 +
 +
To ajaxify a form you use the same technique as with the link. Just add the '''data-ajax''' attribute to the form tag:
 +
 +
<pre><form action="somewhere.php" method="POST" data-ajax="true">
 +
    <!-- your form -->
 +
</form></pre>
 +
 +
Whenever the form is submitted, an AJAX call will be done to the action of the form.
  
 
==Ajax events==
 
==Ajax events==
Line 26: Line 36:
 
This will allow you to bind to your custom ajax event by adding a callback:
 
This will allow you to bind to your custom ajax event by adding a callback:
  
<pre>   phpbb.add_ajax_callback('mymod.link_remove', function() {
+
<pre>phpbb.add_ajax_callback('mymod.link_remove', function() {
        $(this).remove();
+
    $(this).remove();
    });</pre>
+
});</pre>
  
 
Once the AJAX response comes back, the callback is executed.  
 
Once the AJAX response comes back, the callback is executed.  
Line 38: Line 48:
 
If you need to, you can access the response in your callback. The response body gets passed as the single argument to your callback. So you could do something like this:
 
If you need to, you can access the response in your callback. The response body gets passed as the single argument to your callback. So you could do something like this:
  
<pre>   phpbb.add_ajax_callback('mymod.link_remove', function(response) {
+
<pre>phpbb.add_ajax_callback('mymod.link_remove', function(response) {
        $('.my-container').html(response);
+
    $('.my-container').html(response);
    });</pre>
+
});</pre>
  
 
This would dump the entire response into a div.
 
This would dump the entire response into a div.
Line 46: Line 56:
 
However it is recommended to return a JSON response. This means that you can send any data to the browser. It can be an associative array that you can then access from JavaScript. An example of handling a JSON response is this:
 
However it is recommended to return a JSON response. This means that you can send any data to the browser. It can be an associative array that you can then access from JavaScript. An example of handling a JSON response is this:
  
<pre>   phpbb.add_ajax_callback('mymod.link_remove', function(data) {
+
<pre>phpbb.add_ajax_callback('mymod.link_remove', function(data) {
        $(this).text(data.NEW_TEXT);
+
    $(this).text(data.NEW_TEXT);
    });</pre>
+
});</pre>
  
 
This will take the '''NEW_TEXT''' variable from the response and set the text of the element to that value.
 
This will take the '''NEW_TEXT''' variable from the response and set the text of the element to that value.
Line 54: Line 64:
 
On the server side you need to check if the current request is an AJAX request. If it is, you should return JSON instead of a rendered page. You can send any data you need on the client. Here is an example:
 
On the server side you need to check if the current request is an AJAX request. If it is, you should return JSON instead of a rendered page. You can send any data you need on the client. Here is an example:
  
<pre>   if ($request->is_ajax())
+
<pre>if ($request->is_ajax())
    {
+
{
        $new_text = $user->lang($activated ? 'ACTIVATE' : 'DEACTIVATE');
+
    $new_text = $user->lang($activated ? 'ACTIVATE' : 'DEACTIVATE');
        $data = array('NEW_TEXT' => $new_text);
+
    $data = array('NEW_TEXT' => $new_text);
        phpbb_json_response::send($data);
+
    phpbb_json_response::send($data);
    }
+
}
 
      
 
      
    // render normal response here</pre>
+
// render normal response here</pre>
  
 
The server will send a response like this:
 
The server will send a response like this:
Line 71: Line 81:
 
==TODO==
 
==TODO==
  
* Forms
 
 
* Error handling
 
* Error handling
 
* Advanced usage (calling ajaxify manually)
 
* Advanced usage (calling ajaxify manually)
 
* Special server params like S_CONFIRM_ACTION, MESSAGE_TITLE, MESSAGE_TEXT, REFRESH_DATA, S_HIDDEN_FIELDS.
 
* Special server params like S_CONFIRM_ACTION, MESSAGE_TITLE, MESSAGE_TEXT, REFRESH_DATA, S_HIDDEN_FIELDS.

Revision as of 20:52, 15 February 2012

phpBB contains a set of functions to make it very easy to have links use AJAX. This means doing requests in JavaScript without reloading the whole page.

Supported elements

By default following elements can be ajaxified:

  • Links (<a>)
  • Forms (<form>)

Simple usage

To do so, simply add a data-ajax="true" attribute to the element. Here's an example:

<a href="/link.php?id=4" data-ajax="true">link</a>

This will make an AJAX call when the user clicks the link, instead of opening that page in the current browser tab.

Optionally you can add the data-refresh="true" attribute, which will refresh the page after the action is complete. While this can be useful, you should try to use ajax events whenever possible.

Forms

To ajaxify a form you use the same technique as with the link. Just add the data-ajax attribute to the form tag:

<form action="somewhere.php" method="POST" data-ajax="true">
    <!-- your form -->
</form>

Whenever the form is submitted, an AJAX call will be done to the action of the form.

Ajax events

In most cases you will want to do something after the action is complete. You can do this by setting the data-ajax attribute to the event name you want to use. This will be a combination of your MOD name and the action that is happening.

<a href="/link.php?id=4" data-ajax="mymod.link_remove">link</a>

This will allow you to bind to your custom ajax event by adding a callback:

phpbb.add_ajax_callback('mymod.link_remove', function() {
    $(this).remove();
});

Once the AJAX response comes back, the callback is executed. Inside the function that is used "this" refers to the Node where you applied data-ajax="mymod.link_remove" which is in this case the link. To use the jQuery's functions you need to wrap the Node again like it appears in the example ($(this)).

Accessing the response

If you need to, you can access the response in your callback. The response body gets passed as the single argument to your callback. So you could do something like this:

phpbb.add_ajax_callback('mymod.link_remove', function(response) {
    $('.my-container').html(response);
});

This would dump the entire response into a div.

However it is recommended to return a JSON response. This means that you can send any data to the browser. It can be an associative array that you can then access from JavaScript. An example of handling a JSON response is this:

phpbb.add_ajax_callback('mymod.link_remove', function(data) {
    $(this).text(data.NEW_TEXT);
});

This will take the NEW_TEXT variable from the response and set the text of the element to that value.

On the server side you need to check if the current request is an AJAX request. If it is, you should return JSON instead of a rendered page. You can send any data you need on the client. Here is an example:

if ($request->is_ajax())
{
    $new_text = $user->lang($activated ? 'ACTIVATE' : 'DEACTIVATE');
    $data = array('NEW_TEXT' => $new_text);
    phpbb_json_response::send($data);
}
    
// render normal response here

The server will send a response like this:

{"NEW_TEXT": "Deactivate"}

The AJAX function will take care of decoding this into a JavaScript object, so you can use it directly.

TODO

  • Error handling
  • Advanced usage (calling ajaxify manually)
  • Special server params like S_CONFIRM_ACTION, MESSAGE_TITLE, MESSAGE_TEXT, REFRESH_DATA, S_HIDDEN_FIELDS.