ajaxHandler()

The ajaxHandler() function runs an AJAX handler inside Twig and prepares a Cms\Classes\AjaxResponse response object. An example of calling an onResetPassword handler.

{% set result = ajaxHandler('onResetPassword') %}

The following properties can be expected in the resulting object.

# Accessing Data

Variables assigned to the page are available to the resulting object. Take the following AJAX handler definition.

function onResetPassword()
{
    $this['someVariable'] = 'someValue';
}

Next is an, an example of calling the onResetPassword handler.

{% set result = ajaxHandler('onResetPassword') %}

The data variables returned from the handler or set on the page during the handler call will be available via resulting variable.

{{ result.someVariable }}

# Using Responses

When building APIs in your theme, the response can be passed directly to the response() Twig function.

{% do response(ajaxHandler('onResetPassword')) %}

When returning as a response, the data will be available in JSON as the data property.

{
    "data": {}
}

The page variables are not included with the response for security reasons. Call the withPageVars method to include them with the response.

{% do response(ajaxHandler('onResetPassword').withPageVars()) %}

The withVars method can be used to include additional data with the response.

{% do response(ajaxHandler('onResetPassword').withVars({ 'token': 'foobar' })) %}

# Handling Errors

If an exception occurs during the handler, the error message will be available in the error.message property. If the error is a ValidationException then the invalid fields can be found in the error.fields property.

{% if result.error %}
    An error occurred: {{ result.error.message }}
{% endif %}

If an exception occurs, the error information will be available as the error property.

{
    "error": {
        "message": "An error occurred"
    }
}

When returning a response from an AJAX handler, the following status codes are used for the exception type.

# Handling Redirects

If the AJAX handler caused a redirect, this will be available on the redirect property and can be returned directly. For example

function onRedirect()
{
    return Redirect::to('https://octobercms.com');
}

The following will redirect to the browser as a response.

{% do response(ajaxHandler('onTest')) %}

The object contains the redirect messages alongside the data.

{
    "data": {},
    "redirect": "https://octobercms.com"
}

# Handling Flash Messages

If flash messages were used, these will be available in the flash property. Take the following handler as an example.

function onTest()
{
    Flash::success('Test successful');
}

Calling the handler and sending as a response.

{% do response(ajaxHandler('onTest')) %}

The output contains the flash messages alongside the data.

{
    "data": {},
    "flash": {
        "success": "Test successful"
    }
}

# See Also