> ## 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.

# Reload dependent variants via AJAX

> How to reload the selection of dependent variants in WEBSALE V8s via AJAX so that the product page is not rebuilt when the variant changes.

When the customer selects a dependent variant, the product page is normally reloaded. With AJAX, you swap only the affected areas instead. The customer does not lose their position on the page, and a loading indicator can be shown while it is loading.

> [!WARNING]
>
> This feature uses AJAX and layer techniques and is therefore only available if the customer has JavaScript enabled. If it is disabled, the page is rebuilt as usual. Your template must therefore work in both states.
>
> In addition, the WEBSALE JavaScript system library from version 1.1.0 is required.

## How it works

The workflow is the same for both display types.

A click on the select list or the link of a dependent variant calls a JavaScript function. This function starts the AJAX communication and prevents the page from being rebuilt. Beforehand, a function of the design component runs, in which you, for example, show a layer with a waiting graphic.

If no response is received, for example when the internet connection is broken, another function of the design component runs. There you hide the loading graphic again and show a notice instead.

On success, WEBSALE V8s accepts the request and delivers the new content. So that the system library knows which parts of the page to replace, you define swap areas in the product template.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<div id="ID1">
   {ST-Ajax}<WS-Ajax-ID1>{/ST-Ajax}
   ....
   {ST-Ajax}</WS-Ajax-ID1>{/ST-Ajax}
</div>
...
<div id="ID2">
   {ST-Ajax}<WS-Ajax-ID2>{/ST-Ajax}
   ....
   {ST-Ajax}</WS-Ajax-ID2>{/ST-Ajax}
</div>
```

The structure follows a fixed rule: each area begins with the prefix `WS-Ajax-` and sits directly inside a `div` with the same ID. You choose the ID freely. On an AJAX call, the system library writes the content of each area into the `div` with the matching ID. This lets you swap out several places on the page at once.

The bracket `ST-Ajax` around the area markers ensures they are only output on an AJAX call. Otherwise, they would remain visible in the source code on a normal product call.

> [!WARNING]
>
> Check JavaScript that runs inside these `div` containers or refers to elements within them. After an AJAX call, it may behave differently. Some functions, most notably `document.write()`, cannot be used inside such an area at all.

> [!NOTE]
>
> If you use the tracking interface together with this feature, follow the notes there on AJAX-based features. Since no full page build takes place, tracking calls otherwise do not fire.
>
> Guide: Description of the tracking interface&#x20;

## Integration

You extend the product template in six steps. Only the second step differs depending on whether you display the variants as select lists or as links.

### Step 1: include the system library

In the `<head>` of the template, include the system library along with the design component.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<script type="text/javascript" src="/$WS/ws_sysdata/js/ws-system-1.1.0.js"></script>
<script type="text/javascript" src="../js_upload/ws-design-1.1.0.js"></script>
```

### Step 2: add the trigger

Here the two display types differ.

**For select lists**, in the `<head>` create the function `SubmitSelection()`, which is called by the select list via `onchange`. It passes the ID of the product form and the character set.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<head>
...
<script type="text/javascript">
function SubmitSelection()
{
   return ws_AJAXPR('productform', '~WS-Charset~');
}
</script>
...
</head>
```

**For links**, no separate function is needed. Instead, add an `onClick` to each variant link that calls `ws_AJAXPRLink()` with the link's target and the character set.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@PR-DepVariationOption1}
   ...
   <a href="~PR-DepVariationOptionLink1~" onClick="return ws_AJAXPRLink('~PR-DepVariationOptionLink1~', '~WS-Charset~');">
   ...
{/@PR-DepVariationOption1}

{@PR-DepVariationOption2}
   ...
   <a href="~PR-DepVariationOptionLink2~" onClick="return ws_AJAXPRLink('~PR-DepVariationOptionLink2~', '~WS-Charset~');">
   ...
{/@PR-DepVariationOption2}
```

For each additional dependent variant, repeat the block with the next higher number. In both cases the `href` is preserved so that the link continues to work without JavaScript.

### Step 3: create containers for messages

These three containers are shown and hidden via JavaScript and inform the customer about the state of their action. Place them with `position: fixed` over the page so they are visible regardless of the scroll position.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<div id="pr_ajax_wait" style="display:none; left: 50%; position: fixed; top: 200px; margin-left:150px; width: 300px; height: 100px;">
   AJAX start, show loading graphic.
</div>

<div id="pr_ajax_com_error" style="background-color: red; display:none; left: 50%; position: fixed; top: 200px; margin-left:150px; width: 300px; height: 100px;">
   Error during AJAX communication.
   <br>
   <a onclick="javascript:$('#pr_ajax_com_error').hide(); return false;" href="">close</a>
</div>

<div id="pr_ajax_error" style="background-color: red; display:none; left: 50%; position: fixed; top: 200px; margin-left:150px; width: 300px; height: 100px;">
   Your selection is no longer available.
   <br>
   <a onclick="javascript:$('#pr_ajax_error').hide(); return false;" href="">close</a>
</div>
```

The three containers cover three different cases: the wait, the communication error, and the selection reported by the shop as no longer available.

### Step 4: give the product form a unique ID

The function from step 2 addresses the form via its ID. Without it, it cannot find the selected values.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form action="~FORM-Product~" method="post" name="product" id="productform">
```

### Step 5: define the swap areas

Swap out the entire area in which the product is displayed, that is, the central area of the page.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<div id="productcontainer">
{ST-Ajax}<WS-Ajax-productcontainer>{/ST-Ajax}
...
     <form action="~FORM-Product~" method="post" name="product" id="productform">
...
{ST-Ajax}</WS-Ajax-productcontainer>{/ST-Ajax}
</div> <!-- closes the container with the ID productcontainer -->
```

> [!WARNING]
>
> Four points decide whether the swap works:
>
> The start and end markers of the AJAX areas belong inside an `ST-Ajax` bracket.
>
> The form with the action `FORM-Product` must lie inside a swapped area. Otherwise, after reloading, the form still points to the old variant.
>
> The start and end markers stand immediately after or before the associated `div` containers, respectively.
>
> JavaScript inside the swap areas or referring to elements within them must be tested and adjusted if necessary.

### Step 6: populate functions in the design component

The system library calls four functions that live in the design component. There you place your show/hide logic or additional effects. The default looks like this:

```js theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
//////////////////////////////////////////////////////////////////////
//    Module: "Reload dependent variants via AJAX"                  //
//////////////////////////////////////////////////////////////////////

// Runs before the AJAX request is sent, for example for a loading indicator
function ws_AJAXPRStart()
{
        // Hide error and info containers, show loading container
        $('#pr_ajax_com_error').hide();
        $('#pr_ajax_error').fadeOut();
        $('#pr_ajax_wait').fadeIn();
}

// Runs when the variant combination could be loaded
function ws_AJAXPRResponseSuccess()
{
        // Hide loading container
        $('#pr_ajax_wait').fadeOut();
}

// Runs when the variant combination could not be loaded
// The error message generated by WEBSALE V8s can be shown here
function ws_AJAXPRResponseError()
{
        // Hide loading container, show notice message
        $('#pr_ajax_wait').fadeOut();
        $('#pr_ajax_error').show();
}

// Runs when the AJAX communication failed,
// for example when the internet connection is broken
function ws_AJAXPRError()
{
        // Hide loading container, show communication error
        $('#pr_ajax_wait').fadeOut();
        $('#pr_ajax_com_error').show();
}
```

The last two functions cover different cases. `ws_AJAXPRResponseError` applies when the shop responded and reported an error, for example because the chosen combination is no longer available. `ws_AJAXPRError` applies when no response came through at all.

## Tags

| Tag | Meaning |
| - | - |
| `ST-Ajax` | The section only appears when the call was an AJAX request |
| `WS-Ajax-"ID"` | Swap area whose content is written into the `div` with the same ID |

## Related topics

* Guide: Display dependent variants as select lists
* Guide: Display dependent variants as links
* Guide: AJAX functions
* Materials: WEBSALE JavaScript library


## Related topics

- [Display dependent variants as a table](https://dokumentation.websale.de/en/v8s/abhaengige-varianten/abhaengige-varianten-als-tabelle-darstellen.md)
- [Display dependent variants as links](https://dokumentation.websale.de/en/v8s/abhaengige-varianten/abhaengige-varianten-als-links-darstellen.md)
- [Display dependent variants as select lists](https://dokumentation.websale.de/en/v8s/abhaengige-varianten/abhaengige-varianten-als-auswahllisten.md)
- [Display dependent variants as a graphical view](https://dokumentation.websale.de/en/v8s/abhaengige-varianten/abhaengige-varianten-als-grafische-ansicht-anzeigen.md)
- [Reload and submit forms via AJAX](https://dokumentation.websale.de/en/v8s/formulare-fuer-kundenanfragen/formulare-per-ajax-nachladen-und-absenden.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.