From a0ba0baa6f2f118bcb70801648519698f8081d8c Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Thu, 23 Jun 2016 18:24:22 -0700 Subject: [PATCH 1/3] Update TextInput API Make the examples runnable (both copy/paste and with the web player) Add a bit more information in props where needed. Test Plan: http://localhost:8079/react-native/docs/textinput.html --- Libraries/Components/TextInput/TextInput.js | 213 ++++++++++++++------ 1 file changed, 147 insertions(+), 66 deletions(-) diff --git a/Libraries/Components/TextInput/TextInput.js b/Libraries/Components/TextInput/TextInput.js index 2df8d278104d51..6320a18861aada 100644 --- a/Libraries/Components/TextInput/TextInput.js +++ b/Libraries/Components/TextInput/TextInput.js @@ -57,12 +57,29 @@ type Event = Object; * such as `onSubmitEditing` and `onFocus` that can be subscribed to. A simple * example: * - * ``` - * this.setState({text})} - * value={this.state.text} - * /> + * ```ReactNativeWebPlayer + * import React, { Component } from 'react'; + * import { AppRegistry, TextInput } from 'react-native'; + * + * class UselessTextInput extends Component { + * constructor(props) { + * super(props); + * this.state = { text: 'Useless Placeholder' }; + * } + * + * render() { + * return ( + * this.setState({text})} + * value={this.state.text} + * /> + * ); + * } + * } + * + * // App registration and rendering + * AppRegistry.registerComponent('AwesomeProject', () => UselessTextInput); * ``` * * Note that some props are only available with `multiline={true/false}`. @@ -71,10 +88,58 @@ type Event = Object; * `multiline=false`. To achieve the same effect, you can wrap your `TextInput` * in a `View`: * - * ``` - * - * - * + * ```ReactNativeWebPlayer + * import React, { Component } from 'react'; + * import { AppRegistry, View, TextInput } from 'react-native'; + * + * class UselessTextInput extends Component { + * constructor(props) { + * super(props); + * this.state = { + * text: 'Useless Placeholder', + * }; + * } + * + * render() { + * return ( + * + * ); + * } + * } + * + * class UselessTextInputMultiline extends UselessTextInput { + * constructor(props) { + * super(props); + * } + * + * // If you type something in the text box that is a color, the background will change to that + * // color. + * render() { + * return ( + * + * this.setState({text})} + * value={this.state.text} + * /> + * + * ); + * } + * } + * + * // App registration and rendering + * AppRegistry.registerComponent( + * 'AwesomeProject', + * () => UselessTextInputMultiline + * ); * ``` * * `TextInput` has by default a border at the bottom of its view. This border @@ -94,12 +159,12 @@ const TextInput = React.createClass({ propTypes: { ...View.propTypes, /** - * Can tell TextInput to automatically capitalize certain characters. + * Can tell `TextInput` to automatically capitalize certain characters. * - * - characters: all characters, - * - words: first letter of each word - * - sentences: first letter of each sentence (default) - * - none: don't auto capitalize anything + * - `characters`: all characters. + * - `words`: first letter of each word. + * - `sentences`: first letter of each sentence (*default*). + * - `none`: don't auto capitalize anything. */ autoCapitalize: PropTypes.oneOf([ 'none', @@ -108,16 +173,16 @@ const TextInput = React.createClass({ 'characters', ]), /** - * If false, disables auto-correct. The default value is true. + * If `false`, disables auto-correct. The default value is `true`. */ autoCorrect: PropTypes.bool, /** - * If true, focuses the input on componentDidMount. - * The default value is false. + * If `true`, focuses the input on `componentDidMount`. + * The default value is `false`. */ autoFocus: PropTypes.bool, /** - * If false, text is not editable. The default value is true. + * If `false`, text is not editable. The default value is `true`. */ editable: PropTypes.bool, /** @@ -125,9 +190,9 @@ const TextInput = React.createClass({ * * The following values work across platforms: * - * - default - * - numeric - * - email-address + * - `default` + * - `numeric` + * - `email-address` */ keyboardType: PropTypes.oneOf([ // Cross-platform @@ -158,27 +223,33 @@ const TextInput = React.createClass({ * Determines how the return key should look. On Android you can also use * `returnKeyLabel`. * + * *Cross platform* + * * The following values work across platforms: * - * - done - * - go - * - next - * - search - * - send + * - `done` + * - `go` + * - `next` + * - `search` + * - `send` + * + * *Android Only* * * The following values work on Android only: * - * - none - * - previous + * - `none` + * - `previous` + * + * *iOS Only* * * The following values work on iOS only: * - * - default - * - emergency-call - * - google - * - join - * - route - * - yahoo + * - `default` + * - `emergency-call` + * - `google` + * - `join` + * - `route` + * - `yahoo` */ returnKeyType: PropTypes.oneOf([ // Cross-platform @@ -209,28 +280,28 @@ const TextInput = React.createClass({ */ maxLength: PropTypes.number, /** - * Sets the number of lines for a TextInput. Use it with multiline set to + * Sets the number of lines for a `TextInput`. Use it with multiline set to * true to be able to fill the lines. * @platform android */ numberOfLines: PropTypes.number, /** - * If true, the keyboard disables the return key when there is no text and - * automatically enables it when there is text. The default value is false. + * If `true`, the keyboard disables the return key when there is no text and + * automatically enables it when there is text. The default value is `false`. * @platform ios */ enablesReturnKeyAutomatically: PropTypes.bool, /** - * If true, the text input can be multiple lines. - * The default value is false. + * If `true`, the text input can be multiple lines. + * The default value is `false`. */ multiline: PropTypes.bool, /** - * Callback that is called when the text input is blurred + * Callback that is called when the text input is blurred. */ onBlur: PropTypes.func, /** - * Callback that is called when the text input is focused + * Callback that is called when the text input is focused. */ onFocus: PropTypes.func, /** @@ -247,18 +318,18 @@ const TextInput = React.createClass({ */ onEndEditing: PropTypes.func, /** - * Callback that is called when the text input selection is changed + * Callback that is called when the text input selection is changed. */ onSelectionChange: PropTypes.func, /** * Callback that is called when the text input's submit button is pressed. - * Invalid if multiline={true} is specified. + * Invalid if `multiline={true}` is specified. */ onSubmitEditing: PropTypes.func, /** * Callback that is called when a key is pressed. * Pressed key value is passed as an argument to the callback handler. - * Fires before onChange callbacks. + * Fires before `onChange` callbacks. * @platform ios */ onKeyPress: PropTypes.func, @@ -267,32 +338,42 @@ const TextInput = React.createClass({ */ onLayout: PropTypes.func, /** - * The string that will be rendered before text input has been entered + * The string that will be rendered before text input has been entered. */ placeholder: PropTypes.string, /** - * The text color of the placeholder string + * The text color of the placeholder string. */ placeholderTextColor: ColorPropType, /** - * If true, the text input obscures the text entered so that sensitive text - * like passwords stay secure. The default value is false. + * If `true`, the text input obscures the text entered so that sensitive text + * like passwords stay secure. The default value is `false`. */ secureTextEntry: PropTypes.bool, /** - * The highlight (and cursor on ios) color of the text input + * The highlight (and cursor on iOS) color of the text input. */ selectionColor: ColorPropType, /** - * See DocumentSelectionState.js, some state that is responsible for - * maintaining selection information for a document + * An instance of `DocumentSelectionState`, this is some state that is responsible for + * maintaining selection information for a document. + * + * Some functionality that can be performed with this instance is: + * + * - `blur()` + * - `focus()` + * - `update()` + * + * > You can refernce `DocumentSelectionState` in + * > `vendor/document/selection/DocumentSelectionState.js` + * * @platform ios */ selectionState: PropTypes.instanceOf(DocumentSelectionState), /** - * The value to show for the text input. TextInput is a controlled + * The value to show for the text input. `TextInput` is a controlled * component, which means the native value will be forced to match this - * value prop if provided. For most uses this works great, but in some + * value prop if provided. For most uses, this works great, but in some * cases this may cause flickering - one common cause is preventing edits * by keeping value the same. In addition to simply setting the same value, * either set `editable={false}`, or set/update `maxLength` to prevent @@ -301,12 +382,12 @@ const TextInput = React.createClass({ value: PropTypes.string, /** * Provides an initial value that will change when the user starts typing. - * Useful for simple use-cases where you don't want to deal with listening + * Useful for simple use-cases where you do not want to deal with listening * to events and updating the value prop to keep the controlled state in sync. */ defaultValue: PropTypes.string, /** - * When the clear button should appear on the right side of the text view + * When the clear button should appear on the right side of the text view. * @platform ios */ clearButtonMode: PropTypes.oneOf([ @@ -316,28 +397,28 @@ const TextInput = React.createClass({ 'always', ]), /** - * If true, clears the text field automatically when editing begins + * If `true`, clears the text field automatically when editing begins. * @platform ios */ clearTextOnFocus: PropTypes.bool, /** - * If true, all text will automatically be selected on focus + * If `true`, all text will automatically be selected on focus. */ selectTextOnFocus: PropTypes.bool, /** - * If true, the text field will blur when submitted. + * If `true`, the text field will blur when submitted. * The default value is true for single-line fields and false for - * multiline fields. Note that for multiline fields, setting blurOnSubmit - * to true means that pressing return will blur the field and trigger the - * onSubmitEditing event instead of inserting a newline into the field. + * multiline fields. Note that for multiline fields, setting `blurOnSubmit` + * to `true` means that pressing return will blur the field and trigger the + * `onSubmitEditin`g event instead of inserting a newline into the field. */ blurOnSubmit: PropTypes.bool, /** - * Styles + * [Styles](/react-native/docs/style.html) */ style: Text.propTypes.style, /** - * The color of the textInput underline. + * The color of the `TextInput` underline. * @platform android */ underlineColorAndroid: ColorPropType, @@ -357,7 +438,7 @@ const TextInput = React.createClass({ {})) : Object), /** - * Returns if the input is currently focused. + * Returns `true` if the input is currently focused; `false` otherwise. */ isFocused: function(): boolean { return TextInputState.currentlyFocusedField() === @@ -411,7 +492,7 @@ const TextInput = React.createClass({ }, /** - * Removes all text from the input. + * Removes all text from the `TextInput`. */ clear: function() { this.setNativeProps({text: ''}); From 340bdb6b14003ec9229c4cfa6026b56df72e8514 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 24 Jun 2016 10:23:02 -0700 Subject: [PATCH 2/3] Don't extend from another component, just Component --- Libraries/Components/TextInput/TextInput.js | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Libraries/Components/TextInput/TextInput.js b/Libraries/Components/TextInput/TextInput.js index 6320a18861aada..5d0477e7b2c872 100644 --- a/Libraries/Components/TextInput/TextInput.js +++ b/Libraries/Components/TextInput/TextInput.js @@ -105,14 +105,18 @@ type Event = Object; * * ); * } * } * - * class UselessTextInputMultiline extends UselessTextInput { + * class UselessTextInputMultiline extends Component { * constructor(props) { * super(props); + * this.state = { + * text: 'Useless Multiline Placeholder', + * }; * } * * // If you type something in the text box that is a color, the background will change to that From 7e7c2b5d57afe451dc5b6ede6b419819e3ac7fbd Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 24 Jun 2016 10:45:41 -0700 Subject: [PATCH 3/3] More feedback... remove constructor from example, link to DocumentSelectionState.js --- Libraries/Components/TextInput/TextInput.js | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/Libraries/Components/TextInput/TextInput.js b/Libraries/Components/TextInput/TextInput.js index 5d0477e7b2c872..505fdea088a8a6 100644 --- a/Libraries/Components/TextInput/TextInput.js +++ b/Libraries/Components/TextInput/TextInput.js @@ -93,13 +93,6 @@ type Event = Object; * import { AppRegistry, View, TextInput } from 'react-native'; * * class UselessTextInput extends Component { - * constructor(props) { - * super(props); - * this.state = { - * text: 'Useless Placeholder', - * }; - * } - * * render() { * return ( * You can refernce `DocumentSelectionState` in - * > `vendor/document/selection/DocumentSelectionState.js` + * > [`vendor/document/selection/DocumentSelectionState.js`](https://github.com/facebook/react-native/blob/master/Libraries/vendor/document/selection/DocumentSelectionState.js) * * @platform ios */