OLD | NEW |
| (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 <template></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  | |
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  | |
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—that is, | |
171 it compiles the application code | |
172 together with the Web UI library code— | |
173 and puts the final version in the `out` directory. | |
174 | |
175  | |
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—a feature necessary to web components and templates. | |
215 | |
216  | |
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  | |
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  | |
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  | |
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  | |
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  | |
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>{{expression}}</code>. | |
375 Notice that it looks like a natural part of the HTML code. | |
376 | |
377  | |
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 <input> 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  | |
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: {{expression}}. | |
460 The expression is evaluated and converted to a string. | |
461 These are the template expressions used by the shout example: | |
462 | |
463  | |
464 | |
465 | Expression | Description | | |
466 |---|---| | |
467 | {{shoutThis.length}} | Gets the length of the string. The
returned value is an integer that gets converted to a string. | | |
468 | {{shoutThis.toUpperCase()}} | 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 | {{(... ? ... : ... )}} | Uses the conditional ternary oper
ator; if the entered value is longer than 5 characters, a substring is displayed
. | | |
470 | {{palindrome}} | Calls a top-level getter named palindrome
, defined in shout.dart, that creates a palindrome from the entered value. | | |
471 {: .table} | |
472 | |
473  | |
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  | |
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 %} | |
OLD | NEW |