Index: src/site/docs/tutorials/forms/index.markdown |
diff --git a/src/site/docs/tutorials/forms/index.markdown b/src/site/docs/tutorials/forms/index.markdown |
index 1059a55c0dff97c6cebb0b7cce5f10631cf2a545..b5444b573fa9a2d49543cb0a58def9dab4a9a63c 100644 |
--- a/src/site/docs/tutorials/forms/index.markdown |
+++ b/src/site/docs/tutorials/forms/index.markdown |
@@ -69,6 +69,15 @@ several classes from the core Dart library, |
including streams, Futures, HttpRequest, and so on. |
The server uses CORS headers to allow cross-origin requests. |
+<aside class="alert alert-info" markdown="1"> |
+ <strong>Note:</strong> |
+ This tutorial assumes that you have read |
+ [Define a Custom Elment](/docs/tutorials/polymer-intro/) |
+ and [Fetch Data Dynamically](/docs/tutorials/fetchdata/) |
+ and are familiar with Polymer, JSON, and HttpRequest. |
+</aside> |
+ |
+ |
* [About forms, generally](#about-forms) |
* [About the slambook example, specifically](#about-the-slambook-example) |
* [Submitting a form](#submitting-a-form) |
@@ -78,8 +87,9 @@ The server uses CORS headers to allow cross-origin requests. |
* [Setting CORS headers](#setting-cors-headers) |
* [Handling POST requests](#handling-post-requests) |
* [Recipe for client-server web apps](#recipe) |
-* [Binding data to different kinds of inputs](#binding-data) |
+* [Two-way data binding using Polymer](#binding-data) |
* [Other resources](#other-resources) |
+* [What next?](#what-next) |
##About forms, generally {#about-forms} |
@@ -92,18 +102,17 @@ programmatically. |
Let's begin with a basic, HTML-only form to learn a little bit about |
action, method, input elements, and the default behavior of forms. |
-The search_form app running below provides a useful form that |
-you can add to your website pages. |
-It uses Google to search the specified website |
-if the checkbox is selected, |
-or the web if it is not, |
+The form below uses Google to search the website |
+specified in the <form> tag |
+if the checkbox is selected |
+(or the web if it is not), |
for the text entered by the user. |
In this example, |
called `search_form`, |
the default is to search |
[dartlang.org](http://www.dartlang.org) |
for "Cookbook", |
-another useful resource for learning about Dart. |
+a useful resource for learning about Dart. |
<iframe class="running-app-frame" |
style="height:100px;width:500px;" |
@@ -208,11 +217,11 @@ running from a different origin. |
the client program, |
called `slambook`, |
provides a form into which users can enter some information. |
-It uses Polymer data binding to bind the input data to Dart variables. |
+It uses Polymer two-way data binding to bind the input data to Dart variables. |
When the user clicks the submit button, |
the Dart code formats the data into a JSON string, |
-sends it to slambookserver using an OPTIONS request to |
-get access first and then a POST request to send the data. |
+sends an OPTIONS request to get permission from the server, |
+and then a POST request to send the data. |
When the response from the server is ready, |
the client displays it. |
@@ -284,7 +293,7 @@ On the server side, the sections cover |
##Submitting a form |
-Let's first take a look at how that data is submitted to the server. |
+Let's first take a look at how the data is submitted to the server. |
Recall that the search_form example relies on the `action` and |
`method` attributes to set the destination and method for the form request. |
@@ -302,17 +311,18 @@ the automatic behavior of the submit button. |
with help from the Dart libraries. |
The form in the slambook example is |
-a custom element called `x-slambook-form` |
+a custom element called `tute-slambook-form` |
that's instantiated with this HTML code: |
{% prettify html %} |
<div class="container"> |
- <form is="x-slambook-form" id="slambookform"></form> |
+ <form is="tute-slambook-form" id="slambookform"></form> |
</div> |
{% endprettify %} |
Note the absence of either an `action` or a `method` attribute. |
-Instead, the behavior for the submit button is coded in Dart. |
+Instead, the behavior for the submit button is coded in a Dart |
+mouse click handler. |
Below is the HTML code that creates the submit button |
and binds it to a Dart mouse click handler. |
@@ -431,7 +441,8 @@ First the code checks whether the request is complete and successful. |
If it is, the code puts the server's response in a string, |
called `serverResponse`, which is bound to the value of a textarea |
in the slambook app's UI. |
-When the string changes, the UI is automatically updated. |
+When the string changes, the UI is automatically updated, |
+and the message is displayed for the user. |
If the request is complete but unsuccessful, |
the program sets `serverResponse` to an error message, |
@@ -439,13 +450,10 @@ thus displaying it to the user. |
##Resetting a form |
-The reset button is a special input type that, by default, |
+The reset button is a special HTML input type that, by default, |
clears the values of all inputs within the form. |
-Currently, |
-this automatic behavior clears the input elements |
-as expected, |
-but any bound Dart values do not get updated. |
- |
+Instead, we want the button to reset the values in the form |
+to their initial value. |
So, the mouse click handler for the reset button |
needs to suppress the automatic behavior |
and reset the form with neutral data explicitly. |
@@ -466,7 +474,7 @@ void resetForm(Event e) { |
theData['catOrDog'] = 'cat'; |
theData['music'] = 0; |
theData['zombies'] = false; |
- serverResponse = "Data cleared."; |
+ serverResponse = "Data reset."; |
} |
{% endprettify %} |
@@ -514,7 +522,7 @@ The second, `printError`, is called if the binding fails. |
An error might occur if, for example, |
another program is already listening on the same port. |
-The code for gotMessage(), shown below, triages the request |
+The code for gotMessage(), shown below, filters the request |
and calls other methods to handle each specific kind of request. |
{% prettify dart %} |
@@ -535,9 +543,10 @@ void gotMessage(_server) { |
} |
{% endprettify %} |
-To handle other types of requests, |
-you could simply add more `case` statements. |
-For example, `case 'GET'` for HTTP GET requests. |
+To handle other types of requests |
+such as `GET` requests, |
+you could simply add more `case` statements, |
+such as `case 'GET'`. |
###About Futures, briefly |
@@ -562,7 +571,7 @@ two things happen: |
and returns an uncompleted Future object immediately. |
</li> |
<li> |
- Later, when a value is available, |
+ Later, when the value is available, |
the Future object completes with that value or with an error. |
</li> |
</ul> |
@@ -745,23 +754,26 @@ and one in dart:io (for servers). |
| <a href="https://api.dartlang.org/dart_io/HttpResponse.html" target="_blank">HttpResponse</a> | dart:io | Server-side object to carry response to client requests | |
| <a href="https://api.dartlang.org/dart_async/Stream.html" target="_blank">Streams</a> | dart:async | A stream of data | |
| <a href="https://api.dartlang.org/dart_async/Future.html" target="_blank">Future</a> | dart:async | A way to get a value asynchronously | |
-| <a href="https://api.dartlang.org/dart_json.html" target="_blank">stringify()</a> | dart:json | How you format an object into a JSON string | |
+| <a href="https://api.dartlang.org/dart_json.html" target="_blank">stringify()</a> | dart:convert | A library with resources for converting an object into a JSON string | |
| <a href="https://api.dartlang.org/polymer.html" target="_blank">Polymer</a> | Polymer | Custom elements, data binding, templates | |
{: .table} |
-##Binding data to different kinds of inputs {#binding-data} |
+##Two-way data binding using Polymer {#binding-data} |
-The slambook sample uses Polymer to |
+The slambook sample uses Polymer's two-way data binding to |
bind the values of input elements to Dart variables. |
If the user changes the value in an input element, |
the bound variable in the Dart code automatically changes. |
Or if the Dart code changes the value of the bound variable, |
the UI automatically updates. |
[Define a Custom Element](/docs/tutorials/polymer-intro/) |
-provides introductory details |
-about data binding with Polymer. |
+provides introductory details about Polymer and |
+about data binding. |
-With this example, |
+The example also uses declarative event handler mapping to hook |
+event handler functions to input elements. |
+ |
+With the slambook example, |
you can see two-way data binding used with a variety of input elements, |
including new HTML5 elements. |
This table summarizes the two-way data binding attributes |
@@ -769,19 +781,19 @@ you can use with Polymer: |
| Attribute | Dart type | Input element | |
|---|---| |
-| bind-value | String | any <br>with special considerations for elements <br> that allow multiple selection,<br> such as a group of radio buttons and <select> elements | |
-| bind-selected-index | integer | a <select> element in which only one choice is allowed | |
-| bind-checked | bool | individual radio buttons or checkboxes | |
-{: .table .nowraptable} |
+| value | String | any | |
+| selectedIndex | integer | a <select> element in which only one choice is allowed | |
+| checked | bool | individual radio buttons or checkboxes | |
+{: .table} |
-###Using bind-value with any input element |
+###Using value with any input element |
-The `bind-value` attribute works with any input element |
+The `value` attribute works with any input element |
and binds the value to a Dart string. |
-This example uses `bind-value` with a text field, a text area, |
+This example uses `value` with a text field, a text area, |
a color picker, a date chooser, and a range element. |
- |
+ |
(Note that some surrounding code, |
such as that for the labels, |
@@ -793,13 +805,13 @@ to make the bindings. |
The map contains a key-value pair for each input element, |
where the key is a string. |
-The values in the map can be of any type |
-but the values for elements bound with `bind-value` are all strings. |
+The values for elements bound with `value` are all strings. |
The HTML refers to the items in the map |
using their Dart names (identifiers). |
For example, the value of the color picker is bound to |
`theData['favoriteColor']`. |
+{% comment %} |
####Special case: Using bind-value with a group of radio buttons |
The slambook form contains three radio buttons, |
@@ -812,7 +824,6 @@ the bound string reflects the value of the entire group. |
 |
-{% comment %} |
####Special case: Not using bind-value with a multiple select element |
By default a <select> element allows |
@@ -909,25 +920,25 @@ the `books` map, because the getter uses the map. |
When `books` changes, the UI updates the unnumbered list of selected books. |
{% endcomment %} |
-###Using bind-selected-index with a pull-down menu |
+###Using selectedIndex with a pull-down menu |
A <select> element contains one or more <option> elements, |
only one of which, by default, can be selected at a time. |
A single-select element is usually implemented as a pull-down menu. |
-You can use the `bind-selected-index` attribute |
+You can use the `selectedIndex` attribute |
to bind a Dart integer to a pull-down menu. |
The integer indicates the index of the selected item. |
Indices begin at 0. |
- |
+ |
-###Using bind-checked with checkboxes |
+###Using checked with checkboxes |
-You can use the `bind-checked` attribute |
+You can use the `checked` attribute |
to bind a Dart boolean to a single checkbox. |
Here each checkbox is bound to a separate boolean value within a map. |
- |
+ |
##Other resources |
@@ -954,10 +965,10 @@ Here each checkbox is bound to a separate boolean value within a map. |
###What next? |
-Try our |
-<a href="/codelabs/web-ui-writer/index.html" target="_blank"><i class="icon-beaker"> </i>Codelab</a>. |
-In this step-by-step guide, you’ll build a simple, |
-single-page, modern web app for desktop and mobile. |
+The next tutorial, |
+[Use IndexedDB](/docs/tutorials/indexeddb), |
+describes how to save data on the client |
+in the browser's Indexed Database. |
{% endcapture %} |