From d93c9a642b87ad23344d1f1575ba235fc9bcc011 Mon Sep 17 00:00:00 2001 From: Sam G Date: Sun, 11 Jan 2026 14:05:23 +1100 Subject: [PATCH 1/2] Refactor to reference Larajax --- 4.x/cms/ajax/attributes-api.md | 43 ++++------- 4.x/cms/ajax/handlers.md | 12 ++-- 4.x/cms/ajax/hot-controls.md | 54 +++++++------- 4.x/cms/ajax/introduction.md | 6 ++ 4.x/cms/ajax/javascript-api.md | 112 +++++++++-------------------- 4.x/cms/ajax/turbo-router.md | 17 ++--- 4.x/cms/ajax/update-partials.md | 2 +- 4.x/cms/features/flash-messages.md | 16 ++--- 4.x/cms/features/loaders.md | 20 +++--- 9 files changed, 117 insertions(+), 165 deletions(-) diff --git a/4.x/cms/ajax/attributes-api.md b/4.x/cms/ajax/attributes-api.md index 385d700a..42f30bfa 100644 --- a/4.x/cms/ajax/attributes-api.md +++ b/4.x/cms/ajax/attributes-api.md @@ -3,35 +3,13 @@ subtitle: Interact with handlers using HTML attributes. --- # Data Attributes API -The data attributes API lets you issue AJAX requests without any JavaScript. In many cases the data attributes API is less verbose than the JavaScript API - you write less code to get the same result. The supported AJAX data attributes are: +The data attributes API lets you issue AJAX requests without any JavaScript. In many cases the data attributes API is less verbose than the JavaScript API - you write less code to get the same result. -data-request Attribute | Description -------------- | ------------- -**data-request** | specifies the AJAX handler name. -**data-request-confirm** | specifies a confirmation message. A confirmation dialog is displayed before the request is sent. If the user clicks the Cancel button the request isn't sent. -**data-request-redirect** | specifies a URL to redirect the browser after the successful AJAX request. -**data-request-url** | specifies a URL to which the request is sent. default: `window.location.href` -**data-request-update** | specifies a list of partials and page elements (CSS selectors) to update. The format is as follows: `partial: selector, partial: selector`. Usage of quotes is required in some cases, for example: `'my-partial': '#myelement'`. 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. -**data-request-data** | specifies additional POST parameters to be sent to the server. The format is following: `var: value, var: value`. Use quotes if needed: `var: 'some string'`. The attribute can be used on the triggering element, for example on the button that also has the `data-request` attribute, on the closest element of the triggering element and on the parent form element. The framework merges values of the `data-request-data` attributes. If the attribute on different elements defines parameters with the same name, the framework uses the following priority: the triggering element `data-request-data`, the closer parent elements `data-request-data`, the form input data. -**data-request-query** | specifies additional GET parameters to be sent to the server and added to the current URL query string. -**data-request-before-update** | specifies JavaScript code to execute directly before the page contents are updated. -**data-request-success** | specifies JavaScript code to execute after the request is successfully completed. The `data` variable is available in this function containing the response data. -**data-request-error** | specifies JavaScript code to execute if the request encounters an error. The `data` variable is available in this function containing the response data. -**data-request-complete** | specifies JavaScript code to execute if the request is successfully completed or encounters an error. The `data` variable is available in this function containing the response data. -**data-request-cancel** | specifies JavaScript code to execute if the user aborts the request or cancels it via a confirmation dialog. -**data-request-message** | displays a progress message with the specified text, shown while the request is running. This option is used by the [flash messages features](./features/flash-messages.md). -**data-request-loading** | specifies a CSS selector for an element to be displayed while the request runs. You can use this option to show an AJAX loading indicator. The feature uses CSS display `block` and `none` attributes to manage the element visibility. -**data-request-progress-bar** | enable the [progress bar](./features/loaders.md) when an AJAX request occurs. -**data-request-form** | explicitly specify a form element to use for sourcing the form data. If this is unspecified, the closest form to the triggering element is used, including if the element itself is a form. -**data-request-flash** | when included, instructs the server to clear and send any flash messages with the response. This option is used by the [flash messages features](./features/flash-messages.md). -**data-request-files** | when specified the request will accept file uploads using the `FormData` interface. -**data-request-download** | when specified file downloads are accepted with a `Content-Disposition` response. This attribute can be added anonymously or set to the downloaded filename. -**data-request-bulk** | when specified the request be sent as JSON for bulk data transactions. -**data-browser-target** | when specified with `data-request-download` the output will target this window, for example `_blank`. -**data-browser-validate** | when specified browser-based client side validation will run on the request before it submits. -**data-browser-redirect-back** | when a redirect occurs, if the previous URL from the browser is available, use that in place of the redirect URL provided. -**data-auto-submit** | automatically triggers an AJAX request on elements that also have the `data-request` attribute. The request submits when the browser window is active using the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API). The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the request. -**data-track-input** | can be applied to a text, number, or password input field that also has the `data-request` attribute. When defined, the input field automatically sends an AJAX request when a user types something in the field. The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the requests. +The primary attribute is `data-request` which specifies the AJAX handler name. Other common attributes include `data-request-update`, `data-request-confirm`, `data-request-data`, and `data-request-redirect`. + +::: tip +For the complete list of available data attributes and their descriptions, see the [Larajax Attributes Reference](https://larajax.org/api/attributes). +::: When the `data-request` attribute is specified for an element, the element triggers an AJAX request when a user interacts with it. Depending on the type of element, the request is triggered on the following events: @@ -93,7 +71,7 @@ Send a GET parameter `page` with value `6` on the current request. ``` -Show a [flash message](./features/flash-messages.md) while the request is loading. +Show a [flash message](../features/flash-messages.md) while the request is loading. ```html ``` + +#### See Also + +::: also +* [Larajax Attributes Reference](https://larajax.org/api/attributes) +* [JavaScript API](./javascript-api.md) +::: diff --git a/4.x/cms/ajax/handlers.md b/4.x/cms/ajax/handlers.md index 0c115355..a66f70e4 100644 --- a/4.x/cms/ajax/handlers.md +++ b/4.x/cms/ajax/handlers.md @@ -29,7 +29,7 @@ Every AJAX request should specify a handler name, either using the [data attribu - + ``` Handlers defined by pages, layouts and components are all registered automatically. If you are calling a handler from inside a partial, use the [`{% ajaxPartial %}` Twig tag](../../markup/tag/ajax-partial.md), which adjusts the page cycle to register its handlers. @@ -45,10 +45,10 @@ When an AJAX request occurs inside a HTML form tag, all the input values of the ``` -The JavaScript API support this logic with the `oc.request` function. +The JavaScript API support this logic with the `jax.request` function. ```html - + ``` You may use the `input()` PHP function to access the variable. @@ -114,7 +114,7 @@ The data can be fetched with the data attributes API. The same with the JavaScript API. ```html -
``` + +#### See Also + +::: also +* [Larajax Hot Controls](https://larajax.org/controls/definition) +::: diff --git a/4.x/cms/ajax/introduction.md b/4.x/cms/ajax/introduction.md index d403724a..d646e1f3 100644 --- a/4.x/cms/ajax/introduction.md +++ b/4.x/cms/ajax/introduction.md @@ -7,6 +7,12 @@ October CMS includes an AJAX framework that brings a full suite of capabilities, The AJAX framework comes in two flavors, you may either use [the JavaScript API](./javascript-api.md) or [the data attributes API](./attributes-api.md). The data attributes API doesn't require any JavaScript knowledge to use AJAX with October CMS. +## About Larajax + +October CMS uses [Larajax](https://larajax.org) as its AJAX framework foundation. The `jax` JavaScript object provides the client-side API, while the server-side integrates seamlessly with October's CMS components and Twig templating. + +For standalone Laravel applications or advanced usage, refer to the [Larajax Documentation](https://larajax.org). + ## Including the Framework ::: aside diff --git a/4.x/cms/ajax/javascript-api.md b/4.x/cms/ajax/javascript-api.md index 901de79b..b9da9363 100644 --- a/4.x/cms/ajax/javascript-api.md +++ b/4.x/cms/ajax/javascript-api.md @@ -3,64 +3,27 @@ subtitle: Interact with handlers using JavaScript code. --- # JavaScript API -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 JavaScript API is more powerful than the data attributes API. The `jax.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: +The `jax.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: ```html - + ... ``` -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](https://developer.mozilla.org/en-US/docs/Web/API/Blob). 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 `` element. -**browserRedirectBack** | when true and a redirect occurs, if the previous URL from the browser is available, use that in place of the redirect URL provided. Default: `false`. -**message** | displays a progress message with the specified text, shown while the request is running. This option is used by the [flash messages features](./features/flash-messages.md). -**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](./features/loaders.md) 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. +The third argument of the `jax.request` method is an options object. Common options include `update`, `confirm`, `data`, `redirect`, and callback functions like `success` and `error`. -```js -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. +::: tip +For the complete list of request options and their descriptions, see the [Larajax JavaScript API Reference](https://larajax.org/api/framework). +::: ## Usage Examples Request a confirmation before the `onDelete` request is sent. ```js -oc.request('#myform', 'onDelete', { +jax.request('#myform', 'onDelete', { confirm: 'Are you sure?', redirect: '/dashboard' }); @@ -69,7 +32,7 @@ oc.request('#myform', 'onDelete', { Run `onCalculate` handler and inject the rendered **calcresult** partial into the page element with the **result** CSS class. ```js -oc.request('#myform', 'onCalculate', { +jax.request('#myform', 'onCalculate', { update: { calcresult: '.result' } }) ``` @@ -77,13 +40,13 @@ oc.request('#myform', 'onCalculate', { Run `onCalculate` handler with some extra data. ```js -oc.request('#myform', 'onCalculate', { data: { value: 55 } }) +jax.request('#myform', 'onCalculate', { data: { value: 55 } }) ``` Run `onCalculate` handler and run some custom code before the page elements update. ```js -oc.request('#myform', 'onCalculate', { +jax.request('#myform', 'onCalculate', { update: { calcresult: '.result' }, beforeUpdate: function() { /* do something */ } }) @@ -92,15 +55,15 @@ oc.request('#myform', 'onCalculate', { Run `onCalculate` handler and if successful, run some custom code after the page elements are updated. ```js -oc.request('#myform', 'onCalculate', { +jax.request('#myform', 'onCalculate', { afterUpdate: function() { /* do something */ } }) ``` -Use the `oc.ajax` method to execute a request without a FORM element. +Use the `jax.ajax` method to execute a request without a FORM element. ```js -oc.ajax('onCalculate', { +jax.ajax('onCalculate', { success: function() { console.log('Finished!'); } @@ -110,7 +73,7 @@ oc.ajax('onCalculate', { Run `onCalculate` handler and if successful, run some custom code after the default `success` function is done. ```js -oc.request('#myform', 'onCalculate', { +jax.request('#myform', 'onCalculate', { success: function(data) { this.success(data).done(function() { // ... do something after parent success() is finished ... @@ -123,30 +86,13 @@ oc.request('#myform', 'onCalculate', { 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. +Extra details are available on the `event.detail` property of the event handler. Common events include `ajax:before-send`, `ajax:update`, `ajax:update-complete`, `ajax:done`, and `ajax:fail`. -## Usage Examples +::: tip +For the complete list of AJAX events and their details, see the [Larajax Events Reference](https://larajax.org/api/events). +::: + +## Event Examples Executes JavaScript code when the `ajax:update` event is triggered on an element. @@ -159,10 +105,10 @@ document.querySelector('#result').addEventListener('ajax:update', function() { Execute a single request that shows a Flash Message using logic handler. ```js -oc.ajax('onDoSomething', { +jax.ajax('onDoSomething', { flash: true, handleFlashMessage: function(message, type) { - oc.flashMsg({ message: message, type: type }); + jax.flashMsg({ message: message, type: type }); } }); ``` @@ -181,12 +127,12 @@ addEventListener('ajax:setup', function(event) { // Handle Error Messages by triggering a flashMsg of type error options.handleErrorMessage = function(message) { - oc.flashMsg({ message: message, type: 'error' }); + jax.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 }); + jax.flashMsg({ message: message, type: type }); } }); ``` @@ -226,3 +172,11 @@ addEventListener('ajax:update-complete', function(event) { } }); ``` + +#### See Also + +::: also +* [Larajax JavaScript API](https://larajax.org/api/framework) +* [Larajax Events Reference](https://larajax.org/api/events) +* [Data Attributes API](./attributes-api.md) +::: diff --git a/4.x/cms/ajax/turbo-router.md b/4.x/cms/ajax/turbo-router.md index 643e554b..c2d9efce 100644 --- a/4.x/cms/ajax/turbo-router.md +++ b/4.x/cms/ajax/turbo-router.md @@ -20,19 +20,19 @@ Once enabled, all internal links on the page will automatically use PJAX navigat You may programmatically visit a link with the following. ```js -oc.visit(location); +jax.visit(location); ``` To replace the current URL without adding it to the navigation history, similar to `window.history.replaceState`, set the `action` option to **replace**. ```js -oc.visit(location, { action: 'replace' }); +jax.visit(location, { action: 'replace' }); ``` To check if the turbo router is enabled and should be used. ```js -if (oc.useTurbo && oc.useTurbo()) { +if (jax.useTurbo && jax.useTurbo()) { // Use PJAX } ``` @@ -159,18 +159,18 @@ addEventListener('render', function() { }); ``` -The `oc.pageReady` function is used call code when the page and scripts are ready. The function returns a promise that is resolved after all the page scripts have loaded, or immediately if they are already loaded. +The `jax.pageReady` function is used call code when the page and scripts are ready. The function returns a promise that is resolved after all the page scripts have loaded, or immediately if they are already loaded. ```js -oc.pageReady().then(() => { +jax.pageReady().then(() => { // Page has finished loading scripts }); ``` -The `oc.waitFor` is another useful function that will wait for an object or variable to exist. The function returns a promise that is resolved when the variable is found. +The `jax.waitFor` is another useful function that will wait for an object or variable to exist. The function returns a promise that is resolved when the variable is found. ```js -oc.waitFor(() => window.propName).then(() => [ +jax.waitFor(() => window.propName).then(() => [ // window.propName is now available ]); ``` @@ -178,7 +178,7 @@ oc.waitFor(() => window.propName).then(() => [ The second argument provides a timeout interval in milliseconds, the following will stop waiting after two seconds. ```js -oc.waitFor(() => window.propName, 2000).then(() => { +jax.waitFor(() => window.propName, 2000).then(() => { console.log('Found the variable!') }).catch(() => { console.error('Gave up waiting...') @@ -324,5 +324,6 @@ snippetOptions: { #### See Also ::: also +* [Larajax Turbo Router](https://larajax.org/turbo/setup) * [Observable Controls](./hot-controls.md) ::: diff --git a/4.x/cms/ajax/update-partials.md b/4.x/cms/ajax/update-partials.md index 0a2a9316..1eefc785 100644 --- a/4.x/cms/ajax/update-partials.md +++ b/4.x/cms/ajax/update-partials.md @@ -32,7 +32,7 @@ The [JavaScript API](./javascript-api.md) uses the `update` configuration option ```js // JavaScript API -oc.request('#mybutton', 'onRefreshTime', { +jax.request('#mybutton', 'onRefreshTime', { update: { mytime: '#myDiv' } }); ``` diff --git a/4.x/cms/features/flash-messages.md b/4.x/cms/features/flash-messages.md index b27426d4..f99122de 100644 --- a/4.x/cms/features/flash-messages.md +++ b/4.x/cms/features/flash-messages.md @@ -77,22 +77,22 @@ The `data-request-message` attribute can be used to display a flash progress mes ### Styling the Flash Message -To change the appearance of the flash message, target the `.oc-flash-message` CSS class. +To change the appearance of the flash message, target the `.jax-flash-message` CSS class. ```css -.oc-flash-message.success { +.jax-flash-message.success { background: green; } -.oc-flash-message.error { +.jax-flash-message.error { background: red; } -.oc-flash-message.warning { +.jax-flash-message.warning { background: orange; } -.oc-flash-message.info { +.jax-flash-message.info { background: aqua; } -.oc-flash-message.loading { +.jax-flash-message.loading { background: aqua; } ``` @@ -144,10 +144,10 @@ Alternatively, you can include the partial inside a layout, and update it global ## Working with JavaScript -Use the `oc.flashMsg` function to display a flash message using JavaScript. A type can be specified as either `success`, `error` or `warning`. An optional `interval` can be specified to control how long the flash message is displayed in seconds. +Use the `jax.flashMsg` function to display a flash message using JavaScript. A type can be specified as either `success`, `error` or `warning`. An optional `interval` can be specified to control how long the flash message is displayed in seconds. ```js -oc.flashMsg({ +jax.flashMsg({ message: 'Record has been successfully saved. This message will disappear in 1 second.', type: 'success', interval: 1 diff --git a/4.x/cms/features/loaders.md b/4.x/cms/features/loaders.md index 7b87b61c..833a95a2 100644 --- a/4.x/cms/features/loaders.md +++ b/4.x/cms/features/loaders.md @@ -22,28 +22,28 @@ To disable the progress bar for a request, set the `data-request-progress-bar` a In JavaScript, set the `progressBar` option of an AJAX request to `false`. ```js -oc.ajax('onSilentRequest', { progressBar: false }); +jax.ajax('onSilentRequest', { progressBar: false }); ``` To disable the progress bar globally, set the `visibility` style to `hidden` using a StyleSheet. ```css -.oc-progress-bar { +.jax-progress-bar { visibility: hidden; } ``` -You may display the progress bar using JavaScript using the `oc.progressBar` object and `show` / `hide` functions. +You may display the progress bar using JavaScript using the `jax.progressBar` object and `show` / `hide` functions. ```js -oc.progressBar.show(); +jax.progressBar.show(); -oc.progressBar.hide(); +jax.progressBar.hide(); ``` ## Loading Button -When submitting forms, users can accidentally click the button twice and cause a double submission, and this is solved using a loading button. During AJAX requests, button elements that have the `data-attach-loading` attribute will be disabled, and a CSS class `oc-attach-loader` added. This class will spawn a loading spinner on button and anchor elements using the `:after` CSS selector. +When submitting forms, users can accidentally click the button twice and cause a double submission, and this is solved using a loading button. During AJAX requests, button elements that have the `data-attach-loading` attribute will be disabled, and a CSS class `jax-attach-loader` added. This class will spawn a loading spinner on button and anchor elements using the `:after` CSS selector. ```html ``` -When a button exists inside a form that contain the `oc-attach-loader` attribute will display the loading indicator. +When a button exists inside a form that contain the `jax-attach-loader` attribute will display the loading indicator. ```html @@ -72,12 +72,12 @@ Since inputs do not support the `:after` CSS selector, they have a new element i data-attach-loading /> ``` -You can manually add the loader to a button using the `oc.attachLoader` object and `show` / `hide` functions passing the element selector or object as the first argument. +You can manually add the loader to a button using the `jax.attachLoader` object and `show` / `hide` functions passing the element selector or object as the first argument. ```js -oc.attachLoader.show('.my-element'); +jax.attachLoader.show('.my-element'); -oc.attachLoader.hide('.my-element'); +jax.attachLoader.hide('.my-element'); ``` ## Toggling Elements From 30610b8aa1bfdff591c456225362b397909f9740 Mon Sep 17 00:00:00 2001 From: Sam G Date: Wed, 21 Jan 2026 06:44:55 +1100 Subject: [PATCH 2/2] Restore tables --- 4.x/cms/ajax/attributes-api.md | 34 +++++++++++++--- 4.x/cms/ajax/javascript-api.md | 74 +++++++++++++++++++++++++++++----- 2 files changed, 92 insertions(+), 16 deletions(-) diff --git a/4.x/cms/ajax/attributes-api.md b/4.x/cms/ajax/attributes-api.md index 42f30bfa..e641a7e8 100644 --- a/4.x/cms/ajax/attributes-api.md +++ b/4.x/cms/ajax/attributes-api.md @@ -3,13 +3,35 @@ subtitle: Interact with handlers using HTML attributes. --- # Data Attributes API -The data attributes API lets you issue AJAX requests without any JavaScript. In many cases the data attributes API is less verbose than the JavaScript API - you write less code to get the same result. +The data attributes API lets you issue AJAX requests without any JavaScript. In many cases the data attributes API is less verbose than the JavaScript API - you write less code to get the same result. The supported AJAX data attributes are: -The primary attribute is `data-request` which specifies the AJAX handler name. Other common attributes include `data-request-update`, `data-request-confirm`, `data-request-data`, and `data-request-redirect`. - -::: tip -For the complete list of available data attributes and their descriptions, see the [Larajax Attributes Reference](https://larajax.org/api/attributes). -::: +Attribute | Description +------------- | ------------- +[data-request](https://larajax.org/api/attributes/request) | specifies the AJAX handler name. +[data-request-confirm](https://larajax.org/api/attributes/request-confirm) | specifies a confirmation message. A confirmation dialog is displayed before the request is sent. If the user clicks the Cancel button the request isn't sent. +[data-request-redirect](https://larajax.org/api/attributes/request-redirect) | specifies a URL to redirect the browser after the successful AJAX request. +[data-request-url](https://larajax.org/api/attributes/request-url) | specifies a URL to which the request is sent. default: `window.location.href` +[data-request-update](https://larajax.org/api/attributes/request-update) | specifies a list of partials and page elements (CSS selectors) to update. The format is as follows: `partial: selector, partial: selector`. Usage of quotes is required in some cases, for example: `'my-partial': '#myelement'`. 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. +[data-request-data](https://larajax.org/api/attributes/request-data) | specifies additional POST parameters to be sent to the server. The format is following: `var: value, var: value`. Use quotes if needed: `var: 'some string'`. The attribute can be used on the triggering element, for example on the button that also has the `data-request` attribute, on the closest element of the triggering element and on the parent form element. The framework merges values of the `data-request-data` attributes. If the attribute on different elements defines parameters with the same name, the framework uses the following priority: the triggering element `data-request-data`, the closer parent elements `data-request-data`, the form input data. +[data-request-query](https://larajax.org/api/attributes/request-query) | specifies additional GET parameters to be sent to the server and added to the current URL query string. +[data-request-before-update](https://larajax.org/api/attributes/request-before-update) | specifies JavaScript code to execute directly before the page contents are updated. +[data-request-success](https://larajax.org/api/attributes/request-success) | specifies JavaScript code to execute after the request is successfully completed. The `data` variable is available in this function containing the response data. +[data-request-error](https://larajax.org/api/attributes/request-error) | specifies JavaScript code to execute if the request encounters an error. The `data` variable is available in this function containing the response data. +[data-request-complete](https://larajax.org/api/attributes/request-complete) | specifies JavaScript code to execute if the request is successfully completed or encounters an error. The `data` variable is available in this function containing the response data. +[data-request-cancel](https://larajax.org/api/attributes/request-cancel) | specifies JavaScript code to execute if the user aborts the request or cancels it via a confirmation dialog. +[data-request-message](https://larajax.org/api/attributes/request-message) | displays a progress message with the specified text, shown while the request is running. This option is used by the [flash messages features](../features/flash-messages.md). +[data-request-loading](https://larajax.org/api/attributes/request-loading) | specifies a CSS selector for an element to be displayed while the request runs. You can use this option to show an AJAX loading indicator. The feature uses CSS display `block` and `none` attributes to manage the element visibility. +[data-request-progress-bar](https://larajax.org/api/attributes/request-loading) | enable the [progress bar](../features/loaders.md) when an AJAX request occurs. +[data-request-form](https://larajax.org/api/attributes/request) | explicitly specify a form element to use for sourcing the form data. If this is unspecified, the closest form to the triggering element is used, including if the element itself is a form. +[data-request-flash](https://larajax.org/api/attributes/request-flash) | when included, instructs the server to clear and send any flash messages with the response. This option is used by the [flash messages features](../features/flash-messages.md). +[data-request-files](https://larajax.org/api/attributes/request-files) | when specified the request will accept file uploads using the `FormData` interface. +[data-request-download](https://larajax.org/api/attributes/request-files) | when specified file downloads are accepted with a `Content-Disposition` response. This attribute can be added anonymously or set to the downloaded filename. +[data-request-bulk](https://larajax.org/api/attributes/request) | when specified the request be sent as JSON for bulk data transactions. +[data-browser-target](https://larajax.org/api/attributes/request-files) | when specified with `data-request-download` the output will target this window, for example `_blank`. +[data-browser-validate](https://larajax.org/api/attributes/request-validate) | when specified browser-based client side validation will run on the request before it submits. +[data-browser-redirect-back](https://larajax.org/api/attributes/request-redirect) | when a redirect occurs, if the previous URL from the browser is available, use that in place of the redirect URL provided. +[data-request-poll](https://larajax.org/api/attributes/request-poll) | automatically triggers an AJAX request on elements that also have the `data-request` attribute. The request submits when the browser window is active using the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API). The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the request. +[data-track-input](https://larajax.org/api/attributes/request-trigger) | can be applied to a text, number, or password input field that also has the `data-request` attribute. When defined, the input field automatically sends an AJAX request when a user types something in the field. The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the requests. When the `data-request` attribute is specified for an element, the element triggers an AJAX request when a user interacts with it. Depending on the type of element, the request is triggered on the following events: diff --git a/4.x/cms/ajax/javascript-api.md b/4.x/cms/ajax/javascript-api.md index b9da9363..98e59e07 100644 --- a/4.x/cms/ajax/javascript-api.md +++ b/4.x/cms/ajax/javascript-api.md @@ -12,11 +12,48 @@ The `jax.request` takes the target element and AJAX handler name as the first an ... ``` -The third argument of the `jax.request` method is an options object. Common options include `update`, `confirm`, `data`, `redirect`, and callback functions like `success` and `error`. +The third argument of the `jax.request` method is an options object. The following options are specific for the October CMS framework. + +Option | Description +------------- | ------------- +[update](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | 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](https://developer.mozilla.org/en-US/docs/Web/API/Blob). 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](https://larajax.org/api/framework#request-options) | an optional object specifying data to be added to the current URL query string. +[headers](https://larajax.org/api/framework#request-options) | an optional object specifying header values to be sent to the server with the request. +[redirect](https://larajax.org/api/framework#request-options) | string specifying an URL to redirect the browser to after the successful request. +[beforeUpdate](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | a callback function identical to `beforeUpdate` except it executes after the page elements are updated. +[success](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | a callback function execute in case of a success or an error. +[cancel](https://larajax.org/api/framework#request-options) | a callback function execute in case the user aborts the request or cancels it via a confirmation dialog. +[form](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | when true, instructs the server to clear and send any flash messages with the response. Default: `false` +[files](https://larajax.org/api/framework#request-options) | when true, the request will accept file uploads using the `FormData` interface. Default: `false` +[download](https://larajax.org/api/framework#request-options) | when true, file downloads are accepted with a `Content-Disposition` response. When a string, the downloaded filename can be specified. Default: `false` +[bulk](https://larajax.org/api/framework#request-options) | when true, the request be sent as JSON for bulk data transactions. Default: `false` +[browserValidate](https://larajax.org/api/framework#request-options) | 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 `` element. +[browserRedirectBack](https://larajax.org/api/framework#request-options) | when true and a redirect occurs, if the previous URL from the browser is available, use that in place of the redirect URL provided. Default: `false`. +[message](https://larajax.org/api/framework#request-options) | displays a progress message with the specified text, shown while the request is running. This option is used by the [flash messages features](../features/flash-messages.md). +[loading](https://larajax.org/api/framework#request-options) | 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](https://larajax.org/api/framework#request-options) | enable the [progress bar](../features/loaders.md) 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. -::: tip -For the complete list of request options and their descriptions, see the [Larajax JavaScript API Reference](https://larajax.org/api/framework). -::: +```js +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)](https://larajax.org/api/framework#request-options) | called when requesting confirmation from the user. +[handleErrorMessage(message)](https://larajax.org/api/framework#request-options) | called when an error message should be displayed. +[handleValidationMessage(message, fields)](https://larajax.org/api/framework#request-options) | focuses the first invalid field when validation is used. +[handleFlashMessage(message, type)](https://larajax.org/api/framework#request-options) | called when a flash message is provided using the **flash** option (see above). +[handleRedirectResponse(url)](https://larajax.org/api/framework#request-options) | called when the browser should redirect to another location. ## Usage Examples @@ -86,11 +123,28 @@ jax.request('#myform', 'onCalculate', { 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. Common events include `ajax:before-send`, `ajax:update`, `ajax:update-complete`, `ajax:done`, and `ajax:fail`. - -::: tip -For the complete list of AJAX events and their details, see the [Larajax Events Reference](https://larajax.org/api/events). -::: +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](https://larajax.org/api/events#ajax-before-send) | triggered on the window object before sending the request. The handler details provide the `context` object. +[ajax:before-update](https://larajax.org/api/events#ajax-before-update) | triggered on the form object directly after the request is complete, but before the page is updated. +[ajax:update](https://larajax.org/api/events#ajax-update) | triggered on a page element after it has been updated with the framework. +[ajax:update-complete](https://larajax.org/api/events#ajax-update-complete) | triggered on the window object after all elements are updated by the framework. +[ajax:request-success](https://larajax.org/api/events#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](https://larajax.org/api/events#ajax-request-error) | triggered on the form object if the request encounters an error. +[ajax:error-message](https://larajax.org/api/events#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](https://larajax.org/api/events#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](https://larajax.org/api/events#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](https://larajax.org/api/events#ajax-promise) | triggered directly before the AJAX request is sent. The handler details provide the `context` object. +[ajax:fail](https://larajax.org/api/events#ajax-fail) | triggered finally if the AJAX request fails. +[ajax:done](https://larajax.org/api/events#ajax-done) | triggered finally if the AJAX request was successful. +[ajax:always](https://larajax.org/api/events#ajax-always) | triggered regardless if the AJAX request fails or was successful. ## Event Examples @@ -179,4 +233,4 @@ addEventListener('ajax:update-complete', function(event) { * [Larajax JavaScript API](https://larajax.org/api/framework) * [Larajax Events Reference](https://larajax.org/api/events) * [Data Attributes API](./attributes-api.md) -::: +::: \ No newline at end of file