Plugin / Blunt AJAX

Description

This script is for developers like myself that don’t want to load some monolithic JavaScript framework just to do a bit of AJAX.

Document for developers for use of this plugin can be found on the Other Notes page.

This is an adaptation of an AJAX script that I’ve been using and updating since around 2007. I like my scripts small and to the point. Hopefully others will find it useful.

I am open to suggestions for improvement of this plugin. Submit a support request here or on GitHub

Documentation for Developers

For more information about AJAX in WordPress see the WordPress Codex, the best information can be found on the AJAX in Plugins page.

This plugin does not automatically add the Blunt AJAX script to every page of your site. It simply registers the script so that it is available to be included when you need it. You tell WordPress that you need the script by including the script handle as one of the scripts that your script depends on when you register or enqueue your script. The main thing that this means is that in order to use Blunt AJAX you must use one of these built in WordPress functions to include your own scirpts. This promotes the proper way to do it and clean coding standards.

Purpose of Blunt AJAX

The sole purpose of Blunt AJAX is to make an http request and relay the response to a callback function. Blunt AJAX has no facility outside of a simple default callback function to deal with the response. You must write the JavaScript code to call Blunt AJAX and also the callback function to react to the server response if you wish to do more than what the default callback function can do; which is to either put the response into the inner HTML of some element or to show the response in a JavaScript alert message.

How to Include Blunt Ajax

The handle of the Blunt Ajax script is “blunt‑ajax”.
Here is an example bit of code that enqueues a script and causes the Blunt Ajax script to load:
<?php wp_enqueue_script($handle, $src, array(‘blunt-ajax’)); ?>

Usage

In your javascript code you call Blunt AJAX something like this:
<script type=”text/javascript”>
var arguments = {debug:false,
url:”/wp-admin/admin-ajax.php”,
callback: my_callback_function,
encoding: ‘none’,
parameters:{action:’action_name’,
nonce:’12345678′,
my_parameter:’Some Value”‘},
method:”GET”,
element_id:’my-id’,
pass:’any value type or value’};
bluntAjax(arguments);
</script>

Arguments may be specified in any order

debug: (boolean)(optional) Should Debugging be turned on. You can turn on debugging that will display errors encountered by Blunt AJAX. The default value is false (actually, the defualt value is set in the php file for this script, but unless you change it there the default is false. For more information on this see the Advanced Debugging and Testing section.) Prior to version 1.1.0 debug needed to be the first parameter in the arguments. In version 1.1.0 the JS code was changed and it no longer matters what order the debug parameter is included in the arguments list.

url (string)(optional) This would be the URL for the path of the server side PHP script that will handle the AJAX request. The defualt value for this argument is the path to the file admin‑ajax.php on your site. This is the way you are supposed to handle AJAX requests in WP, you can read more about that in the link I referenced above.

However, I know that not everyone does it this way and it is not always necessary to go through the WordPress AJAX script. I will say that if you are going to access anything about your WordPress site that you should do it properly. Again, when not accessing the WordPress site, for example you’re just going to set a SESSION value or something of that nature, you can provide the path to your own script. This path MUST be on your own server. AJAX only allows connection to the same server that hosts the page it is on and this script WILL NOT provide access to another server. You do not need to include the absolute path to your script, AJAX requests work perfectly well with root relative URLs

callback (function)(optional)
A valid callback function to process the server response. The default value of the parameter is the default callback function that is explained below.

parameters (object)(optional)
An object containing a list of name/value pairs to be sent with the http request.
Important Note: See encoding for information on how parameter values are escaped or encoded
Starting in version 1.1.0 it is possible to pass multidimensional objects and arrays to Blunt Ajax as parameters. Simple Example:

  var arguments = {debug:false,
                   url:"/wp-admin/admin-ajax.php",
                   callback: my_callback_function,
                   encoding: 'none',
                   parameters:{action:'action_name',
                               nonce:'12345678',
                               object1: {name1:'value1',
                                         name2:'value2',
                                         name3:['array value 1', 'array value 2', [1,2,4]]},
                               my_parameter:'Some Value"'},
                   method:"GET",
                   element_id:'my-id',
                   pass:'any value type or value'};
  bluntAjax(arguments);

As you can see, the parameter value contians an object that is itself a multidimensional object containing other objects and arrays.

encoding (string)(optional)
The encoding method to use for all parameter values. Valid values are “none”, “escape” or “uri”. The default value for this argument is “none” in order to maintain backwards compatibility with previous versions of Blunt Ajax. Prior to version 1.1.0 no escaping of parameters was done and the user of this script was required to properly escape or encode values before passing to Blunt Ajax.

• none: No escaping or encoding is done. Values are passed to the server exactly as passed to Blunt Ajax.
• escape: Each parameter value is escaped using the JaveScript escape() function, i.e. value = escape(value)
• uri: Each parameter value is encoded using the JavaScript encodeURIComponent() function, i.e. value = encodeURIComponent(value)

If you do a search you’ll find plenty of those voicing their opionion about what the proper encoding method is for query parameters. I’m not here to judge. Use the method that works best for you. I think I have included anything you could need.

method (string)(optional)
The method that should be used for the HTTP request, either “GET” or “POST”. The default value of this argument is “GET”. This value is case insensitive.

element_id (string)(optional)
A valid element id attribute in your document. This value can be used by the callback function for inserting HTML into the page. Default value is false.

pass (any type)(optional)
This argument can be of any type or value. The value of this object is not checked or altered in any way and is simply passed to the callback function.

Callback Functions

All AJAX scripts use callback functions. This is a function that processes or acts upon the response recieved from the server. The Blunt AJAX script does not alter the server response in any way, it is up to you to write a callback function for this purpose.

The following is what the default callback function looks like. The default callback function can be used to either show the server’s response in a JavaScript alert message or to put it into the inner HTML attribute of an element if an element id was specified when calling the bluntAjax function.

<script type="text/javascript">
  function bluntAjaxDefaultCallback(response, element_id, pass) {
    if (element_id !== false) {
      document.getElementById(element_id).innerHTML = response;
    } else {
      // element_id not given alert response
      alert(response);
    }
  }
</script>

Notice that the pass parameter is not used in the default callback function, it is simply included to show you the parameters that are passed to the callback function and the order that they are passed in. You can use the default callback function to simply alert your response or insert it into the page. It is also valuable for debugging purposes.

Once again I want to stress that the server response is not altered in any way. Whatever response your server side action sends is exactly what this parameter will contain. You can send any type of value (i.e. XML, HTML, plain text, JSON), but you must write the callback function to deal with the data. This plugin and the blunt-ajax.js script is for the sole purpose of sending a request and relaying the response.

Advanced Debugging and Testing

There are some PHP methods that you can call to do several things:

1. To turn debugging on call the method bluntAjax::debugOn(). When debug is turned on the javascript file debug.js in the blunt-ajax plugin folder will be loaded. I use this file, as is probably obvious, for degugging purposes.
2. To automatically run a test call the method bluntAjax::test(). This will cause a test to be run that will send an AJAX request. The response of this request will be displayed in a JavaScript alert message. This message will contain the request method used and a list of the paremeters that were sent with the request. When testing is turned on the the file test.js in the blunt-ajax plugin folder will be loaded. I use this to test that everything is working as I expect.
3. To include the full JavaScript version in your page call bluntAjax::minifiedOff(). This will cause the un-minified version of the blunt AJAX javascript to be loaded. I don’t know why you would want to do this. I do it when I’m making modifications and testing the script before creating the new minified version.

All of these functions must be called on the ‘init’ action. This is when the blunt-ajax.js file is engueued. My init method has a priority of 100 so your init function must have a lower priority; in most cases the default priority will be sufficient.

Example of calling degugging and testing function

calling all functions together in a function

<?php 
  add_action('init', 'my_init_function');
  function my_init_function() {
    bluntAjax::debugOn();
    bluntAjax::testOn();
    bluntAjax::minifiedOff();
  }
?>

using init action to call funtions
<?php
$instance = bluntAjax::getInstance();
add_action(‘init’, array($instance, ‘degucOn’));
add_action(‘init’, array($instance, ‘testOn’));
add_action(‘init’, array($instance, ‘minifiedOff’));
?>