Merge WHATWG change: Define FormData more clearly as a list of name/value pairs where value is always a File object (which can be created from a Blob)
authorJungkee Song <jungkee.song@samsung.com>
Wed, 23 Oct 2013 14:04:13 +0900
changeset 134 996407158161
parent 133 1052a0749456
child 135 8b516a9ba0cc
Merge WHATWG change: Define FormData more clearly as a list of name/value pairs where value is always a File object (which can be created from a Blob)
Overview.html
Overview.src.html
data/xrefs/dom/xhr.json
--- a/Overview.html	Wed Oct 23 12:25:56 2013 +0900
+++ b/Overview.html	Wed Oct 23 14:04:13 2013 +0900
@@ -2633,10 +2633,6 @@
 
 <h2 id="interface-formdata"><span class="secno">5 </span>Interface <code title="">FormData</code></h2>
 
-<p>The <code><a href="#formdata">FormData</a></code> object represents an ordered collection of
-entries. Each entry has a name, a value, a type, and optionally a filename
-(if type is "file").
-
 <pre class="idl">[<a href="#dom-formdata" title="dom-FormData">Constructor</a>(optional <a class="external" href="http://www.w3.org/html/wg/drafts/html/master/the-form-element.html#htmlformelement">HTMLFormElement</a> <var>form</var>)]
 interface <dfn id="formdata">FormData</dfn> {
   void <a href="#dom-formdata-append" title="dom-FormData-append">append</a>(DOMString <var>name</var>, <a class="external" href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a> <var title="">value</var>, optional DOMString <var title="">filename</var>);
@@ -2648,14 +2644,29 @@
 <a class="external" href="http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#exposed-to-javascript">exposed to JavaScript</a> as if the constructor part of the
 IDL reads <code title="">[Constructor]</code> (i.e. has no arguments).
 <!-- maybe move this into IDL at some point -->
- 
+
+<p>The <code><a href="#formdata">FormData</a></code> object represents an ordered list of
+<dfn id="concept-formdata-entry" title="concept-FormData-entry">entries</dfn>. Each
+<a href="#concept-formdata-entry" title="concept-FormData-entry">entry</a> consists of a
+<dfn id="concept-formdata-entry-name" title="concept-FormData-entry-name">name</dfn> and a
+<dfn id="concept-formdata-entry-value" title="concept-FormData-entry-value">value</dfn>.
+
+<p>For the purposes of interaction with other algorithms, an
+<a href="#concept-formdata-entry" title="concept-FormData-entry">entry</a>'s type is "string" if
+<a href="#concept-formdata-entry-value" title="concept-FormData-entry-value">value</a> is a string and "file" otherwise. If
+an <a href="#concept-formdata-entry" title="concept-FormData-entry">entry</a>'s type is "file", its filename is the
+value of <a href="#concept-formdata-entry" title="concept-FormData-entry">entry</a>'s
+<a href="#concept-formdata-entry-value" title="concept-FormData-entry-value">value</a>'s
+<code class="external" title="dom-File-name"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-name">name</a></code> attribute.
+
 <dl class="domintro">
  <dt><code><var title="">fd</var> = new <a href="#dom-formdata" title="dom-FormData">FormData</a>([<var title="">form</var>])</code>
- <dd><p>Returns a new <code><a href="#formdata">FormData</a></code> object, optionally initialized
- with the data from <var title="">form</var> (if given).
+ <dd><p>Returns a new <code><a href="#formdata">FormData</a></code> object, optionally initialized with the
+ <a href="#concept-formdata-entry" title="concept-FormData-entry">entries</a> from <var title="">form</var> (if given).
 
  <dt><code><var title="">fd</var> . <a href="#dom-formdata-append" title="dom-FormData-append">append</a>(<var title="">name</var>, <var title="">value</var> [, <var title="">filename</var>])</code>
- <dd><p>Appends a new entry to the <code><a href="#formdata">FormData</a></code> object.
+ <dd><p>Appends a new <a href="#concept-formdata-entry" title="concept-FormData-entry">entry</a> to the
+ <code><a href="#formdata">FormData</a></code> object. 
 </dl>
 
   <p>The
@@ -2665,37 +2676,40 @@
   <ol>
    <li><p>Let <var title="">fd</var> be a new <code><a href="#formdata">FormData</a></code> object.
 
-   <li><p>If <var>form</var> is given, set <var title="">fd</var>'s entries to
-   the result of
-   <a class="external" href="http://www.w3.org/html/wg/drafts/html/master/constraints.html#constructing-form-data-set">constructing the form data set</a> for
-   <var>form</var>.
+   <li><p>If <var>form</var> is given, set <var title="">fd</var>'s
+   <a href="#concept-formdata-entry" title="concept-FormData-entry">entries</a> to the result of
+   <a class="external" href="http://www.w3.org/html/wg/drafts/html/master/constraints.html#constructing-form-data-set">constructing the form data set</a> for <var>form</var>.
 
    <li><p>Return <var title="">fd</var>.
   </ol>
 
 <p>The
 <dfn id="dom-formdata-append" title="dom-FormData-append"><code>append(<var>name</var>, <var>value</var>, <var>filename</var>)</code></dfn>
-method must create a new entry with the following parameters set and append
-it to the end of the collection the <code><a href="#formdata">FormData</a></code> object represents:
-
-<ul>
- <li><p>Set its name to <var>name</var>.
-
- <li><p>Set its value to <var>value</var>.
-
- <li><p>Set its type to "text" if <var>value</var> is a string and "file" if
- it is a <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>.
-
- <li><p>If its type is "file" set its filename to "<code title="">blob</code>".
-
- <li><p>If its type is "file" and <var>value</var> is a
- <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#file">File</a></code> whose
- <code class="external" title="dom-File-name"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-name">name</a></code> attribute
- is not the empty string, set entry's filename to the attribute's value.
-
- <li><p>If the <var title="">filename</var> parameter is not omitted set
- entry's filename to <var title="">filename</var>.
-</ul>
+method must run these steps:
+
+<ol>
+ <li><p>Let <var title="">entry</var> be a new
+ <a href="#concept-formdata-entry" title="concept-FormData-entry">entry</a>.
+
+ <li><p>Set <var title="">entry</var>'s <a href="#concept-formdata-entry-name" title="concept-FormData-entry-name">name</a>
+ to <var>name</var>.
+
+ <li><p>If <var>value</var> is a <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>, set
+ <var>value</var> to a new <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#file">File</a></code> object whose
+ <code class="external" title="dom-File-name"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-name">name</a></code> attribute value is
+ "<code title="">blob</code>". 
+
+ <li><p>If <var>value</var> is a <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#file">File</a></code> and
+ <var title="">filename</var> is given, set <var>value</var>'s
+ <code class="external" title="dom-File-name"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-name">name</a></code> attribute value to
+ <var title="">filename</var>.
+
+ <li><p>Set <var title="">entry</var>'s <a href="#concept-formdata-entry-value" title="concept-FormData-entry-value">value</a>
+ to <var>value</var>. 
+
+ <li><p>Append <var title="">entry</var> to <code><a href="#formdata">FormData</a></code> object's list of
+ <a href="#concept-formdata-entry" title="concept-FormData-entry">entries</a>.
+</ol> 
 
 
 <h2 id="data:-urls-and-http"><span class="secno">6 </span><code>data:</code> URLs and HTTP</h2>
--- a/Overview.src.html	Wed Oct 23 12:25:56 2013 +0900
+++ b/Overview.src.html	Wed Oct 23 14:04:13 2013 +0900
@@ -2642,10 +2642,6 @@
 
 <h2>Interface <code title>FormData</code></h2>
 
-<p>The <code>FormData</code> object represents an ordered collection of
-entries. Each entry has a name, a value, a type, and optionally a filename
-(if type is "file").
-
 <pre class="idl">[<span title="dom-FormData">Constructor</span>(optional <span data-anolis-spec=html>HTMLFormElement</span> <var>form</var>)]
 interface <dfn>FormData</dfn> {
   void <span title="dom-FormData-append">append</span>(DOMString <var>name</var>, <span data-anolis-spec=fileapi>Blob</span> <var title>value</var>, optional DOMString <var title>filename</var>);
@@ -2657,14 +2653,29 @@
 <span data-anolis-spec=html>exposed to JavaScript</span> as if the constructor part of the
 IDL reads <code title>[Constructor]</code> (i.e. has no arguments).
 <!-- maybe move this into IDL at some point -->
- 
+
+<p>The <code>FormData</code> object represents an ordered list of
+<dfn title=concept-FormData-entry>entries</dfn>. Each
+<span title=concept-FormData-entry>entry</span> consists of a
+<dfn title=concept-FormData-entry-name>name</dfn> and a
+<dfn title=concept-FormData-entry-value>value</dfn>.
+
+<p>For the purposes of interaction with other algorithms, an
+<span title=concept-FormData-entry>entry</span>'s type is "string" if
+<span title=concept-FormData-entry-value>value</span> is a string and "file" otherwise. If
+an <span title=concept-FormData-entry>entry</span>'s type is "file", its filename is the
+value of <span title=concept-FormData-entry>entry</span>'s
+<span title=concept-FormData-entry-value>value</span>'s
+<code data-anolis-spec=fileapi title=dom-File-name>name</code> attribute.
+
 <dl class=domintro>
  <dt><code><var title>fd</var> = new <span title="dom-FormData">FormData</span>([<var title>form</var>])</code>
- <dd><p>Returns a new <code>FormData</code> object, optionally initialized
- with the data from <var title>form</var> (if given).
+ <dd><p>Returns a new <code>FormData</code> object, optionally initialized with the
+ <span title=concept-FormData-entry>entries</span> from <var title>form</var> (if given).
 
  <dt><code><var title>fd</var> . <span title=dom-FormData-append>append</span>(<var title>name</var>, <var title>value</var> [, <var title>filename</var>])</code>
- <dd><p>Appends a new entry to the <code>FormData</code> object.
+ <dd><p>Appends a new <span title=concept-FormData-entry>entry</span> to the
+ <code>FormData</code> object. 
 </dl>
 
   <p>The
@@ -2674,37 +2685,40 @@
   <ol>
    <li><p>Let <var title>fd</var> be a new <code>FormData</code> object.
 
-   <li><p>If <var>form</var> is given, set <var title>fd</var>'s entries to
-   the result of
-   <span data-anolis-spec=html>constructing the form data set</span> for
-   <var>form</var>.
+   <li><p>If <var>form</var> is given, set <var title>fd</var>'s
+   <span title=concept-FormData-entry>entries</span> to the result of
+   <span data-anolis-spec=html>constructing the form data set</span> for <var>form</var>.
 
    <li><p>Return <var title>fd</var>.
   </ol>
 
 <p>The
 <dfn title="dom-FormData-append" id="dom-formdata-append"><code>append(<var>name</var>, <var>value</var>, <var>filename</var>)</code></dfn>
-method must create a new entry with the following parameters set and append
-it to the end of the collection the <code>FormData</code> object represents:
-
-<ul>
- <li><p>Set its name to <var>name</var>.
-
- <li><p>Set its value to <var>value</var>.
-
- <li><p>Set its type to "text" if <var>value</var> is a string and "file" if
- it is a <code data-anolis-spec=fileapi>Blob</code>.
-
- <li><p>If its type is "file" set its filename to "<code title>blob</code>".
-
- <li><p>If its type is "file" and <var>value</var> is a
- <code data-anolis-spec=fileapi>File</code> whose
- <code data-anolis-spec=fileapi title=dom-File-name>name</code> attribute
- is not the empty string, set entry's filename to the attribute's value.
-
- <li><p>If the <var title>filename</var> parameter is not omitted set
- entry's filename to <var title>filename</var>.
-</ul>
+method must run these steps:
+
+<ol>
+ <li><p>Let <var title>entry</var> be a new
+ <span title=concept-FormData-entry>entry</span>.
+
+ <li><p>Set <var title>entry</var>'s <span title=concept-FormData-entry-name>name</span>
+ to <var>name</var>.
+
+ <li><p>If <var>value</var> is a <code data-anolis-spec=fileapi>Blob</code>, set
+ <var>value</var> to a new <code data-anolis-spec=fileapi>File</code> object whose
+ <code data-anolis-spec=fileapi title=dom-File-name>name</code> attribute value is
+ "<code title>blob</code>". 
+
+ <li><p>If <var>value</var> is a <code data-anolis-spec=fileapi>File</code> and
+ <var title>filename</var> is given, set <var>value</var>'s
+ <code data-anolis-spec=fileapi title=dom-File-name>name</code> attribute value to
+ <var title>filename</var>.
+
+ <li><p>Set <var title>entry</var>'s <span title=concept-FormData-entry-value>value</span>
+ to <var>value</var>. 
+
+ <li><p>Append <var title>entry</var> to <code>FormData</code> object's list of
+ <span title=concept-FormData-entry>entries</span>.
+</ol> 
 
 
 <h2><code>data:</code> URLs and HTTP</h2>
--- a/data/xrefs/dom/xhr.json	Wed Oct 23 12:25:56 2013 +0900
+++ b/data/xrefs/dom/xhr.json	Wed Oct 23 14:04:13 2013 +0900
@@ -5,6 +5,9 @@
     "arraybuffer response entity body": "arraybuffer-response-entity-body",
     "author request headers": "author-request-headers",
     "blob response entity body": "blob-response-entity-body",
+    "concept-formdata-entry": "concept-formdata-entry",
+    "concept-formdata-entry-name": "concept-formdata-entry-name",
+    "concept-formdata-entry-value": "concept-formdata-entry-value",
     "concept-response-header": "concept-response-header",
     "concept-xmlhttprequest-document": "concept-xmlhttprequest-document",
     "cross-origin request event rules": "cross-origin-request-event-rules",