Sign up to our newsletter to receive updates on Winter CMS releases,
new features in the works, and much more.
We'll never spam or give
this address away.
AJAX event handlers are PHP functions that can be defined in the page or layout PHP section or inside components. Handler names should have the following pattern: 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 be executed. The handlers defined in components have the lowest priority.
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> $.request('onSubmitContactForm') </script>
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>
You may want to use the __SELF__
reference variable instead of the hard coded alias in case the user changes the component alias used on the page.
<form data-request="{{ __SELF__ }}::onCalculate" data-request-update="'{{ __SELF__ }}::calcresult': '#result'">
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>
If you need to redirect the browser to another location, return the Redirect
object from the AJAX handler. The framework will redirect the browser as soon as the response is returned from the server. Example AJAX handler:
function onRedirectMe()
{
return Redirect::to('https://google.com');
}
In advanced cases you may want to return structured data from your AJAX handlers. If an AJAX handler returns an array, you can access its elements in the success
event handler. Example AJAX handler:
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="$(this).request('onHandleForm', {
success: function(data) {
console.log(data);
}
}); return false;">
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
]);
NOTE: When throwing this exception type partials will be updated as normal.
Sometimes you may want code to execute before a handler executes. Defining an onInit
function as part of the page 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 component class or backend widget class.
function init()
{
// From a component or widget class
}
Sign up to our newsletter to receive updates on Winter CMS releases,
new features in the works, and much more.
We'll never spam or give
this address away.
Released October 20, 2022
14 UX/UI Improvements, 25 API Changes, 33 Bug Fixes, 4 Security Improvements, 5 Translation Improvements, 1 Performance Improvement, 2 Community Improvements, 2 Dependencies, 0 New Contributors
* @cstorus made their first contribution in https://github.com/wintercms/winter/pull/616
* @simonmannsfeld made their first contribution in https://github.com/wintercms/winter/pull/623
* @quangtrongonline made their first contribution in https://github.com/wintercms/winter/pull/636
* @nathanlesage made their first contribution in https://github.com/wintercms/winter/pull/665
* @vllvll made their first contribution in https://github.com/wintercms/winter/pull/669
* @robertalexa made their first contribution in https://github.com/wintercms/winter/pull/668
* @iamyigitkoc made their first contribution in https://github.com/wintercms/winter/pull/624
* @hecc127 made their first contribution in https://github.com/wintercms/winter/pull/682
* @prsuhas made their first contribution in https://github.com/wintercms/winter/pull/723