Reload dependent variants via AJAX - WEBSALE Dokumentation

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.

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.

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

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.

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

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.

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

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

{@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.

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

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

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

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:

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

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

​How it works

​Integration

​Step 1: include the system library

​Step 2: add the trigger

​Step 3: create containers for messages

​Step 4: give the product form a unique ID

​Step 5: define the swap areas

​Step 6: populate functions in the design component

​Tags

​Related topics

How it works

Integration

Step 1: include the system library

Step 2: add the trigger

Step 3: create containers for messages

Step 4: give the product form a unique ID

Step 5: define the swap areas

Step 6: populate functions in the design component

Tags

Related topics