om-tools

A ClojureScript library of general-purpose tools for building applications with Om and Facebook's React.

Leiningen dependency (Clojars): [prismatic/om-tools "0.2.2"]

This is an alpha release. The API and organizational structure are subject to change. Comments and contributions are much appreciated.

Introduction

om-tools aims to provide higher-order abstractions and utilities frequently useful when building components with Om's API.

DOM tools
Components tools
Mixin tools

DOM tools

om-tools.dom mirrors the om.dom namespace while using macros and minimal runtime overhead to make the following improvements:

Element attributes are not required to be JavaScript values and are optional. You don't need to use the #js reader macro or nil for no attributes.
More natural attribute names. We translate attributes like :class to :className and :on-click to :onClick to stay consistent with Clojure naming conventions.
Children can be in collections. You don't need to use apply if you have a sequence of children or use concat for combining sequences of siblings.

Example by comparison. First with om.dom:

(ns example
  (:require [om.dom :as dom :include-macros true]))

(dom/div
  nil
  (apply dom/ul #js {:className "a-list"}
         (for [i (range 10)]
           (dom/li #js {:style #js {:color "red"}}
                   (str "Item " i)))))

And with om-tools.dom:

(ns example
  (:require [om-tools.dom :as dom :include-macros true]))

(dom/div
  (dom/ul {:class "a-list"}
          (for [i (range 10)]
            (dom/li {:style {:color "red"}}
                    (str "Item " i)))))

Component tools

`defcomponent`

The om-tools.core/defcomponent macro defines Om component constructor functions. It has two main advantages over the ordinary defn & reify approach:

Adds Schema support to specify and validate the data when component is built.

One of React's most powerful features is prop validation, which allows a component's author to document and validate which properties a component requires and their types. This functionality is not utilized in Om because we use normal ClojureScript data structures as component inputs. However, with more complex input structures, documentation and validation are even more important.

Schema annotations are optional and validation is disabled by default.
Removes boilerplate code around using reify to instantiate objects with Om lifecycle methods. Component definitions become much smaller and easier to read.

Example of defcomponent including schema annotation:

(ns example
    (:require [om.core :as om :include-macros true]
              [om-tools.core :refer-macros [defcomponent]]
              [om-tools.dom :as dom :include-macros true]))

(defcomponent counter [data owner]
  (will-mount [_]
    (om/set-state! owner :n (:init data)))
  (render-state [_ {:keys [n]}]
    (dom/div
      (dom/span (str "Count: " n))
      (dom/button
        {:on-click #(om/set-state! owner :n (inc n))}
        "+")
      (dom/button
        {:on-click #(om/set-state! owner :n (dec n))}
        "-"))))

(om/root counter {:init 5}
         {:target js/document.body})

`defcomponentk`

The om-tools.core/defcomponentk macro is similar to defcomponent, except that it uses Plumbing's fnk destructuring syntax for constructor arguments. This enables succinct and declaritive definition of the structure and requirements of component input data.

It also provides additional useful utilities mentioned in Component Inputs.

Fnk-style Arguments

The args vector of defcomponentk uses Fnk syntax that's optimized for destructuring (nested) maps with keyword keys. It is the similar pattern used in our Fnhouse library to expressively declare HTTP handlers.

If you are unfamiliar with this syntax, here are some quick comparisons to default Clojure map destructuring.

{:keys [foo bar]}                    :: [foo bar]
{:keys [foo bar] :as m}              :: [foo bar :as m]
{:keys [foo bar] :or {bar 21}}       :: [foo {bar 21}]
{{:keys [baz qux]} :foo :keys [bar]} :: [[:foo baz qux] bar]

However, an important distinction between Clojure's default destructuring and Fnk-style is that specified keys are required by default. Rather than defaulting to nil, if a key that's destructured is missing and no default value is specified, an error is thrown.

By being explicit about component inputs, we are less error-prone and debugging is often easier because errors happen closer to the source.

Component Inputs

The map that's passed to defcomponentk arg vector has the following keys:

Key	Description
`:data`	The data (cursor) passed to component when built
`:owner`	The backing React component
`:opts`	The optional map of options passed when built
`:shared`	The map of globally shared data from om.core/get-shared
`:state`	An atom-like object for convenience to om.core/get-state and om.core/set-state!

Example

(ns example
  (:require-macros
    [schema.macros :refer [defschema]]
    [om-tools.core :refer [defcomponentk]])
  (:require
    [om.core :as om]))

(defschema ProgressBar
  {:value number
   (s/optional-key :min) number
   (s/optional-key :max) number})

(defcomponentk progress-bar
  "A simple progress bar"
  [[:data value {min 0} {max 100}] :- ProgressBar owner]
  (render [_]
    (dom/div {:class "progress-bar"}
      (dom/span
        {:style {:width (-> (/ value (- max min))
                            (* 100)
                            (int)
                            (str "%"))}}))))

;; Valid
(om/root progress-bar {:value 42}
  {:target (. js/document (getElementById "app"))})

;; Throws error: Key :value not found in (:wrong-data)
(om/root progress-bar {:wrong-data true}
  {:target (. js/document (getElementById "app"))})

;; Throws error: Value does not match schema
(schema.macros/with-fn-validation
  (om/root progress-bar {:value "42"}
    {:target (. js/document (getElementById "app"))})

State Proxy (experimental)

A component using defcomponntk can use the key, :state, to access an atom-like object that conveniently wraps om.core/get-state and om.core/set-state! so that we can read and write state idiomatically with deref, reset! and swap!.

(defcomponentk progress-bar
  "A simple progress bar"
  [[:data value {min 0} {max 100}] state]
  (render [_]
    (dom/div {:class "progress-bar"}
      (dom/span
        {:style {:width (-> (/ value (- max min))
                            (* 100)
                            (int)
                            (str "%"))}
         :on-mouse-enter #(swap! state assoc :show-value? true)
         :on-mouse-leave #(swap! state assoc :show-value? false))}
        (when (:show-value? @state)
          (str value "/" total))))))

It's important to note that while state looks and behaves like an atom, there is at least one minor difference: changes made by swap! and reset! are not immediately available if you deref in the same render phase.

Mixin tools

React provides mixin functionality to handle cross-cutting concerns and allow highly reusable component behaviors. While mixins are possible with Om, it does not provide much functionality to support this React feature. One issue is that you must create a React constuctor and specify it each time the component is built. This puts the responsibility of using mixins on both the component (create a constructor) and its parent (specify the constructor). Another issue is having to drop down to raw JavaScript functions, breaking you out of Om's data and state abstractions.

om-tools provides a defmixin macro in the om-tools.mixin namespace to define mixins. The syntax of defmixin follows same pattern as the component macros.

One last thing: the factory functions created by defcomponent/defcomponentk (ie (->component-name data)) encapsulate any custom constructor automatically. So a parent component no longer needs to be aware when a child uses mixins!

Here's how you could reimplement React's mixin example:

(ns example
  (:require
    [om-tools.core :refer-macros [defcomponentk]
    [om-tools.dom :as dom :include-macros true]
    [om-tools.mixin :refer-macros [defmixin]]))

(defmixin set-interval-mixin
  (will-mount [owner]
    (set! (. owner -intervals) #js []))
  (will-unmount [owner]
    (.. owner -intervals (map js/clearInterval)))
  (set-interval [owner f t]
    (.. owner -intervals (push (js/setInterval f t)))))

(defcomponentk tick-tock [owner state]
  (:mixins set-interval-mixin)
  (init-state [_]
    {:seconds 0})
  (did-mount [_]
    (.set-interval owner #(swap! state update-in [:seconds] inc) 1000))
  (render [_]
    (dom/p
      (str "React has been running for " (:seconds @state) " seconds."))))

See example for full version.

Community

Please feel free to open an issue on GitHub

For announcements of new releases, you can also follow on @PrismaticEng on Twitter.

We welcome contributions in the form of bug reports and pull requests; please see CONTRIBUTING.md in the repo root for guidelines.

drcode/om-tools