diff --git a/4.x/cms/ajax/attributes-api.md b/4.x/cms/ajax/attributes-api.md index 385d700a..e641a7e8 100644 --- a/4.x/cms/ajax/attributes-api.md +++ b/4.x/cms/ajax/attributes-api.md @@ -5,33 +5,33 @@ subtitle: Interact with handlers using HTML attributes. 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: -data-request Attribute | Description +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. +[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: @@ -93,7 +93,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..98e59e07 100644 --- a/4.x/cms/ajax/javascript-api.md +++ b/4.x/cms/ajax/javascript-api.md @@ -3,41 +3,41 @@ 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. +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** | 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. +[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. @@ -49,18 +49,18 @@ You may also override some of the request logic by passing new functions as opti 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. +[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 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 +69,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 +77,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 +92,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 +110,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 ... @@ -127,26 +127,26 @@ Extra details are available on the `event.detail` property of the event handler. 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. +[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** | 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. +[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. -## Usage Examples +## Event Examples Executes JavaScript code when the `ajax:update` event is triggered on an element. @@ -159,10 +159,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 +181,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 +226,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) +::: \ No newline at end of file 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