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

example.html

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

Now you don’t have to bother creating partial files anymore. You can send the current page as a response to a request (not navigation). Briz will automatically find a data-swap with a matching value and will only change that portion. However, you can still create partial responses if needed. This makes it easier for the backend to manage responses without the hassle of creating multiple partial endpoints.

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

add.html

<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

add.html

<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

add.html

<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

add.html

<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

add.html

<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

add.html

<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

add.html

<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

add.html

<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

add.html

<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

add.html

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