AJAX functions - WEBSALE Dokumentation

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.

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

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.

The customer clicks on a link or a button. The called function suppresses the normal page navigation.
Before the request is sent, the startFunction runs. Here you typically show a layer with a loading graphic.
The request goes to WEBSALE V8s. The requested template is generated there and returned.
If no response is received, for example because the internet connection dropped or a timeout occurs, the failureFunction runs.
If a response comes back, its content decides: on success, the successCallback runs; if WEBSALE V8s reports an error instead, the errorCallback runs.
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.

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.

<a onclick="return ws_AJAXloadTemplate('Link', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   Link name
</a>

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.

<head>
   ...
   <script type="text/javascript" src="/$WS/ws_sysdata/js/ws-system-1.8.3.js"></script>
   <script type="text/javascript" src="../js_upload/ws-design-1.8.3.js"></script>
   ...
</head>

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.

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

<div id="inhalt1">
   ...
</div>
<div id="inhalt2">
   ...
</div>

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.

<WS-Ajax-inhalt1>
   ....
</WS-Ajax-inhalt1>

<WS-Ajax-inhalt2>
   ....
</WS-Ajax-inhalt2>

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.

{ST-Ajax}<WS-Ajax-inhalt1>{/ST-Ajax}
    ....
{ST-Ajax}</WS-Ajax-inhalt1>{/ST-Ajax}

{ST-Ajax}<WS-Ajax-inhalt2>{/ST-Ajax}
    ....
{ST-Ajax}</WS-Ajax-inhalt2>{/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.

<a onclick="return ws_AJAXloadTemplate('Link', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   Link name
</a>

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.

<form action="~FORM-Template(Your template)~" method="post" id="form">
   ...
   <input type="submit" value="submit" onclick="return ws_AJAXsendFormTemplate('form', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   ...
</form>

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.

<head>
   ...
   <script type="text/javascript" src="/$WS/ws_sysdata/js/ws-system-1.8.3.js"></script>
   <script type="text/javascript" src="../js_upload/ws-design-1.8.3.js"></script>
   ...
</head>

Step 4: Define the display area

On the template that is to receive the form, create a display area with an ID.

<div id="formular">
   ...
</div>

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.

<WS-Ajax-formular>
   ....
</WS-Ajax-formular>

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.

{ST-Ajax}<WS-Ajax-formular>{/ST-Ajax}
    ....

   {ST-Ajax}
   <input type="submit" value="submit" onclick="return ws_AJAXsendFormTemplate('form', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   {/ST-Ajax}

   {!ST-Ajax}
   <input type="submit" value="submit">
   {/!ST-Ajax}

{ST-Ajax}</WS-Ajax-formular>{/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

<a onclick="return ws_AJAXloadTemplate('Link', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   Link name
</a>

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

<input type="submit" value="submit" onclick="return ws_AJAXsendFormTemplate('form', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">

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

​Prerequisites

​How an AJAX call works

​Loading content via AJAX

​Step 1: Create the link

​Step 2: Include the system library and design component

​Step 3: Define display areas

​Step 4: Create WS-Ajax sections in the target template

​Loading and submitting forms via AJAX

​Step 1: Load the form via a link

​Step 2: Adapt the form and submit button

​Step 3: Extend the design component

​Step 4: Define the display area

​Step 5: Create a WS-Ajax section

​Syntax of the functions

​ws_AJAXloadTemplate

​ws_AJAXsendFormTemplate

​Possible integrations with AJAX

Prerequisites

How an AJAX call works

Loading content via AJAX

Step 1: Create the link

Step 2: Include the system library and design component

Step 3: Define display areas

Step 4: Create WS-Ajax sections in the target template

Loading and submitting forms via AJAX

Step 1: Load the form via a link

Step 2: Adapt the form and submit button

Step 3: Extend the design component

Step 4: Define the display area

Step 5: Create a WS-Ajax section

Syntax of the functions

ws_AJAXloadTemplate

ws_AJAXsendFormTemplate

Possible integrations with AJAX