Add a guide to the docs

[pesterhazy]

Reagent has goods docs but they're somewhat hard to find. Some topics are covered in the API docs, others are discussed in the NEWS posts. Some information again is best covered in re-frame's docs or in the Reagent Cookbook.

To make Reagent more accessible, it would be helpful to include a Table of Contents in the README that links to the various docs. Here's a breakdown of topics that I think would be useful to cover.

Thoughts?

Mounting components

• r/render
• considerations to ensure proper reloading

State management

• ratom
• reaction
• cursor
• track
• track!
• wrap

React interop

• create-element
• adapt-react-class
• [:> ...]
• as-element
• reactify-component
• requiring react - how React is found

Performance

• async rendering
• flush
• force-update-all
• force-update
• next-tick
• after-update

Lifecycle methods

• List of available lifecycle methods
• Form-2 components vs Form-3 components
• Accessing props in lifecycle methods
• Cleaning up: with-let
• How should-component-update works in Reagent

Accessing DOM nodes/backing instances

• dom-node
• callback refs

Render methods

• Accessing props and children
• Form-2 components: remembering to repeat arguments in the inner function
• :render vs :reagent-render

Reagent-flavored hiccup

• Nested element syntax: [:li.foo>a.bar]
• Handling nil
• Vectors and sequences are handled differently
• Settinging keys through meta-data
• How props case is handled (:on-change -> "onChange")

Handling input elements

• Keeping cursor position
• Latency hacks
• Using 3rd party input elements (e.g. from Semantic UI React)

Component-local state

• Component-local ratoms
• Form-2 components
• reagent.core/state and reagent.core/set-state

Advanced topics

• Server-side rendering

[gadfly361]

@pesterhazy I really like this idea! Would you be interested in starting a PR for this?

There are several outstanding issues that I think this could help solve: 249, 209, 166, and 147

I am hopeful that we can triage the relevant links to add to it. And if certain bullets are without links, it could potentially be a good opportunity for community members to write a blog post and help with some documentation.

[xari]

Hey @pesterhazy @gadfly361 ,

This issue is still open, and I'm wondering what else you're hoping to expand the documentation with. Coming from a React background, and not a Clojure background, I found the documentation very different from what I'm used-to.

Particularly; I'm used to the React docs which get into patterns like Render-props, Controlled components, etc., and that kind of language seems to be missing from the Reagent docs. Obviously, the patterns in Reagent aren't exactly the same as those in React, but there is overlap, and I think that React developers might find it easier to adopt Reagent, if the docs spoke to them about the kind of patterns that they're already used-to.

[pesterhazy]

Hi @Xaris as should be obvious by now, I haven't had a chance to work on this. It's obviously quite a lot of work.

As you say it would be great to have docs on patterns. But even just basic functions and concepts (like Reactions, or how lifecycle methods translate to Reagent) are barely documented. So if I had the time, I'd probably start there.

[xari]

@pesterhazy ,

I'd be happy to take a crack at this --although it might take me a couple of weeks as well. Reactions are new to me, but they seem like they might be a similar interface to the new useEffect function in React.... The only reference I can find to them is this question on StackOverflow.

https://stackoverflow.com/questions/40615929/clojure-reagent-how-to-create-reaction-atom

[mike-thompson-day8]

@Xaris this should help you (although it has a re-frame tilt) https://github.com/Day8/re-frame/blob/master/docs/SubscriptionFlow.md

[xari]

Ok, cool --thanks, @mike-thompson-day8 . I probably won't get free to work on this until around New Years, so expect something from me around then.