itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-10-02 07:21:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update websockets extension documentation (#928)

Browse Source 
* Update websockets extension documentation

* Add mention of message queuing mechanism
* Expand on the topic of swapping logic

* Expand the example of WebSocket message from the server
This commit is contained in:
Denis Palashevskii 2022-06-02 23:03:14 +04:00 committed by GitHub
parent 8e7a4bca27
commit 5bb2273297
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
www/extensions/web-sockets.md
View File

@ -18,10 +18,11 @@ of the event specified by [`hx-trigger`])
```html ```html
<div hx-ext="ws" ws-connect="/chatroom"> <div hx-ext="ws" ws-connect="/chatroom">
<div id="notifications"></div>
<div id="chat_room"> <div id="chat_room">
... ...
</div> </div>
<form ws-send> <form id="form" ws-send>
<input name="chat_message"> <input name="chat_message">
</form> </form>
</div> </div>
@ -32,6 +33,24 @@ of the event specified by [`hx-trigger`])
The example above establishes a WebSocket to the `/chatroom` end point. Content that is sent down from the websocket will The example above establishes a WebSocket to the `/chatroom` end point. 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](/attributes/hx-swap-oob). be parsed as HTML and swapped in by the `id` property, using the same logic as [Out of Band Swaps](/attributes/hx-swap-oob).
As such, if you want to change the swapping method (e.g., append content at the end of an element or delegate swapping to an extension),
you need to specify that in the message body, sent by the server.
```html
<!-- will be interpreted as hx-swap-oob="true" by default -->
<form id="form">
...
</form>
<!-- will be appended to #notifications div -->
<div id="notifications" hx-swap-oob="beforeend">
New message received
</div>
<!-- will be swapped using an extension -->
<div id="chat_room" hx-swap-oob="morphdom">
....
</div>
```
### Sending Messages to a WebSocket ### Sending Messages to a WebSocket
In the example above, the form uses the `ws-send` attribute to indicate that when it is submitted, the form values should be **serialized as JSON** In the example above, the form uses the `ws-send` attribute to indicate that when it is submitted, the form values should be **serialized as JSON**
@ -54,6 +73,7 @@ htmx.config.wsReconnectDelay = function(retryCount) {
} }
``` ```
The extension also implements a simple queuing mechanism that keeps messages in memory when the socket is not in `OPEN` state and sends them once the connection is restored.
### Testing with the Demo Server ### Testing with the Demo Server
Htmx includes a demo WebSockets server written in Go that will help you to see WebSockets in action, and begin bootstrapping your own WebSockets code. It is located in the /test/servers/ws folder of the htmx distribution. Look at /test/servers/ws/README.md for instructions on running and using the test server. Htmx includes a demo WebSockets server written in Go that will help you to see WebSockets in action, and begin bootstrapping your own WebSockets code. It is located in the /test/servers/ws folder of the htmx distribution. Look at /test/servers/ws/README.md for instructions on running and using the test server.