​
Swaps

Swaps define how new content replaces or is inserted into existing DOM elements. WSX provides flexible swap strategies with timing and animation controls.

​
Basic Swap Types

​
innerHTML (Default)

Replace the content inside an element: 
<div id="content">
  <p>Original content</p>
</div>

<!-- Server returns: <p>New content</p> -->
<!-- Result: <div id="content"><p>New content</p></div> -->

​
outerHTML

Replace the entire element: 
<div id="content">
  <p>Original content</p>
</div>

<!-- Server returns: <section id="content"><p>New content</p></section> -->
<!-- Result: <section id="content"><p>New content</p></section> -->

​
Text Content

Replace only the text content: 
<div id="content">Original text</div>

<!-- Server returns: "New text" -->
<!-- Result: <div id="content">New text</div> -->

​
Positional Swaps

​
beforebegin

Insert before the element: 
<div id="target">Existing content</div>

<!-- Server returns: <div>New content</div> -->
<!-- Result: 
<div>New content</div>
<div id="target">Existing content</div>
-->

​
afterbegin

Insert at the beginning of the element: 
<div id="target">
  <p>Existing content</p>
</div>

<!-- Server returns: <p>New content</p> -->
<!-- Result: 
<div id="target">
  <p>New content</p>
  <p>Existing content</p>
</div>
-->

​
beforeend

Insert at the end of the element: 
<div id="target">
  <p>Existing content</p>
</div>

<!-- Server returns: <p>New content</p> -->
<!-- Result: 
<div id="target">
  <p>Existing content</p>
  <p>New content</p>
</div>
-->

​
afterend

Insert after the element: 
<div id="target">Existing content</div>

<!-- Server returns: <div>New content</div> -->
<!-- Result: 
<div id="target">Existing content</div>
<div>New content</div>
-->

​
Swap Specifications

​
Client-Side Specification

Use wx-swap attribute to specify swap behavior: 
<!-- Replace innerHTML -->
<div wx-swap="innerHTML">Content</div>

<!-- Replace outerHTML -->
<div wx-swap="outerHTML">Content</div>

<!-- Insert at beginning -->
<div wx-swap="afterbegin">Content</div>

<!-- Insert at end -->
<div wx-swap="beforeend">Content</div>

​
Server-Side Specification

Specify swap in the response: 
wsx.on("my-action", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>New content</div>`,
    swap: "innerHTML"  // Override client-side swap
  };
});

​
Timing Modifiers

​
Swap Timing

Control when the swap occurs: 
<!-- Immediate swap -->
<div wx-swap="innerHTML">Content</div>

<!-- 300ms delay before swap -->
<div wx-swap="innerHTML swap:300ms">Content</div>

<!-- 1 second delay -->
<div wx-swap="innerHTML swap:1s">Content</div>

​
Settle Timing

Control when animations settle: 
<!-- 100ms settle time -->
<div wx-swap="innerHTML settle:100ms">Content</div>

<!-- Combined timing -->
<div wx-swap="innerHTML swap:300ms settle:100ms">Content</div>

​
Server-Side Timing

wsx.on("animated-update", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>New content</div>`,
    swap: "innerHTML swap:300ms settle:100ms"
  };
});

​
Animation and Effects

​
Fade Effects

<!-- Fade in new content -->
<div wx-swap="innerHTML swap:300ms settle:100ms">Content</div>

<style>
  .wsx-settling {
    opacity: 0;
    transition: opacity 300ms ease;
  }
  
  .wsx-settled {
    opacity: 1;
  }
</style>

​
Slide Effects

<div wx-swap="innerHTML swap:300ms settle:200ms">Content</div>

<style>
  .wsx-settling {
    transform: translateX(-100%);
    transition: transform 300ms ease;
  }
  
  .wsx-settled {
    transform: translateX(0);
  }
</style>

​
Custom Animations

<div wx-swap="innerHTML swap:500ms settle:200ms">Content</div>

<style>
  .wsx-settling {
    transform: scale(0.8);
    opacity: 0;
    transition: all 500ms cubic-bezier(0.4, 0, 0.2, 1);
  }
  
  .wsx-settled {
    transform: scale(1);
    opacity: 1;
  }
</style>

​
Scroll Behavior

​
Auto-Scroll

Control scrolling after swaps: 
<!-- Scroll to top -->
<div wx-swap="innerHTML show:top">Content</div>

<!-- Scroll to bottom -->
<div wx-swap="innerHTML show:bottom">Content</div>

<!-- Scroll to element -->
<div wx-swap="innerHTML show:window">Content</div>

<!-- Smooth scrolling -->
<div wx-swap="innerHTML show:top scroll:smooth">Content</div>

​
Server-Side Scroll Control

wsx.on("scroll-action", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>New content</div>`,
    swap: "innerHTML show:top scroll:smooth"
  };
});

​
Best Practices

  1. Choose Appropriate Swap Types: Use the right swap for your use case
  2. Add Smooth Transitions: Use timing modifiers for better UX
  3. Handle Scroll Behavior: Control scrolling for long content
  4. Clean Up Resources: Handle cleanup before swaps
  5. Test Animations: Ensure animations work across browsers
  6. Consider Performance: Avoid expensive animations on slow devices

​
Next Steps