aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-06-23 17:51:36 +0200
committerLoïc Hoguin <[email protected]>2014-06-23 17:51:36 +0200
commit642630fea10490e3bbe214652142c51c7787de46 (patch)
treec556e842ec016cd05525ff153c5e5c0f54914030
parent5cd2f0516ad746716105f371a8b51eb71fb41d21 (diff)
downloadcowboy-642630fea10490e3bbe214652142c51c7787de46.tar.gz
cowboy-642630fea10490e3bbe214652142c51c7787de46.tar.bz2
cowboy-642630fea10490e3bbe214652142c51c7787de46.zip
Add a multipart intro chapter to the guide
-rw-r--r--guide/multipart_intro.md53
-rw-r--r--guide/toc.md2
2 files changed, 54 insertions, 1 deletions
diff --git a/guide/multipart_intro.md b/guide/multipart_intro.md
new file mode 100644
index 0000000..dde4099
--- /dev/null
+++ b/guide/multipart_intro.md
@@ -0,0 +1,53 @@
+Introduction to multipart
+=========================
+
+Multipart originates from MIME, an Internet standard that
+extends the format of emails. Multipart messages are a
+container for parts of any content-type.
+
+For example, a multipart message may have a part
+containing text and a second part containing an
+image. This is what allows you to attach files
+to emails.
+
+In the context of HTTP, multipart is most often used
+with the `multipart/form-data` content-type. This is
+the content-type you have to use when you want browsers
+to be allowed to upload files through HTML forms.
+
+Multipart is of course not required for uploading
+files, it is only required when you want to do so
+through HTML forms.
+
+Structure
+---------
+
+A multipart message is a list of parts. Parts may
+contain either a multipart message or a non-multipart
+content-type. This allows parts to be arranged in a
+tree structure, although this is a rare case as far
+as the Web is concerned.
+
+Form-data
+---------
+
+In the normal case, when a form is submitted, the
+browser will use the `application/x-www-form-urlencoded`
+content-type. This type is just a list of keys and
+values and is therefore not fit for uploading files.
+
+That's where the `multipart/form-data` content-type
+comes in. When the form is configured to use this
+content-type, the browser will use one part of the
+message for each form field. This means that a file
+input field will be sent in its own part, but the
+same applies to all other kinds of fields.
+
+A form with a text input, a file input and a select
+choice box will result in a multipart message with
+three parts, one for each field.
+
+The browser does its best to determine the content-type
+of the files it sends this way, but you should not
+rely on it for determining the contents of the file.
+Proper investigation of the contents is recommended.
diff --git a/guide/toc.md b/guide/toc.md
index db10317..9787f0a 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -39,7 +39,7 @@ REST
Multipart
---------
- * Understanding multipart
+ * [Introduction to multipart](multipart_intro.md)
* [Multipart requests](multipart_req.md)
* Multipart responses