diff --git a/src/head-support/README.md b/src/head-support/README.md index 7560f91..796f2b5 100644 --- a/src/head-support/README.md +++ b/src/head-support/README.md @@ -1,109 +1 @@ - -The `head-support` extension adds support for [head tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) -in responses to htmx requests. - -htmx began as a library focused on _partial replacement_ of HTML within the `body` tag. As such, merging additional -information such as the head tag was not a focus of the library. (This is in contrast with, for example, TurboLinks, -which was focused on merging entire web pages retrieved via AJAX into the browser.) - -The [`hx-boost`](@/attributes/hx-boost.md) attribute moved htmx closer to this world of full HTML-document support & -support for extracting the `title` tag out of head elements was eventually added, but full head tag support has never been -a feature of the library. This extension addresses that shortcoming. - -## Install - -```html - -``` - -## Usage - -```html - - ... -``` - -With this installed, all responses that htmx receives that contain a `head` tag in them (even if they are not complete -HTML documents with a root `` element) will be processed. - -How the head tag is handled depends on the type of htmx request. - -If the htmx request is from a boosted element, then the following merge algorithm is used: - -* Elements that exist in the current head as exact textual matches will be left in place -* Elements that do not exist in the current head will be added at the end of the head tag -* Elements that exist in the current head, but not in the new head will be removed from the head - -If the htmx request is from a non-boosted element, then all content will be _appended_ to the existing head element. - -If you wish to override this behavior in either case, you can place the `hx-head` attribute on the new `` tag, -with either of the following two values: - -* `merge` - follow the merging algorithm outlined above -* `append` - append the elements to the existing head - -### Controlling Merge Behavior - -Beyond this, you may also control merging behavior of individual elements with the following attributes: - -* If you place `hx-head="re-eval"` on a head element, it will be re-added (removed and appended) to the head tag on every - request, even if it already exists. This can be useful to execute a script on every htmx request, for example. -* If you place `hx-preserve="true"` on an element, it will never be removed from the head - -### Example - -As an example, consider the following head tag in an existing document: - -```html - - - - - - -``` - -If htmx receives a request containing this new head tag: - -```html - - - - - - -``` - -Then the following operations will occur: - -* `` will be left alone -* `` will be removed from the head -* `` will be added to the head -* `` will be removed from the head -* `` will be left alone -* `` will be added to the head - -The final head element will look like this: - -```html - - - - - - -``` - -## Events - -This extension triggers the following events: - -* `htmx:removingHeadElement` - triggered when a head element is about to be removed, with the element being removed - available in `event.detail.headElement`. If `preventDefault()` is invoked on the event, the element will not be removed. -* `htmx:addingHeadElement` - triggered when a head element is about to be added, with the element being added - available in `event.detail.headElement`. If `preventDefault()` is invoked on the event, the element will not be added. -* `htmx:afterHeadMerge` - triggered after a head tag merge has occurred, with the following values available in the event `detail`: - * `added` - added head elements - * `kept` - kept head elements - * `removed` - removed head elements -* `htmx:beforeHeadMerge` - triggered before a head merge occurs +See https://htmx.org/extensions/head-support/, or https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/head-support.md \ No newline at end of file diff --git a/src/htmx-1-compat/README.md b/src/htmx-1-compat/README.md index a35a84e..47c80f9 100644 --- a/src/htmx-1-compat/README.md +++ b/src/htmx-1-compat/README.md @@ -1,25 +1 @@ -The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2. - -## Install - -```html - -``` - -## What it covers -Htmx 2 introduced a few [breaking changes](https://v2-0v2-0.htmx.org/migration-guide-htmx-1/). - -To make upgrading from htmx 1.x to htmx 2 easier, we're providing this extension that reverts most of those, so you're able to benefit from the other changes without breaking your application. - -### Obsolete attributes -- htmx 2 removed the deprecated [hx-ws](https://htmx.org/attributes/hx-ws/) and [hx-sse](https://htmx.org/attributes/hx-sse/) attributes, that this extension restores. -- htmx 2 removed the deprecated `hx-on` attribute in favor of the wildcard [`hx-on*` attribute](https://htmx.org/attributes/hx-on/), that this extension restores. - -### Default Changes -- reverts [htmx.config.scrollBehavior](https://htmx.org/reference/#config) to 'smooth'. -- makes `DELETE` requests use a form-encoded body rather than URL parameters (htmx 2 uses URL parameters for `DELETE` as default as per [the spec](https://www.rfc-editor.org/rfc/rfc9110.html#name-delete)). -- allows cross-domain requests by default (htmx 2 now forbids it by default). - -## What it does not cover -- IE11 support was dropped in htmx 2, and this extension cannot revert that. If you need IE11 support, please stay with htmx 1 that will continue being supported. -- htmx 2 introduced the breaking change that is the [swap method](https://v2-0v2-0.htmx.org/api/#swap) to the extensions API. If you were only using core extensions, then you shouldn't need any additional work. If you were using custom or community extensions, make sure that they were updated to work with htmx 2's API. +See https://htmx.org/extensions/htmx-1-compat/, or https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/htmx-1-compat.md \ No newline at end of file diff --git a/src/preload/README.md b/src/preload/README.md index f5b8deb..489f133 100644 --- a/src/preload/README.md +++ b/src/preload/README.md @@ -1,101 +1 @@ - -The `preload` extension allows you to load HTML fragments into your browser's cache before they are requested by the user, so that additional pages appear to users to load nearly instantaneously. As a developer, you can customize its behavior to fit your applications needs and use cases. - -**IMPORTANT:** Preloading content judiciously can improve your web application's perceived performance, but preloading too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many unused requests. Use this extension carefully! - -## Install - -```html - -``` - -## Usage - -Register the extension with htmx using the `hx-ext` attribute. Then, add a `preload` attribute to any hyperlinks and `hx-get` elements you want to preload. By default, resources will be loaded as soon as the `mousedown` event begins, giving your application a roughly 100-200ms head start on serving responses. See configuration below for other options. - -```html - -

What Works

- WILL BE requested using a standard XMLHttpRequest() and default options (below) - - -

What WILL NOT WORK

- WILL NOT be preloaded because it does not have an explicit "preload" attribute - WILL NOT be preloaded because it is an HX-POST transaction. - -``` - -### Inheriting Preload Settings - -You can add the `preload` attribute to the top-level element that contains several `` or `hx-get=""` elements, and all of them will be preloaded. Be careful with this setting, because you can end up wasting bandwidth if you preload many more resources than you need. - -```html - - - -``` - -### Preloading of Linked Images - -After an HTML page (or page fragment) is preloaded, this extension can also preload linked image resources. It will not load or run linked Javascript or Cascading Stylesheet content, whether linked or embedded in the preloaded HTML. To preload images as well, use the following syntax. - -```html -
- Next Page -
-``` - -### Configuration - -Defaults for this extension are chosen to balance users' perceived performance with potential load on your servers from unused requests. As a developer, you can modify two settings to customize this behavior to your specific use cases. - -#### preload="mousedown" (DEFAULT) - -The default behavior for this extension is to begin loading a resource when the user presses the mouse down. This is a conservative setting that guarantees the user actually intends to use the linked resource. Because user click events typically take 100-200ms to complete, this setting gives your server a significant headstart compared with a regular click. - -```html -This will be preloaded when the user begins to click. -``` - -#### preload="mouseover" - -To preload links more aggressively, you can trigger the preload to happen when the user's mouse hovers over the link instead. To prevent many resources from being loaded when the user scrolls or moves the mouse across a large list of objects, a 100ms delay is built in to this action. If the user's mouse leaves the element *before* this timeout expires, then the resource is not preloaded. - -Typical users hover over links for several hundred milliseconds before they click, which gives your server even more time to respond to the request than the `mousedown` option above. [Test your own hover timing here.](http://instantclick.io/click-test). However, be careful when using this option because it can increase server load by requesting resources unnecessarily. - -```html -This will be preloaded when the user's mouse remains over it for more than 100ms. -``` - -#### preload="custom-event-name" - -Preload can also listen to any custom event within the system, triggering resources to be preloaded (if they have not already been cached by the browser). The extension itself generates an event called `preload:init` that can be used to trigger preloads as soon as an object has been processed by htmx. - -```html - - -
-
- -``` - -* The response from the `/register` URL will replace contents of the `div` with the - `id` `response-div` when response code is 200 (OK). - -* The response from the `/register` URL will replace contents of the `div` with the `id` - `serious-errors` when response code begins with a digit 5 (server errors). - -* The response from the `/register` URL will replace contents of the `div` with - the `id` `not-found` when response code is 404 (Not Found). - -Sometimes you may not want to handle 5xx and 4xx errors separately, in which case you -can use `hx-target-error`: - -```html -
-
- -
-
-``` - -2xx codes will be handled as in the previous example. However, when the response code is 5xx -or 4xx, the response from `/register` will replace the contents of the `div` with the `id` -`any-errors`. - -## Wildcard resolution - -When status response code does not match existing `hx-target-[CODE]` attribute name -then its numeric part expressed as a string is trimmed with last character being -replaced with the asterisk (`*`). This lookup process continues until the attribute -is found or there are no more digits. - -For example, if a browser receives 404 error code, the following attribute names will -be looked up (in the given order): - -* `hx-target-404` -* `hx-target-40*` -* `hx-target-4*` -* `hx-target-*`. - - -_If you are using tools that do not support asterisks in HTML attributes, you -may instead use the `x` character, e.g., `hx-target-4xx`._ - -## Notes - -* `hx-target-…` is inherited and can be placed on a parent element. -* `hx-target-…` cannot be used to handle HTTP response code 200. -* `hx-target-…` will honor `HX-Retarget` by default and will prefer it over any - calculated target but it can be changed by disabling the - `htmx.config.responseTargetPrefersRetargetHeader` configuration option. -* To avoid surprises the `hx-ext` attribute used to enable this extension should be - placed on a parent element containing elements with `hx-target-…` and `hx-target` - attributes. - -## See also - -* [`hx-target`](https://htmx.org/reference/hx-target.md), specifies the target element to be swapped +See https://htmx.org/extensions/response-targets, or https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/response-targets.md \ No newline at end of file diff --git a/src/sse/README.md b/src/sse/README.md index b46b8d3..e7f38c6 100644 --- a/src/sse/README.md +++ b/src/sse/README.md @@ -1,187 +1 @@ -The `Server Sent Events` extension connects to an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) directly from HTML. It manages the connections to your web server, listens for server events, and then swaps their contents into your htmx webpage in real-time. - -SSE is a lightweight alternative to WebSockets that works over existing HTTP connections, so it is easy to use through proxy servers and firewalls. Remember, SSE is a uni-directional service, so you cannot send any messages to an SSE server once the connection has been established. If you need bi-directional communication, then you should consider using [WebSockets](@/web-sockets.md) instead. - -This extension replaces the experimental `hx-sse` attribute built into previous versions of htmx. For help migrating from older versions, see the migration guide at the bottom of this page. - -Use the following attributes to configure how SSE connections behave: - -* `sse-connect=""` - The URL of the SSE server. -* `sse-swap=""` - The name of the message to swap into the DOM. -* `hx-trigger="sse:"` - SSE messages can also trigger HTTP callbacks using the [`hx-trigger`](https://htmx.org/reference/hx-trigger.md) attribute. -* `sse-close=` - To close the EventStream gracefully when that message is received. This might be helpful if you want to send information to a client that will eventually stop. - -## Install - -```html - -``` - -## Usage - -```html -
- Contents of this box will be updated in real time - with every SSE message received from the chatroom. -
-``` - -### Connecting to an SSE Server - -To connect to an SSE server, use the `hx-ext="sse"` attribute to install the extension on that HTML element, then add `sse-connect=""` to the element to make the connection. - -When designing your server application, remember that SSE works just like any HTTP request. Although you cannot send any messages to the server after you have established a connection, you can send parameters to the server along with your request. So, instead of making an SSE connection to your server at `https://my-server/chat-updates` you can also connect to `https://my-server/chat-updates?friends=true&format=detailed`. This allows your server to customize its responses to what your client needs. - -### Receiving Named Events - -SSE messages consist of an event name and a data packet. No other metadata is allowed in the message. Here is an example: - -```txt -event: EventName -data:
Content to swap into your HTML page.
-``` - -We'll use the `sse-swap` attribute to listen for this event and swap its contents into our webpage. - -```html -
-``` - -Notice that the name `EventName` from the server's message must match the value in the `sse-swap` attribute. Your server can use as many different event names as necessary, but be careful: browsers can only listen for events that have been explicitly named. So, if your server sends an event named `ChatroomUpdate` but your browser is only listening for events named `ChatUpdate` then the extra event will be discarded. - -### Receiving Unnamed Events - -SSE messages can also be sent without any event name. In this case, the browser uses the default name `message` in its place. The same rules specified above still apply. If your server sends an unnamed message, then you must listen for it by including `sse-swap="message"`. There is no option for using a catch-all name. Here's how this looks: - -```txt -data:
Content to swap into your HTML page.
-``` - -```html -
-``` - -### Receiving Multiple Events - -You can also listen to multiple events (named or unnamed) from a single EventSource. Listeners must be either 1) the same element that contains the `hx-ext` and `sse-connect` attributes, or 2) child elements of the element containing the `hx-ext` and `sse-connect` attributes. - -```html - -Multiple events in the same element -
- -Multiple events in different elements (from the same source). -
-
-
-
-``` - -### Trigger Server Callbacks - -When a connection for server sent events has been established, child elements can listen for these events by using the special [`hx-trigger`](https://htmx.org/reference/hx-trigger.md) syntax `sse:`. This, when combined with an `hx-get` or similar will trigger the element to make a request. - -Here is an example: - -```html -
-
- ... -
-
-``` - -This example establishes an SSE connection to the `event_stream` end point which then triggers -a `GET` to the `/chatroom` url whenever the `chatter` event is seen. - -### Automatic Reconnection - -If the SSE Event Stream is closed unexpectedly, browsers are supposed to attempt to reconnect automatically. However, in rare situations this does not work and your browser can be left hanging. This extension adds its own reconnection logic (using an [exponential-backoff algorithm](https://en.wikipedia.org/wiki/Exponential_backoff)) on top of the browser's automatic reconnection, so that your SSE streams will always be as reliable as possible. - -### Testing SSE Connections with the Demo Server - -Htmx includes a demo SSE server written in Node.js that will help you to see SSE in action, and begin bootstrapping your own SSE code. It is located in the /test/ws-sse folder of the htmx distribution. Look at /test/ws-sse/README.md for instructions on running and using the test server. - -### Migrating from Previous Versions - -Previous versions of htmx used a built-in tag `hx-sse` to implement Server Sent Events. This code has been migrated into an extension instead. Here are the steps you need to take to migrate to this version: - -| Old Attribute | New Attribute | Comments | -|--------------------------------|--------------------------|------------------| -| `hx-sse=""` | `hx-ext="sse"` | Use the `hx-ext="sse"` attribute to install the SSE extension into any HTML element. | -| `hx-sse="connect:"` | `sse-connect=""` | Add a new attribute `sse-connect` to the tag that specifies the URL of the Event Stream. This attribute must be in the same tag as the `hx-ext` attribute. | -| `hx-sse="swap:"` | `sse-swap=""` | Add a new attribute `sse-swap` to any elements that will be swapped in via the SSE extension. This attribute must be placed **on** or **inside of** the tag containing the `hx-ext` attribute. | -| `hx-trigger="sse:"` | NO CHANGE | any `hx-trigger` attributes do not need to change. The extension will identify these attributes and add listeners for any events prefixed with `sse:` | - -### Listening to events dispatched by this extension - -This extension dispatches several events. You can listen for these events like so: - -```javascript -document.body.addEventListener('htmx:sseBeforeMessage', function (e) { - // do something before the event data is swapped in -}) -``` - -Each event object has a `detail` field that contains details of the event. - -#### `htmx:sseOpen` - -This event is dispatched when an SSE connection has been successfully established. - -##### Details - -* `detail.elt` - The element on which the SSE connection was setup. This is the element which has the `sse-connect` attribute. -* `detail.source` - The [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) object. - -#### `htmx:sseError` - -This event is dispatched when an SSE connection could not be established. - -##### Details - -* `detail.error` - The error that occured while creating an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource). -* `detail.source` - The [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource). - -#### `htmx:sseBeforeMessage` - -This event is dispatched just before the SSE event data is swapped into the DOM. If you don't want to swap call `preventDefault()` on the event. Additionally the `detail` field is a [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event) - this is the event created by [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) when it receives an SSE message. - -##### Details - -* `detail.elt` - The swap target. - -#### `htmx:sseMessage` - -This event is dispatched after the SSE event data has been swapped into the DOM. The `detail` field is a [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event) - this is the event created by [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) when it receives an SSE message. - -#### `htmx:sseClose` - -This event is dispatched in three different closing scenario. To control for the scenario the user can control for the evt.detail.sseclose property. - -```javascript -document.body.addEventListener('htmx:sseClose', function (e) { - const reason = e.detail.type - switch(reason) { - case "nodeMissing": - // Parent node is missing and therefore connection was closed - ... - case "nodeReplaced": - // Parent node replacement caused closing of connection - ... - case "message": - // connection was closed due to reception of message sse-close - ... - } -}) -``` - -##### Details - -* `detail.elt` - The swap target. - -### Additional SSE Resources - -* [Wikipedia](https://en.wikipedia.org/wiki/Server-sent_events) -* [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) -* [Can I Use?](https://caniuse.com/eventsource) +See https://htmx.org/extensions/sse, or https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/sse.md \ No newline at end of file diff --git a/src/ws/README.md b/src/ws/README.md index d620ebf..f5c5b45 100644 --- a/src/ws/README.md +++ b/src/ws/README.md @@ -1,249 +1 @@ -The `WebSockets` extension enables easy, bi-directional communication -with [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) -servers directly from HTML. This replaces the experimental `hx-ws` attribute built into previous versions of htmx. For -help migrating from older versions, see the [Migrating](#migrating-from-previous-versions) guide at the bottom of this page. - -Use the following attributes to configure how WebSockets behave: - -* `ws-connect=""` or `ws-connect=":"` - A URL to establish a `WebSocket` connection against. -* Prefixes `ws` or `wss` can optionally be specified. If not specified, HTMX defaults to adding the location's scheme-type, - host and port to have browsers send cookies via websockets. -* `ws-send` - Sends a message to the nearest websocket based on the trigger value for the element (either the natural - event - or the event specified by [`hx-trigger`]) - -## Install - -```html - -``` - -## Usage - -```html - -
-
-
- ... -
-
- -
-
-``` - -### Configuration - -WebSockets extension support two configuration options: - -- `createWebSocket` - a factory function that can be used to create a custom WebSocket instances. Must be a function, - returning `WebSocket` object -- `wsBinaryType` - a string value, that defines - socket's [`binaryType`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType) property. Default value - is `blob` - -### Receiving Messages from a WebSocket - -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](https://htmx.org/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 - -
- ... -
- -
- New message received -
- -
- .... -
-``` - -### 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** -and send to the nearest enclosing `WebSocket`, in this case the `/chatroom` endpoint. - -The serialized values will include a field, `HEADERS`, that includes the headers normally submitted with an htmx -request. - -### Automatic Reconnection - -If the WebSocket is closed unexpectedly, due to `Abnormal Closure`, `Service Restart` or `Try Again Later`, this -extension will attempt to reconnect until the connection is reestablished. - -By default, the extension uses a -full-jitter [exponential-backoff algorithm](https://en.wikipedia.org/wiki/Exponential_backoff) that chooses a randomized -retry delay that grows exponentially over time. You can use a different algorithm by writing it -into `htmx.config.wsReconnectDelay`. This function takes a single parameter, the number of retries, and returns the -time (in milliseconds) to wait before trying again. - -```javascript -// example reconnect delay that you shouldn't use because -// it's not as good as the algorithm that's already in place -htmx.config.wsReconnectDelay = function (retryCount) { - return retryCount * 1000 // return value in milliseconds -} -``` - -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. - -### Events - -WebSockets extensions exposes a set of events that allow you to observe and customize its behavior. - -#### Event - `htmx:wsConnecting` {#htmx:wsConnecting} - -This event is triggered when a connection to a WebSocket endpoint is being attempted. - -##### Details - -* `detail.event.type` - the type of the event (`'connecting'`) - -#### Event - `htmx:wsOpen` {#htmx:wsOpen} - -This event is triggered when a connection to a WebSocket endpoint has been established. - -##### Details - -* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) -* `detail.event` - the original event from the socket -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsClose` {#htmx:wsClose} - -This event is triggered when a connection to a WebSocket endpoint has been closed normally. -You can check if the event was caused by an error by inspecting `detail.event` property. - -##### Details - -* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) -* `detail.event` - the original event from the socket -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsError` {#htmx:wsError} - -This event is triggered when `onerror` event on a socket is raised. - -##### Details - -* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) -* `detail.error` - the error object -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsBeforeMessage` {#htmx:wsBeforeMessage} - -This event is triggered when a message has just been received by a socket, similar to `htmx:beforeOnLoad`. This event -fires -before any processing occurs. - -If the event is cancelled, no further processing will occur. - -* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) -* `detail.message` - raw message content -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsAfterMessage` {#htmx:wsAfterMessage} - -This event is triggered when a message has been completely processed by htmx and all changes have been -settled, similar to `htmx:afterOnLoad`. - -Cancelling this event has no effect. - -* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) -* `detail.message` - raw message content -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsConfigSend` {#htmx:wsConfigSend} - -This event is triggered when preparing to send a message from `ws-send` element. -Similarly to [`htmx:configRequest`](https://htmx.org/events#htmx:configRequest), it allows you to modify the message -before sending. - -If the event is cancelled, no further processing will occur and no messages will be sent. - -##### Details - -* `detail.parameters` - the parameters that will be submitted in the request -* `detail.unfilteredParameters` - the parameters that were found before filtering - by [`hx-select`](https://htmx.org/reference/hx-select.md) -* `detail.headers` - the request headers. Will be attached to the body in `HEADERS` property, if not falsy -* `detail.errors` - validation errors. Will prevent sending and - trigger [`htmx:validation:halted`](https://htmx.org/events#htmx:validation:halted) event if not empty -* `detail.triggeringEvent` - the event that triggered sending -* `detail.messageBody` - raw message body that will be sent to the socket. Undefined, can be set to value of any type, - supported by WebSockets. If set, will override - default JSON serialization. Useful, if you want to use some other format, like XML or MessagePack -* `detail.elt` - the element that dispatched the sending (the one with `ws-send` attribute) -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsBeforeSend` {#htmx:wsBeforeSend} - -This event is triggered just before sending a message. This includes messages from the queue. -Message can not be modified at this point. - -If the event is cancelled, the message will be discarded from the queue and not sent. - -##### Details - -* `detail.elt` - the element that dispatched the request (the one with `ws-connect` attribute) -* `detail.message` - the raw message content -* `detail.socketWrapper` - the wrapper around socket object - -#### Event - `htmx:wsAfterSend` {#htmx:wsAfterSend} - -This event is triggered just after sending a message. This includes messages from the queue. - -Cancelling the event has no effect. - -##### Details - -* `detail.elt` - the element that dispatched the request (the one with `ws-connect` attribute) -* `detail.message` - the raw message content -* `detail.socketWrapper` - the wrapper around socket object - -#### Socket wrapper - -You may notice that all events expose `detail.socketWrapper` property. This wrapper holds the socket -object itself and the message queue. It also encapsulates reconnection algorithm. It exposes a few members: - -- `send(message, fromElt)` - sends a message safely. If the socket is not open, the message will be persisted in the - queue - instead and sent when the socket is ready. -- `sendImmediately(message, fromElt)` - attempts to send a message regardless of socket state, bypassing the queue. May - fail -- `queue` - an array of messages, awaiting in the queue. - -This wrapper can be used in your event handlers to monitor and manipulate the queue (e.g., you can reset the queue when -reconnecting), and to send additional messages (e.g., if you want to send data in batches). -The `fromElt` parameter is optional and, when specified, will trigger corresponding websocket events from -specified element, namely `htmx:wsBeforeSend` and `htmx:wsAfterSend` events when sending your messages. - -### Testing with the Demo Server - -Htmx includes a demo WebSockets server written in Node.js that will help you to see WebSockets in action, and begin -bootstrapping your own WebSockets code. It is located in the /test/ws-sse folder of the htmx distribution. Look at -/test/ws-sse/README.md for instructions on running and using the test server. - -### Migrating from Previous Versions - -Previous versions of htmx used a built-in tag `hx-ws` to implement WebSockets. This code has been migrated into an -extension instead. Here are the steps you need to take to migrate to this version: - -| Old Attribute | New Attribute | Comments | -|-------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------| -| `hx-ws=""` | `hx-ext="ws"` | Use the `hx-ext="ws"` attribute to install the WebSockets extension into any HTML element. | -| `hx-ws="connect:"` | `ws-connect=""` | Add a new attribute `ws-connect` to the tag that defines the extension to specify the URL of the WebSockets server you're using. | -| `hx-ws="send"` | `ws-send=""` | Add a new attribute `ws-send` to mark any child forms that should send data to your WebSocket server | +See https://htmx.org/extensions/ws, or https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/ws.md \ No newline at end of file