Skip to content

Commit

Permalink
Merge pull request omcljs#873 from omcljs/new-readme
Browse files Browse the repository at this point in the history 
New README
  • Loading branch information
@swannodette
swannodette authored Jun 14, 2017
2 parents e9bff93 + a1a556e commit f31832b
Show file tree
Hide file tree
Showing 2 changed files with 295 additions and 202 deletions.
246 changes: 44 additions & 202 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,202 +1,67 @@
# Om

A [ClojureScript](http://github.com/clojure/clojurescript) interface
to [Facebook's React](http://facebook.github.io/react/).

Om allows users to represent their UIs simply as
[EDN](http://github.com/edn-format/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.

[See](http://swannodette.github.io/todomvc/labs/architecture-examples/om-undo/index.html)
for [yourself](http://swannodette.github.io/2013/12/31/time-travel).

## Unique Features

Om supports features not currently present in React:

* Global state management facilities built in
* Components may have arbitrary data dependencies, not limited to props & state
* 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 over 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.
A [ClojureScript](http://github.com/clojure/clojurescript) UI framework and
client/server architecture over [Facebook's
React](http://facebook.github.io/react/).

## Tutorials

There is an in-depth tutorial that will introduce you to the core
concepts of Om
[here](http://github.com/swannodette/om/wiki/Basic-Tutorial) and a
real-world integration example
[here](http://github.com/swannodette/om/wiki/Intermediate-Tutorial). The
community maintained [om-cookbook](https://github.com/omcljs/om-cookbook)
covers many common idioms and patterns.

## Examples
Om UIs are out of the box snapshotable and undoable and these operations have
no implementation complexity and little overhead.

```clojure
(ns example
(:require [om.core :as om]
[om.dom :as dom]))
Om borrows ideas liberally from [Facebook's
Relay](https://facebook.github.io/relay/) and [Netflix's
Falcor](http://netflix.github.io/falcor/) with a dash of inspiration from
[Datomic pull syntax](http://docs.datomic.com/pull.html) to avoid the typical
incidental complexity that arises from client/server state management.

(defn widget [data owner]
(reify
om/IRender
(render [this]
(dom/h1 nil (:text data)))))
## Dependency Information

(om/root widget {:text "Hello world!"}
{:target (. js/document (getElementById "my-app"))})
```
Latest release: 1.0.0-beta1

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](http://leiningen.org/)
installed, to build an example run:
[Leiningen](http://github.com/technomancy/leiningen/) and [Boot](http://boot-clj.com)
dependency information:

```
lein cljsbuild once <build-id>
[org.omcljs/om "1.0.0-beta1"]
```

Then open the corresponding `index.html` in your favorite browser.

For a more fleshed-out example, please see the Om implementation of
[TodoMVC](http://todomvc.com)
[exists here](http://github.com/swannodette/todomvc/blob/gh-pages/labs/architecture-examples/om/src/todomvc/app.cljs).
[Maven](http://maven.apache.org) dependency information:

## Documentation

There is documentation [here](http://github.com/swannodette/om/wiki/Documentation).

There is also a
[conceptual overview](http://github.com/swannodette/om/wiki/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.

## Reusable Components

Om emphasizes building modular and adaptable components. Some
examples:

* [om-bootstrap](https://github.com/racehub/om-bootstrap), Bootstrap 3 Om Components
* [ankha](http://github.com/noprompt/ankha), an EDN inspector view
* [om-draggable](https://github.com/sgrove/om-draggable), generic
draggable
* [om-autocomplete](https://github.com/arosequist/om-autocomplete),
customizable autocompleter
* [ff-om-draggable](https://github.com/neo/ff-om-draggable)
* [om-widgets](https://bitbucket.org/athieme/om-widgets)
* [om-dev-component](https://github.com/ioRekz/om-dev-component), add dev features (e.g. state history navigation) to your component
* [om-sync](http://github.com/swannodette/om-sync), keep client and
server in sync (experimental)

## Applications built with Om

* [Project FiFo](https://blog.project-fifo.net/the-stack-we-choose-erlang-smartos-clojure/), a SmartOS cloud orchestration platform
* [Recurse Center Community](https://github.com/hackerschool/community)
* [Framed](http://www.framed.io/)
* [Netrunner](https://github.com/mtgred/netrunner)
* [CircleCI](http://www.circleci.com/), source [here](https://github.com/circleci/frontend)
* [Precursor](https://precursorapp.com)
* [Assistant](https://github.com/29decibel/assistant)
* [Fitsme](http://fitsmeapp.com)
* [Goya](http://jackschaedler.github.io/goya/), pixel editor with
undo/redo and visual history
* [AppShare](https://github.com/zubairq/AppShare), a Clojure web framework
* [wordsmith](http://wordsmith.variadic.me), a markdown editor
* [omchaya](http://github.com/sgrove/omchaya)
* [BVCA Private Equity Map](http://bvca.clustermap.trampolinesystems.com/)
* [session](http://github.com/kovasb/session)
* [pOModoro](http://pomodoro.trevorlandau.net)
* [Dakait](http://github.com/verma/dakait), a web-based tool to manage
downloads
* [Mega Super Mario World](http://github.com/city41/mario-review), a detailed review of the classic video game and a SNES video editor
* [Time for Coffee!](http://www.timeforcoffee.ch), a handy website to display the next departures at public transport stops in Switzerland
* [Omingard](https://omingard.5apps.com), a Solitaire-like card game. Making-of: [My Way into Clojure](http://www.railslove.com/stories/my-way-into-clojure-building-a-card-game-with-om-part-1).
* [Horizon Alpha](https://github.com/BertrandDechoux/horizon-alpha), a quick Hack and slash game using the Noob universe
* [Solari Architects](http://solariarchitects.com/), portfolio for architecture firm.

## Using it

The current version depends on React 0.13.3.

Make sure you have [Leiningen](http://leiningen.org/) installed.

Your `project.clj` should include something like the following:

```clojure
(defproject foo "0.1.0"
...
:dependencies [[org.clojure/clojure "1.6.0"]
[org.clojure/clojurescript "0.0-2760"]
[org.omcljs/om "0.9.0"]]
...)
```
<dependency>
<groupId>org.omcljs</groupId>
<artifactId>om</artifactId>
<version>1.0.0-beta1</version>
</dependency>
```

### React with Add-Ons

If you would rather use React with Add-Ons you can configure this
with Maven's exclusions feature:
## Example

```clojure
(defproject foo "0.1.0"
...
:dependencies [[org.clojure/clojure "1.6.0"]
[org.clojure/clojurescript "0.0-2760"]
[org.omcljs/om "0.9.0" :exclusions [cljsjs/react]]
[cljsjs/react-with-addons "0.13.3-0"]]
...)
```
(ns example
(:require [goog.dom :as gdom]
[om.dom :as dom]
[om.next :as om :refer [defui]]))

### Build configuration
(defui Hello
Object
(render [this]
(dom/h1 nil "Hello, world!")))

For local development your
[lein-cljsbuild](http://github.com/emezeske/lein-cljsbuild) settings
should look something like this:
(def hello (om/factory Hello))

```clojure
:cljsbuild {
:builds [{:id "dev"
:source-paths ["src"]
:compiler {
:main main.core
:output-to "main.js"
:output-dir "out"
:optimizations :none
:source-map true}}]}
(.render js/ReactDOM (hello) (gdom/getElement "example"))
```

Your markup should look something like the following:
## Tutorials

```html
<html>
<body>
<div id="my-app"></div>
<script src="main.js" type="text/javascript"></script>
</body>
</html>
```
There is an Quick Start tutorial that will introduce you to the core
concepts of Om
[here](https://github.com/omcljs/om/wiki/Quick-Start-%28om.next%29). There are
also a variety of other guides [here](https://github.com/omcljs/om/wiki#om-next).

For production your [lein-cljsbuild](http://github.com/emezeske/lein-cljsbuild) settings should look something
like this:
## Documentation

```clojure
:cljsbuild {
:builds [{:id "release"
:source-paths ["src"]
:compiler {
:main main.core
:output-to "main.js"
:optimizations :advanced
:pretty-print false}}]}
```
There is documentation [here](https://github.com/omcljs/om/wiki/Documentation-%28om.next%29)

## Contributing

Expand All @@ -210,39 +75,16 @@ If you are looking for help please get in touch either on the
[clojurians.slack.com **#om** channel](http://clojurians.net) or the
[om-cljs Google Group](https://groups.google.com/d/forum/om-cljs).

## FAQ

### Can I use a different HTML Syntax?

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:

* [sablono](http://github.com/r0man/sablono), Hiccup-style
* [kioo](http://github.com/ckirkendall/kioo), Enlive-style

### Does Om provide routing?

Om does not ship with a router and is unlikely to. However
ClojureScript routing libraries exist that handle this problem quite
well:

* [secretary](http://github.com/gf3/secretary)
* [silk](http://github.com/DomKM/silk)
* [bidi](http://github.com/juxt/bidi)

### How do I test Om programs?

* Sean Grove's [omchaya](http://github.com/sgrove/omchaya) is a good
starting point for understanding common testing patterns
* There are some notes [here](http://github.com/swannodette/om/wiki/Testing)

## References

* [Worlds: Controlling the Scope of Side Effects](http://www.vpri.org/pdf/tr2011001_final_worlds.pdf)
* [A Functional I/O System](http://www.ccs.neu.edu/racket/pubs/icfp09-fffk.pdf)
* [Directness and Liveness in the Morphic User Interface Construction Environment](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.103.600&rep=rep1&type=pdf)
* [Learnable Programming](http://worrydream.com/LearnableProgramming/)
* [Relay](https://facebook.github.io/relay/)
* [Falcor](http://netflix.github.io/falcor/)
* [GraphQL](http://graphql.org)
* [Datomic pull syntax](http://docs.datomic.com/pull.html)

## Copyright and license

Expand Down
Loading

0 comments on commit f31832b

Please sign in to comment.