diff options
author | Loïc Hoguin <[email protected]> | 2014-06-23 17:51:36 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2014-06-23 17:51:36 +0200 |
commit | 642630fea10490e3bbe214652142c51c7787de46 (patch) | |
tree | c556e842ec016cd05525ff153c5e5c0f54914030 | |
parent | 5cd2f0516ad746716105f371a8b51eb71fb41d21 (diff) | |
download | cowboy-642630fea10490e3bbe214652142c51c7787de46.tar.gz cowboy-642630fea10490e3bbe214652142c51c7787de46.tar.bz2 cowboy-642630fea10490e3bbe214652142c51c7787de46.zip |
Add a multipart intro chapter to the guide
-rw-r--r-- | guide/multipart_intro.md | 53 | ||||
-rw-r--r-- | guide/toc.md | 2 |
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 |