Main Website →
JavaScript API
Interact with handlers using JavaScript code.
The JavaScript API is more powerful than the data attributes API. The oc.request method can be used with any element that is inside a form, or on a form element. When the method is used with an element inside a form, it is forwarded to the form.
The oc.request takes the target element and AJAX handler name as the first and second arguments. The target element can be a selector string or a HTML element. For example:
<form onsubmit="oc.request(this, 'onProcess'); return false;">
...
The third argument of the oc.request method is an options object. The following options are specific for the October CMS framework.
| Option | Description |
|---|---|
| update | an object, specifies a list partials and page elements (as CSS selectors) to update: {'partial': '#select'}. The selector string should start with a # or . character, except you may also prepend it with @ to append contents to the element, ^ to prepend, ! to replace with and = to use any CSS selector. |
| confirm | the confirmation string. If set, a confirmation dialog is displayed before the request is sent. If the user clicks the Cancel button, the request cancels. |
| data | an optional object specifying data to be sent to the server along with the form data: {var: 'value'}. You may also include files to be uploaded in this object by using Blob objects (opens new window). To specify the filename of any Blob objects, simply set the filename property on the Blob object. (Eg. var blob = new Blob(variable); blob.filename = 'test.txt'; var data = {uploaded_file: blob};) |
| query | an optional object specifying data to be added to the current URL query string. |
| headers | an optional object specifying header values to be sent to the server with the request. |
| redirect | string specifying an URL to redirect the browser to after the successful request. |
| beforeUpdate | a callback function to execute before page elements are updated. The this variable inside the function resolves to the request content - an object containing 2 properties: handler and options representing the original request() parameters. |
| afterUpdate | a callback function identical to beforeUpdate except it executes after the page elements are updated. |
| success | a callback function to execute in case of a successful request. If this option is supplied it overrides the default framework functionality: the elements are not updated, the beforeUpdate and afterUpdate callbacks are not triggered, the ajax:update and ajax:update-complete events are not triggered. To call the default framework functionality, use this.success(...) inside your function. |
| error | a callback function execute in case of an error. By default the alert message is displayed. If this option is overridden the alert message won't be displayed. |
| complete | a callback function execute in case of a success or an error. |
| cancel | a callback function execute in case the user aborts the request or cancels it via a confirmation dialog. |
| form | a form element to use for sourcing the form data sent with the request, either passed as a selector string or a form element. |
| flash | when true, instructs the server to clear and send any flash messages with the response. default: false |
| files | when true, the request will accept file uploads using the FormData interface. default: false |
| download | when true, file downloads are accepted with a Content-Disposition response. When a string, the downloaded filename can be specified. default: false |
| bulk | when true, the request be sent as JSON for bulk data transactions. default: false |
| browserValidate | when true, browser-based client side validation will be performed on the request before submitting. Only applies to requests triggered in the context of a <form> element. |
| message | displays a progress message with the specified text, shown while the request is running. This option is used by the flash messages features. |
| loading | an optional string or object to be displayed when a request runs. The string should be a CSS selector for an element or the object should support the show() and hide() functions to manage the visibility. |
| progressBar | enable the progress bar when an AJAX request occurs. |
The beforeUpdate, afterUpdate, success, error, and complete options all take functions with three arguments: the data object received from the server, the HTTP status code and the XHR object.
success: function(data, responseCode, xhr) { }
You may also override some of the request logic by passing new functions as options. These logic handlers are available.
| Handler | Description |
|---|---|
| handleConfirmMessage(message, promise) | called when requesting confirmation from the user. |
| handleErrorMessage(message) | called when an error message should be displayed. |
| handleValidationMessage(message, fields) | focuses the first invalid field when validation is used. |
| handleFlashMessage(message, type) | called when a flash message is provided using the flash option (see above). |
| handleRedirectResponse(url) | called when the browser should redirect to another location. |
# Usage Examples
Request a confirmation before the onDelete request is sent.
oc.request('#myform', 'onDelete', {
confirm: 'Are you sure?',
redirect: '/dashboard'
});
Run onCalculate handler and inject the rendered calcresult partial into the page element with the result CSS class.
oc.request('#myform', 'onCalculate', {
update: { calcresult: '.result' }
})
Run onCalculate handler with some extra data.
oc.request('#myform', 'onCalculate', { data: { value: 55 } })
Run onCalculate handler and run some custom code before the page elements update.
oc.request('#myform', 'onCalculate', {
update: { calcresult: '.result' },
beforeUpdate: function() { /* do something */ }
})
Run onCalculate handler and if successful, run some custom code after the page elements are updated.
oc.request('#myform', 'onCalculate', {
afterUpdate: function() { /* do something */ }
})
Use the oc.ajax method to execute a request without a FORM element.
oc.ajax('onCalculate', {
success: function() {
console.log('Finished!');
}
})
Run onCalculate handler and if successful, run some custom code after the default success function is done.
oc.request('#myform', 'onCalculate', {
success: function(data) {
this.success(data).done(function() {
// ... do something after parent success() is finished ...
});
}
})
# Global AJAX Events
The AJAX framework triggers events on the updated elements, triggering element, form, and window object. The events are triggered regardless of which API was used - the data attributes API or the JavaScript API.
Extra details are available on the event.detail property of the event handler. Unless otherwise specified, the handler details are the context object, the data object received from the server, the responseCode and the xhr object.
| Event | Description |
|---|---|
| ajax:before-send | triggered on the window object before sending the request. The handler details provide the context object. |
| ajax:before-update | triggered on the form object directly after the request is complete, but before the page is updated. |
| ajax:update | triggered on a page element after it has been updated with the framework. |
| ajax:update-complete | triggered on the window object after all elements are updated by the framework. |
| ajax:request-success | triggered on the form object after the request is successfully completed. The handler gets 5 parameters: the event object, the context object, the data object received from the server, the status text string, and the XHR object. |
| ajax:request-error | triggered on the form object if the request encounters an error. |
| ajax:error-message | triggered on the window object if the request encounters an error. The handler has a message detail with the error message returned from the server. |
| ajax:confirm-message | triggered on the window object when confirm option is given. The handler has a message detail with a text message assigned to the handler as part of confirm option. A promise detail is also provided to defer or cancel the outcome, this is useful for implementing custom confirm logic/interface instead of native javascript confirm box. |
These events are fired on the triggering element:
| Event | Description |
|---|---|
| ajax:setup | triggered before the request is formed. The handler details provide the context object, allowing options to be modified via the context.options property. |
| ajax:promise | triggered directly before the AJAX request is sent. The handler details provide the context object. |
| ajax:fail | triggered finally if the AJAX request fails. |
| ajax:done | triggered finally if the AJAX request was successful. |
| ajax:always | triggered regardless if the AJAX request fails or was successful. |
# Usage Examples
Executes JavaScript code when the ajax:update event is triggered on an element.
document.querySelector('#result').addEventListener('ajax:update', function() {
console.log('Updated!');
});
Execute a single request that shows a Flash Message using logic handler.
oc.ajax('onDoSomething', {
flash: true,
handleFlashMessage: function(message, type) {
oc.flashMsg({ message: message, type: type });
}
});
Applies configurations to all AJAX requests globally.
addEventListener('ajax:setup', function(event) {
const { options } = event.detail.context;
// Enable AJAX handling of Flash messages on all AJAX requests
options.flash = true;
// Disable the progress bar for all AJAX requests
options.progressBar = false;
// Handle Error Messages by triggering a flashMsg of type error
options.handleErrorMessage = function(message) {
oc.flashMsg({ message: message, type: 'error' });
}
// Handle Flash Messages by triggering a flashMsg of the message type
options.handleFlashMessage = function(message, type) {
oc.flashMsg({ message: message, type: type });
}
});
Using a supplied promise from the event detail.
addEventListener('ajax:confirm-message', function(event) {
const { message, promise } = event.detail;
// Prevent default behavior
event.preventDefault();
// Handle promise
if (confirm(message)) {
promise.resolve();
}
else {
promise.reject();
}
});
Animating an element after a specific AJAX handler completes its update.
addEventListener('ajax:update-complete', function(event) {
const { handler } = event.detail.context;
// If the handler is either of the following
if (['onRemoveFromCart', 'onAddToCart'].includes(handler)) {
// Run an animation for 2 seconds
var el = document.querySelector('#miniCart');
el.classList.add('animate-shockwave');
setTimeout(function() { el.classList.remove('animate-shockwave'); }, 2000);
}
});