Repository navigation
Documentation: Rewrite Data docs as tutorial - #5379
Conversation
|
Haven't read yet, but maybe there's room for both. The README could stay more like an API reference and the tutorial could go in the handbook? |
|
@youknowriad I tried to strike more of a balance, so the functions are all documented, just more elaboration of the "when", "why", and "how". |
|
@aduth Will take a deeper look. As an aside, I think we should add a "modules" section to the handbook with the README of all modules. (A page per module) |
|
Maybe the Comparison with Redux section could come right at the start after the description. Avoiding confusion to new people. |
youknowriad
left a comment
There was a problem hiding this comment.
Really nice work here 👍 I have a diverging opinion about the need to surface presentational/container components but it's fine
| - `store.subscribe( listener: Function )`: Registers a function called any time the value of state changes. | ||
| - _Redux parallel:_ [`subscribe`](https://redux.js.org/api-reference/store#subscribe(listener)) | ||
| - Differences from Redux: | ||
| - In Redux, a subscriber is called on every dispatch, regardless of whether a change has occurred. In `@wordpress/data`, a subscriber is only called when state has changed. |
There was a problem hiding this comment.
Not certain we have to mention this as it's a very small difference.
There was a problem hiding this comment.
Not certain we have to mention this as it's a very small difference.
Right. One of my initial goals in writing this was to highlight any and all differences to Redux, but I agree for most people this would have no impact. Do you think we should mention this anywhere? The "Comparison with Redux" section perhaps?
There was a problem hiding this comment.
Moving to "comparison with redux" sounds good to me
| A higher-order component is a function which accepts a [component](https://github.com/WordPress/gutenberg/tree/master/element) and returns a new, enhanced component. A stateful user interface should respond to changes in the underlying state and updates its displayed element accordingly. WordPress uses higher-order components both as a means to separate the purely visual aspects of an interface from its data backing, and to ensure that the data is kept in-sync with the stores. | ||
|
|
||
| #### Example: | ||
| In the React/Redux ecosystem, this distinction is often labelled [_Presentational and Container Components_](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0). [React Redux](https://github.com/reactjs/react-redux) is the official bindings between React and Redux for providing this behavior. The higher-order components offered in the data module are very much like React Redux's `connect` function, but offered as independent functions for retrieving and manipulating data: `withSelect` and `withDispatch`. |
There was a problem hiding this comment.
I personally don't think it's necessary to explain Presentational and Container components, I feel it introduces more confusion than it solves.
There was a problem hiding this comment.
I personally don't think it's necessary to explain Presentational and Container components, I feel it introduces more confusion than it solves.
What confusions do you have concerns about? I think the article goes into much more detail about this distinction and could be good for further reading, and to preempt thoughts of "Hey, that sounds a lot like...".
There was a problem hiding this comment.
I know for a lot of people, this distinction is important but from mine, it doesn't make a lot of sense :).
A person reading this could assume that a Presentation component can be reused with any data or store, just providing props but that's not true because Presentation components can use Container components which means they are not reusable.
I like to think of everything as just React Components :). If I were to split types for React Components, I would prefer "Context-free components" and "Context-dependent components" :)
"Context-free" could be the UI components or the Presentation components
and
"Context-dependent" the more data heavy components
There was a problem hiding this comment.
For the purposes of this document in introducing someone who may have no familiarity of these concepts, how can we set them on the correct course? Is a "presentational and container" distinction harmful? Or can it be seen as more of a guideline to encourage developers from tying their components too directly to a specific source of props?
There was a problem hiding this comment.
So for me I think we can talk about connect as a Higher Order Component to inject props without the need to talk about Presentational and container components. Just explaining that a Higher Order Component is a function injecting extra props to a component and returning component.
I don't think you need to know Presentational and Container components to understand how HoC work.
There was a problem hiding this comment.
Okay, I think we could just remove it in the initial push.
One common pitfall I see where this distinction can be helpful is when component authors provide complex data unnecessarily to a component. Consider a <Title /> component where someone passes the post object and we render via the value of post.title. Why does that component need the entire post object? It doesn't; it's less reusable, and on a more practical level it causes issues with unnecessary re-renders via pure-render on the object (the value of the post object is likely to change more frequently than the title string). The component author should just pass in the title string.
Thinking that guides like this can be useful for helping avoid these pitfalls, even if the rules themselves shouldn't be so strictly binding.
There was a problem hiding this comment.
Agree with the pitfall here, but not sure it's related to presentation/container separation, I know it's often explained when talking about this separation though.
I approved the PR, you choose :). I do have concerns about this separation but don't have strong objections to include it in the docs as it's a common React pattern people should know about.
There was a problem hiding this comment.
I'm going to drop this paragraph. The previous paragraph has a brief mention of separating visual and data concerns, which I think is sufficient for now.
| To inject state-derived props into a WordPress Element Component, use the `withSelect` higher-order component: | ||
| #### `withDispatch( mapDispatchToProps: Function ): Function` | ||
|
|
||
| Use `withDispatch` to inject dispatching action props into your component. Passed a function which returns an object mapping prop names to action dispatchers, a higher-order component function is returned. The higher-order component can be used to enhance a presentational component, often providing callback behaviors for user interactions. The mapping function is passed the [`dispatch` function](#dispatch) and the props passed to the original component. |
There was a problem hiding this comment.
Technically withSelect and withDispatch can enhance any component and not only presentational components.
There was a problem hiding this comment.
Technically
withSelectandwithDispatchcan enhance any component and not only presentational components.
The thinking was to build upon this idea that visual components become enhanced to react to state with these higher-order components. Not to imply a sort of "rule" about when they can be used.
Do you have an example in mind that contradicts this advice?
I'm a bit wary of this module being considered as merely "Redux for WordPress", for a few reasons:
To me anyways, the most effective use of critical first sections of this documentation are in describing why and how it's to be used. I would agree that for someone who happens to already be familiar with Redux, it's odd to not describe the comparison until the end of the documentation, particularly when there are multiple references to Redux documentation within the guide itself. Perhaps the introduction section could include a mention of this to make it explicit, with a link to the final section (similar to what existed previously with "exposes a Redux-like API"). |
Demonstrate use of `ownProps` in `withDispatch`
This pull request seeks to rewrite documentation for
@wordpress/datato be less of a API overview and more of a walkthrough of expected uses of the module, explanations of key concepts, and contrasting with the Redux library upon which it is built. Importantly, it surfacesregisterStoreas the preferred registration point (introduced in #5206).View Documentation
Testing instructions:
There are no code changes.