JSON Responses with JResponseJson

Overview

Recently a new class JResponseJson was added to Joomla! 3.x which is able to simplify things with Ajax requests. With that class it is now possible to prepare responses to Ajax requests in a standardized and easy manner. You can have a look at the file here: https://github.com/joomla/joomla-cms/blob/master/libraries/cms/response/json.php It will mostly be used in controllers of components where you get the following advantages:

• Using the flag 'success' the JavaScript code (whether Mootools JRequest.JSON or jQuery.getJSON) can check whether the task was successful or not and react accordingly (If the request itself failes the error event of the JavaScript API can be used).
• Then, the actual response data (if any) can be retrieved from data in the JSON object and
• optionally a main response message from message.
• Additionally, all gathered messages in the JApplication message queue are also automatically sent back in messages. This can optionally be turned off.

Another advantage is that no $app->close(); is necessary anymore if the Ajax request is done with 'format=json' because the already existing API handles the rest. Just echo the response object at the end of the task.

How to Use

Most Common Cases

Here is an example controller file:

class MyController extends JControllerLegacy
{
  public function execute()
  {
    try
    {
      $anyParam = JFactory::getApplication()->input->get('anyparam');

      $result = $this->getModel('example')->createSomething($anyParam);

      echo new JResponseJson($result);
    }
    catch(Exception $e)
    {
      echo new JResponseJson($e);
    }
  }
}

As you can see in the default case the return value of something that has been calculated by the model is simply pushed into a new JResponseJson object and written to the output. This will automatically create a JSON encoded string as follows (except that it is more compressed in reality):

{"success":true,"message":null,"messages":null,"data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}

So, in the 'data' field you can send any array, object or value you want and the 'success' flag is automatically set to 'true'.

If any exception occured in the model this exception is simply passed directly to a new JResponseJson object in our example which would create the following output:

{"success":false,"message":"This is the message of the exception","messages":null,"data":null}

Since it is an exception the 'success' flag was automatically set to 'false' and the message of the exception became the main response message.

Additional Options

If not an exception is passed as the first argument of the JResponseJson constructor you can specify an arbitrary main response message by passing a string as the second argument:

echo new JResponseJson($result, JText::_('COM_COMPONENT_MY_TASK_SUCCESS'));

which creates e.g.:

{"success":true,"message":"The request was successful.","messages":null,"data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}

You can also manually set the error flag to 'false' with the help of the third argument ($error):

echo new JResponseJson($result, JText::_('COM_COMPONENT_MY_TASK_ERROR'), true);

which creates e.g.:

{"success":false,"message":"The was an error.","messages":null,"data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}

Please note that this way you can also send some data back.

Regardless of having an error response or a success response JResponseJson sends all messages back to the client that have been gathered in the application object:

$app = JFactory::getApplication();
// Some code ($result = ...)
$app->enqueueMessage('This part was successful');
// Some more code
$app->enqueueMessage('Here was a small warning');

echo new JResponseJson($result, 'Main response message');

This results in

{"success":true,"message":"Main response message","messages":"<<all the encoded messages of $app>>","data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}

You can see the big advantage of that below in the JavaScript section.

If you don't want to send the messages back (rather that they stay in the session), simply set the fourth argument ($ignoreMessages) of the contructor to 'true'.

Corresponding JavaScript Code

Here is some sample JavaScript used which can be used on the client side together with JResponseJson on the server side. The example is written with some Mootools code, but something similar can also be done with jQuery or any other JavaScript library for Ajax requests.

var req = new Request.JSON({
	method: 'post',
	url: 'index.php?option=com_component&task=mycontroller.execute&format=json',
	onSuccess: function(r)
	{
		if (!r.success && r.message)
		{
			// Success flag is set to 'false' and main response message given
			// So you can alert it or insert it into some HTML element
			alert(r.message);
		}

		if (r.messages)
		{
			// All the enqueued messages of the $app object can simple be
			// rendered by the respective helper function of Joomla!
			// They will automatically be displayed at the messages section of the template
			Joomla.renderMessages(r.messages);
		}

		if (r.data)
		{
			// Here you can access all the data of your response
			alert(r.data.myfirstcustomparam);
			alert(r.data.mysecondcustomparam);
		}
	}.bind(this),
	onFailure: function(xhr)
	{
		// Reaching this point means that the Ajax request itself was not successful
		// So JResponseJson was never called
		alert('Ajax error');
	}.bind(this),
	onError: function(text, error)
	{
		// Reaching this point means that the Ajax request was answered by the server, but
		// the response was no valid JSON (this happens sometimes if there were PHP errors,
		// warnings or notices during the development process of a new Ajax request).
		alert(error + "\n\n" + text);
	}.bind(this)
});
req.post('anyparam=myvalue');

Best Practice

As already seen above, code of the controller can be kept very simple using JResponseJson. The model is calculating the data which can be passed to JResponseJson afterwards (of course you can still modify it in the controller if you want to). If you are developing an MVC component you should save such a controller in a file called 'mycontroller.json.php' and place it inside your 'controllers' folder. This way, that controller is automatically executed if your request URL contains 'format=json'.

Please note that as you can see in the example, there is no need for closing the application (e.g. $app->close();) because the architecture of Joomla! handles that for you. So, this is very clean and good programming.

class MyController extends JControllerLegacy
{
  public function execute()
  {
    try
    {
      $anyParam = JFactory::getApplication()->input->get('anyparam');

      $count = $this->getModel('example')->countSomething($anyParam);

      echo new JResponseJson($count);
    }
    catch(Exception $e)
    {
      echo new JResponseJson($e);
    }
  }
}

Additional Note

If you want to support no-js users by for example doing the same task with a normal request and a final redirect back to the page, there is not much you have do additionally. Just create another controller (now with name 'mycontroller.php') and code like this:

class MyController extends JControllerLegacy
{
  public function execute()
  {
    $app = JFactory::getApplication();
    $app->setRedirect(JRoute::_('index.php?option=com_mycomponent&view=myview', false));

    try
    {
      $anyParam = JFactory::getApplication()->input->get('anyparam');

      $count = $this->getModel('example')->countSomething($anyParam);

      $app->setMessage(JText::plural('COM_COMPONENT_COUNT_TASK', $count));
    }
    catch(Exception $e)
    {
      $app->setMessage(JText::sprintf('COM_COMPONENT_COUNT_TASK_ERROR', $e->getMessage()), 'error');
    }
  }
}

No changes necessary in the model!

So depending on whether you do the request with 'format=json' (Ajax-Request) or via normal request (without 'format' parameter), the correct controller is executed automatically and the response is prepared accordingly.