Lambda Island

React’s component based approach means you don’t have to reinvent the wheel, there are literally thousands of building blocks freely available.

When using React components from Reagent there are a few things to watch out for, this episode will show you how to use some popular React components from Reagent, and point out useful constructs and patterns.

You’ll also get to see some of the new cljs.main feature that landed in ClojureScript 1.10.

Transcript

One of the great things about React is the large amount of ready made components for you to pick from, but when using these components with Reagent and ClojureScript there are a few things to watch out for. This episode will walk you through a few practical examples, using popular open source React components.

You’ll also get a demonstration of the cljs.main functionality that came out in ClojureScript 1.10.

This episode will make use of the Clojure CLI tools that came out with Clojure 1.9. For Linux and OS X you can follow the Clojure Getting Started guide, you’ll find the link in the show notes.

$ clj --help

Usage: clojure [dep-opt*] [init-opt*] [main-opt] [arg*]
       clj     [dep-opt*] [init-opt*] [main-opt] [arg*]

The clojure script is a runner for Clojure. clj is a wrapper
for interactive repl use. These scripts ultimately construct and
invoke a command-line of the form:

java [java-opt*] -cp classpath clojure.main [init-opt*] [main-opt] [arg*]

The Clojure CLI tools are not yet available for Windows, but the ClojureScript Quick-Start Guide has instructions on how to run cljs.main directly from the ClojureScript release JAR.

What I love about this new generation of tooling is that you need so little to get started. You don’t need to generate dozens of files, just a deps.edn with a few dependencies and you’re off to the races.

You’ll need Clojure and ClojureScript of course, as well as Reagent, since that’s what this episode is all about.

{:deps {org.clojure/clojure       {:mvn/version "1.9.0"}
        org.clojure/clojurescript {:mvn/version "1.10.238"}
        reagent                   {:mvn/version "0.8.0"}}}

Time to add a first ClojureScript source file. The "src" directory is the default place the compiler will look for those. I’ll use ep41 as a common namespace prefix, so this file will contain the ep41.slider namespace.

$ mkdir -p src/ep41
$ touch src/ep41/slider.cljs
$ tree
.
├── deps.edn
└── src
    └── ep41
        └── slider.cljs

2 directories, 2 files

For starters let’s make sure things are hooked up correctly, so you are able to compile ClojureScript and run it in the browser. enable-console-print! is there to make the output of println go to the browser console. Finally print out the evergreen phrase "hello, world".

(ns ep41.slider)

(enable-console-print!)

(println "hello, world!")

That’s all you need, with these two files in place, you can kick off the ClojureScript compiler.

--main cljs.main tells Clojure to invoke the ClojureScript compiler. You want --watch the "src" directory for changes, so they get recompiled automatically. Finally you tell the compiler to use ep41.slider as the main namespace, and to start a REPL.

This might take a moment, but after a little while your browser should pop up with this ClojureScript welcome page. If you open the JavaScript console you’ll find “hello, world!” there among some other debug messages, and if you switch back to your terminal you’ll see that you now have a ClojureScript REPL awaiting your command.

clj --main cljs.main --watch src --compile ep41.slider --repl

Try a js/alert and you’ll see that it’s your browser that executes the ClojureScript you type into the REPL.

(js/alert "mayonnaise")

Note that, when running this way, ClojureScript writes its compilation logs to a file called out/watch.log. It’s a good idea to use tail -f in a separate terminal to keep an eye on it. If your code fails to compile this is where you’ll find out what’s wrong.

tail -f out/watch.log

The ClojureScript welcome page will suggest you make your own index.html, so you can change the HTML that your app will load into. Simply add it to the root of the project, next to deps.edn. Copy the provided template, and add these CSS styles, as well as an extra <div> with an id of "app", so you have a place to mount the Reagent app.

Remember you can find this code in the transcript and on Github, so no need to type it in by hand.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <style>
      .slider {
        border-radius: 4px;
        background-color: rgb(240, 240, 232);
        position: relative;
        margin: 5px 3px 10px;
        width: 450px;
        height: 50px;
      }
      .slider-block {
        position: absolute;
        width: 50px;
        height: 50px;
        border-radius: 4px;
        background-color: rgb(130, 181, 198);
      }
    </style>
  </head>
  <body>
    <div id="app"></div>
    <script src="out/main.js" type="text/javascript"></script>
  </body>
</html>

Time to get reactive! Pull in reagent.core as r, grab the app div you just added, and render a paragraph element.

Assuming your REPL is still open this code will recompile as soon as you save it. Do a browser refresh to load the new index.html and your freshly compiled app. (Ctrl-R/Cmd-R or F5).

(ns ep41.core
  (:require [reagent.core :as r]))

(enable-console-print!)

(r/render [:p "hello, world!"]
          (js/document.getElementById "app"))

I’ll show you how to use react-motion with Reagent. At 200’000 downloads per week you could say it’s a fairly popular package.

Like most popular packages react-motion is available on CLJSJS, so adding it to the project is straightforward, you add it to deps.edn like any other Maven or Clojars dependency.

{:deps {,,,
        cljsjs/react-motion {:mvn/version "0.5.2-0"}}}

Restart cljs.main so it picks up the dependency. You can exit the REPL with Ctrl-D.

I’m going to recreate the simple transition demo that’s included with react-motion.

This is what the code of that demo looks like using JSX. This is a bit simplified, it’s just to have an idea of what we want to translate to ClojureScript.

There’s a button with a mouse-down handler which toggles a bit of component-local state on and off, and then there’s the actual slider, which is wrapped in a callback, which is passed to the Motion component.

You pass Motion a style property, a JavaScript object whose values are “springs”. These specify how to do the interpolation. In this case depending on the current state we want to move towards 400, or towards 0, but in a smooth, springy way.

Inside the Motion component you would normally put any child elements, but in this case Motion expects you to put a callback there which renders the element, based on an interpolated value of style.

import {Motion, spring} from 'react-motion';

function render() {
  <div>
    <button onMouseDown={this.handleMouseDown}>
      Toggle
    </button>

    <Motion style={{x: spring(this.state.open ? 400 : 0)}}>
     {({x}) =>
       <div className="slider">
         <div className="slider-block" style={{transform: `translate3d(${x}px, 0, 0)`}} />
       </div>
     }
    </Motion>
  </div>
}

Now let’s try to translate that into Reagent, I’ll first do a one-to-one, naive translation, and then look at the extra bits needed to make it actually work. Finally I’ll pull out all that plumbing into a wrapper component, so that the final result again looks more ore less how you would expect it to.

Start by adding cljsjs.react-motion to the namespace declaration. This “synthetic” namespace makes sure react-motion gets loaded. After that you access it through the JavaScript globals it defines, in this case there’s a ReactMotion global, which contains Motion and spring.

(ns ep41.core
  (:require [reagent.core :as r]
            [cljsjs.react-motion]))

(def Motion js/ReactMotion.Motion)
(def spring js/ReactMotion.spring)

Instead of component-local state use a reagent atom called toggled?.

Define a single component named app, which renders the slider, and then update the render call to use this app component.

You can take a moment to look through that code, it’s really a direct translation of the JavaScript code you just saw.

There’s a button with a mouse-down handler, which toggles the atom’s value on and off. Then there’s a actual slider, wrapped in a callback, wrapped inside the Motion component.

Motion still receives a :style property mapping keys to “springs”, and then provides interpolated values to the callback, where they are used to do the actual rendering.

(def toggled? (r/atom false))

(defn app []
  [:div
   [:button {:on-mouse-down #(swap! toggled? not)} "Toggle"]
   [Motion {:style {:x (spring (if @toggled? 400 0))}}
    (fn [style]
      [:div.slider
       [:div.slider-block
        {:style {:transform (str "translate3d(" (:x style) "px, 0, 0)")}}]])]])

(r/render [app] (js/document.getElementById "app"))

This looks great, except for the small fact that it does not work. There are two kinds of problems we need to deal with: interop between ClojureScript and JavaScript, and compatibility between Reagent and React.

We’re used to dealing with ClojureScript vectors and maps, but JavaScript libraries expect plain arrays and objects, so in both directions you need to make sure you’re using the right type of data structures, and convert them when necessary.

If your interop is a little rusty then I recommend Lambda Island episode 4, about ClojureScript/JavaScript interop for a refresher.

Beyond that we also need to handle Reagent/React compatibility. Reagent has its own representation of components and elements, so before using a React component like react-motion you need to convert it into a Reagent one.

[]
#js []

{}
#js {}

Let’s walk through the code with these things in mind.

Motion is a React class, to use it inside a Reagent component you use adapt-react-class.

[(r/adapt-react-class Motion) ,,,]

Since you’re already defining Motion higher up you could do the conversion there, which is a bit more elegant. Alternatively there’s this this “smily bird” pseudo-element which lets you use React components in your Hiccup directly.

[:> Motion ,,,]

The first argument to Motion is the map of props. Reagent will handle this one, so it should be a regular ClojureScript map, but any values therein are passed on to Motion, so those should use plain JavaScript collections.

Since this is a map literal adding a #js reader tag is enough.

[:> Motion {:style #js {:x (spring (if @toggled? 400 0))}}
  ,,,]

ClojureScript’s fn creates regular JavaScript functions, so you can use one as a callback just fine, but you do have to take care of the style argument, and of the function’s return value.

style is a JavaScript object, so the easiest way to get the x property out is with .-x.

[:> Motion {:style #js {:x (spring (if @toggled? 400 0))}}
 (fn [style]
   (let [x  (.-x style)]
     ,,,
     ))]

Now let’s look at this callback’s return value, using Hiccup syntax may seem natural to us, but to a React component those ClojureScript vectors are as alien as polar bears to Iberians.

With Reagent’s as-element you can turn that Hiccup into a plain React element, which Motion will be more than happy to render for you.

[:> Motion {:style #js {:x (spring (if @toggled? 400 0))}}
 (fn [style]
   (let [x (.-x style)]
     (r/as-element
      [:div.slider
       [:div.slider-block
        {:style {:transform (str "translate3d(" x "px, 0, 0)")}}]])))]

And with that we should have working code again! Save the file, and reload it. You can do a browser refresh, or do it from the REPL with (require 'ep41.slider :reload)

(require 'ep41.slider :reload)

Now what would it look if we pulled all that boilerplate into a separate component,a wrapper which makes ReactMotion appear to be just another Reagent component?

Have it take a map of props containing a map of styles, and a callback, and turn the styles into a JavaScript object before passing them on to ReactMotion.

Wrap the callback in another function, so you can convert both the input and the output.

This function is a plain Reagent form-1 component. With clj->js and js->clj it converts between ClojureScript and JavaScript, and with the “smily bird” and reagent.core/as-element it bridges the gap between Reagent and React.

(defm motion [{style :style} callback]
  [:> Motion {:style (clj->js style)} 
   (fn [style]
     (r/as-element (callback (js->clj style :keywordize-keys true))))])

Now you can get rid of all that special treatment in your own application code. You can drop the call to as-element, as well as the let, since you can now destructure the style map directly in the argument list. This is very similar to what the original JavaScript code did with ES6 object destructuring.

(defn app []
  [:div
   [:button {:on-mouse-down #(swap! toggled? not)} "Toggle"]
   [motion {:style {:x (spring (if @toggled? 400 0))}}
    (fn [{x :x}]
      [:div.slider
       [:div.slider-block
        {:style {:transform (str "translate3d(" x "px, 0, 0)")}}]])]])

So to recap, you’ve seen how to convert React components to Reagent, and how to turn Reagent-style hiccup syntax into a React element. How about going the other way, using a Reagent component from React, or using React elements inside Reagent?

;; React component -> Reagent component
(reagent.core/adapt-react-class react-component)
[:> react-component ,,,]

;; Hiccup -> React element
(reagent.core/as-element [:p "hiccup"])

;; Reagent component -> React component
??

;; React element -> Hiccup
??

I’ll demonstrate these things using the “ultimate pagination” component. This package is again available on CLJSJS. Now what if you want to use a package that isn’t yet on CLJSJS? In that case I recommend adding it yourself. The process is well documented, and there are hundreds of example packages to learn from. You submit a pull request with a recipe for building the package, and it will get built and added to the repository automatically.

{:deps {,,,
        cljsjs/react-ultimate-pagination {:mvn/version "1.2.0-1"}}}

To have something to paginate I’m going to render a table with types of tea, scraped from Wikipedia. There’s a bit of code here already, but I’ll walk you through.

The namespace includes reagent, and I’ve already added the pagination component as well, we’ll be hooking that one up in a bit.

(ns ep41.teas
  (:require [reagent.core :as r]
            [cljsjs.react-ultimate-pagination]))

table and app are two regular Reagent components, they render a div, containing a header, and a HTML table with four columns, and bunch of rows.

The only thing that might seem odd here is the use of the backtick syntax outside of macros. I find it very useful though for defining Hiccup forms, since it’s essentially a templating system.

(defn table [rows]
  `[:table
    [:thead
     [:tr ~@(for [x ["Title" "Name" "Type" "Origin"]]
              [:th x])]]
    [:tbody
     ~@(for [row rows]
         `[:tr ~@(for [cell row] [:td cell])])]])

(defn app []
  [:div
   [:h1 "List of Teas"]
   [table (current-page-data)]])

There’s a single atom to keep the application state: the current page number, the number of items per page, and the data itself.

(def state (r/atom {:page 1
                    :page-size 10
                    :data []}))

This data is loaded from a JSON files with JavaScript’s fetch API, and added to the state atom. The current-page-data helper function uses the current page number and page size to only return the rows that are currently visible.

(defn fetch-data []
  (-> (js/fetch "teas.json")
      (.then #(.json %))
      (.then (fn [json]
               (swap! state assoc :data json)))))

(defn current-page-data []
  (let [{:keys [page page-size data]} @state]
    (->> data
         (drop (* (dec page) page-size))
         (take page-size))))

Finally there are two top-level forms, one to render the app, and one to fetch the data.

(r/render [app] (js/document.getElementById "app"))
(fetch-data)

Start the REPL again so it picks up the new dependency, while you’re add it also pass it the name of the new namespace, so it uses that as the main entry point.

Once it’s finished downloading the new dependency a browser window pops up again. This is what the app looks like so far, we have the table, but we’re only seeing the first ten results. Time to add in that pagination!

clj --main cljs.main --watch src --compile ep41.tea-table --repl

Here’s an example of how to use ReactUltimatePagination, I’ve adapted this code straight from the package’s README.

You first define a bunch of small components, one for each type of pagination button, and a wrapper that acts as a container for the rest. With these you build up a configuration map, and pass that map to createUltimatePagination, which then returns the actual pagination component.

Now you can use that like any other component, passing it the current page, total number of pages, and an on-change handler.

The interesting thing to note is that this package doesn’t itself render any elements, everything is delegated to the components you provide.

function Page(props) {
  return <button onClick={props.onClick}>{props.value}</button>;
}

function Ellipsis(props) { ... }
function FirstPageLink(props) { ... }
function PreviousPageLink(props) { ... }
function NextPageLink(props) { ... }
function LastPageLink(props) { ... }

function Wrapper(props) {
  return <div>{props.children}</div>
}

var itemTypeToComponent = {
  'PAGE': Page,
  'ELLIPSIS': Ellipsis,
  'FIRST_PAGE_LINK': FirstPageLink,
  'PREVIOUS_PAGE_LINK': PreviousPageLink,
  'NEXT_PAGE_LINK': NextPageLink,
  'LAST_PAGE_LINK': LastPageLink
};

var UltimatePagination = ReactUltimatePagination.createUltimatePagination({
  itemTypeToComponent: itemTypeToComponent,
  WrapperComponent: Wrapper
});

Let’s translate that to Reagent. I’ve started by creating the button and wrapper components.

There are a few things to note here, while these are regular Reagent components, the properties like onClick and isDisabled will be coming directly from ReactUltimatePagination, so we need to use the keys that ReactUltimatePagination uses, which is why they are camelcased rather than kebap-case.

When you look at the wrapper component, you see that the children are passed in as a prop, as they are in React, rather than as positional arguments. If you’ve used React directly this should look familiar, but it’s different from Reagent and so something to look out for.

Another thing is that these children are React elements, don’t we need to convert them to Hiccup first? Turns out that’s not necessary, you can use React elements, or in this case, fragments directly inside your Reagent forms.

(defn page [{:keys [value isActive onClick isDisabled]}]
  [:button {:style (if isActive {:font-weight "bold"}), :on-click onClick, :disabled isDisabled} value])

(defn ellipsis [{:keys [onClick isDisabled]}]
  [:button {:on-click onClick, :disabled isDisabled} "..."])

(defn first-page-link [{:keys [onClick isDisabled]}]
  [:button {:on-click onClick, :disabled isDisabled} "<<"])

(defn last-page-link [{:keys [onClick isDisabled]}]
  [:button {:on-click onClick, :disabled isDisabled} ">>"])

(defn next-page-link [{:keys [onClick isDisabled]}]
  [:button {:on-click onClick, :disabled isDisabled} ">"])

(defn previous-page-link [{:keys [onClick isDisabled]}]
  [:button {:on-click onClick, :disabled isDisabled} "<"])

(defn wrapper [{:keys [children]}]
  [:div {:style {:padding "1em 0"}}
   children])

Next you create the configuration object that you can pass to createUltimatePagination. This is where we’re meeting a new type of conversion function. This time we have Reagent components that we want to pass into the world of React, so we need to “reactify” them first, turning them into plain React components. Also notice the #js reader literals, since createUltimatePagination expects JavaScript objects.

I could have used the clj->js function as well, but I prefer to use reader literals whenever possible. They’re processed at compile time, and don’t have to traverse data structures recursively, making them a lot faster.

The result of createUltimatePagination is a React component, which you then turn into a Reagent one with adapt-react-class, this is the equivalent of the “smily bird” I used with the slider.

(def pagination-config
  #js {:itemTypeToComponent
       #js {:PAGE               (r/reactify-component page)
            :ELLIPSIS           (r/reactify-component ellipsis)
            :FIRST_PAGE_LINK    (r/reactify-component first-page-link)
            :LAST_PAGE_LINK     (r/reactify-component last-page-link)
            :NEXT_PAGE_LINK     (r/reactify-component next-page-link)
            :PREVIOUS_PAGE_LINK (r/reactify-component previous-page-link)}
       :WrapperComponent (r/reactify-component wrapper)})

(def pagination
  (r/adapt-react-class
   (.createUltimatePagination js/ReactUltimatePagination pagination-config)))

That was a good bunch of setup again, but you now have a pagination component that you can use like any other Reagent component. I’ve added some helpers which you’re not seeing, to get the current page, total number of pages, and to change the current page, and with that this looks pretty clean to me. Only the camelcased props give away its React origins.

(defn current-page []
  (:page @state))

(defn total-pages []
  (let [{:keys [page-size data]} @state]
    (max 1 (Math/ceil (/ (count data) page-size)))))

(defn set-page! [page]
  (swap! state assoc :page page))

(defn app []
  [:div
   [:h1 "List of Teas"]
   [table (current-page-data)]
   [pagination {:currentPage (current-page)
                :totalPages  (total-pages)
                :onChange    set-page!}]])

And here’s what that looks like in the browser. I hope I managed to show you that there’s no need to reinvent the wheel. Both Clojure and ClojureScript are hosted languages, precisely because it allows us to leverage a massive pre-existing ecosystem, and so getting familiar with the idioms to do so really pays off in the long run.

Using React Components with Reagent