Swap Mechanism

In Briz, we replace the DOM by swapping it with the server response using the data-swap contract.

data-swap

data-swap is a contract attribute used to swap DOM elements with server responses (also HTML elements) with the same value. It also has several swap methods, including the default, append, prepend, after, and before methods. You can use data-swap on any element. The way to write it is <div data-swap="uniquename:mode"></div>

Client

<!-- default method -->
<div data-swap="result"></div>

<!-- append method -->
<div data-swap="cart:append"></div>

<!-- prepend method -->
<div data-swap="user:prepend"></div>

<!-- after method -->
<div data-swap="product:after"></div>

<!-- before method -->
<div data-swap="salary:before"></div>

Briz use Strict Contract Match. If on your client you use <div data-swap="result"></div> then the server response must also contain data-swap="result". If on your client you use <div data-swap="result:append"></div> then the server response must also contain data-swap="result:append".

Response Server

<!-- default method -->
<div data-swap="result"></div>

<!-- append method -->
<div data-swap="cart:append"></div>

<!-- prepend method -->
<div data-swap="user:prepend"></div>

<!-- after method -->
<div data-swap="product:after"></div>

<!-- before method -->
<div data-swap="salary:before"></div>

The data-swap value must be unique and cannot be the same as each other, otherwise an error will occur.

swap mode

As you’ve read above, there are five swap modes: default, append, prepend, after, and before. The default method swaps the element’s outer HTML. In modes other than the default, Briz takes the children of the server response element and inserts them into the appropriate positions relative to the target element on the client.

Default mode example

Replace outerHTML

Client

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result">
  ...waiting response
</div>

Server Response

<p data-swap="result">
  New Server Response!
</p>

Result

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<p data-swap="result">
  New Server Response!
</p>

Append mode example

Adding children at the end

Client

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:append">
  <p>Waiting response</p>
</div>

Server Response

<p data-swap="result:append">
  <p>New response</p>
</p>

Result

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:append">
  <p>Waiting response</p>
  <p>New response</p>
</div>

Prepend mode example

Adding children at the beginning

Client

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:prepend">
  <p>Waiting response</p>
</div>

Server Response

<p data-swap="result:prepend">
  <p>New response</p>
</p>

Result

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:prepend">
  <p>New response</p>
  <p>Waiting response</p>
</div>

Before mode example

Adding children of partial response before target element

Client

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:before">
  <p>Waiting response</p>
</div>

Server Response

<p data-swap="result:before">
  <p>New response</p>
</p>

Result

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<!-- placed here -->
<p>New response</p>
<div data-swap="result:before">
  <p>Waiting response</p>
</div>

After mode example

Add children of partial response after target element

Client

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:after">
  <p>Waiting response</p>
</div>

Server Response

<p data-swap="result:after">
  <p>New response</p>
</p>

Result

<form data-ajax action="/user" method="POST">
  <input type="text" name="name" />
  <input type="text" name="address" />
  <button type="submit">Add User</button>
</form>

<div data-swap="result:after">
  <p>Waiting response</p>
</div>
<p>New response</p> <!-- <-- -->

Swapping the entire body content is strictly prohibited, as this can cause strange behavior on your page. Use <a data-nav href="/someEndpoint"> if you need page navigation.

always perform server-side sanitization before sending HTML snippets.