A Simple To-Do List
- -Things to do:
- --
-
- {:width="500"} - - 6. Optionally, improve the formatting by editing `web/styles.css`, - then reload the app to check your changes. - - {% prettify css tag=pre+code %} - #output { - padding: 20px; - [!text-align: left;!] - } - {% endprettify %} - - -## 7. Use Dart DevTools to inspect the app - -Use Dart DevTools to set breakpoints, view values and types, -and step through your app's Dart code. -For setup details and a walkthrough, see -[Debugging Dart Web Apps][]. - -{{site.alert.info}} - **Feeling lost? Don't worry!** This was a whirlwind introduction to Dart and - web programming that left out many details. For a gentler approach, try a - [low-level HTML tutorial for Dart][]. -{{site.alert.end}} - - -## What next? - -Check out these resources: - -* Tutorials and codelabs for Dart - * [Tutorials](/tutorials) - * [Codelabs](/codelabs) -* Dart language, libraries, and conventions - * [Language tour](/language) - * [Core library documentation](/libraries) - * [Effective Dart](/effective-dart) -* Tools & libraries - * [Dart SDK](/tools/sdk) - * [Dart tools](/tools) - * [IDEs](/tools#ides-and-editors) - * [Web libraries and packages](/web/libraries) - -If you get stuck, find help at [Community and support.](/community) - -[DartPad documentation]: /tools/dartpad -[Dart language tour]: /language -[Dart core library documentation]: /libraries -[Dart tools]: /tools -[Debugging Dart Web Apps]: /web/debugging -[low-level HTML tutorial for Dart]: /tutorials/web/low-level-html -[overview of editors & debuggers]: /tools#ides-and-editors -[Tutorial introduction to using Dart for basic web programming]: /tutorials/web/low-level-html/connect-dart-html -[`webdev`]: /tools/webdev -[`webdev serve`]: /tools/webdev#serve diff --git a/src/tutorials/web/index.md b/src/tutorials/web/index.md deleted file mode 100644 index 585e2b430d..0000000000 --- a/src/tutorials/web/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Tutorials: web apps" -description: Tutorials for writing Dart web apps. -toc: false ---- - -{% include web-tutorials.md %} - -For more tutorials, see the [Dart tutorials page](/tutorials). diff --git a/src/tutorials/web/low-level-html/add-elements.md b/src/tutorials/web/low-level-html/add-elements.md deleted file mode 100644 index af91f5487c..0000000000 --- a/src/tutorials/web/low-level-html/add-elements.md +++ /dev/null @@ -1,527 +0,0 @@ ---- -title: Add elements to the DOM -description: Learn how to add created elements to the DOM. -js: [{url: 'https://dartpad.dev/inject_embed.dart.js', defer: true}] - -nextpage: - url: /tutorials/web/low-level-html/remove-elements - title: Remove DOM elements -prevpage: - url: /tutorials/web/low-level-html/connect-dart-html - title: Connect Dart and HTML ---- - -
- `.
- * Change the DOM by adding or removing children of elements.
- * Respond to user input with an `EventListener`.
-
-
-{{site.alert.note}}
- This page uses embedded DartPads to display runnable examples.
- {% include dartpads-embedded-troubleshooting.md %}
-{{site.alert.end}}
-
-As you learned in the previous tutorial,
-the DOM represents the structure
-of a web page document using a simple tree structure.
-Each node in the tree represents an item on the page.
-Each node in the tree keeps track of both
-its parent and its children.
-In Dart, the
-[`Node`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Node-class.html){:target="_blank" rel="noopener"}
-class contains the methods and properties
-that implement a node's tree functionality.
-
-HTML page elements are one kind of node that can be in the DOM tree.
-They have a rectangular area on the page and can receive events.
-Examples of elements include
-heading elements, paragraph elements, table elements,
-button elements, and so on.
-
-In Dart,
-elements are implemented by the
-[`Element`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Element-class.html){:target="_blank" rel="noopener"}
-class, which is a subclass of `Node`.
-Because the nodes you care about most are usually elements,
-this tutorial focuses on `Element`,
-rather than on `Node`.
-
-## Running the Todo app {#try-app}
-
-In this tutorial, you will be working with a sample web app
-that is a partial implementation of a todo list.
-This program dynamically changes the DOM,
-and therefore the web page,
-by adding elements to the DOM tree.
-
-**Try it!**
-Click **Run** to start the web app.
-Then type in the app's text field, and press return.
-The app adds an item to the list.
-Enter a few items into the input field.
-
-```dart:run-dartpad:mode-html:ga_id-running_the_todo_app:null_safety-true
-{$ begin main.dart $}
-import 'dart:html';
-
-final InputElement toDoInput = querySelector('#to-do-input') as InputElement;
-final UListElement toDoList = querySelector('#to-do-list') as UListElement;
-
-void main() {
- toDoInput.onChange.listen(addToDoItem);
-}
-
-void addToDoItem(Event e) {
- final newToDo = LIElement()..text = toDoInput.value;
- toDoInput.value = '';
- toDoList.children.add(newToDo);
-}
-{$ end main.dart $}
-{$ begin index.html $}
-What's the point?
- - * In Dart, page elements are of type `Element`. - * An `Element` knows its parent. - * An `Element` keeps its children in a `ListProcrastinator's Todo
- -
-
-
-
-
-
-{$ end index.html $}
-{$ begin styles.css $}
-body {
- font-family: 'Roboto', sans-serif;
- background-color: WhiteSmoke;
- margin: 15px;
- color: black;
-}
-
-h2 {
- color: black;
-}
-
-#to-do-input {
- font-family: 'Roboto', sans-serif;
- font-size: 14px;
- font-weight: normal;
- padding: 5px 0px 5px 5px;
- width: 100%;
- border: 1px solid Silver;
- background-color: White;
-}
-
-#to-do-list {
- padding: 0;
- margin: 0;
- list-style-position: inside;
-}
-
-#to-do-list li {
- padding: 5px 0px 5px 5px;
- border-bottom: 1px dotted Silver;
-}
-{$ end styles.css $}
-```
-
-This is the beginning of an app to manage a list of things to do.
-Right now, this app is for procrastinators only
-because the program can only add items to your to do list
-but not remove them.
-
-## About parent and child Elements in Dart {#tree-structure}
-
-The `Node` class implements the basic treeing behavior
-for nodes in the Dart DOM.
-The `Element` class is a subclass of `Node` that implements
-the behavior specific to page element nodes.
-For example,
-an element knows the width and height of
-its enclosing rectangle on the page
-and it can receive events.
-
-You can manipulate the DOM tree by adding and deleting nodes.
-However, many Dart apps are concerned only with page elements.
-So for convenience and code simplicity,
-the `Element` class implements API
-for interacting with
-a subset of the DOM that includes
-only the nodes that are elements.
-You can work with a virtual tree of elements
-rather than the more complex tree of `Node` objects.
-This tutorial shows you how to manipulate the
-DOM through the `Element` class.
-
-An `Element` object has a parent `Element`
-and maintains references to its children elements in a list.
-
--
-
-
-An `Element` object has at most one parent `Element`.
-An `Element` object's parent is final and cannot be changed.
-So you cannot move an `Element` by changing its parent.
-Get an `Element`'s parent with the getter `parent`.
-For example, if you have an `Element` with the name `anElement`
-you would refer to its parent element with `anElement.parent`.
-
-
-
-An `Element` object maintains references to its child elements in a list.
-[`List`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/List-class.html){:target="_blank" rel="noopener"}is a class in the dart:core library
-that implements an indexable collection with a length.
-A list can be of fixed size or extendable.
-
-`List` is an example of a _generic_ (or _parameterized_) type—a type
-that can declare formal type parameters.
-This means that a list can be declared
-to contain only objects of a particular type.
-For example:
-
-| List declaration | List description |
-|------------------|------------------|
-| `List
-
-You can change the tree structure by adding children to
-and removing children from an element's list of children.
-
-
-
-When you change an `Element` or its child elements in your Dart program,
-you change the DOM and therefore the web page.
-The browser re-renders the page automatically.
-
-## Setting up the page in HTML {#html-code}
-
-Let's take a look at the todo app
-to see how it dynamically
-adds an element to the DOM
-and displays a new item in the list of things to do.
-
-The HTML code for the todo app sets up the initial HTML page,
-and thereby the initial DOM tree.
-You could get the same results using Dart code,
-but it's usually better to define the primary page elements
-in HTML code (easier to read, quicker to load).
-
-
-
-The following diagram shows a partial DOM tree for the todo app.
-
-
-
-Of interest are the two-page elements that have IDs:
-`to-do-input` and `to-do-list`.
-The first identifies the `` element into which the user types.
-The second identifies the `- ` (unordered list) element
-containing the task items.
-Dart code adds elements to this list
-whenever the user enters text into the input element.
-
-## Getting an element from the DOM {#dart-code}
-
-The following diagram shows
-the Dart code for the todo app.
-
-
- ` | [`LIElement`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/LIElement-class.html){:target="_blank" rel="noopener"} |
-{: .table}
-
-## Registering an event handler {#event-handler}
-
-When a user enters text into the input field,
-a _change_ event fires,
-indicating that the value in the input field has just changed.
-The todo app defines a function, `addToDoItem()`,
-that can handle these change events.
-The following code connects `addToDoItem()` to the input field:
-
-
-
-Rather than dissect this busy line of code,
-think of it as a Dart idiom
-for adding an event handler to an `Element` object.
-
-
-
-A change event is just one of many types of events
-that an input element can generate.
-For example, you can use `click` to handle mouse clicks,
-or `keyDown` for when the user presses a key on the keyboard.
-
-## About EventListener functions {#about-event-listeners}
-
-The argument passed to the `listen()` method is a _callback function_
-of type
-[`EventListener`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/EventListener.html){:target="_blank" rel="noopener"}.
-`EventListener` is a typedef defined in the `dart:html` library as follows:
-
-```dart
-typedef void EventListener(Event event)
-```
-
-As you can see, an EventListener returns no value (`void`) and takes an
-[`Event`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Event-class.html){:target="_blank" rel="noopener"}object as an argument.
-Any function with this signature is an `EventListener`.
-Based on its signature, the `addToDoItem()` function is an `EventListener`.
-
-```dart
-void addToDoItem(Event e) { ... }
-```
-
-The `Event` object passed into an `EventListener` function
-carries information about the `Event` that occurred.
-For example, the `Event` object knows which `Element` fired the event,
-and when.
-For location-specific events such as mouse clicks,
-the `Event` object also knows where the event occurred.
-
-The `addToDoItem()` function ignores the Event object passed to it.
-
-## Adding an element to the DOM tree {#add-elem}
-
-The change event handler has the following code:
-
-
-
-The final line of code is where the DOM gets changed.
-
-An `Element` object keeps references to all of its children
-in a list called `children`.
-By adding and removing elements to and from this list,
-the code changes the DOM.
-When the DOM changes, the browser re-renders the browser page.
-The effect, in our todo app, is that a new bullet item appears
-in the to do list.
-
-## Styling the page elements {#about-css}
-
-Let's take a look at the CSS file for this app.
-
-
-
-This code uses three different kinds of CSS selectors.
-The first is an HTML element selector that matches the `` element
-and sets some basic style attributes,
-such as the background color,
-for the entire page.
-Next in the file are two ID selectors:
-`#to-do-input` controls the appearance of the input field
-and `#to-do-list` sets the appearance of the unordered list element
-in general.
-The elements in the list are controlled by the final rule,
-which uses both an ID selector and an HTML selector.
-This rule matches all ` - ` elements in the
-element with the ID `to-do-list`, thus styling
-each item in the to do list.
-
-## Moving elements within the DOM tree {#moving-elements}
-
-The Anagram app shows how to move an element within the DOM.
-
-**Try it!**
-Click **Run** to start the web app.
-Then form a word by clicking the app's letter tiles.
-
-```dart:run-dartpad:mode-html:ga_id-moving_elements_within_the_dom_tree
-{$ begin main.dart $}
-import 'dart:html';
-import 'dart:math';
-
-// Should remove tiles from here when they are selected
-// otherwise the ratio is off.
-const String scrabbleLetters =
- 'aaaaaaaaabbccddddeeeeeeeeeeeeffggghhiiiiiiiiijkllllmmnnnnnnooooooooppqrrrrrrssssttttttuuuuvvwwxyyz**';
-const Map
buttons = []; -final Element letterpile = querySelector('#letterpile') as Element; -final Element result = querySelector('#result') as Element; -final Element value = querySelector('#value') as Element; -final ButtonElement clearButton = - querySelector('#clear-button') as ButtonElement; -int wordValue = 0; - -void main() { - clearButton.onClick.listen(newLetters); - generateNewLetters(); -} - -void moveLetter(MouseEvent e) { - final letter = e.target; - if (letter is! Element) { - return; - } - if (letter.parent == letterpile) { - result.children.add(letter); - wordValue += scrabbleValues[letter.text] ?? 0; - value.text = '$wordValue'; - } else { - letterpile.children.add(letter); - wordValue -= scrabbleValues[letter.text] ?? 0; - value.text = '$wordValue'; - } -} - -void newLetters(Event e) { - letterpile.children.clear(); - result.children.clear(); - generateNewLetters(); -} - -void generateNewLetters() { - final indexGenerator = Random(); - wordValue = 0; - value.text = '0'; - buttons.clear(); - for (var i = 0; i < 7; i++) { - final letterIndex = indexGenerator.nextInt(scrabbleLetters.length); - // Should remove the letter from scrabbleLetters to keep the - // ratio correct. - final button = ButtonElement(); - button.classes.add('letter'); - button.onClick.listen(moveLetter); - button.text = scrabbleLetters[letterIndex]; - buttons.add(button); - letterpile.children.add(button); - } -} -{$ end main.dart $} -{$ begin index.html $} - Anagram
- -Pile:
---Word:
--- -Scrabble Value:
- - - -{$ end index.html $} -{$ begin styles.css $} -body { - background-color: #F8F8F8; - font-family: 'Roboto', sans-serif; - font-size: 14px; - font-weight: normal; - line-height: 1.2em; - margin: 15px; -} - -h1, h3, p { - color: black; -} - -.letter { - width: 48px; - height: 48px; - font-size: 32px; - background-color: Lavender; - color: purple; - border: 1px solid black; - margin: 2px 2px 2px 2px; -} -{$ end styles.css $} -``` - -When the program starts, -it creates one button element for each of seven -randomly selected letters. -The program adds each button to a DOM element—a simple -`` element identified by the CSS selector `letterpile`—with -a call to `letterpile.children.add()`. - -
-
-Each button element in the letter pile
-has a mouse click handler called `moveLetter()`.
-If the button is in the letter pile,
-the mouse click handler moves the button to the end of the word.
-If the button is in the word,
-the mouse click handler moves the button back to the letter pile.
-
-To move the button from the letter pile to the word or back,
-the code simply adds the button to a DOM element
-that is different from the button's current parent.
-Because an element can have only one parent,
-adding the button to a different parent
-automatically removes it from its previous parent.
-
-
-
-The `+=` operator is a compound assignment operator,
-which combines an operation (`+`) with an assignment.
-
-The `scrabbleValues` variable is a
-[`Map`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/Map-class.html){:target="_blank" rel="noopener"}—a
-data structure that contains key/value pairs.
-Use the square bracket syntax to retrieve a value by its key
-and the `length` property to get the number of pairs it contains.
-
-## What next?
-
-The next tutorial, [Remove DOM Elements](remove-elements),
-describes how to remove elements from the DOM and items off your todo list.
diff --git a/src/tutorials/web/low-level-html/connect-dart-html.md b/src/tutorials/web/low-level-html/connect-dart-html.md
deleted file mode 100644
index 90e7d30ab6..0000000000
--- a/src/tutorials/web/low-level-html/connect-dart-html.md
+++ /dev/null
@@ -1,543 +0,0 @@
----
-title: Connect Dart and HTML
-description: Learn how to set up basic scaffolding of a Dart web app.
-nextpage:
- url: /tutorials/web/low-level-html/add-elements
- title: Add elements to the DOM
----
-
-This tutorial is the first of a series on
-basic, low-level web programming with the dart:html library.
-If you use a web framework,
-some of these concepts might be useful,
-but you might not need to use the dart:html library at all.
-
--- -To write a low-level web app with Dart, -you need to understand -several topics—the DOM tree, nodes, elements, -HTML, and the Dart language and libraries. - -The interdependencies are circular, -but we have to begin somewhere, -so we begin with a simple HTML file, -which introduces the DOM tree and nodes. -From there, -you build a bare bones, stripped-down -Dart app -that contains just enough code to -dynamically put text on the page from the Dart side. - -Though simple, -this example shows you how to connect a Dart -app to an HTML page and -one way that a Dart app can interact with items on the page. -These concepts provide the foundation -for more interesting and useful web apps. - -## About the Dart, HTML, and CSS triumvirate {#source-files} - -If you've used -[DartPad]({{site.dartpad}}){:target="_blank" rel="noopener"}, -you may have already seen the Dart, HTML, and CSS tabs -that let you write the code for a web app. -Each of these three languages -is responsible for a different aspect of the web app. - -| Language | Purpose | -|----------|----------------------------------------------------------------------------------------------| -| Dart | Implements the interactivity and dynamic behavior of the web app | -| HTML | Describes the content of the web app's page (the elements in the document and the structure) | -| CSS | Governs the appearance of page elements | -{: .table} - -A Dart program can -respond to events such as mouse clicks, -manipulate the elements on a web page dynamically, -and save information. -Before the web app is deployed, -the Dart code must be compiled into JavaScript code. - -HTML is a language for describing web pages. -Using tags, HTML sets up the initial page structure, -puts elements on the page, -and embeds any scripts for page interactivity. -HTML sets up the initial document tree -and specifies element types, classes, and IDs, -which allow HTML, CSS, and Dart programs to refer to the same elements. - -CSS, which stands for _Cascading Style Sheets_, describes the appearance -of the elements within a document. -CSS controls many aspects of formatting: -type face, font size, color, background color, -borders, margins, and alignment, to name a few. - - -## About the DOM {#dom-intro} - -The Document Object Model (DOM) -represents the structure of a web document as a tree of nodes. -When an HTML file is loaded into a browser, -the browser interprets the HTML -and displays the document in a window. -The following diagram shows a simple HTML file and -the resulting web browser page in Chrome. - -What's the point?
- - * DartPad lets you write a simple Dart web app without HTML boilerplate. - * A Dart web app has Dart, HTML, and (usually) CSS code. - * Compile a web app's Dart code to JavaScript to run the app in any modern browser. - * An HTML file hosts your Dart code in a browser page. - * The DOM models a browser page in a tree/node structure. - * Use `querySelector()` with an ID to get an element from the DOM. - * CSS selectors are patterns used to select matching elements in the DOM. - * Use CSS rules to style elements. -
-
-HTML uses tags to describe the document.
-For example, the simple HTML code above
-uses the `` tag for the page title, -`<h1>` for a level-one header, -and `<p>` for a paragraph. -Some tags in the HTML code, -such as `<head>` and `<body>`, -are not visible on the web page, -but do contribute to the structure of the document. - -In the DOM, -the document object sits at the root of the tree -(it has no parent). -Different kinds of nodes in the tree -represent different kinds of objects in the document. -For example, the tree has page elements, -text nodes, and attribute nodes. -Here is the DOM tree for the simple HTML file above. - -<img class="scale-img-max" src="/assets/img/tutorials/web/simple-dom-tree.png" - alt="A Dart dynamically changing the DOM"> - -Notice that some tags, such as the `<p>` paragraph tag, -are represented by multiple nodes. -The paragraph itself is an element node. -The text within the paragraph is a text node -(and in some cases, might be a subtree containing many nodes). -And the ID is an attribute node. - -Except for the root node, each node in the tree has exactly one parent. -Each node can have many children. - -An HTML file defines the initial structure of a document. -Dart or JavaScript can dynamically modify that document -by adding, deleting, and modifying the nodes in the DOM tree. -When the DOM is changed, -the browser immediately re-renders the window. - -<img class="scale-img-max" src="/assets/img/tutorials/web/dynamic-dart.png" - alt="A Dart program can dynamically change the DOM"> - -The diagram shows a small Dart program that makes -a modest change to the DOM by dynamically -changing a paragraph's text. -A program could add and delete nodes, -or even insert an entire subtree of nodes. - - -## Create a new Dart app {#create-dart-app} - -1. Go to the [DartPad]({{site.dartpad}}){:target="_blank" rel="noopener"}. -2. Click the **New Pad** button to undo any changes you might have made - the last time you visited DartPad. -3. Click **Dart**. -4. Select **HTML** (below **Dart**), - so you can edit HTML and CSS in DartPad. - -{{site.alert.note}} - These instructions feature DartPad, - which hides some HTML boilerplate code. - If you want to use any other editor, - then we recommend starting with a small Dart web app sample - and modifying the non-script tags inside the `<body>` section. - [HTML and Dart connections](#connections) shows the full HTML code. -{{site.alert.end}} - -## Edit the HTML source code {#create-html} - -1. Click **HTML**, at the upper left of DartPad. - The view switches from Dart code to the (currently non-existent) HTML code. - -2. Add the following HTML code: - - ```html - <p id="RipVanWinkle"> - RipVanWinkle paragraph. - </p> - ``` - -3. Expand the output pane to see how a browser would render your HTML. - - -## About the HTML source code {#about-html-code} - -This HTML code is similar to the HTML code in the -various diagrams earlier in this tutorial, -but it's even simpler. - -In DartPad you need only the tags you really care about—in this case: `<p>`. -You don't need surrounding tags such as `<html>` and `<body>`. -Because DartPad knows where your Dart code is, -you don't need a `<script>` tag. - -{{site.alert.info}} - [HTML and Dart connections](#connections) shows the full HTML code - that you need to run your web app outside DartPad. -{{site.alert.end}} - -The paragraph tag has the identifier `RipVanWinkle`. -The Dart code you create in the next step uses this ID -to get the paragraph element. - - -## Edit the Dart source code {#dart-editor-happiness} - -1. Click **Dart** at the upper right of DartPad. - The view switches from HTML code to Dart code. - -2. Change the Dart code to the following: - - ```dart - import 'dart:html'; - - void main() { - querySelector('#RipVanWinkle')!.text = 'Wake up, sleepy head!'; - } - ``` - -3. Click **Run** to execute your code. - -The text in the output pane changes to "Wake up, sleepy head!" - - -## About the Dart source code {#about-dart-code} - -Let's step through the Dart code. - -### Importing libraries - -The import directive imports the specified library, -making all the classes and functions -in that library -available to your program. - -The following `import` statement imports Dart's HTML library, -which contains key classes and functions for programming the DOM: - -```dart -import 'dart:html'; -``` - -This program imports Dart's HTML library, -which contains key classes and functions for programming the DOM. -Key classes include: - -| Dart class | Description | -|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| -| <a href="{{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Node-class.html" target="_blank" rel="noopener">Node</a> | Implements a DOM node. | -| <a href="{{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Element-class.html" target="_blank" rel="noopener">Element</a> | A subclass of Node; implements a web page element. | -| <a href="{{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Document-class.html" target="_blank" rel="noopener">Document</a> | Another subclass of Node; implements the document object. | -{: .table} - -The `dart:core` library, which is automatically imported, -contains many other useful classes, such as: -[`List`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/List-class.html){:target="_blank" rel="noopener"}, -a parameterized class that can specify the type of its members. -An instance of `Element` keeps its list of child Element objects -in a `List<Element>`. - -### Using the querySelector() function - -This app's `main()` function contains a single -line of code that is a little like a run-on sentence -with multiple things happening one after another. -Let's deconstruct it. - -`querySelector()` is a top-level function provided by the `dart:html` library -that gets an `Element` object from the DOM. - -{% prettify dart tag=pre+code %} -[!querySelector!]('#RipVanWinkle')!.text = 'Wake up, sleepy head!'; -{% endprettify %} - -The argument to `querySelector()` is a string -containing a CSS selector that identifies the object. -Most commonly CSS selectors specify classes, identifiers, or attributes. -We'll look at these in more detail later, -when we add a CSS file to the mini app. -In this case, RipVanWinkle is the unique ID for a paragraph element -declared in the HTML file, -and `#RipVanWinkle` specifies that ID. - -Another useful function for getting elements from the DOM -is `querySelectorAll()`, -which returns multiple `Element` objects via -a list of elements—`List<Element>`—all -of which match the provided selector. - -### Handling nullable elements - -Because DOM elements might be missing, -the `querySelector()` function returns a nullable result, -as indicated by the `?` in the function's return type (`Element?`). -A `null` return value means that -no element matches the specified CSS selector. - -To use the `text` property of a returned `Element?`, -the type must be promoted to `Element`. -Because we wrote the HTML and know that the element is always present, -we can use the -[null assertion operator](/null-safety/understanding-null-safety#null-assertion-operator) (`!`) -when referring to the element's properties: - -{% prettify dart tag=pre+code %} -querySelector('#RipVanWinkle')[!!!].text = 'Wake up, sleepy head!'; -{% endprettify %} - -If the element with the `#RipVanWinkle` ID -isn't guaranteed to be present in the DOM, -you can instead use the conditional member access operator (`?.`) -to set `text` only if the returned element is not `null`: - -{% prettify dart tag=pre+code %} -querySelector('#RipVanWinkle')[!?!].text = 'Wake up, sleepy head!'; -{% endprettify %} - -If you plan to access the element multiple times -and know its type, -another option is to -[typecast](/language/operators#type-test-operators) -the queried element to the expected type: - -{% prettify dart tag=pre+code %} -final paragraph = querySelector('#RipVanWinkle') [!as ParagraphElement!]; -paragraph.text = 'Wake up, sleepy head!'; -{% endprettify %} - -To learn more about nullable types and null safety in general, -see [Sound null safety](/null-safety). - -### Setting the text of an Element - -In the DOM, the text of a page element is contained -in a child node, specifically, a text node. -In the following diagram, -the node containing the string -"RipVanWinkle paragraph." -is a text node. - -<img class="scale-img-max" src="/assets/img/tutorials/web/paragraph-dom.png" - alt="DOM tree for a paragraph element"> - -More complex text, -such as text with style changes or -embedded links and images, -would be represented with a subtree of text nodes and other objects. - -In Dart, -you can simply use the Element `text` property, -which has a getter and setter -that walk the subtree of nodes for you and extract or set their text: - -{% prettify dart tag=pre+code %} -querySelector('#RipVanWinkle')![!.text!] = 'Wake up, sleepy head!'; -{% endprettify %} - -However, if the text node has styles (and thus a subtree), -getting text and then setting it immediately is likely -to change the DOM, as a result of losing subtree information. -Often, as with our RipVanWinkle example, -this simplification has no adverse effects. - -The assignment operator (`=`) sets the text -of the `Element` returned by the `querySelector()` function -to the string "Wake up, sleepy head!". - -{% prettify dart tag=pre+code %} -querySelector('#RipVanWinkle')!.text [!=!] 'Wake up, sleepy head!'; -{% endprettify %} - -This causes the browser to immediately re-render -the browser page containing this app, -thus dynamically displaying the text on the browser page. - - -## HTML and Dart connections {#connections} - -The Dart web app changed -the text in the browser window dynamically at runtime. -Of course, placing text on a browser page -and doing nothing else -could be accomplished with straight HTML. -This little app only shows you how to make a connection -from a Dart app to a browser page. - -In DartPad, the only visible connection between -the Dart code and the HTML code -is the `RipVanWinkle` ID. - -<img class="scale-img-max" src="/assets/img/tutorials/web/dart-html-connect.png" - alt="The RipVanWinkle ID is used by both Dart and HTML"> - -To run your app outside DartPad, -you need to compile your Dart code to JavaScript. -Use the [`webdev build`][build] command -to compile your app to deployable JavaScript. -Then you need to make another connection between the HTML and -generated JavaScript: -you must add a `<script>` tag to the HTML -to tell the browser where to find the compiled Dart code. - -Here's the full HTML code for this app, -assuming that the Dart code is in a file named `main.dart`: - -```html -<!DOCTYPE html> - -<html> - <head> - <title>A Minimalist App - - - -- RipVanWinkle paragraph. -
- -
-
-The top-level variables are initialized using
-the `dart:html` library's top-level `querySelector()` function
-to get the interesting elements from the DOM.
-Because calling `querySelector()` isn't free,
-if a program refers to an element more than once
-it should stash a reference to the element if possible.
-
-This program stashes a reference
-to the input element
-in a top-level variable called `toDoInput`.
-The unordered list
-is in the top-level variable `toDoList`.
-
-Note the types of these variables: `InputElement` and `UListElement`.
-These are both subclasses of `Element`.
-The `dart:html` library has dozens of `Element` subclasses,
-many of which correspond to certain HTML tags.
-This program uses three:
-
-| HTML tag | Dart class |
-|-----------|-------------------------------------------------------------------------------------------------------------------------------------------|
-| `` | [`InputElement`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/InputElement-class.html){:target="_blank" rel="noopener"} |
-| `- ` | [`UListElement`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/UListElement-class.html){:target="_blank" rel="noopener"} |
-| `