Header Small Ahoy!

Out-of-Band Swaps

Trongate MX introduces a powerful feature for updating multiple parts of your webpage with a single request: the mx-select-oob attribute. This "out-of-band" swapping mechanism allows you to update elements beyond the primary target of your request, providing a more dynamic and efficient way to refresh your page content.

Understanding mx-select-oob

The mx-select-oob attribute enables you to select specific content from a server response and swap it into designated parts of your current DOM. This provides precise control over both the source of the content in the response and where it should be inserted in your page.

Syntax

The mx-select-oob attribute uses a comma-separated list of selector pairs. Each pair consists of two parts separated by a colon (:):

mx-select-oob="[source selector]:[target selector], [source selector]:[target selector], ..."
  • Source selector: Identifies the content in the server response
  • Target selector: Specifies where in the current DOM to insert the content

Basic Example

Here's a simple example demonstrating the use of mx-select-oob:

<div>
  <div id="alert"></div>
  <div id="sidebar"></div>
  <button mx-get="<?= BASE_URL ?>info" 
          mx-select="#info-details" 
          mx-swap="outerHTML" 
          mx-select-oob="#alert-content:#alert, #sidebar-content:#sidebar">
    Get Info!
  </button>
</div>

When this button is clicked, Trongate MX will:

  1. Make a GET request to <?= BASE_URL ?>info
  2. Replace the button with the #info-details element from the response
  3. Insert the #alert-content from the response into the #alert div
  4. Insert the #sidebar-content from the response into the #sidebar div

Advanced Usage: Specifying Swap Strategies

You can specify different swap strategies for each out-of-band swap by adding a third part to the selector pair:

<button mx-get="<?= BASE_URL ?>info" 
        mx-select="#info-details" 
        mx-swap="outerHTML" 
        mx-select-oob="#alert-content:#alert:afterbegin, #sidebar-content:#sidebar:innerHTML">
  Get Info!
</button>

In this advanced example:

  • The alert content will be prepended to the #alert div
  • The sidebar content will replace the inner HTML of the #sidebar div

Key Features

  • Inheritance: mx-select-oob can be placed on a parent element and will be inherited by its children.
  • Precise Control: Unlike some similar libraries, mx-select-oob requires explicit specification of both source and target selectors, offering more precise control over out-of-band swaps.
  • Flexible DOM Updates: The colon-separated format allows for different source and target selectors, enabling more flexible DOM updates.
  • Default Behavior: If no swap strategy is specified for an out-of-band swap, it will default to the swap strategy of the triggering element, or 'innerHTML' if not specified.

Best Practices

  • Use Meaningful IDs: Employ descriptive IDs for your source and target elements to keep your code readable and maintainable.
  • Consider Performance: While updating multiple elements in a single request can be efficient, be mindful of the increased complexity in your server response.
  • Judicious Use: Out-of-band swaps are powerful for updating related content, but overuse can lead to complex and hard-to-maintain code.
  • Server Response Structure: Ensure your server responses are structured to match your mx-select-oob selectors to avoid unexpected behavior.
  • Combine with Other Attributes: Use mx-select-oob in conjunction with other Trongate MX attributes for more sophisticated interactions.
Note: When using mx-select-oob, it's crucial to maintain consistency between your client-side selectors and server-side response structure. This ensures smooth and predictable updates across your application.

Summary

Out-of-band content selection and swapping with mx-select-oob is a powerful feature in Trongate MX that enables developers to create more dynamic and responsive web applications. By allowing multiple parts of a page to be updated efficiently with a single server request, it opens up new possibilities for interactive and real-time user experiences. Master this feature to take full advantage of Trongate MX's capabilities in building modern, efficient web applications.