Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(14)

Side by Side Diff: src/site/docs/tutorials/web-ui/index.markdown

Issue 26922002: removing Web UI tutorials, updating remaining 4 to current release, + review pass (Closed) Base URL: https://github.com/dart-lang/dartlang.org.git@master
Patch Set: provided redirects for web UI tutes, put deprecated notice in code lab Created 7 years, 2 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
(Empty)
1 ---
2 layout: default
3 title: "Get Started with Web UI"
4 description: "Web UI provides web components, templates, data binding, and encap sulation."
5 has-permalinks: true
6 tutorial:
7 id: get-started-web-ui
8 next: templates/
9 next-title: "Use Templates"
10 prev: shared-pkgs/
11 prev-title: "Install Shared Packages"
12 ---
13
14 {% capture whats_the_point %}
15
16 * Web UI is an open-source package.
17 * Web UI provides web components for Dart apps.
18 * Other features support separation of data and presentation.
19 * Compile Web UI apps automatically in Dart Editor.
20 * Use data binding to sync Dart variables and UI elements.
21 * Attach event handlers to UI elements in HTML.
22
23 {% endcapture %}
24
25 {% capture sample_links %}
26
27 <p>
28 Get the source code for the samples featured in this target:</p>
29
30 <ul>
31 <li>
32 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web /target06/littleben"
33 target="_blank">littleben</a>
34 </li>
35 <li>
36 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web /target06/shout"
37 target="_blank">shout</a>
38 </li>
39 <li>
40 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web /target06/stopwatch"
41 target="_blank">stopwatch</a>
42 </li>
43 </ul>
44
45 {% endcapture %}
46
47 {% capture content %}
48
49 <div class="tute-target-title">
50 <h1>{{page.title}}</h1>
51 <h3>Declaratively create dynamic user interfaces.</h3>
52 </div>
53
54 <hr>
55
56 <aside class="alert" style="background-color:Lavender;color:SlateBlue">
57 <font size="24">
58 <i class="icon-bullhorn"> </i>
59 </font>
60 Web UI is being upgraded to polymer.dart.
61 For more information about polymer.dart,
62 including tips on porting Web UI apps to polymer.dart
63 and the current status of the project,
64 check out the <a href="/polymer-dart/" target="_blank">polymer.dart</a>
65 home page.
66 For polymer.dart versions of the tutorial's Web UI apps,
67 check out the tutorial's
68 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/"
69 target="_blank">code repo</a> on github.
70 </aside>
71
72 <hr>
73
74
75 The
76 <a href="https://pub.dartlang.org/packages/web_ui" target="_blank">Web UI packag e</a>
77 provides the tools and Dart code
78 that implement data binding, web components,
79 templates, and encapsulation.
80 To use these Web UI features,
81 you need to install the Web UI package in each application that uses it
82 and compile the project using the Web UI compiler.
83 To streamline the development process,
84 you can use Dart Editor to help set up your project,
85 install the package, and automate the build process.
86
87 This target begins by showing you how to set up a project to use Web UI,
88 including how to install the package.
89 (If you are unfamiliar with packages, the previous target,
90 <a href="/docs/tutorials/shared-pkgs/">Install Shared Packages</a>,
91 has details.)
92 Then this target describes how to use two features of the Web UI package.
93 Specifically, you will learn
94 how to use data binding to embed mutable Dart data in your HTML page
95 and to declaratively attach event handlers to UI elements.
96
97 The next two targets,
98 <a href="/docs/tutorials/templates/">Target 7: Use &lt;template&gt;</a>
99 and
100 <a href="/docs/tutorials/custom-elements/">Target 8: Define a Custom DOM Tag</a> ,
101 describe other features of the Web UI package.
102
103 * [About using the Web UI package](#about-web-ui)
104 * [Create a new application with Web UI installed](#create-new)
105 * [Install the Web UI package in an existing web application](#install-web-ui)
106 * [Set up background compilation in Dart Editor](#set-up)
107 * [Embedding data in a web page with one-way data binding](#one-way-data-binding )
108 * [Binding the value of an element to a Dart variable](#two-way-data-binding)
109 * [About template expressions](#template-expressions)
110 * [Binding event handlers](#binding-event-handlers)
111 * [Other resources](#other-resources)
112
113 ##About using the Web UI package {#about-web-ui}
114
115 You can use Web UI features directly in your HTML code
116 as naturally as you use standard HTML.
117 In fact, some of the Web UI syntax looks like regular HTML tags,
118 so you could think of the Web UI library as extending the HTML language.
119
120 Before you can run an app that uses Web UI,
121 you must compile the app using the Web UI compiler `dwc`.
122 The compiler translates the Web UI code
123 into standard HTML and Dart scripts
124 and includes the code that implements the Web UI features.
125 You run the compiled version of the app as you normally would
126 using the Dart VM or by converting it to JavaScript.
127
128 ![Compiling your program with Web UI packages](images/webui-compile.png)
129
130 In this way,
131 Web UI provides an extra
132 layer between your code and the browser platform,
133 seamlessly providing you with new browser features like
134 web components and templates.
135
136 You can set up Dart Editor to automate the compilation process
137 for projects that use the Web UI library.
138 Dart Editor detects changes to your project files
139 and automatically compiles in the background.
140 With Dart Editor at the center of your development cycle,
141 you can create, edit, compile, and run your application
142 with Web UI quickly and easily.
143
144 ##Create a new application with Web UI installed {#create-new}
145
146 The easiest way to begin using the Web UI package
147 is to create a new application in Dart Editor.
148
149 <ol>
150 <li markdown="1">
151 In Dart Editor,
152 create a new project using **File > New Application**.
153 In the window that appears,
154 select **Generate sample content** and
155 in the list beneath it,
156 select
157 **Web application (using the web_ui library)**.
158 Call the project `webui_click_counter`.
159
160 ![Create a new application using the Web UI library](images/create-with-web-ui.p ng)
161 </li>
162
163 <li markdown="1">
164 Dart Editor creates a directory
165 and the source files for your project.
166 Dart Editor also automatically runs `pub install`
167 to resolve the package dependencies
168 and install all of the necessary packages including the Web UI package.
169
170 Finally, Dart Editor builds the project&mdash;that is,
171 it compiles the application code
172 together with the Web UI library code&mdash;
173 and puts the final version in the `out` directory.
174
175 ![Sample Web UI application](images/new-app-files.png)
176 </li>
177
178 <li markdown="1">
179 Select `webui_click_counter.html` and click the Run button
180 <img src="images/run.png" width="16" height="16" alt="Run button">.
181 The app uses the custom element and data binding
182 features from the Web UI package to
183 implement the button and display the number of clicks.
184 </li>
185
186 <li>
187 You can use this sample application as the basis for your
188 Web UI application.
189 </li>
190 </ol>
191
192 ##Install the Web UI package in an existing Web application {#install-web-ui}
193
194 If you already have an application to which you would like to add Web UI,
195 you need to set up the package dependencies
196 and install the Web UI package libraries into your project.
197 This section assumes that you have read
198 the previous target,
199 <a href="/docs/tutorials/shared-pkgs/">Install Shared Packages</a>,
200 and are familiar with the process
201 of installing packages.
202
203 <ol>
204 <li markdown="1">
205 In Dart Editor,
206 open an existing project.
207 For the example here,
208 we're using the default sample application
209 generated by Dart Editor
210 when you create a new web application
211 without Web UI support.
212 Later in this target,
213 you will modify this application to use
214 data binding&mdash;a feature necessary to web components and templates.
215
216 ![Open an existing web application](images/open-existing-app.png)
217 </li>
218
219 <li markdown="1">
220 Open the pubspec.yaml file, which is
221 in the top-level directory of your project.
222 By default,
223 Dart Editor displays the **Overview** panel,
224 which provides a handy UI for viewing and modifying the pubspec file.
225 You can use the **Source**
226 tab at the bottom of the window to view
227 the pubspec.yaml source code.
228 </li>
229
230 <li markdown="1">
231 Add the Web UI package to the list of dependencies
232 by adding the Web UI package name,
233 `web_ui`, to the list.
234 Click **Add...** in the **Overview** panel,
235 or add the package name
236 to the dependencies list directly in the pubspec.yaml source.
237 YAML is whitespace-sensitive
238 so take care to indent the package name as shown:
239
240 ![Sample pubspec file with web_ui dependency](images/sample-pubspec.png)
241
242 <aside class="alert" markdown="1">
243 <strong>Note:</strong>
244 If you include a version constraint,
245 instead of using `any`,
246 your code will be less likely to break
247 because of new releases of the package.
248 For example: `web_ui: >=0.4.1 <0.4.2`.
249 You can proactively upgrade to new versions when you are ready.
250 Check the Web UI package
251 <a href="https://github.com/dart-lang/web-ui/blob/master/CHANGELOG.md" target="_ blank">
252 CHANGELOG</a>
253 to see what version of the package
254 works with the version of the SDK you are running.
255 </aside>
256 </li>
257
258 <li markdown="1">
259 Select pubspec.yaml, and install the package by
260 choosing **Tools > Pub Install** from the menu.
261 This recursively installs the web_ui package
262 and all the packages that it depends on.
263 The diagram below shows the file hierarchy for your application
264 after the package installation:
265
266 ![The littleben application with web_ui installed](images/app-with-pkgs.png)
267 </li>
268
269 <li markdown="1">
270 In the `littleben` sample,
271 the application files are in a directory called `web`.
272 To run the app, select the main host HTML file,
273 web/littleben.html,
274 and click the Run button
275 <img src="images/run.png" width="16" height="16" alt="Run button">.
276 </li>
277 </ol>
278
279 ##Set up background compilation in Dart Editor {#set-up}
280
281 Applications that use features from the Web UI package must be compiled.
282 You can set up Dart Editor to automatically compile
283 your project when any of its files change.
284 Once you have background compilation set up,
285 your edit/refresh/test cycle within Dart Editor will be quick and easy.
286
287 <ol>
288 <li markdown="1">
289 Create a file called `build.dart` in the same directory as pubspec.yaml.
290 In this case, that's the project's top-level directory.
291 Replace the auto-generated code with the following:
292
293 {% prettify dart %}
294 import 'package:web_ui/component_build.dart';
295 import 'dart:io';
296
297 void main() {
298 build(new Options().arguments, ['web/littleben.html']);
299 }
300 {% endprettify %}
301
302 build.dart refers to the application's primary HTML file `web/littleben.html`.
303 The pathname is specified relative to the build.dart file.
304
305 ![build.dart file names the project's main HTML file](images/build-dart-file.png )
306 </li>
307
308 <li markdown="1">
309 Make sure build.dart is selected and click
310 <img src="images/run.png" width="16" height="16"
311 alt="Run button">.
312 After a beat, a directory named `out` appears under the web directory.
313
314 ![Output from build.dart](images/after-build-dart.png)
315
316 Your project is now set up for background compilation.
317 Every time Dart Editor detects that you changed a file in your project,
318 it uses the Web UI compiler
319 to compile your project and update the files in web/out.
320 Generally speaking you can ignore the files in the `web/out` directory.
321 When you run your app,
322 Dart Editor runs these files automatically.
323 </li>
324
325 <li markdown="1">
326 Run your app as you normally would:
327 select the original HTML file, web/littleben.html,
328 and click the Run button
329 <img src="images/run.png" width="16" height="16"
330 alt="Run button">.
331 Dart Editor runs the generated file in the web/out directory.
332
333 ![Running web/littleben.html](images/run-app.png)
334
335 With background compilation set up in Dart Editor,
336 you can be certain that you are always running
337 the most up-to-date version of your app.
338 </li>
339
340 <li markdown="1">
341 Edit & Refresh.
342 As you work, you continue to edit your original project files.
343 Do not modify the files in web/out because the compiler will overwrite them.
344 </li>
345 </ol>
346
347 ##Embedding data in a web page with one-way data binding {#one-way-data-binding}
348
349 The web app running below uses one-way data binding.
350 The Dart code computes the current time and
351 formats it into a String.
352 The HTML code embeds the value of that Dart String
353 into the HTML using the data binding feature provided by the Web UI package.
354 Use one-way data binding
355 when the value of the bound expression (here, a Dart string)
356 can change only in the Dart code.
357
358 <iframe class="running-app-frame"
359 style="height:100px;width:300px;"
360 src="http://dart-lang.github.io/dart-tutorials-samples/web/target06/litt leben/web/out/littleben.html">
361 </iframe>
362
363 You can find the complete source code for this sample on github at
364 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/tar get06/littleben" target="_blank">littleben</a>.
365
366 On the HTML side, the code uses a _template expression_
367 to embed the value of the String `currentTime` into the page.
368 In this example,
369 the expression is simply the name of a Dart variable
370 and it appears as part of an element's text property.
371 A template expression is specified
372 with a double pair of curly brackets,
373 which enclose the expression to be evaluated:
374 <code>&#123;&#123;expression&#125;&#125;</code>.
375 Notice that it looks like a natural part of the HTML code.
376
377 ![One-way data binding in the littleben app](images/little-ben-dart.png)
378
379 On the Dart side,
380 the String `currentTime` is marked with `@observable`.
381 This marker causes the Web UI compiler to generate
382 the code needed to keep the HTML page in sync with this variable.
383 To use `@observable`,
384 the Dart code must import the Web UI package.
385
386 {% comment %}
387 @observable marks the variable as observable.
388 If the variable points to a different object,
389 you'll know thanks to @observable.
390 However, if the internal value of the variable changes
391 (like, list contents), @observable doesn't help you.
392 You'll need to also say
393 "I want to observe list contents" with toObservable().
394 {% endcomment %}
395
396 The value of `currentTime` changes every second
397 thanks to a periodic
398 <a href="https://api.dartlang.org/dart_async/Timer.html" target="_blank">Timer</ a>
399 object.
400 When the string changes,
401 the HTML page gets updated automatically.
402
403 This sample also uses the
404 <a href="https://api.dartlang.org/dart_core/DateTime.html" target="_blank">DateT ime</a>
405 class to get the current time.
406
407 ##Binding the value of an element to a Dart variable {#two-way-data-binding}
408
409 Using the Web UI package's two-way data binding feature,
410 you can bind the value of an element,
411 typically an &lt;input&gt; element,
412 to the value of a Dart variable.
413
414 Try it! Type in the input field in the example running below.
415
416 <iframe class="running-app-frame"
417 style="height:230px;width:300px;"
418 src="http://dart-lang.github.io/dart-tutorials-samples/web/target06/shou t/web/out/shout.html">
419 </iframe>
420
421 You can find the complete source code for this sample on github at
422 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/tar get06/shout" target="_blank">shout</a>.
423
424 The value of the text field is bound to a Dart string called `shoutThis`.
425 The string is declared
426 and marked with `@observable`
427 in the Dart code.
428 The string is bound to the input field in the HTML code
429 using the `bind-value` attribute.
430 As you type, the value of the string in the Dart program changes.
431 To demonstrate the change,
432 the UI displays variations of the string using several
433 one-way bound template expressions.
434
435 This is called two-way binding because the string can be changed
436 on the HTML-side when the user types,
437 or programmatically by the Dart code
438 (although you must be careful doing this.)
439
440 ![An input field using two-way data binding](images/shoutthis.png)
441
442 To bind data to the value of an element,
443 specify the `bind-value` attribute on an element in the HTML code.
444 For example, this is the code from the shout example that
445 binds the value of the text field to the shoutThis string:
446
447 {% prettify dart %}
448 <input type="text" bind-value="shoutThis" placeholder="Shout This!">
449 {% endprettify %}
450
451 You can use `bind-value` with different kinds of input elements,
452 text areas, and select elements (drop-down lists.)
453 Also, you can use `bind-checked` with radio button elements and checkboxes.
454 And you can use `bind-selected-index` with select element.
455
456 ##About template expressions {#template-expressions}
457
458 A template expression can be any valid Dart expression
459 and is formed with double curly brackets: &#123;&#123;expression&#125;&#125;.
460 The expression is evaluated and converted to a string.
461 These are the template expressions used by the shout example:
462
463 ![Examples of valid template expressions](images/expressions.png)
464
465 | Expression | Description |
466 |---|---|
467 | &#123;&#123;shoutThis.length&#125;&#125; | Gets the length of the string. The returned value is an integer that gets converted to a string. |
468 | &#123;&#123;shoutThis.toUpperCase()&#125;&#125; | Calls a string function that converts the string to upper case letters. Note that toUpperCase() returns a ne w string; it does NOT change the value of shoutThis. |
469 | &#123;&#123;(... ? ... : ... )&#125;&#125; | Uses the conditional ternary oper ator; if the entered value is longer than 5 characters, a substring is displayed . |
470 | &#123;&#123;palindrome&#125;&#125; | Calls a top-level getter named palindrome , defined in shout.dart, that creates a palindrome from the entered value. |
471 {: .table}
472
473 ![Palindrome getter uses but does NOT modify shoutThis](images/palindrome-func.p ng)
474
475 The palindrome getter does NOT modify shoutThis.
476 If it did, it would create a situation in which an infinite loop is possible.
477 The Web UI system has a protection against infinite loops;
478 it detects if the values don't converge
479 and stops the loop after several iterations.
480 However, this is simply a protection and not a feature you should rely on.
481
482 Use caution!
483 You should use expressions that are practically side-effect free.
484
485 ##Binding event handlers
486
487 The Web UI package provides a declarative way
488 to bind Dart event handlers to UI elements.
489 Each button in the stopwatch example below
490 has an event handler for responding to mouse clicks.
491 The event handlers are bound to the button in the HTML code
492 and implemented in Dart.
493
494 Try it! Click the buttons to start, stop, and reset the stop watch.
495
496 <iframe class="running-app-frame"
497 style="height:175px;width:205px;"
498 src="http://dart-lang.github.io/dart-tutorials-samples/web/target06/stop watch/web/out/stopwatch.html">
499 </iframe>
500
501 You can find the complete source code for this sample on github at
502 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/tar get06/stopwatch" target="_blank">stopwatch</a>.
503
504 Here's the code that sets the mouse click handler for the **Start** button.
505
506 ![Set event handlers directly in HTML code](images/event-handler.png)
507
508 Event handlers are declared using attributes,
509 where the attribute name specifies the event type
510 using a hyphenated form of the Dart event name beginning with `on-`.
511 The buttons in the example specify event handlers for mouse clicks
512 using `on-click`.
513
514 Other common events
515 are double-click events (`on-double-click`)
516 and change events on input fields (`on-change`).
517 See the API docs for
518 <a href="https://api.dartlang.org/dart_html/Element.html"
519 target="_blank">Element</a>
520 for a complete list of event names.
521 {% comment %}
522 Events classes are planned to change
523 and this section will need updating.
524 {% endcomment %}
525
526 The attribute value is a Dart expression that usually
527 specifies a function call.
528 In the stopwatch example,
529 the startwatch() mouse click handler
530 is declared void and takes no arguments.
531 If the event handler needed information about the event that occurred,
532 it could accept an Event argument.
533 The event handler binding
534 in that case would be written `on-click="startwatch($event)"`.
535 The function would be declared `void startwatch(Event e)`.
536
537 ##Other resources
538
539 <ul>
540 <li> Check out
541 <a href="/docs/cookbook/">
542 <i class="icon-food"> </i> Dart Cookbook</a>.
543 You'll find several
544 <a href="/docs/cookbook/#web-ui">Web UI recipes</a>.
545 </li>
546 <li>
547 Sigmund Cherem's article,
548 <a href="/articles/dart-web-components/">Web UI Package</a>,
549 contains several interactive examples on the page
550 and the corresponding source code.
551 </li>
552 </ul>
553
554 {% endcapture %}
555
556 {% include tutorial.html %}
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698