re-frame workshop

Game board: solitaire/board.cljs

initial-board:

[[:blocked :blocked :peg :peg   :peg :blocked :blocked]
 [:blocked :blocked :peg :peg   :peg :blocked :blocked]
 [:peg     :peg     :peg :peg   :peg :peg     :peg]
 [:peg     :peg     :peg :empty :peg :peg     :peg]
 [:peg     :peg     :peg :peg   :peg :peg     :peg]
 [:blocked :blocked :peg :peg   :peg :blocked :blocked]
 [:blocked :blocked :peg :peg   :peg :blocked :blocked]]

Exercise 2

1. Copy exercises/ex_02/views.cljs over the original views.cljs
2. You’ll find already defined components that render each type of a field
3. Your task is to change board-view to render all the fields of the board
4. Use the comments in the file for guidance

• 🕑: 10 mins
• Solution: exercises/ex_02/solution/views.cljs

Application state: app-db

(def default-db
  {:board board/initial-board})

• Not accessed or changed directly
• Think of it as a “database”

Accessing state: subscriptions

• Subscriptions are “named queries” to our database
• A subscription is a vector [:name arg1 arg2 …]
  • Example: [::field 4 4]
• Defined with reg-sub

(rf/reg-sub
 ::field          ; <- subscription name
 (fn [db [_ x y]] ; <- second arg: “query vector”
   {:x x
    :y y
    :type (get-in db [:board y x])}))

Using subscriptions in components

(defn board-view []
  (let [[width height] @(rf/subscribe [::subs/board-dimensions])]
    (into
     [:div.board]
     (for [y (range height)
           x (range width)]
       [field-view @(rf/subscribe [::subs/field x y])]))))

• Subscriptions are reactive: when the return value changes, all components dereferencing it are rerendered

Dependent subscriptions

(rf/reg-sub
 ::board
 (fn [db _]
   (:board db)))

(rf/reg-sub
 ::board-dimensions
 :<- [::board] ; instead of the entire db
 (fn [board _]
   (board/dimensions board)))

• Subscriptions can depend on other subscriptions

Selecting fields

• We add a new key to our state: :selected-field

(def default-db
  {:board board/initial-board
   :selected-field [3 1]})

Exercise 3

1. Copy files in exercises/ex_03 over existing files
2. Edit solitaire/subs.clj
3. In the ::field subscription, add a new key, :selected?, telling us whether the peg is selected (highlighted)
4. Use the comments in the file for guidance

• 🕑: 10 mins
• Solution: exercises/ex_03/solution/subs.cljs

Events

(rf/reg-event-db
 ::start
 (fn [db event-vector]
   (assoc db :board board/initial-board)))

• Events tell re-frame to change the state
• They look like subscriptions: [:name arg1 arg2 …]
• Pure functions!

Dispatching events

(defn field-peg [{:keys [selected? x y]}]
  [:div.field
   [:div.peg
    {:class (when selected? "peg--selected")
     :on-click #(rf/dispatch [::events/select-field x y])}]])

• Events are triggered (dispatched) by calling rf/dispatch
• Typically from a component’s DOM event handler

Exercise 4

1. Copy files in exercises/ex_04 over existing files
2. Edit solitaire/events.clj
3. In the ::select-field subscription, add code to change :selected-field in db as necessary
4. Use the comments in the file for guidance

• 🕑: 10 mins
• Solution: exercises/ex_04/solution/events.cljs

Exercise 5

1. Copy files in exercises/ex_05 over existing files
2. Edit solitaire/views.clj
3. In the field-empty component, add code to dispatch the ::events/make-move event on click
4. Use the comments in the file for guidance

• 🕑: 10 mins
• Solution: exercises/ex_05/solution/views.cljs

Effectful events

(rf/reg-event-fx
 ::end-game
 (fn [{db :db} _]
   {:db (assoc db :status :game-over)
    :alert "Game over!"}))

• reg-event-fx instead of reg-event-db
• Input no longer just db, but a map that contains :db
• Output no longer just db, but a map that contains :db and other things
  • :dispatch, :dispatch-n, :dispatch-later, :http…
• Still a pure function!

Ending and restarting game

• We add a new key to our state: :status (can be :not-started, :in-progress, or :game-over)

(def default-db
  {:board          board/initial-board
   :selected-field nil
   :status         :not-started})

Copy files from exercises/final to see it in action

Do’s and Don’ts

• Have a schema/spec for your app-db
• Have separate db/views/subs/events files per app section when your app is large
• Keep views as simple as possible
• Test your subscriptions and events
• Prefer simple subscriptions over fewer generic ones

Where to go from here

• Explore re-frame’s documentation
• Expand the game you’ve created today!
• Look at open-source projects using re-frame

Questions?