From 4d575e709023727db49bd5d7249299e91bc90a5b Mon Sep 17 00:00:00 2001 From: Jackie Lang Date: Fri, 22 Jun 2018 12:04:09 -0700 Subject: [PATCH] Improve tutorial.md's clarity and structure (#649) * Improve tutorial.md's clarity and structure * Fix typos and make additional changes to tutorial.md * edits * moar changes --- content/tutorial/nav.yml | 75 ++++--- content/tutorial/tutorial.md | 393 ++++++++++++++++++++--------------- 2 files changed, 277 insertions(+), 191 deletions(-) diff --git a/content/tutorial/nav.yml b/content/tutorial/nav.yml index adc5cf3a..a679ee9d 100644 --- a/content/tutorial/nav.yml +++ b/content/tutorial/nav.yml @@ -1,21 +1,30 @@ - title: Tutorial items: - - id: before-we-start - title: Before We Start - href: /tutorial/tutorial.html#before-we-start + - id: before-we-start-the-tutorial + title: Before We Start the Tutorial + href: /tutorial/tutorial.html#before-we-start-the-tutorial forceInternal: true subitems: - id: what-were-building - title: What We're Building - href: /tutorial/tutorial.html#what-were-building + title: What Are We Building? + href: /tutorial/tutorial.html#what-are-we-building forceInternal: true - id: prerequisites title: Prerequisites href: /tutorial/tutorial.html#prerequisites forceInternal: true - - id: how-to-follow-along - title: How to Follow Along - href: /tutorial/tutorial.html#how-to-follow-along + - id: setup-for-the-tutorial + title: Setup for the Tutorial + href: /tutorial/tutorial.html#setup-for-the-tutorial + forceInternal: true + subitems: + - id: setup-option-1-write-code-in-the-browser + title: "Option 1: Write Code in the Browser" + href: /tutorial/tutorial.html#setup-option-1-write-code-in-the-browser + forceInternal: true + - id: setup-option-2-local-development-environment + title: "Option 2: Local Development Environment" + href: /tutorial/tutorial.html#setup-option-2-local-development-environment forceInternal: true - id: help-im-stuck title: Help, I'm Stuck! @@ -27,30 +36,34 @@ forceInternal: true subitems: - id: what-is-react - title: What is React? + title: What Is React? href: /tutorial/tutorial.html#what-is-react forceInternal: true - - id: getting-started - title: Getting Started - href: /tutorial/tutorial.html#getting-started + - id: inspecting-the-starter-code + title: Inspecting the Starter Code + href: /tutorial/tutorial.html#inspecting-the-starter-code forceInternal: true - id: passing-data-through-props title: Passing Data Through Props href: /tutorial/tutorial.html#passing-data-through-props forceInternal: true - - id: an-interactive-component - title: An Interactive Component - href: /tutorial/tutorial.html#an-interactive-component + - id: making-an-interactive-component + title: Making an Interactive Component + href: /tutorial/tutorial.html#making-an-interactive-component forceInternal: true - id: developer-tools title: Developer Tools href: /tutorial/tutorial.html#developer-tools forceInternal: true - - id: lifting-state-up - title: Lifting State Up - href: /tutorial/tutorial.html#lifting-state-up + - id: completing-the-game + title: Completing the Game + href: /tutorial/tutorial.html#completing-the-game forceInternal: true subitems: + - id: lifting-state-up + title: Lifting State Up + href: /tutorial/tutorial.html#lifting-state-up + forceInternal: true - id: why-immutability-is-important title: Why Immutability Is Important href: /tutorial/tutorial.html#why-immutability-is-important @@ -67,18 +80,26 @@ title: Declaring a Winner href: /tutorial/tutorial.html#declaring-a-winner forceInternal: true - - id: storing-a-history - title: Storing A History - href: /tutorial/tutorial.html#storing-a-history + - id: adding-time-travel + title: Adding Time Travel + href: /tutorial/tutorial.html#adding-time-travel forceInternal: true subitems: - - id: showing-the-moves - title: Showing the Moves - href: /tutorial/tutorial.html#showing-the-moves + - id: storing-a-history-of-moves + title: Storing a History of Moves + href: /tutorial/tutorial.html#storing-a-history-of-moves + forceInternal: true + - id: lifting-state-up-again + title: Lifting State Up, Again + href: /tutorial/tutorial.html#lifting-state-up-again + forceInternal: true + - id: showing-the-past-moves + title: Showing the Past Moves + href: /tutorial/tutorial.html#showing-the-past-moves forceInternal: true - - id: keys - title: Keys - href: /tutorial/tutorial.html#keys + - id: picking-a-key + title: Picking a Key + href: /tutorial/tutorial.html#picking-a-key forceInternal: true - id: implementing-time-travel title: Implementing Time Travel diff --git a/content/tutorial/tutorial.md b/content/tutorial/tutorial.md index 63ecdf36..ebe79590 100644 --- a/content/tutorial/tutorial.md +++ b/content/tutorial/tutorial.md @@ -12,45 +12,41 @@ redirect_from: - "docs/tutorial-zh-CN.html" --- -## Before We Start +## Before We Start the Tutorial -### What We're Building +### What Are We Building? -Today, we're going to build an interactive tic-tac-toe game. +In this tutorial, we'll show how to build an interactive tic-tac-toe game with React. -If you like, you can check out the final result here: [Final Result](https://codepen.io/gaearon/pen/gWWZgR?editors=0010). Don't worry if the code doesn't make sense to you yet, or if it uses an unfamiliar syntax. We will be learning how to build this game step by step throughout this tutorial. +You can see what we'll be building here: [Final Result](https://codepen.io/gaearon/pen/gWWZgR?editors=0010). If the code doesn't make sense to you, or if you are unfamiliar with the code's syntax, don't worry! The goal of this tutorial is to help you understand React and its syntax. -Try playing the game. You can also click on a button in the move list to go "back in time" and see what the board looked like just after that move was made. +We recommend that you check out the tic-tac-toe game before continuing with the tutorial. One of the features that you'll notice is that there is a numbered list to the right of the game's board. This list gives you a history of all of the moves that have occurred in the game, and is updated as the game progresses. -Once you get a little familiar with the game, feel free to close that tab, as we'll start from a simpler template in the next sections. +You can close the tic-tac-toe game once you're familiar with it. We'll be starting from a simpler template in this tutorial. Our next step is to set you up so that you can start building the game. ### Prerequisites -We'll assume some familiarity with HTML and JavaScript, but you should be able to follow along even if you haven't used them before. +We'll assume that you have some familiarity with HTML and JavaScript, but you should be able to follow along even if you're coming from a different programming language. We'll also assume that you're familiar with programming concepts like functions, objects, arrays, and to a lesser extent, classes. -If you need a refresher on JavaScript, we recommend reading [this guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript). Note that we're also using some features from ES6, a recent version of JavaScript. In this tutorial, we're using [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), [classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let), and [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) statements. You can use the [Babel REPL](babel://es5-syntax-example) to check what ES6 code compiles to. +If you need to review JavaScript, we recommend reading [this guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript). Note that we're also using some features from ES6 -- a recent version of JavaScript. In this tutorial, we're using [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), [classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let), and [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) statements. You can use the [Babel REPL](babel://es5-syntax-example) to check what ES6 code compiles to. -### How to Follow Along +## Setup for the Tutorial -There are two ways to complete this tutorial: you could either write the code right in the browser, or you could set up a local development environment on your machine. You can choose either option depending on what you feel comfortable with. +There are two ways to complete this tutorial: you can either write the code in your browser, or you can set up a local development environment on your computer. -#### If You Prefer to Write Code in the Browser +### Setup Option 1: Write Code in the Browser This is the quickest way to get started! -First, open this [starter code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010) in a new tab. It should display an empty tic-tac-toe field. We will be editing that code during this tutorial. +First, open this [starter code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010) in a new tab. The new tab should display an empty tic-tac-toe game board and React code. We will be editing the React code in this tutorial. -You can now skip the next section about setting up a local development environment and head straight to the [overview](#overview). +You can now skip the second setup option, and go to the [Overview](#overview) section to get an overview of React. -#### If You Prefer to Write Code in Your Editor +### Setup Option 2: Local Development Environment -Alternatively, you can set up a project on your computer. +**This is completely optional and not required for this tutorial!** -Note: **this is completely optional and not required for this tutorial!** - -This is more work, but lets you work from the comfort of your editor. - -If you want to do it, here are the steps to follow: +This setup requires more work but allows you to complete the tutorial using an editor of your choice. Here are the steps to follow: 1. Make sure you have a recent version of [Node.js](https://nodejs.org/en/) installed. 2. Follow the [installation instructions](/docs/add-react-to-a-new-app.html) to create a new project. @@ -85,15 +81,15 @@ We recommend following [these instructions](http://babeljs.io/docs/editors) to c ### Help, I'm Stuck! -If you get stuck, check out the [community support resources](/community/support.html). In particular, [Reactiflux chat](/community/support.html#reactiflux-chat) is a great way to get quick help. If you don't get a good answer anywhere, please file an issue, and we'll help you out. - -With this out of the way, let's get started! +If you get stuck, check out the [community support resources](/community/support.html). In particular, [Reactiflux Chat](/community/support.html#reactiflux-chat) is a great way to get help quickly. If you don't receive an answer, or if you remain stuck, please file an issue, and we'll help you out. ## Overview -### What is React? +Now that you're set up, let's get an overview of React! -React is a declarative, efficient, and flexible JavaScript library for building user interfaces. +### What Is React? + +React is a declarative, efficient, and flexible JavaScript library for building user interfaces. It lets you compose complex UIs from small and isolated pieces of code called "components". React has a few different kinds of components, but we'll start with `React.Component` subclasses: @@ -116,11 +112,11 @@ class ShoppingList extends React.Component { // Example usage: ``` -We'll get to the funny XML-like tags in a second. Your components tell React what you want to render – then React will efficiently update and render just the right components when your data changes. +We'll get to the funny XML-like tags soon. We use components to tell React what we want to see on the screen. When our data changes, React will efficiently update and re-render our components. -Here, ShoppingList is a **React component class**, or **React component type**. A component takes in parameters, called `props`, and returns a hierarchy of views to display via the `render` method. +Here, ShoppingList is a **React component class**, or **React component type**. A component takes in parameters, called `props` (short for "properties"), and returns a hierarchy of views to display via the `render` method. -The `render` method returns a *description* of what you want to render, and then React takes that description and renders it to the screen. In particular, `render` returns a **React element**, which is a lightweight description of what to render. Most React developers use a special syntax called JSX which makes it easier to write these structures. The `
` syntax is transformed at build time to `React.createElement('div')`. The example above is equivalent to: +The `render` method returns a *description* of what you want to see on the screen. React takes the description and displays the result. In particular, `render` returns a **React element**, which is a lightweight description of what to render. Most React developers use a special syntax called "JSX" which makes these structures easier to write. The `
` syntax is transformed at build time to `React.createElement('div')`. The example above is equivalent to: ```javascript return React.createElement('div', {className: 'shopping-list'}, @@ -131,31 +127,33 @@ return React.createElement('div', {className: 'shopping-list'}, [See full expanded version.](babel://tutorial-expanded-version) -If you're curious, `createElement()` is described in more detail in the [API reference](/docs/react-api.html#createelement), but we won't be using it directly in this tutorial. Instead, we will keep using JSX. +If you're curious, `createElement()` is described in more detail in the [API reference](/docs/react-api.html#createelement), but we won't be using it in this tutorial. Instead, we will keep using JSX. + +JSX comes with the full power of JavaScript. You can put *any* JavaScript expressions within braces inside JSX. Each React element is a JavaScript object that you can store in a variable or pass around in your program. -You can put any JavaScript expression within braces inside JSX. Each React element is a real JavaScript object that you can store in a variable or pass around your program. +The `ShoppingList` component above only renders built-in DOM components like `
` and `
  • `. But you can compose and render custom React components too. For example, we can now refer to the whole shopping list by writing ``. Each React component is encapsulated and can operate independently; this allows you to build complex UIs from simple components. -The `ShoppingList` component only renders built-in DOM components, but you can compose custom React components just as easily, by writing ``. Each component is encapsulated so it can operate independently, which allows you to build complex UIs out of simple components. +## Inspecting the Starter Code -### Getting Started +**If you're going to work on the tutorial in your browser,** open this code in a new tab: [Starter Code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010). -Start with this example: [Starter Code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010). +**If you're going to work on the tutorial locally,** open `src/index.js` in your project folder (you have already touched this file during the [setup](#setup-option-2-local-development-environment)). -It contains the shell of what we're building today. We've provided the styles so you only need to worry about the JavaScript. +This Starter Code is the base of what we're building. We've provided the CSS styling so that you only need focus on learning React and programming the tic-tac-toe game. -In particular, we have three components: +By inspecting the code, you'll notice that we have three React components: * Square * Board * Game -The Square component renders a single ` ); @@ -259,21 +270,21 @@ class Square extends React.Component { } ``` -Whenever `this.setState` is called, an update to the component is scheduled, causing React to merge in the passed state update and rerender the component along with its descendants. When the component rerenders, `this.state.value` will be `'X'` so you'll see an X in the grid. +By calling `this.setState` from an `onClick` handler in the Square's `render` method, we tell React to re-render that Square whenever its ` ); @@ -399,17 +421,19 @@ class Square extends React.Component { } ``` -Now when the square is clicked, it calls the `onClick` function that was passed by Board. Let's recap what happens here: +When a Square is clicked, the `onClick` function provided by the Board is called. Here's a review of how this is achieved: 1. The `onClick` prop on the built-in DOM `