Add FAQ pages #43

alexkrolick · 2017-10-07T02:38:00Z

Adds an FAQ page addressing some of the ideas from #29

Comments welcome!

Port of [website] Add FAQ pages to docs facebook/react#11001 (comment) to new repo
Closes Add an official React FAQ to the docs #29
Covers request for AJAX guide in New guides wanted #83
Covers Document how to pass args to event handlers #75 although the main guide should probably also have information on event handling

reactjs-bot · 2017-10-07T02:40:43Z

Deploy preview ready!

Built with commit 2b4b34a

https://deploy-preview-43--reactjs.netlify.com

bvaughn · 2017-10-07T04:28:00Z

cc @markerikson

JasonEtco · 2017-10-09T05:52:05Z

content/docs/faq-ajax.md

+
+### How can I make an AJAX call?
+
+You can use an AJAX library you like with React. Some popular ones are [Axios](https://github.com/axios/axios), [jQuery AJAX](https://api.jquery.com/jQuery.ajax/), and the browser built-in [window.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).


There's a typo in the first few words here, should read:

You can use any

JasonEtco · 2017-10-09T05:54:14Z

content/docs/faq-build.md

+### How can I write comments in JSX?
+
+```
+ {*/ Comment goes here */}


I believe that the */ is mixed up at the beginning here, it should be:

{/* Comment goes here */}

JasonEtco · 2017-10-09T05:55:40Z

content/docs/faq-functions.md

+
+```jsx
+render() {
+  {*/ handleClick is called instead of passed as a reference! */}


This should probably be:

{/* handleClick is called instead of passed as a reference! */}

Thanks for the review, fixed these typos.

bvaughn · 2017-10-10T21:57:39Z

I could review this but I'd love for @markerikson to take a first pass if he's willing 😄

kaycebasques · 2017-11-02T19:02:15Z

Some tech writers hold the opinion that FAQs are simply hints of content that need to be better integrated into the core doc experience.

I personally find them useful sometimes, and I understand that it's a common doc pattern, but I suggest also looking into how you can integrate each of these Qs into the core "Docs" and "Tutorials" sections.

Just trying to be helpful and give an outside perspective! I appreciate all of your work and think the docs are great :)

bvaughn · 2017-11-02T21:47:35Z

Friendly ping to @markerikson in case you'd like to take a first pass 😄

markerikson · 2017-11-02T23:04:13Z

I'll try to take a look at it tomorrow.

bvaughn · 2017-11-10T09:53:00Z

content/docs/faq-ajax.md

+  componentDidMount() {
+    fetch('https://api.example.com/items')
+      .then(res => res.json())
+      .then(result => this.setState({items: result.items))


The main gist of this example is good, but there are a couple of minor syntax and variable naming errors, and the array of list items is missing a key attribute.

What do you think about the following?

class MyComponent extends React.Component { state = { error: null, isLoaded: false, items: [] }; componentDidMount() { fetch("https://api.example.com/items") .then(res => res.json()) .then(result => this.setState({ isLoaded: true, items: result.items }) ) .catch(error => this.setState({ isLoaded: true, error }) ); } render() { const { error, items } = this.state; if (error) { return <div>Error: {error.message}</div>; } else if (!isLoaded) { return <div>Loading ...</div>; } else { return ( <ul> {items.map(item => ( <li key={item.name}> {item.name} {item.price} </li> ))} </ul> ); } } }

bvaughn · 2017-11-10T09:57:47Z

content/docs/faq-build.md

+### How can I write comments in JSX?
+
+```jsx
+ {/* Comment goes here */}


Could be nice to frame this within the context of a JSX tag or two, for added clarity, eg:

<div> {/* Comment goes here */} Hello, {name}! </div>

bvaughn · 2017-11-10T09:59:53Z

content/docs/faq-functions.md

+    console.log('Click happened')
+  }
+  render() {
+    return <button onClick={this.handleClick.bind(this)}>Click Me</button>


This section should have the same note as the "Arrow Function in Render" section below.

bvaughn · 2017-11-10T10:00:42Z

content/docs/faq-functions.md

+        Just clicked: {this.state.justClicked}
+        <ul>
+          { this.state.items.map(i => 
+            <li onClick={() => this.handleClick(i)}>


Add missing key attribute.

bvaughn · 2017-11-10T10:01:50Z

content/docs/faq-functions.md

+        Just clicked: {this.state.justClicked}
+        <ul>
+          { this.state.items.map(i => 
+            <li data-i={i} onClick={this.handleClick}>


Add missing key attribute.

Since I generated the Array in the constructor, what do you suggest for the key? I could change the example to assume it has some other unique attributes I suppose.

That would be fine. I just don't think we should show an example that omits an important, required property like key.

bvaughn · 2017-11-10T10:08:57Z

content/docs/faq-state.md

+
+### Why is `setState` is giving me the wrong value?
+
+Calls to `setState` are batched, so it is possible to "lose" an update if you call it with the partial object syntax:


I'm not sure the wording "partial object syntax" is particularly user-friendly. I'm not sure this is much better, but what do you think about this?

Calls to setState may be asynchronous! If you need to reference a value in state when updating it, use an updater function instead. (See below for an example.)

Good point about that phrasing; I'd like to come up with something in between that explains a bit more about why async patches can drop updates. A link to a Codepen might be sufficient.

bvaughn

I'm not sure I'm the best person to review this issue, but since the PR has been open for a while- I decided to review it this morning, because I feel bad about it just sitting here. 😄

I've left some thoughts.

bvaughn · 2017-11-10T10:10:12Z

content/docs/faq-state.md

+}
+```
+
+https://reactjs.org/docs/react-component.html#setstate


Maybe change this to something more like:

Learn more.

bvaughn · 2017-11-10T10:12:04Z

content/docs/faq-styling.md

+
+### Can I use inline styles?
+
+Yes, see https://reactjs.org/docs/dom-elements.html#style


For links within the website, I think it's nicer to use a shorter format rather than the full URL. For example:

Yes! Read here to learn more.

markerikson · 2017-11-13T02:44:23Z

Okay, I finally had a chance to look at this.

I don't think I have many nitpick-type comments. I do feel like a lot of the answers are kind of bare-bones, and could use both more extensive answers and links to relevant additional info. (Then again, that's also how I view things, and how I tackled the Redux FAQ, so YMMV.)

That said, this clearly doesn't have to be a final unchangeable thing. I'm inclined to say we get the FAQ in now, and then keep improving things from there.

alexkrolick · 2017-11-13T02:45:30Z

@markerikson I agree, the idea was to get the skeleton out there, and let the community improve it.

alexkrolick · 2017-11-13T04:07:37Z

@bvaughn addressed your comments and rebased from master

bvaughn · 2017-11-13T16:04:40Z

Yeah, I'm down with the idea of iterating on this.

bvaughn

Cool 👍 Thanks for getting the FAQ ball rolling!

gaearon · 2017-11-20T21:28:20Z

content/docs/faq-ajax.md

+          items: result.items
+        })
+      )
+      .catch(error =>


This is a very problematic pattern. We have about 20 issues about it in different forms in the React repo. The problem is that this swallows exceptions from rendering if the component in question throws. We shouldn't be recommending this.

gaearon · 2018-06-11T01:18:42Z

content/docs/faq-ajax.md

+
+### Cancellation
+
+Note that if the component unmounts before an AJAX call is complete, you may see a warning like `cannot read property 'setState' of undefined`. If this is an issue you may want to keep track of inflight AJAX requests and cancel them in the `componentWillUnmount` lifecycle method.


I just noticed this. It's not true—where is this information coming from? If a component unmounts it won't magically lose setState. You can only get this message if you forget to bind the handler.

* Adding first translations * Adding more translation (ultil) colocated tests * Translating until Flow texts * More translations... * 31 lines remaining * Preparing to pull * Fixing some details * Fix detail 01 Co-Authored-By: lamecksilva <[email protected]> * Fixing details 2

facebook-github-bot added the CLA Signed label Oct 7, 2017

alexkrolick mentioned this pull request Oct 9, 2017

Document how to pass args to event handlers #75

Closed

JasonEtco reviewed Oct 9, 2017

View reviewed changes

This was referenced Oct 9, 2017

New guides wanted #83

Open

added documentation for passing arguments to event handlers #81

Merged

alexkrolick mentioned this pull request Nov 2, 2017

CSS recommendations? #235

Closed

bvaughn reviewed Nov 10, 2017

View reviewed changes

bvaughn requested changes Nov 10, 2017

View reviewed changes

alexkrolick and others added 5 commits November 12, 2017 19:25

Add FAQ pages

e9b132a

add example component to AJAX FAQ

84c63dd

add cancellation topic to AJAX FAQ

a904140

fix typos

0143515

add example using data-attributes for event handler data

bac965e

alexkrolick force-pushed the add-faq branch from b2ef5ff to bac965e Compare November 13, 2017 03:26

alexkrolick added 6 commits November 12, 2017 20:04

Handle more states in async example code

b1d64dc

Add context to comment syntax example

3dbc635

Add note about performance implications of .bind in render

3a029d5

make sure param-passing example uses keys realistically

d7beebb

Don't show raw URLs in links

6d8c199

Clarify setState troubleshooting example

2114385

bvaughn added 3 commits November 13, 2017 08:06

Changed link style

c4faaf6

Formatted inline "Notes"

996508d

Corrected my own typo :)

2b4b34a

bvaughn approved these changes Nov 13, 2017

View reviewed changes

bvaughn merged commit cc1fb09 into reactjs:master Nov 13, 2017

gaearon reviewed Nov 20, 2017

View reviewed changes

bvaughn mentioned this pull request Nov 20, 2017

Add Error Handling to FAQ #309

Closed

gaearon reviewed Jun 11, 2018

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add FAQ pages #43

Add FAQ pages #43

alexkrolick commented Oct 7, 2017 •

edited

Loading

reactjs-bot commented Oct 7, 2017 •

edited

Loading

bvaughn commented Oct 7, 2017

JasonEtco Oct 9, 2017

JasonEtco Oct 9, 2017

JasonEtco Oct 9, 2017

alexkrolick Oct 9, 2017

bvaughn commented Oct 10, 2017

kaycebasques commented Nov 2, 2017

bvaughn commented Nov 2, 2017

markerikson commented Nov 2, 2017

bvaughn Nov 10, 2017

bvaughn Nov 10, 2017

bvaughn Nov 10, 2017

bvaughn Nov 10, 2017

bvaughn Nov 10, 2017

alexkrolick Nov 10, 2017

bvaughn Nov 10, 2017

bvaughn Nov 10, 2017

alexkrolick Nov 10, 2017

bvaughn left a comment

bvaughn Nov 10, 2017

bvaughn Nov 10, 2017

markerikson commented Nov 13, 2017

alexkrolick commented Nov 13, 2017

alexkrolick commented Nov 13, 2017

bvaughn commented Nov 13, 2017

bvaughn left a comment

gaearon Nov 20, 2017

gaearon Jun 11, 2018

This comment was marked as outdated.


		### How can I make an AJAX call?

		You can use an AJAX library you like with React. Some popular ones are [Axios](https://github.com/axios/axios), [jQuery AJAX](https://api.jquery.com/jQuery.ajax/), and the browser built-in [window.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).


		### Why is `setState` is giving me the wrong value?

		Calls to `setState` are batched, so it is possible to "lose" an update if you call it with the partial object syntax:


		### Can I use inline styles?

		Yes, see https://reactjs.org/docs/dom-elements.html#style


		### Cancellation

		Note that if the component unmounts before an AJAX call is complete, you may see a warning like `cannot read property 'setState' of undefined`. If this is an issue you may want to keep track of inflight AJAX requests and cancel them in the `componentWillUnmount` lifecycle method.

Add FAQ pages #43

Add FAQ pages #43

Conversation

alexkrolick commented Oct 7, 2017 • edited Loading

reactjs-bot commented Oct 7, 2017 • edited Loading

bvaughn commented Oct 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvaughn commented Oct 10, 2017

kaycebasques commented Nov 2, 2017

bvaughn commented Nov 2, 2017

markerikson commented Nov 2, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markerikson commented Nov 13, 2017

alexkrolick commented Nov 13, 2017

alexkrolick commented Nov 13, 2017

bvaughn commented Nov 13, 2017

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as outdated.

alexkrolick commented Oct 7, 2017 •

edited

Loading

reactjs-bot commented Oct 7, 2017 •

edited

Loading