diff --git a/README.md b/README.md index 019fc76f..dbf7f065 100644 --- a/README.md +++ b/README.md @@ -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 +[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"]] - ...) +``` + + org.omcljs + om + 1.0.0-beta1 + ``` -### 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 - - -
- - - -``` +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 @@ -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 diff --git a/README.old.md b/README.old.md new file mode 100644 index 00000000..019fc76f --- /dev/null +++ b/README.old.md @@ -0,0 +1,251 @@ +# 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. + +## 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 + +```clojure +(ns example + (:require [om.core :as om] + [om.dom :as dom])) + +(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](http://leiningen.org/) +installed, to build an example run: + +``` +lein cljsbuild once +``` + +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). + +## 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"]] + ...) +``` + +### React with Add-Ons + +If you would rather use React with Add-Ons you can configure this +with Maven's exclusions feature: + +```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"]] + ...) +``` + +### Build configuration + +For local development your +[lein-cljsbuild](http://github.com/emezeske/lein-cljsbuild) settings +should look something like this: + +```clojure +:cljsbuild { + :builds [{:id "dev" + :source-paths ["src"] + :compiler { + :main main.core + :output-to "main.js" + :output-dir "out" + :optimizations :none + :source-map true}}]} +``` + +Your markup should look something like the following: + +```html + + +
+ + + +``` + +For production your [lein-cljsbuild](http://github.com/emezeske/lein-cljsbuild) settings should look something +like this: + +```clojure +:cljsbuild { + :builds [{:id "release" + :source-paths ["src"] + :compiler { + :main main.core + :output-to "main.js" + :optimizations :advanced + :pretty-print false}}]} +``` + +## Contributing + +Please contact me via email to request an electronic Contributor +Agreement. Once your electronic CA has been signed and returned to me +I will accept pull requests. + +## Community + +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/) + +## Copyright and license + +Copyright © 2013-2017 David Nolen + +Licensed under the EPL (see the file epl.html).