From afc3b2622587a1f7f3fdc46fd6ffbabcbb693370 Mon Sep 17 00:00:00 2001
From: carson <carson@leaddyno.com>
Date: Wed, 30 Sep 2020 08:57:45 -0600
Subject: [PATCH] docs

---
 www/attributes/hx-encoding.md | 17 +++++++++++++++++
 www/docs.md                   | 12 ++++++++++++
 www/events.md                 | 31 +++++++++++++++++++++++++++++++
 www/reference.md              |  4 ++++
 4 files changed, 64 insertions(+)
 create mode 100644 www/attributes/hx-encoding.md

diff --git a/www/attributes/hx-encoding.md b/www/attributes/hx-encoding.md
new file mode 100644
index 00000000..3f488571
--- /dev/null
+++ b/www/attributes/hx-encoding.md
@@ -0,0 +1,17 @@
+---
+layout: layout.njk
+title: </> htmx - hx-encoding
+---
+
+## `hx-encoding`
+
+The `hx-encoding` attribute allows you to switch the request encoding from the usual `application/x-www-form-urlencoded`
+encoding to `multipart/form-data`, usually to support file uploads in an ajax request.
+
+The value of this attribute should be `multipart/form-data`.
+
+The `hx-encoding` tag may be placed on parent elements.
+
+### Notes
+
+* `hx-encoding` is inherited and can be placed on a parent element
diff --git a/www/docs.md b/www/docs.md
index 73a1fe89..5fd9a48a 100644
--- a/www/docs.md
+++ b/www/docs.md
@@ -344,6 +344,18 @@ If you wish to filter out some parameters you can use the [hx-params](/attribute
 Finally, if you want to programatically modify the parameters, you can use the [htmx:configRequest](/events#htmx:configRequest) 
 event.
 
+#### <a name="files"></a> [File Upload](#files)
+
+If you wish to upload files via an htmx request, you can set the [hx-encoding](/attributes/hx-encoding) attribute to 
+`multipart/form-data`.  This will use a `FormData` object to submit the request, which will properly include the file
+in the request.
+
+Note that depending on your server-side technology, you may have to handle requests with this type of body content very 
+differently.
+
+Note that htmx fires a `htmx:xhr:progress` event periodically based on the standard `progress` event during upload, 
+which you can hook into to show the progress of the upload.
+
 #### <a name="vars"></a> [Variables](#variables)
 
 You can also include dynamically computed variables in the parameters of a request by using the 
diff --git a/www/events.md b/www/events.md
index c131f40e..433b9552 100644
--- a/www/events.md
+++ b/www/events.md
@@ -290,3 +290,34 @@ This event is triggered when a request is halted due to validation errors.
 * `detail.elt` - the element that triggered the request
 * `detail.errors` - an array of error objects with the invalid elements and errors associated with them
 
+### <a name="htmx:xhr:abort"></a> Event - [htmx:xhr:abort](#htmx:xhr:abort)
+
+This event is triggered when an ajax request aborts
+
+##### Details
+
+* `detail.elt` - the element that triggered the request
+
+### <a name="htmx:xhr:loadstart"></a> Event - [htmx:xhr:loadstart](#htmx:xhr:loadstart)
+
+This event is triggered when an ajax request starts
+
+##### Details
+
+* `detail.elt` - the element that triggered the request
+
+### <a name="htmx:xhr:loadend"></a> Event - [htmx:xhr:loadend](#htmx:xhr:loadend)
+
+This event is triggered when an ajax request finishes
+
+##### Details
+
+* `detail.elt` - the element that triggered the request
+
+### <a name="htmx:xhr:progress"></a> Event - [htmx:xhr:progress](#htmx:xhr:progress)
+
+This event is triggered periodically when an ajax request that supports progress is in flight
+
+##### Details
+
+* `detail.elt` - the element that triggered the request
diff --git a/www/reference.md b/www/reference.md
index 1717dde3..b6186a10 100644
--- a/www/reference.md
+++ b/www/reference.md
@@ -122,6 +122,10 @@ title: </> htmx - Attributes
 | [`htmx:validation:validate`](/events#htmx:validation:validate)  | triggered before an element is validated
 | [`htmx:validation:failed`](/events#htmx:validation:failed)  | triggered when an element fails validation
 | [`htmx:validation:halted`](/events#htmx:validation:halted)  | triggered when a request is halted due to validation errors
+| [`htmx:xhr:abort`](/events#htmx:xhr:abort)  | triggered when an ajax request aborts
+| [`htmx:xhr:loadend`](/events#htmx:xhr:loadend)  | triggered when an ajax request ends
+| [`htmx:xhr:loadstart`](/events#htmx:xhr:loadstart)  | triggered when an ajax request starts
+| [`htmx:xhr:progress`](/events#htmx:xhr:progress)  | triggered periodically during an ajax request that supports progress events
 
 </div>