reagent/README.md

136 lines
4.2 KiB
Markdown
Raw Normal View History

2013-12-19 12:11:02 +00:00
2014-01-17 10:12:11 +00:00
# Reagent
2013-12-19 12:11:02 +00:00
A simple [ClojureScript](http://github.com/clojure/clojurescript) interface to [React](http://facebook.github.io/react/).
The main repository for Reagent is now located [here](https://github.com/reagent-project/reagent).
2013-12-19 12:11:02 +00:00
Reagent provides a way to write efficient React components using (almost) nothing but plain ClojureScript functions.
* **[Detailed intro with live examples](http://reagent-project.github.io/)**
* **[News](http://reagent-project.github.io/news/index.html)**
2014-11-29 00:09:14 +00:00
* **[Reagent Project Mailing List](https://groups.google.com/forum/#!forum/reagent-project)**
2013-12-19 12:11:02 +00:00
To create a new Reagent project simply run:
lein new reagent myproject
This will setup a new Reagent project with some reasonable defaults, see here for more [details](https://github.com/reagent-project/reagent-template).
To use Reagent in an existing project you add this to your dependencies in `project.clj`:
2013-12-19 13:06:49 +00:00
2015-03-11 18:06:46 +00:00
[reagent "0.5.0"]
2014-01-10 12:59:38 +00:00
This is all you need to do if you want the standard version of React. If you want the version of React with addons, you'd use something like this instead:
2014-01-10 12:59:38 +00:00
2015-03-11 18:06:46 +00:00
[reagent "0.5.0" :exclusions [cljsjs/react]]
[cljsjs/react-with-addons "0.12.2-4"]
2014-01-10 12:59:38 +00:00
If you want to use your own build of React (or React from a CDN), you have to use `:exclusions` variant of the dependency, and also provide a file named "cljsjs/react.cljs", containing just `(ns cljsjs.react)`, in your project.
2014-01-10 12:59:38 +00:00
2013-12-19 13:06:49 +00:00
2013-12-19 12:11:02 +00:00
## Examples
2014-01-17 10:12:11 +00:00
Reagent uses [Hiccup-like](https://github.com/weavejester/hiccup) markup instead of React's sort-of html. It looks like this:
2013-12-19 12:11:02 +00:00
```clj
(defn some-component []
[:div
[:h3 "I am a component!"]
[:p.someclass
"I have " [:strong "bold"]
[:span {:style {:color "red"}} " and red"]
" text."]])
```
You can use one component inside another:
2013-12-19 12:11:02 +00:00
```clj
(defn calling-component []
[:div "Parent component"
[some-component]])
```
And pass properties from one component to another:
```clj
2014-02-21 16:16:26 +00:00
(defn child [name]
[:p "Hi, I am " name])
2013-12-19 12:11:02 +00:00
(defn childcaller []
2014-02-21 16:16:26 +00:00
[child "Foo Bar"])
2013-12-19 12:11:02 +00:00
```
You mount the component into the DOM like this:
```clj
(defn mountit []
2014-01-17 10:12:11 +00:00
(reagent/render-component [childcaller]
(.-body js/document)))
2013-12-19 12:11:02 +00:00
```
2014-01-17 10:12:11 +00:00
assuming we have imported Reagent like this:
2013-12-19 12:11:02 +00:00
```clj
(ns example
2014-01-17 10:12:11 +00:00
(:require [reagent.core :as reagent :refer [atom]]))
2013-12-19 12:11:02 +00:00
```
2014-01-17 10:12:11 +00:00
State is handled using Reagent's version of `atom`, like this:
2013-12-19 12:11:02 +00:00
```clj
(def click-count (atom 0))
2013-12-19 12:11:02 +00:00
(defn state-ful-with-atom []
[:div {:on-click #(swap! click-count inc)}
"I have been clicked " @click-count " times."])
```
2014-01-17 10:12:11 +00:00
Any component that dereferences a `reagent.core/atom` will be automatically re-rendered.
2013-12-19 12:11:02 +00:00
If you want do some setting up when the component is first created, the component function can return a new function that will be called to do the actual rendering:
```clj
(defn timer-component []
(let [seconds-elapsed (atom 0)]
(fn []
(js/setTimeout #(swap! seconds-elapsed inc) 1000)
[:div
"Seconds Elapsed: " @seconds-elapsed])))
2013-12-19 12:11:02 +00:00
```
This way you can avoid using React's lifecycle callbacks like `getInitialState` and `componentWillMount` most of the time.
2014-01-17 10:12:11 +00:00
But you can still use them if you want to, either using `reagent.core/create-class` or by attaching meta-data to a component function:
2013-12-19 12:11:02 +00:00
```clj
(def my-html (atom ""))
2014-02-21 16:16:26 +00:00
(defn plain-component []
[:p "My html is " @my-html])
2013-12-19 12:11:02 +00:00
(def component-with-callback
(with-meta plain-component
{:component-did-mount
(fn [this]
2014-01-17 10:12:11 +00:00
(reset! my-html (.-innerHTML (reagent/dom-node this))))}))
2013-12-19 12:11:02 +00:00
```
See the examples directory for more examples.
## Performance
2014-01-17 10:12:11 +00:00
React is pretty darn fast, and so is Reagent. It should even be faster than plain old javascript React a lot of the time, since ClojureScript allows us to skip a lot of unnecessary rendering (through judicious use of React's `shouldComponentUpdate`).
2013-12-19 12:11:02 +00:00
The ClojureScript overhead is kept down, thanks to lots of caching.
2014-01-10 12:59:38 +00:00
Code size is a little bigger than React.js, but still quite small. The todomvc example clocks in at roughly 53K gzipped, using advanced compilation.
2013-12-19 12:11:02 +00:00
## About
The idea and some of the code for making components atom-like comes from [pump](https://github.com/piranha/pump). The reactive-atom idea (and some code) comes from [reflex](https://github.com/lynaghk/reflex).
The license is MIT.