Event Handlers
Design your API and update the page dynamically.
AJAX event handlers are API endpoints for the AJAX framework to communicate with the server. They can respond with raw data, redirect the browser or dynamically update partials on the page.
# AJAX Handlers
To create an AJAX handler, define it as a PHP function the page, partial or layout PHP section, or inside CMS components. Handler names should use the onSomething
pattern, for example, onName
. All handlers support the use of updating partials as part of the AJAX request.
function onSubmitContactForm()
{
// ...
}
If two handlers with the same name are defined in a page and layout together, the page handler will take priority. The handlers defined in components have the lowest priority.
# Calling a Handler
Every AJAX request should specify a handler name, either using the data attributes API or the JavaScript API. When the request is made, the server will search all the registered handlers and locate the first one it finds.
<!-- Attributes API -->
<button data-request="onSubmitContactForm">Go</button>
<!-- JavaScript API -->
<script> oc.ajax('onSubmitContactForm') </script>
# Form Serialization
When an AJAX request occurs inside a HTML form tag, all the input values of the form are available to the handler. In the example below, the first_name
value will be sent with the request.
<form id="myForm">
<input name="first_name" />
<button data-request="onSubmitContactForm">Go</button>
</form>
The JavaScript API support this logic with the oc.request
function.
<script> oc.request('#myForm', 'onSubmitContactForm') </script>
You may use the input()
PHP function to access the variable.
function onSubmitContactForm()
{
$firstName = input('first_name');
}
# Generic Handler
Sometimes you may need to make an AJAX request for the sole purpose of updating page contents, not needing to execute any code. You may use the onAjax
handler for this purpose. This handler is available everywhere without needing to write any code.
<button data-request="onAjax">Do nothing</button>
# Component Handlers
If two components register the same handler name, it is advised to prefix the handler with the component short name or alias. If a component uses an alias of mycomponent the handler can be targeted with mycomponent::onName
.
<button data-request="mycomponent::onSubmitContactForm">Go</button>
See the Component Development article to learn more.
# Redirects in AJAX Handlers
If you need to redirect the browser to another location, return the Redirect
response object from the AJAX handler. The framework will redirect the browser as soon as the response is returned from the server. Example AJAX handler with a redirect.
function onRedirectMe()
{
return Redirect::to('http://google.com');
}
# Returning Data from AJAX Handlers
The response from an AJAX handler can serve as consumable API by returning structured data. If an AJAX handler returns an array, you can access its elements in the success
event handler. Example AJAX handler that returns a data object.
function onFetchDataFromServer()
{
// Some server-side code
return [
'totalUsers' => 1000,
'totalProjects' => 937
];
}
The data can be fetched with the data attributes API.
<form data-request="onHandleForm" data-request-success="console.log(data)">
The same with the JavaScript API.
<form onsubmit="oc.request(this, 'onHandleForm', {
success: function(data) {
console.log(data);
}
}); return false"
>
# Throwing an AJAX Exception
You may throw an AJAX exception using the AjaxException
class to treat the response as an error while retaining the ability to send response contents as normal. Simply pass the response contents as the first argument of the exception.
throw new AjaxException([
'error' => 'Not enough questions',
'questionsNeeded' => 2
]);
These errors are handled by the AJAX framework.
<form data-request="onHandleForm" data-request-error="console.log(data)">
The same with the JavaScript API.
<form onsubmit="oc.request(this, 'onHandleForm', {
error: function(data) {
console.log(data);
}
}); return false"
>
When throwing this exception type partials will be updated as normal.
# Running Code Before Handlers
Sometimes you may want code to execute before a handler executes. Defining an onInit
function as part of the Layout Execution Life Cycle allows code to run before every AJAX handler.
function onInit()
{
// From a page or layout PHP code section
}
You may define an init
method inside a CMS component class.
function init()
{
// From a component or widget class
}