Improve documentation for websocket extension

[W1M0R]

There are a few examples that could be added that would help users to better understand how to work with the websocket extension.

Example 1: Explicit Websocket message example

This StackOverflow issue explains the situation: https://stackoverflow.com/questions/77422127/htmx-websockets-are-not-replacing-content-in-dom

In short, if your websocket connection works, but you don't see anything displayed, then make sure that the html you are receiving from the websocket has the correct id attribute value, that matches the id of the element that it should replace.

Given the usage example taken from the docs:

<div hx-ext="ws" ws-connect="/chatroom">
    <div id="notifications"></div>
    <div id="chat_room">
        ...
    </div>
    <form id="form" ws-send>
        <input name="chat_message">
    </form>
</div>

The documentation can be improved by explicitly stating what an example message from the websocket should look like for the given example:

<div id="notifications"><span>Example message from websocket.</span></div>

The documentation page (https://htmx.org/extensions/web-sockets/#receiving-messages-from-a-websocket) does mention it, but for newcomers it is not so clear exactly what is meant by it:

Content that is sent down from the websocket will be parsed as HTML and swapped in by the id property, using the same logic as Out of Band Swaps.

Example 2: Reshaping json using a custom extension

An example can be added to show how to transform incoming json data to another shape using a custom htmx extension.

With inspiration taken from: https://github.com/wodny/htmx-experiments/blob/master/websockets-and-client-side-templates/js/main.js

htmx.defineExtension("ws-json-example", {
    transformResponse : function(text, xhr, elt) {
        let data = JSON.parse(text);
        data["payload_id"] = `${data.payload.id}`;
        return JSON.stringify(data);
    }
});

  <span hx-ext="debug,ws,ws-json-example,client-side-templates" ws-connect="/chatroom" mustache-template="foo">
    <div id="notifications"></div>
    <template id="foo">
      <div id="notifications">
        Hello World {{payload_id}}
      </div>
    </template>
  </span>

Example 3: Transforming json to html using a custom extension

An example can be added to show how to transform incoming json data to html using a custom htmx extension.

With inspiration taken from: https://github.com/wodny/htmx-experiments/blob/master/websockets-and-client-side-templates/js/main.js

htmx.defineExtension("ws-html-example", {
    transformResponse : function(text, xhr, elt) {
        const data = JSON.parse(text);
        return `<div id="notifications">Hello World ${data.payload.id}</div>`;
    }
});

  <span hx-ext="debug,ws,ws-html-example" ws-connect="/chatroom">
    <div id="notifications"></div>
  </span>

Example 4: Using client-side-templates with ws extension

Here is an example of using the client-side-templates extension (and a mustache template), to transform json object messages received from the ws extension to html that satisfies the ws swapping mechanism. It also demonstrate the use of the debug extension to get more information about the execution steps of htmx.

This is like Example 2, but without json reshaping.

With inspiration taken from:

1. Websockets and client-side-templates #1678
2. https://github.com/wodny/htmx-experiments/blob/master/websockets-and-client-side-templates/index.html

  <span hx-ext="debug,ws,client-side-templates" ws-connect="/chatroom" mustache-template="foo">
    <div id="notifications"></div>
    <template id="foo">
      <div id="notifications">
        Hello World {{payload.id}}
      </div>
    </template>
  </span>