A ClojureScript interface to Facebook's React.
Om allows users to represent their UIs simply as EDN. Because ClojureScript data is immutable data, Om can always rapidly re-render the UI from the root. Thus Om UIs are out of the box snapshotable and undoable and these operations have no implementation complexity and little overhead.
Om supports features not currently present in React:
- Component construction can be intercepted via
:instrument
. Simplifies debugging components and generic editors. - Provides stream of all application state change deltas via
:tx-listen
. Simplifies synchronization online and offline. - Customizable semantics. Fine grained control how components store state, even for components outside of your control. Simplifies using Om components outside the Om framework, debugging, and adding event hooks not anticipated by original component designer.
There is an in-depth tutorial that will introduce you to the core concepts of Om here and a real-world integration example here.
(ns example
(:require [om.core :as om :include-macros true]
[om.dom :as dom :include-macros true]))
(defn widget [data owner]
(reify
om/IRender
(render [this]
(dom/h1 nil (:text data)))))
(om/root widget {:text "Hello world!"}
{:target (. js/document (getElementById "my-app"))})
The repo includes several simple examples you can build yourself. If
you view the project.clj
you will see their build
identifiers. Assuming you have Leiningen
installed, to build an example run:
lein cljsbuild once <build-id>
Then open the corresponding index.html
in your favorite browser.
For a more fleshed-out example, please see the Om implementation of TodoMVC exists here.
There is documentation here.
There is also a conceptual overview that we recommend reading as there are some design choices in Om that make it quite different from other client side solutions and even React itself.
Om emphasizes building modular and adaptable components. Some examples:
- om-sync, keep client and server in sync
- ankha, an EDN inspector view
- om-draggable, generic draggable
- om-autocomplete, customizable autocompleter
- om-widgets
- om-dev-component, add dev features (e.g. state history navigation) to your component
- CircleCI
- Prismatic
- Fitsme
- Goya, pixel editor with undo/redo and visual history
- wordsmith, a markdown editor
- omchaya
- BVCA Private Equity Map
- session
- pOModoro
- Dakait, A web-based tool to manage downloads
Om is alpha software.
Make sure you have Leiningen installed.
Your project.clj
should include something like the following:
(defproject foo "0.1.0"
...
:dependencies [[org.clojure/clojure "1.5.1"]
[org.clojure/clojurescript "0.0-2173"]
[om "0.6.5"]]
...)
For local development your lein-cljsbuild settings should look something like this:
:cljsbuild {
:builds [{:id "dev"
:source-paths ["src"]
:compiler {
:output-to "main.js"
:output-dir "out"
:optimizations :none
:source-map true}}]}
Your local development markup should look something like the following:
<html>
<body>
<div id="my-app"></div>
<script src="http://fb.me/react-0.9.0.js"></script>
<script src="out/goog/base.js" type="text/javascript"></script>
<script src="main.js" type="text/javascript"></script>
<script type="text/javascript">goog.require("main.core");</script>
</body>
</html>
For production your lein-cljsbuild settings should look something like this:
:cljsbuild {
:builds [{:id "release"
:source-paths ["src"]
:compiler {
:output-to "main.js"
:optimizations :advanced
:pretty-print false
:preamble ["react/react.min.js"]
:externs ["react/externs/react.js"]}}]}
This will generate a single file main.js
. Your production markup
should look something like this:
<html>
<body>
<div id="my-app"></div>
<script src="main.js" type="text/javascript"></script>
</body>
</html>
No pull requests at this time please.
Om is still in the design phase so enhancements are low priority. However, bug reports are welcome for the existing functionality.
For a sense of where Om is going the existing issues give a rough idea.
Om is not opinionated about HTML syntax, third parties can provide the
preferred flavors over the React.DOM
api. Alternative syntaxes will
be listed here:
Om does not ship with a router and is unlikely to. However ClojureScript routing libraries exist that handle this problem quite well:
- Sean Grove's omchaya is a good starting point for understanding common testing patterns
- There are some notes here
- Worlds: Controlling the Scope of Side Effects
- A Functional I/O System
- Directness and Liveness in the Morphic User Interface Construction Environment
- Learnable Programming
Copyright © 2013-2014 David Nolen
Licensed under the EPL (see the file epl.html).