New Handling Touches Tutorial

Summary: Finally, a place where `Button` is properly introduced. This is based on the old Handling Touches guide, which has been simplified (with some content moved over to the scroll views tutorial). I've also updated the ordering of the guides into something that makes more sense to someone just getting started with React Native. Closes #14371 Differential Revision: D5201127 Pulled By: hramos fbshipit-source-id: 819192e2db9febb8a315f51693dae557752b6002
facebook · Jun 7, 2017 · f42f2df · f42f2df
1 parent 81c2f3b
commit f42f2df
Show file tree

Hide file tree

Showing 30 changed files with 316 additions and 104 deletions.
diff --git a/docs/Accessibility.md b/docs/Accessibility.md
@@ -5,7 +5,7 @@ layout: docs
 category: Guides
 permalink: docs/accessibility.html
 next: timers
-previous: debugging
+previous: animations
 ---
 
 ## Native App Accessibility (iOS and Android)

diff --git a/docs/AndroidBuildingFromSource.md b/docs/AndroidBuildingFromSource.md
@@ -153,11 +153,11 @@ Start by following the `Point Gradle to your Android SDK` section of this page.
 ./gradlew ReactAndroid:installArchives
 ```
 
-This will package everything that would typically be included in the `android` directory of your `node_modules/react-native/` installation in the root directory of your React Native checkout. 
+This will package everything that would typically be included in the `android` directory of your `node_modules/react-native/` installation in the root directory of your React Native checkout.
 
 ## Testing
 
-If you made changes to React Native and submit a pull request, all tests will run on your pull request automatically. To run the tests locally, see [Testing](docs/testing.html).
+If you made changes to React Native and submit a pull request, all tests will run on your pull request automatically. To run the tests locally, see [Running Tests](docs/testing.html).
 
 ## Troubleshooting
 

diff --git a/docs/Animations.md b/docs/Animations.md
@@ -4,8 +4,8 @@ title: Animations
 layout: docs
 category: Guides
 permalink: docs/animations.html
-next: navigation
-previous: handling-touches
+next: accessibility
+previous: images
 ---
 
 Animations are very important to create a great user experience.

diff --git a/docs/BuildingForAppleTV.md b/docs/BuildingForAppleTV.md
@@ -2,7 +2,7 @@
 id: building-for-apple-tv
 title: Building For Apple TV
 layout: docs
-category: Guides (Apple TV)
+category: Guides (iOS)
 permalink: docs/building-for-apple-tv.html
 banner: ejected
 next: native-modules-android
@@ -84,12 +84,10 @@ class Game2048 extends React.Component {
 
 ```
 
-- *TV remote animations*: `RCTTVView` native code implements Apple-recommended parallax animations to help guide the eye as the user navigates through views.  The animations can be disabled or adjusted with new optional view properties. 
+- *TV remote animations*: `RCTTVView` native code implements Apple-recommended parallax animations to help guide the eye as the user navigates through views.  The animations can be disabled or adjusted with new optional view properties.
 
 - *Back navigation with the TV remote menu button*: The `BackHandler` component, originally written to support the Android back button, now also supports back navigation on the Apple TV using the menu button on the TV remote.
 
 - *Known issues*:
 
   - [ListView scrolling](https://github.com/facebook/react-native/issues/12793).  The issue can be easily worked around by setting `removeClippedSubviews` to false in ListView and similar components.  For more discussion of this issue, see [this PR](https://github.com/facebook/react-native/pull/12944).
-
-
diff --git a/docs/Colors.md b/docs/Colors.md
@@ -1,11 +1,11 @@
 ---
 id: colors
-title: Colors
+title: Color Reference
 layout: docs
 category: Guides
 permalink: docs/colors.html
-next: platform-specific-code
-previous: images
+next: integration-with-existing-apps
+previous: direct-manipulation
 ---
 
 Components in React Native are [styled using JavaScript](docs/style.html). Color properties usually match how [CSS works on the web](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).

diff --git a/docs/Debugging.md b/docs/Debugging.md
@@ -4,8 +4,8 @@ title: Debugging
 layout: docs
 category: Guides
 permalink: docs/debugging.html
-next: accessibility
-previous: platform-specific-code
+next: performance
+previous: timers
 ---
 
 ## Enabling Keyboard Shortcuts

diff --git a/docs/DirectManipulation.md b/docs/DirectManipulation.md
@@ -4,7 +4,7 @@ title: Direct Manipulation
 layout: docs
 category: Guides
 permalink: docs/direct-manipulation.html
-next: performance
+next: colors
 previous: javascript-environment
 ---
 
@@ -267,4 +267,3 @@ Requests focus for the given input or view. The exact behavior triggered will de
 ### blur()
 
 Removes focus from an input or view. This is the opposite of `focus()`.
-
diff --git a/docs/GestureResponderSystem.md b/docs/GestureResponderSystem.md
@@ -4,7 +4,7 @@ title: Gesture Responder System
 layout: docs
 category: Guides
 permalink: docs/gesture-responder-system.html
-next: testing
+next: javascript-environment
 previous: performance
 ---
 

diff --git a/docs/HandlingTextInput.md b/docs/HandlingTextInput.md
@@ -4,7 +4,7 @@ title: Handling Text Input
 layout: docs
 category: The Basics
 permalink: docs/handling-text-input.html
-next: using-a-scrollview
+next: handling-touches
 previous: flexbox
 ---
 

diff --git a/docs/HandlingTouches.md b/docs/HandlingTouches.md
@@ -2,41 +2,97 @@
 id: handling-touches
 title: Handling Touches
 layout: docs
-category: Guides
+category: The Basics
 permalink: docs/handling-touches.html
-next: animations
-previous: components
+next: using-a-scrollview
+previous: handling-text-input
 ---
 
-Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map.
+Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive [gesture responder system](docs/gesture-responder-system.html) to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.
 
-React Native provides components to handle common gestures, such as taps and swipes, as well as a comprehensive [gesture responder system](docs/gesture-responder-system.html) to allow for more advanced gesture recognition.
+## Displaying a basic button
 
-## Tappable Components
+[Button](docs/button.html) provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:
 
-You can use "Touchable" components when you want to capture a tapping gesture. They take a function through the `onPress` props which will be called when the touch begins and ends within the bounds of the component.
+```javascript
+<Button
+  onPress={() => { Alert.alert('You tapped the button!')}}
+  title="Press Me"
+/>
+```
 
-Example:
+This will render a blue label on iOS, and a blue rounded rectangle with white text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.
 
-```javascript
-class MyButton extends Component {
+![](img/Button.png)
+
+Go ahead and play around with the `Button` component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.
+
+```SnackPlayer?name=Button%20Basics
+import React, { Component } from 'react';
+import { Alert, AppRegistry, Button, StyleSheet, View } from 'react-native';
+
+export default class ButtonBasics extends Component {
   _onPressButton() {
-    console.log("You tapped the button!");
+    Alert.alert('You tapped the button!')
   }
 
   render() {
     return (
-      <TouchableHighlight onPress={this._onPressButton}>
-        <Text>Button</Text>
-      </TouchableHighlight>
+      <View style={styles.container}>
+        <View style={styles.buttonContainer}>
+          <Button
+            onPress={this._onPressButton}
+            title="Press Me"
+          />
+        </View>
+        <View style={styles.buttonContainer}>
+          <Button
+            onPress={this._onPressButton}
+            title="Press Me"
+            color="#841584"
+          />
+        </View>
+        <View style={styles.alternativeLayoutButtonContainer}>
+          <Button
+            onPress={this._onPressButton}
+            title="This looks great!"
+          />
+          <Button
+            onPress={this._onPressButton}
+            title="OK!"
+            color="#841584"
+          />
+        </View>
+      </View>
     );
   }
 }
+
+const styles = StyleSheet.create({
+  container: {
+   flex: 1,
+   justifyContent: 'center',
+  },
+  buttonContainer: {
+    margin: 20
+  },
+  alternativeLayoutButtonContainer: {
+    margin: 20,
+    flexDirection: 'row',
+    justifyContent: 'space-between'
+  }
+})
+
+// skip this line if using Create React Native App
+AppRegistry.registerComponent('AwesomeProject', () => ButtonBasics);
 ```
 
-Tappable components should provide feedback that show the user what is handling their touch, and what will happen when they lift their finger. The user should also be able to cancel a tap by dragging their finger away.
 
-Which component you use will depend on what kind of feedback you want to provide:
+## Touchables
+
+If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.
+
+Which "Touchable" component you use will depend on what kind of feedback you want to provide:
 
 - Generally, you can use [**TouchableHighlight**](docs/touchablehighlight.html) anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.
 
@@ -46,22 +102,82 @@ Which component you use will depend on what kind of feedback you want to provide
 
 - If you need to handle a tap gesture but you don't want any feedback to be displayed, use [**TouchableWithoutFeedback**](docs/touchablewithoutfeedback.html).
 
-### Long presses
+In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the `onLongPress` props of any of the "Touchable" components.
 
-In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the `onLongPress` props of any of the touchable components listed above.
+Let's see all of these in action:
 
-## Scrolling lists and swiping views
+```SnackPlayer?platform=android&name=Touchables
+import React, { Component } from 'react';
+import { Alert, AppRegistry, Platform, StyleSheet, Text, TouchableHighlight, TouchableOpacity, TouchableNativeFeedback, TouchableWithoutFeedback, View } from 'react-native';
 
-A common pattern to many mobile apps is the scrollable list of items. Users interact with these using panning or swiping gestures. The [ScrollView](docs/using-a-scrollview.html) component displays a list of items that can be scrolled using these gestures.
+export default class Touchables extends Component {
+  _onPressButton() {
+    Alert.alert('You tapped the button!')
+  }
 
-ScrollViews can scroll vertically or horizontally, and can be configured to allow paging through views using swiping gestures by using the `pagingEnabled` props. Swiping horizontally between views can also be implemented on Android using the [ViewPagerAndroid](docs/viewpagerandroid.html) component.
+  _onLongPressButton() {
+    Alert.alert('You long-pressed the button!')
+  }
 
-A [FlatList](docs/using-a-listview.html) is a special kind of ScrollView that is best suited for displaying long vertical lists of items. If you want to display section headers and footers, similar to `UITableView`s on iOS, then [SectionList](docs/using-a-listview.html) is the way to go.
 
-### Pinch-to-zoom
+  render() {
+    return (
+      <View style={styles.container}>
+        <TouchableHighlight onPress={this._onPressButton} underlayColor="white">
+          <View style={styles.button}>
+            <Text style={styles.buttonText}>TouchableHighlight</Text>
+          </View>
+        </TouchableHighlight>
+        <TouchableOpacity onPress={this._onPressButton}>
+          <View style={styles.button}>
+            <Text style={styles.buttonText}>TouchableOpacity</Text>
+          </View>
+        </TouchableOpacity>
+        <TouchableNativeFeedback
+            onPress={this._onPressButton}
+            background={Platform.OS === 'android' ? TouchableNativeFeedback.SelectableBackground() : ''}>
+          <View style={styles.button}>
+            <Text style={styles.buttonText}>TouchableNativeFeedback</Text>
+          </View>
+        </TouchableNativeFeedback>
+        <TouchableWithoutFeedback
+            onPress={this._onPressButton}
+            >
+          <View style={styles.button}>
+            <Text style={styles.buttonText}>TouchableWithoutFeedback</Text>
+          </View>
+        </TouchableWithoutFeedback>
+        <TouchableHighlight onPress={this._onPressButton} onLongPress={this._onLongPressButton} underlayColor="white">
+          <View style={styles.button}>
+            <Text style={styles.buttonText}>Touchable with Long Press</Text>
+          </View>
+        </TouchableHighlight>
+      </View>
+    );
+  }
+}
 
-A ScrollView with a single item can be used to allow the user to zoom content. Set up the `maximumZoomScale` and `minimumZoomScale` props and your user will be able to use pinch and expand gestures to zoom in and out.
+const styles = StyleSheet.create({
+  container: {
+    paddingTop: 60,
+    alignItems: 'center'
+  },
+  button: {
+    marginBottom: 30,
+    width: 260,
+    alignItems: 'center',
+    backgroundColor: '#2196F3'
+  },
+  buttonText: {
+    padding: 20,
+    color: 'white'
+  }
+})
+
+// skip this line if using Create React Native App
+AppRegistry.registerComponent('AwesomeProject', () => Touchables);
+```
 
-## Handling additional gestures
+## Scrolling lists, swiping pages, and pinch-to-zoom
 
-If you want to allow a user to drag a view around the screen, or you want to implement your own custom pan/drag gesture, take a look at the [PanResponder](docs/panresponder.html) API or the [gesture responder system docs](docs/gesture-responder-system.html).
+Another gesture commonly used in mobile apps is the swipe or pan. This gesture allows the user to scroll through a list of items, or swipe through pages of content. In order to handle these and other gestures, we'll learn [how to use a ScrollView](docs/using-a-scrollview.html) next.
diff --git a/docs/Images.md b/docs/Images.md
@@ -4,7 +4,7 @@ title: Images
 layout: docs
 category: Guides
 permalink: docs/images.html
-next:  colors
+next:  animations
 previous: navigation
 ---
 
@@ -96,9 +96,9 @@ Many of the images you will display in your app will not be available at compile
 ```
 
 ### Network Requests for Images
-  
+
   If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:
-  
+
   ```javascript
   <Image source={{
       uri: 'https://facebook.github.io/react/img/logo_og.png',

diff --git a/docs/IntegrationWithExistingApps.md b/docs/IntegrationWithExistingApps.md
@@ -6,7 +6,7 @@ category: Guides
 permalink: docs/integration-with-existing-apps.html
 banner: ejected
 next: running-on-device
-previous: testing
+previous: colors
 ---
 
 <style>

diff --git a/docs/JavaScriptEnvironment.md b/docs/JavaScriptEnvironment.md
@@ -5,7 +5,7 @@ layout: docs
 category: Guides
 permalink: docs/javascript-environment.html
 next: direct-manipulation
-previous: timers
+previous: gesture-responder-system
 ---
 
 ## JavaScript Runtime

diff --git a/docs/MoreResources.md b/docs/MoreResources.md
@@ -4,8 +4,8 @@ title: More Resources
 layout: docs
 category: The Basics
 permalink: docs/more-resources.html
-next: components
-previous: networking
+next: platform-specific-code
+previous: network
 ---
 
 If you just read through this website, you should be able to build a pretty cool React Native app. But React Native isn't just a product made by one company - it's a community of thousands of developers. So if you're interested in React Native, here's some related stuff you might want to check out.
@@ -34,8 +34,6 @@ The folks who built the app for Facebook's F8 conference in 2016 also [open-sour
 
 [Expo](https://docs.expo.io) is a development environment plus application that focuses on letting you build React Native apps in the Expo development environment, without ever touching Xcode or Android Studio. If you wish React Native was even more JavaScripty and webby, check out Expo.
 
-[Deco](https://www.decoide.org) is an all-in-one development environment specifically designed for React Native. It can automatically set up a new project, search for open source components, and insert them. You can also tweak your app graphically in real time. Check it out if you use macOS.
-
 ## Where React Native People Hang Out
 
 The [React Native Community](https://www.facebook.com/groups/react.native.community) Facebook group has thousands of developers, and it's pretty active. Come there to show off your project, or ask how other people solved similar problems.
@@ -46,4 +44,4 @@ The [React Twitter account](https://twitter.com/reactjs) covers both React and R
 
 There are a lot of [React Native Meetups](http://www.meetup.com/topics/react-native/) that happen around the world. Often there is React Native content in React meetups as well.
 
-Sometimes we have React conferences. We posted the [videos from React.js Conf 2016](https://www.youtube.com/playlist?list=PLb0IAmt7-GS0M8Q95RIc2lOM6nc77q1IY), and we'll probably have more conferences in the future, too. Stay tuned.
+Sometimes we have React conferences. We posted the [videos from React.js Conf 2017](https://www.youtube.com/playlist?list=PLb0IAmt7-GS3fZ46IGFirdqKTIxlws7e0) and [React.js Conf 2016](https://www.youtube.com/playlist?list=PLb0IAmt7-GS0M8Q95RIc2lOM6nc77q1IY), and we'll probably have more conferences in the future, too. Stay tuned. You can also find a list of dedicated React Native conferences [here](http://www.awesome-react-native.com/#conferences).
diff --git a/docs/NativeModulesAndroid.md b/docs/NativeModulesAndroid.md
@@ -6,7 +6,7 @@ category: Guides (Android)
 permalink: docs/native-modules-android.html
 banner: ejected
 next: native-components-android
-previous: communication-ios
+previous: building-for-apple-tv
 ---
 
 Sometimes an app needs access to a platform API that React Native doesn't have a corresponding module for yet. Maybe you want to reuse some existing Java code without having to reimplement it in JavaScript, or write some high performance, multi-threaded code such as for image processing, a database, or any number of advanced extensions.