Core components tutorial

Summary:
Create the initial Core Components tutorial. The core components are `Text`, `Image`, `View`, `TextInput`, `ListView`.

1. Provide a summary for each core component, including a runnable sample.
2. Allow the tutorials for each component to be extended with more details and detailed examples, particularly after we add other tutorials (i.e., around state and props).
3. The samples should be runnable in a React Native simulator, if we can get that going in the docs.
4. Reorganize the docs sidebar to make the current Tutorial actually a Sample App, etc.
Closes https://github.com/facebook/react-native/pull/7593

Differential Revision: D3313563

Pulled By: JoelMarcey

fbshipit-source-id: cfe1d397d60822b8c531405d66b4e73694c7dbf9

docs/QuickStart-GettingStarted.md

@@ -1,10 +1,10 @@
 ---
-id: getting-started
+id: quick-start-getting-started
 title: Getting Started
 layout: docs
 category: Quick Start
 permalink: docs/getting-started.html
-next: tutorial
+next: tutorial-core-components
 ---
 
 

docs/SampleApplication-F8App.md

@@ -0,0 +1,8 @@
+---
+id: sample-application-f8
+title: F8 2016 App
+layout: docs
+category: Sample Applications
+permalink: http://makeitopen.com/
+next: videos
+---

docs/SampleApplication-Movies.md

@@ -1,25 +1,20 @@
 ---
-id: tutorial
-title: Tutorial
+id: sample-application-movies
+title: Movie Fetcher
 layout: docs
-category: Quick Start
-permalink: docs/tutorial.html
-next: videos
+category: Sample Applications
+permalink: docs/sample-application-movies.html
+next: sample-application-f8
 ---
 
-## Preface
+## Overview
 
-This tutorial aims to get you up to speed with writing iOS and Android apps using React Native. If you're wondering what React Native is and why Facebook built it, this [blog post](https://code.facebook.com/posts/1014532261909640/react-native-bringing-modern-web-techniques-to-mobile/) explains that.
-
-We assume you have experience writing applications with React. If not, you can learn about it on the [React website](http://facebook.github.io/react/).
-
-### Building a real-world app
-
-This tutorial explains how to build a simple app to get you started. If you're looking for a more advanced tutorial on building a real-world app, check out [makeitopen.com](http://makeitopen.com/).
+In this tutorial we'll be building a simple version of a Movies app that fetches 25 movies that are in theaters and displays them in a `ListView`.
 
 ## Setup
 
-React Native requires the basic setup explained at [React Native Getting Started](docs/getting-started.html#content).
+> This sample application requires the basic setup explained at
+> [React Native Getting Started](docs/quick-start/getting-started.html#content).
 
 After installing these dependencies there are two simple commands to get a React Native project all set up for development.
 
@@ -27,22 +22,17 @@ After installing these dependencies there are two simple commands to get a React
 
     react-native-cli is a command line interface that does the rest of the set up. It’s installable via npm. This will install `react-native` as a command in your terminal. You only ever need to do this once.
 
-2. `react-native init AwesomeProject`
+2. `react-native init SampleAppMovies`
 
-    This command fetches the React Native source code and dependencies and then creates a new Xcode project in `AwesomeProject/iOS/AwesomeProject.xcodeproj` and a gradle project in `AwesomeProject/android/app`.
-
-
-## Overview
-
-In this tutorial we'll be building a simple version of the Movies app that fetches 25 movies that are in theaters and displays them in a ListView.
+    This command fetches the React Native source code and dependencies and then creates a new Xcode project in `SampleAppMovies/iOS/SampleAppMovies.xcodeproj` and a gradle project in `SampleAppMovies/android/app`.
 
 ### Starting the app on iOS
 
-Open this new project (`AwesomeProject/ios/AwesomeProject.xcodeproj`) in Xcode and simply build and run it with `⌘+R`. Doing so will also start a Node server which enables live code reloading. With this you can see your changes by pressing `⌘+R` in the simulator rather than recompiling in Xcode.
+Open this new project (`SampleAppMovies/ios/SampleAppMovies.xcodeproj`) in Xcode and simply build and run it with `⌘+R`. Doing so will also start a Node server which enables live code reloading. With this you can see your changes by pressing `⌘+R` in the simulator rather than recompiling in Xcode.
 
 ### Starting the app on Android
 
-In your terminal navigate into the `AwesomeProject` and run:
+In your terminal navigate into the `SampleAppMovies` and run:
 
     react-native run-android
 
@@ -50,7 +40,11 @@ This will install the generated app on your emulator or device, as well as start
 
 ### Hello World
 
-`react-native init` will generate an app with the name of your project, in this case AwesomeProject. This is a simple hello world app. For iOS, you can edit `index.ios.js` to make changes to the app and then press ⌘+R in the simulator to see the changes. For Android, you can edit `index.android.js` to make changes to the app and press `Reload JS` from the rage shake menu to see the changes.
+`react-native init` will generate an app with the name of your project, in this case `SampleAppMovies`. This is a simple hello world app. For iOS, you can edit `index.ios.js` to make changes to the app and then press ⌘+R in the simulator to see the changes. For Android, you can edit `index.android.js` to make changes to the app and press `Reload JS` from the rage shake menu to see the changes.
+
+## Actual App
+
+Now that we have initialized our React Native project, we can begin creating our Movie application.
 
 ### Mocking data
 
@@ -62,7 +56,6 @@ var MOCKED_MOVIES_DATA = [
 ];
 ```
 
-
 ### Render a movie
 
 We're going to render the title, year, and thumbnail for the movie. Since thumbnail is an Image component in React Native, add Image to the list of React imports below.
@@ -210,7 +203,7 @@ Go ahead and press `⌘+R` / `Reload JS` and you'll see the updated view.
 
 Fetching data from Rotten Tomatoes's API isn't really relevant to learning React Native so feel free to breeze through this section.
 
-Add the following constants to the top of the file (typically below the imports) to create the REQUEST_URL used to request data with.
+Add the following constants to the top of the file (typically below the imports) to create the `REQUEST_URL`s used to request data with.
 
 ```javascript
 /**
@@ -411,7 +404,7 @@ import {
 
 var REQUEST_URL = 'https://raw.githubusercontent.com/facebook/react-native/master/docs/MoviesExample.json';
 
-class AwesomeProject extends Component {
+class SampleAppMovies extends Component {
   constructor(props) {
     super(props);
     this.state = {
@@ -507,5 +500,5 @@ var styles = StyleSheet.create({
   },
 });
 
-AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject);
+AppRegistry.registerComponent('SampleAppMovies', () => SampleAppMovies);
 ```

docs/Tutorial-CoreComponents.md

@@ -0,0 +1,141 @@
+---
+id: tutorial-core-components
+title: Core Components
+layout: docs
+category: Tutorials
+permalink: docs/tutorial-core-components.html
+next: sample-application-movies
+---
+
+Components are the building blocks for a React Native application. A React Native user interface (UI) is specified by declaring components, possibly nested, and then those components are mapped to the native UI on the targeted platform.
+
+React Native has a number of core components that are commonly used in applications, either on their own or combined to build new components.
+
+## Text
+
+The most basic component in React Native is the [`Text`](/react-native/docs/text.html#content) component. The `Text` component simply renders text.
+
+This example displays the `string` `"Hello"` on the device.
+
+```JavaScript
+import React from 'react';
+import { AppRegistry, Text } from 'react-native';
+
+const App = () => {
+  return (
+    <Text>Hello World!</Text>
+  );
+}
+
+// App registration and rendering
+AppRegistry.registerComponent('MyApp', () => App);
+```
+
+## Image
+
+The other basic React Native component is the [`Image`](/react-native/docs/image.html#content) component. Like `Text`, the `Image` component simply renders an image.
+
+> An `Image` is analogous to using `img` when building websites.
+
+The simplest way to render an image is to provide a source file to that image via the `source` attribute.
+
+This example displays a checkbox `Image` on the device.
+
+```JavaScript
+import React from 'react';
+import { AppRegistry, Image } from 'react-native';
+
+const App = () => {
+  return (
+    <Image source={require('./img/check.png')} />
+  );
+}
+
+// App registration and rendering
+AppRegistry.registerComponent('MyApp', () => App);
+```
+
+## View
+
+A [`View`](/react-native/docs/view.html#content) is the most basic building block for a React Native application. The `View` is an abstraction on top of the target platform's native equivalent, such as iOS's `UIView`.
+
+> A `View` is analogous to using a `div` for building websites.
+
+While basic components such as `Text` and `Image`, can be displayed without a `View`, this is not generally recommended since the `View` gives you the control for styling and layout of those components.
+
+This example creates a `View` that aligns the `string` `Hello` in the top center of the device, something which could not be done with a `Text` component alone (i.e., a `Text` component without a `View` would place the `string` in a fixed location in the upper corner):
+
+```JavaScript
+import React from 'react';
+import { AppRegistry, Text, View } from 'react-native';
+
+const App = () => {
+  return (
+    <View style={{alignItems: 'center'}}>
+      <Text>Hello!</Text>
+    </View>
+  );
+}
+
+// App registration and rendering
+AppRegistry.registerComponent('MyApp', () => App);
+```
+
+## TextInput
+
+Direct text-based user input is a foundation for many apps. Writing a post or comment on a page is a canonical example of this. [`TextInput`](/react-native/docs/textinput.html#content) is a basic component that allows the user to enter text.
+
+This example creates a simple `TextInput` box with the `string` `Hello` as the placeholder when the `TextInput` is empty.
+
+```JavaScript
+import React, { AppRegistry, TextInput, View } from 'react-native'
+
+const App = () => {
+  return (
+      <View>
+        <TextInput placeholder="Hello" />
+      </View>
+  );
+}
+
+// App registration and rendering
+AppRegistry.registerComponent('MyApp', () => App);
+```
+
+## ListView
+
+On mobile devices, lists are a core element in many applications. The [`ListView`](/react-native/docs/listview.html#content) component is a special type of [`View`](/react-native/docs/tutorials/core-components.html#view) that displays a vertically scrolling list of changing data.
+
+The `ListView` component requires two properties, `dataSource` and `renderRow`. `dataSource` is the actual source of information that will be part of the list. `renderRow` takes the data and returns a renderable component to display.
+
+This example creates a simple `ListView` of hardcoded data. It first initializes the `datasource` that will be used to populate the `ListView`. Then it renders that `ListView` with that data.
+
+> A `rowHasChanged` function is required to use `ListView`. Here we just say a row has changed if the row we are on is not the same as the previous row.
+
+```JavaScript
+import React from 'react';
+import { AppRegistry, Text, View, ListView} from 'react-native';
+
+var SimpleList = React.createClass({
+  // Initialize the hardcoded data
+  getInitialState: function() {
+    var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2});
+    return {
+      dataSource: ds.cloneWithRows(['John', 'Joel', 'James', 'Jimmy', 'Jackson', 'Jillian', 'Julie'])
+    };
+  },
+  render: function() {
+    return (
+      <View>
+        <ListView
+          dataSource={this.state.dataSource}
+          renderRow={(rowData) => <Text>{rowData}</Text>}
+        />
+      </View>
+    );
+  }
+});
+
+// App registration and rendering
+AppRegistry.registerComponent('MyApp', () => SimpleList);
+```

website/src/react-native/css/react-native.css

@@ -670,7 +670,7 @@ h2 {
 .documentationContent blockquote {
   padding: 15px 30px 15px 15px;
   margin: 20px 0;
-  background-color: rgba(204, 122, 111, 0.1);
+  background-color: rgba(248, 245, 236, 0.1);
   border-left: 5px solid rgba(191, 87, 73, 0.2);
 }