| 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 |