status-im
/
re-frame
mirror of https://github.com/status-im/re-frame.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

More docs

This commit is contained in:
Mike Thompson 2016-08-29 13:11:15 +10:00
parent 2a2db3d2e6
commit a0679e12a2
5 changed files with 150 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.idea/codeStyleSettings.xml
View File

@ -12,5 +12,6 @@
</value>
</option>
<option name="USE_PER_PROJECT_SETTINGS" value="true" />
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default (2)" />
</component>
</project>

9
docs/README.md
View File

@ -18,4 +18,11 @@
1. [Loading Initial Data](Loading-Initial-Data.md)
2. [Talking To Servers](Talking-To-Servers.md)
3. [Subscribing to External Data](Subscribing-To-External-Data.md)
3. [Subscribing to External Data](Subscribing-To-External-Data.md)
## Miscellaneous:
1. [Using Stateful JS Components.md](Using-Stateful-JS-Components.md)
2. [The re-frame Logo](The-ref-frame-logo.md)

45
docs/The-ref-frame-logo.md Normal file
View File

@ -0,0 +1,45 @@
## The re-frame Logo
![logo](/images/logo/re-frame_256w.png?raw=true)
### Who
Created by the mysterious deep thinker, known only as @martinklepsch.
Some say he appears on high value stamps in Germany and that he once
punched a horse to the ground. Others say he loves recursion so much
that, in his wallet, he carries a photograph of his wallet.
All we know for sure is that he wields [Sketch.app](https://www.sketchapp.com/) like
Bruce Lee wielded nunchucks.
### Genesis Theories
Great, unexplained works encourage fan theories, and the re-frame logo
is no exception.
A noisy bunch think @martinklepsch wanted to `Put the 'f' back into infinity`. They have t-shirts.
Others speculate he created the logo as a bifarious rainbow homage
to Frank Lloyd Wright's masterpiece, the Guggenheim Museum. A classic case
of premature abstraction and over engineering if you ask me. Their theory, not the Guggenheim.
![](/images/logo/Guggenheim.jpg)
The infamous "Bad Touch" faction look at the logo and see the cljs logo mating noisily with re-frame's official
architecture diagram. Attend one of their parties and you have a 50% chance of arrest.
![](/images/logo/Genesis.png)
The Functional Fundamentalists, a stern bunch, see the logo as a flowing poststructuralist rebuttal of OO's
vowel duplication and horizontal adjacency. Their approach, FF, is apparently fine because "everyone loves a
fricative".
For his part, @martinklepsch has never confirmed any theory, teasing us instead with coded clues
like "Will you please stop emailing me" and "Why did you say I hit a horse?".
### Assets Where?
Within this repo, look in `/images/logo/`

94
docs/Using-Stateful-JS-Components.md Normal file
View File

@ -0,0 +1,94 @@
## Using Stateful JS Components
You know what's good for you, and you know what's right. But it
doesn't matter - the wickedness of the temptation is too much.
The JS world is brimming with shiny component baubles: D3,
Google Maps, Chosen, etc.
But they are salaciously stateful and mutative. And, you,
raised in a pure, functional home, with caring, immutable parents,
know they are wrong. But, my, how you still yearn for the sweet
thrill of that forbidden fruit.
I won't tell, if you don't. But careful plans must be made ...
### The overall plan
To use a stateful js component, you'll need to write two Reagent components:
- an **outer component** responsible for sourcing data via a subscription or r/atom or cursor, etc.
- an **inner component** responsible for wrapping and manipulating the stateful JS component via lifecycle functions.
The pattern involves the outer component, which sources data, supplying this data to the inner component **via props**.
### Example Using Google Maps
```cljs
(defn gmap-inner []
(let [gmap (atom nil)
options (clj->js {"zoom" 9})
update (fn [comp]
(let [{:keys [latitude longitude]} (reagent/props comp)
latlng (js/google.maps.LatLng. latitude longitude)]
(.setPosition (:marker @gmap) latlng)
(.panTo (:map @gmap) latlng)))]
(reagent/create-class
{:reagent-render (fn []
[:div
[:h4 "Map"]
[:div#map-canvas {:style {:height "400px"}}]])
:component-did-mount (fn [comp]
(let [canvas (.getElementById js/document "map-canvas")
gm (js/google.maps.Map. canvas options)
marker (js/google.maps.Marker. (clj->js {:map gm :title "Drone"}))]
(reset! gmap {:map gm :marker marker}))
(update comp))
:component-did-update update
:display-name "gmap-inner"})))
(defn gmap-outer []
(let [pos (subscribe [:current-position])] ;; obtain the data
(fn []
[gmap-inner @pos])))
```
Notes:
- `gmap-outer` obtains data via a subscription. It is quite simple - trivial almost.
- it then passes this data __as a prop__ to `gmap-inner`. This inner component has the job of wrapping/managing the stateful js component (Gmap in our case above)
- when the data (delivered by the subscription) to the outer layer changes, the inner layer, `gmap-inner`, will be given a new prop - `@pos` in the case above.
- when the inner component is given new props, its entire set of lifecycle functions will be engaged.
- the renderer for the inner layer ALWAYS renders the same, minimal container hiccup for the component. Even though the `props` have changed, the same hiccup is output. So it will appear to React as if nothing changes from one render to the next. No work to be done. React/Reagent will leave the DOM untouched.
- but this inner component has other lifecycle functions and this is where the real work is done.
- for example, after the renderer is called (which ignores its props), `component-did-update` will be called. In this function, we don't ignore the props, and we use them to update/mutate the stateful JS component.
- the props passed (in this case `@pos`) in must be a map, otherwise `(reagent/props comp)` will return nil.
### Pattern Discovery
This pattern has been independently discovered by many. To my knowledge,
[this description of the Container/Component pattern](https://medium.com/@learnreact/container-components-c0e67432e005#.3ic1uipvu)
is the first time it was written up.
### Code Credit
The example gmaps code above was developed by @jhchabran in this gist:
https://gist.github.com/jhchabran/e09883c3bc1b703a224d#file-2_google_map-cljs
### D3 Examples
D3 (from @zachcp):
- Blog Post: http://zachcp.org/blog/2015/reagent-d3/
- Code: https://github.com/zachcp/simplecomponent
- Example: http://zachcp.github.io/simplecomponent/
### Advanced Lifecycle Methods
If you mess around with lifecycle methods, you'll probably want to read Martin's explanations:
https://www.martinklepsch.org/posts/props-children-and-component-lifecycle-in-reagent.html

37
images/logo/README.md
View File

@ -1,40 +1,7 @@
## The re-frame Logo
![logo](/images/logo/re-frame_256w.png?raw=true)
Created by the mysterious @martinklepsch
Some say he appears on high value stamps in Germany and that he once
punched a horse to the ground. Others say he loves recursion so much
that his wallet contains a photograph of his wallet.
All we know for sure is that he wields [Sketch.app](https://www.sketchapp.com/) like
Bruce Lee wielded nunchucks.
## Genesis Theories
Great, unexplained works encourage fan theories, and the re-frame logo
is no exception.
Some speculate @martinklepsch created it as a bifarious rainbow homage
to Frank Lloyd Wright's Guggenheim.
![](Guggenheim.jpg)
Others see the cljs logo mating noisily with re-frame's official
architecture diagram.
![](Genesis.png)
Yet others see a poststructuralist rebuttal of OO's
vowel duplication and horizontal adjacency. Their T-shirts claim:
> He's put the 'f' back into infinity
For his part, Martin has never confirmed any theory, teasing us instead with coded clues
like "Will you please stop emailing me" and "Why did you say I hit a horse?".
### Notes
Use [Sketch.app](https://www.sketchapp.com/) to update the `re-frame-logo.sketch` file.
Created via [Sketch.app](https://www.sketchapp.com/). See the file `re-frame-logo.sketch`
Unfortunately the gradients are not exported properly so we can't provide an SVG here for now.