From 4243d682a0423a63cb2f6fa74c974418e638a689 Mon Sep 17 00:00:00 2001 From: Eric Nakagawa Date: Wed, 22 Jun 2016 10:00:12 -0700 Subject: [PATCH] Docs: Basic Components Update Summary: This is an improvement to basic components docs. * I updated the basic components example code to better render components on iOS (added paddingTop). * I also modified the code to allow reader to easily copy, paste, and then run the code in their project if they followed the 'Getting Started' quick start guide. * I also added additional copy to clarify suggested usage/guidelines. Closes https://github.com/facebook/react-native/pull/8292 Differential Revision: D3469943 Pulled By: JoelMarcey fbshipit-source-id: 21ff6ee13b59741c43d80aab68a38aace0fbfca6 --- docs/Basics-Component-Image.md | 8 ++++---- docs/Basics-Component-ListView.md | 16 ++++++++------- docs/Basics-Component-Text.md | 31 +++++++++++++++++++++++++++--- docs/Basics-Component-TextInput.md | 23 +++++++++++++++------- docs/Basics-Component-View.md | 12 ++++++------ docs/Basics-Components.md | 28 +++++++++++++++++++++------ 6 files changed, 85 insertions(+), 33 deletions(-) diff --git a/docs/Basics-Component-Image.md b/docs/Basics-Component-Image.md index 262736048..eb8a2e064 100644 --- a/docs/Basics-Component-Image.md +++ b/docs/Basics-Component-Image.md @@ -7,9 +7,9 @@ permalink: docs/basics-component-image.html next: basics-component-view --- -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. +Another 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. +> An `Image` is analogous to the `` HTML tag when building websites. The simplest way to render an image is to provide a source file to that image via the `source` attribute. @@ -19,12 +19,12 @@ This example displays a checkbox `Image` on the device. import React from 'react'; import { AppRegistry, Image } from 'react-native'; -const App = () => { +const AwesomeProject = () => { return ( ); } // App registration and rendering -AppRegistry.registerComponent('MyApp', () => App); +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); ``` diff --git a/docs/Basics-Component-ListView.md b/docs/Basics-Component-ListView.md index f3eb1f08b..de5841501 100644 --- a/docs/Basics-Component-ListView.md +++ b/docs/Basics-Component-ListView.md @@ -13,27 +13,29 @@ On mobile devices, lists are a core element in many applications. The [`ListView > Unlike the more generic [`ScrollView`](/react-native/docs/basics-component-scrollview.html), the `ListView` only renders elements that are currently showing on the screen, not all the elements at once. -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. +The `ListView` component requires two properties, `dataSource` and `renderRow`. `dataSource` is the source of information for the list. `renderRow` takes one item from the source and returns a formatted component to render. -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. +This example creates a simple `ListView` of hardcoded data. It first initializes the `dataSource` that will be used to populate the `ListView`. Each item in the `dataSource` is then rendered as a `Text` component. Finally it renders the `ListView` and all `Text` components. > 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'; +import { AppRegistry, ListView, Text, View } from 'react-native'; -var SimpleList = React.createClass({ +var AwesomeList = 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']) + dataSource: ds.cloneWithRows([ + 'John', 'Joel', 'James', 'Jimmy', 'Jackson', 'Jillian', 'Julie' + ]) }; }, render: function() { return ( - + {rowData}} @@ -44,5 +46,5 @@ var SimpleList = React.createClass({ }); // App registration and rendering -AppRegistry.registerComponent('MyApp', () => SimpleList); +AppRegistry.registerComponent('AwesomeProject', () => AwesomeList); ``` diff --git a/docs/Basics-Component-Text.md b/docs/Basics-Component-Text.md index 3167375f7..208f95a72 100644 --- a/docs/Basics-Component-Text.md +++ b/docs/Basics-Component-Text.md @@ -15,12 +15,37 @@ This example displays the `string` `"Hello World!"` on the device. import React from 'react'; import { AppRegistry, Text } from 'react-native'; -const App = () => { +const AwesomeProject = () => { return ( - Hello World! + Hello World! ); } // App registration and rendering -AppRegistry.registerComponent('MyApp', () => App); +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); ``` + +In this slightly more advanced example we will display the `string` `"Hello World"` retrieved from this.state on the device and stored in the `text` variable. The value of the `text` variable is rendered by using `{text}`. + +```JavaScript +import React from 'react'; +import { AppRegistry, Text } from 'react-native'; + +var AwesomeProject = React.createClass({ + getInitialState: function() { + return {text: "Hello World"}; + }, + render: function() { + var text = this.state.text; + return ( + + {text} + + ); + } +}); + +// App registration and rendering +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); + +``` \ No newline at end of file diff --git a/docs/Basics-Component-TextInput.md b/docs/Basics-Component-TextInput.md index 9d44207af..2409055fd 100644 --- a/docs/Basics-Component-TextInput.md +++ b/docs/Basics-Component-TextInput.md @@ -9,20 +9,29 @@ next: basics-component-scrollview 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. +This example creates a simple `TextInput` box with the `string` `Type something here` as the placeholder when the `TextInput` is empty. ```JavaScript import React from 'react'; -import { AppRegistry, TextInput, View } from 'react-native'; +import { AppRegistry, Text, TextInput, View } from 'react-native'; -const App = () => { +const AwesomeProject = () => { return ( - - - + + + ); } // App registration and rendering -AppRegistry.registerComponent('MyApp', () => App); +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); ``` diff --git a/docs/Basics-Component-View.md b/docs/Basics-Component-View.md index 47e2c0530..f2bb366e3 100644 --- a/docs/Basics-Component-View.md +++ b/docs/Basics-Component-View.md @@ -9,24 +9,24 @@ next: basics-component-textinput 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. +> A `View` is analogous to using a `
` HTML tag 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. +It is recommended that you wrap your components in a `View` to style and control layout. -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): +The example below 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 = () => { +const AwesomeProject = () => { return ( - + Hello! ); } // App registration and rendering -AppRegistry.registerComponent('MyApp', () => App); +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); ``` diff --git a/docs/Basics-Components.md b/docs/Basics-Components.md index a9bd13ca1..a39d65da3 100644 --- a/docs/Basics-Components.md +++ b/docs/Basics-Components.md @@ -7,14 +7,30 @@ permalink: docs/basics-components.html next: basics-component-text --- -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. +Components are the building blocks for a React Native application. A React Native user interface (UI) is specified by declaring components, often nested. Those components are then mapped to the native UI on the targeted platform. + +####Props#### + +#####`this.props`##### + +Components can be configured by passing properties `props` to the constructor. You can access `props` from your component's methods by accessing `this.props`. You should not alter your props within component methods. + +####State#### + +#####`this.state`##### + +Components maintain their state using the state object. You can access your component state via `this.state`. Each component should manage its own state. Parent components should not manage children state and children components should not manage parent component state. + +#####`this.setState({key: value, ...})`##### + +To update or change the state of your component passing a new object representing your newly desired state to `this.setState(obj)`. The specificed keys will be merged into `this.state`. Any existing keys will be overridden by new values. ## Core Components. 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](/react-native/docs/tutorial-component-text.html) -- [Image](/react-native/docs/tutorial-component-image.html) -- [View](/react-native/docs/tutorial-component-view.html) -- [TextInput](/react-native/docs/tutorial-component-textinput.html) -- [ListView](/react-native/docs/tutorial-component-listview.html) +- [Text](/react-native/docs/basics-component-text.html) +- [Image](/react-native/docs/basics-component-image.html) +- [View](/react-native/docs/basics-component-view.html) +- [TextInput](/react-native/docs/basics-component-textinput.html) +- [ListView](/react-native/docs/basics-component-listview.html) \ No newline at end of file