> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # AJAX functions > How to load content and forms via AJAX in WEBSALE V8s without rebuilding the entire page. It is assumed that you are familiar with the templates of your shop and with the WEBSALE JavaScript library. Normally, the browser opens a follow-up page with every click on a link. With an AJAX integration (Asynchronous JavaScript and XML), the click instead calls a JavaScript function. This function starts the AJAX communication and prevents the browser from reloading the page. The requested content is loaded and inserted dynamically into the existing page. The benefit lies in reduced data traffic. A piece of content is only fetched when it is needed, for example when the buyer clicks on the "Question about the product" tab. The rest of the page remains untouched. > [!WARNING] > > AJAX requires the customer to have JavaScript activated in their browser. If JavaScript is disabled, the page is fully rebuilt as usual. Your templates must therefore work in both states. The section on WS-Ajax sections shows how to achieve this. ## Prerequisites For all AJAX integrations you need the WEBSALE JavaScript system library together with its design component, at least in version 1.8.1. The system library brings the AJAX functions with it. In the design component you store your own reactions to success and errors. Guide: JavaScript and jQuery Materials: WEBSALE JavaScript library > [!NOTE] > > If you use the tracking interface together with AJAX, follow the notes on AJAX-based functions in the tracking documentation. Since a full page build does not take place with an AJAX call, tracking calls otherwise do not take effect. > > Guide: Description of the tracking interface ## How an AJAX call works Before you build the first link, it is worth taking a look at the flow. It is the same for content and forms and explains why you specify four JavaScript functions. 1. The customer clicks on a link or a button. The called function suppresses the normal page navigation. 2. Before the request is sent, the `startFunction` runs. Here you typically show a layer with a loading graphic. 3. The request goes to WEBSALE V8s. The requested template is generated there and returned. 4. If no response is received, for example because the internet connection dropped or a timeout occurs, the `failureFunction` runs. 5. If a response comes back, its content decides: on success, the `successCallback` runs; if WEBSALE V8s reports an error instead, the `errorCallback` runs. 6. On success, the system library automatically inserts the returned content into the display areas of your page. The difference between `failureFunction` and `errorCallback` is important for your error messages. The `failureFunction` stands for a communication error where the shop did not respond at all. The `errorCallback` stands for a response from the shop that reports an error, for example a template that was not found. The requested content is fetched via the `WS-LoadTpl` tag, possibly in combination with `WS-ExternInclude`, `FORM-Template`, or `FORM-SSLTemplate`. ![Ajax Load Tplnew](https://mintcdn.com/websaleag-44ee7ea6/GhYeuPYs7oEmFYIy/images/ajax_load_tplnew.jpg?fit=max\&auto=format\&n=GhYeuPYs7oEmFYIy\&q=85\&s=14aaac4fdf098832134d3b081c4df7d0) ## Loading content via AJAX The simpler of the two cases is loading content, for example an information page behind a tab. It consists of four steps: build the link, include the library, create the display area, prepare the target template. ### Step 1: Create the link The link calls the `ws_AJAXloadTemplate` function. The `return` in front prevents the browser from additionally following the link. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Link name ``` The meaning of the individual parameters can be found in the "Syntax of the functions" section. Reference: WS-LoadTpl() ### Step 2: Include the system library and design component Include the system library together with its design component. If you have already done so, check the version. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ... ... ``` Then extend the design component with the four functions that you specified in the link. Without these functions, the call breaks as soon as the system library tries to invoke them. ```js theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} // Runs before the AJAX request is sent, for example for a loading indicator function startFunction() { ... } // Runs when the load was successful function successCallback() { ... } // Runs when WEBSALE V8s returned an error function errorCallback() { ... } // Runs when the AJAX communication failed, for example when the internet connection is interrupted function failureFunction() { ... } ``` ### Step 3: Define display areas On the template with the link, create one or more display areas. The loaded content is inserted into them. Use any HTML element with an ID. The ID is the connection to the target template and must therefore be unique. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
...
...
``` ### Step 4: Create WS-Ajax sections in the target template WEBSALE V8s returns the template that the link calls. So that the system library knows which part of it belongs where, you divide the target template into WS-Ajax sections. The section name consists of the prefix `WS-Ajax-` and the ID of the display area. This way, you can exchange several areas at the same time with a single call. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} .... .... ``` Reference: WS-Ajax-"ID" If the same template is also reachable via a normal call, wrap the section markers with `ST-Ajax`. Without this bracketing, the markers would appear visibly in the source code on a normal call. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {ST-Ajax}{/ST-Ajax} .... {ST-Ajax}{/ST-Ajax} {ST-Ajax}{/ST-Ajax} .... {ST-Ajax}{/ST-Ajax} ``` Reference: ST-Ajax ## Loading and submitting forms via AJAX A form goes through the same flow, but twice: once when the form is loaded and once when it is submitted. There is a separate function for submitting because the field contents are sent along. The result of the submission depends on the input. If it is faulty, WEBSALE V8s returns the form again, together with error messages. If it was valid, the confirmation page of the form comes back. In both cases the response ends up in the same display area. ### Step 1: Load the form via a link Loading the form is no different from loading a piece of content. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Link name ``` ### Step 2: Adapt the form and submit button Integrate your `form` element as usual and assign an ID. Via this ID the function finds the field contents on submission. On the submit button, add the call to `ws_AJAXsendFormTemplate`. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
... ...
``` ### Step 3: Extend the design component Include the system library together with its design component and add the same four functions there as for loading content. Both calls can share the same functions or use their own. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ... ... ``` ### Step 4: Define the display area On the template that is to receive the form, create a display area with an ID. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
...
``` ### Step 5: Create a WS-Ajax section Wrap the form template with a WS-Ajax section whose name ends with the ID of the display area. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} .... ``` If the same form is also used without AJAX, wrap the section markers again with `ST-Ajax`. Also remember the button: without AJAX it must not carry the function call, otherwise the form would not be submitted at all. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {ST-Ajax}{/ST-Ajax} .... {ST-Ajax} {/ST-Ajax} {!ST-Ajax} {/!ST-Ajax} {ST-Ajax}{/ST-Ajax} ``` ## Syntax of the functions Both functions expect the same parameters, only the first one differs. When loading, it is the link; when submitting, it is the ID of the form. Pay attention to the quotation marks: `startFunction` and `failureFunction` are passed as function objects, that is, without quotation marks and without parentheses. `successCallback` and `errorCallback`, on the other hand, are passed as strings containing the complete function call including parentheses. ### ws\_AJAXloadTemplate ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Link name ``` | Parameter | Type | Required | Description | | - | - | - | - | | `link` | string | yes | Link to the desired page, generated via `WS-LoadTpl()` or `WS-SSLLoadTpl()` | | `charset` | string | yes | Character set of the shop, dynamically settable via `~WS-Charset~` | | `startFunction` | function object | yes | Runs before the AJAX communication starts, for example for a loading indicator | | `failureFunction` | function object | yes | Runs when the communication fails, for example on missing connection or timeout | | `successCallback` | string | yes | Function call for the success case | | `errorCallback` | string | yes | Function call if the communication succeeded but WEBSALE V8s returns an error | | `additionalPayload` | string | no | Additional parameter-value pairs in URL-encoded form, for example `otp1=my_param&otp2=my_second_param` | Reference: WS-Charset ### ws\_AJAXsendFormTemplate ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ``` | Parameter | Type | Required | Description | | - | - | - | - | | `formid` | string | yes | ID of the form whose fields are sent | | `charset` | string | yes | Character set of the shop | | `startFunction` | function object | yes | Runs before the AJAX communication starts, for example for a loading indicator | | `failureFunction` | function object | yes | Runs when the communication fails, for example on missing connection or timeout | | `successCallback` | string | yes | Function call for the success case | | `errorCallback` | string | yes | Function call if the communication succeeded but WEBSALE V8s returns an error | | `additionalPayload` | string | no | Additional parameter-value pairs in URL-encoded form, for example `otp1=my_param&otp2=my_second_param` | ## Possible integrations with AJAX The following content and features can be integrated via AJAX with the functions described. The respective pages show the integration using a concrete example, together with the function names used there. * Loading information pages via AJAX * Loading and submitting forms via AJAX * Quick login for existing customers ## Related topics - [Reload and submit forms via AJAX](https://dokumentation.websale.de/en/v8s/formulare-fuer-kundenanfragen/formulare-per-ajax-nachladen-und-absenden.md) - [Reload dependent variants via AJAX](https://dokumentation.websale.de/en/v8s/abhaengige-varianten/abhaengige-varianten-per-ajax-nachladen.md) - [Loading information pages via AJAX](https://dokumentation.websale.de/en/v8s/informationsseiten/informationsseiten-per-ajax-nachladen.md) - [Link shortener](https://dokumentation.websale.de/en/v8s/funktionen-zur-shop-optimierung/link-shortener.md) - [Forms for customer inquiries](https://dokumentation.websale.de/en/v8s/formulare-fuer-kundenanfragen/formulare-fuer-kundenanfragen.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.