Using [] instead of ()

This is a quick tutorial around the use of () and [] in Reagent renderers.

Reagent is a terrific library. You get going fast and everything just kinda works.

But, eventually, you'll want to understand how some of that lovely magic happens. This tutorial looks at one aspect. One day, in the peace of a shower, or on that serene bike ride to work, your eyes will flick to the left and you'll wonder "wait, how exactly has this EVER worked for me all this time?". Which can be followed by other doubts: "if I don't understand this, what else don't I know?", which can lead to "do I really understand ANYTHING?". And, before you know it, you'll be over at your parent's house demanding to know if you were adopted.

Best to nip these things in the bud. Read on ...

Components

In an earlier tutorial Creating Reagent Components , we saw that the centerpiece of a Reagent/React component is a renderer function. Optionally, a Component might have other lifecycle functions, but a renderer function is central and mandatory.

We also saw that Reagent render functions turn data into hiccup: data -> hiccup

Meet greet

Here's an example Component:

(defn greet
  [name]
  [:div  "Hello " name])

No, wait, what? That's not a Component, that's a function.

Yes, indeed it is. And, right there, we have the nub of the issue.

It is only when greet is used in a particular way, that it is "promoted" to become the renderer for a Reagent Component. Unless you are paying attention, you might not even realise when that magic is happening, and not happening.

Right. So given use is king, let's look at two forms of it ...

Using Greet Via ()

If you use greet in a function call via (), it returns a vector with 3 elements:

(greet "You")
;; => [:div  "Hello " "You"]   ;; a vector of a keyword and two strings

(first (greet "You"))
;; => :div

(second (greet "You"))
;; => "Hello"

So, simply calling such function certainly doesn't magically create a Reagent Component. It just returns a vector.

Hmmm. How about we call greet within another function:

(defn greet-family-1
  [member1 member2 member3]
  [:div
    (greet member1)    ;; return value put into the vector
    (greet member2)    ;; and again 
    (greet member3)])  ;; and again

greet-family-1 returns a 4 element vector. And what's in that vector if we call it like this?

(greet-family-1 "Mum" "Dad" "Aunt Edith")

Because (greet "Mum") returns [:div "Hello " "Mum"], that's the 2nd element in the vector. And so on.

 [:div
    [:div  "Hello " "Mum"]          ;; <-- (greet "Mum") 
    [:div  "Hello " "Dad"]          ;; <-- (greet "Dad") 
    [:div  "Hello " "Aunt Edith"]]  ;; <-- (greet "Aunt Edith") 

Using Greet Via []

Let's keep greet the same, but change the way it is used:

(defn greet-family-2
  [member1 member2 member3]
  [:div
    [greet member1]      ;; not using ()
    [greet member2]     
    [greet member3]])  

Let's be crystal clear: [greet member1] is a two element vector, just like [1 2].

And, what would this call return?

(greet-family-2 "Mum" "Dad" "Aunt Edith")  

Answer:

 [:div
    [greet "Mum"]         
    [greet "Dad"]
    [greet "Aunt Edith"]]

So, greet is not called inside of greet-family-2. Instead, it is placed into a vector.

The Key Difference Between () and []

Here is the hiccup returned by greet-family-1.

 [:div
    [:div  "Hello " "Mum"]          ;; the return value of greet put in here
    [:div  "Hello " "Dad"]          ;; and again 
    [:div  "Hello " "Aunt Edith"]]  ;; and again

You'll notice this hiccup contains no references to greet. Only the values returned by calls to greet.

On the other hand, there are references to greet in the hiccup returned by greet-family-2

 [:div
    [greet "Mum"]         
    [greet "Dad"]
    [greet "Aunt Edith"]]

The Interpretation Of Hiccup

After renderers return hiccup, Reagent interprets it.

As it is interpreting hiccup, if Reagent sees a vector where the first element is a function, for example [greet "Mum"], it interprets that function as a renderer and it builds a React component around that renderer.

Let's pause and remember that a renderer function is the key, mandatory, central part of a Component. Defaults can be supplied for the other React lifecycle functions, like component-should-update, but a renderer must be supplied.

So Reagent recognises greet as a candidate renderer function and, if it is found in the right place (1st element of a vector), Reagent will mix it with other default lifecycle functions to form a full React/Reagent Component. It gives greet a, er, promotion.

The other elements of the vector, after greet, are interpreted as parameters to the renderer - in React terms, props.

Same DOM

Both approaches will result in the same final DOM!!

Doesn't that effectively mean they are the same? Is there any reason to favour one over the other?

The difference is subtle (but important): the use of [] means you get a distinct React Component which will have its own React lifecycle, and can be rerendered (new VDOM produced) independently of its siblings. And that doesn't happen if you use ().

Next Up

We've now seen how we can use functions and [] to create Components. In the next tutorial, we'll understand how and when these Components update.

Appendix #1

hiccup can be created like any normal cljs data structure. You don't have to use literals.

Our version of greet-family-1 from above returns something of a 4 element vector literal:

(defn greet-family-1
  [member1 member2 member3]
  [:div
    (greet member1)    
    (greet member2)  
    (greet member3)]) 

Here's a rewrite in which the hiccup is less literal and more generated:

(defn greet-family-1b       ;; a re-write of greet-family-1
  [& members]
  (into [:div] (map greet members)))

When called with 3 parameters, the 1 and 1b versions of this function return the same hiccup:

(= (greet-family-1  "Mum" "Dad" "Aunt Edith") 
   (greet-family-1b "Mum" "Dad" "Aunt Edith"))
;; => true

Appendix #2

When interpreting hiccup, Reagent regards vectors as special, and it has some demands about their 1st element.

In Reagent hiccup, the 1st element of a vector must always be something it can use to build a Component.

Reagent can use greet to build a Component, so that works. So does :div because Reagent knows what Component you mean. And there are a few other options.

So this is okay: [greet ...] and so is this [:div ...]

But if your hiccup contains a vector like [1 2 3], then you'll get an error because Reagent can't use 1 to build a Component.

So this code has a problem:

(defn greet-v
   [v]
   (into [:div] (map greet v)))

(defn greet-family
   []
   [greet-v ["Mum" "Dad" "Aunt Edith"]])  ;; <-- error here

Notice the vector ["Mum" "Dad" "Aunt Edith"] in the hiccup. Reagent will try to build a Component using "Mum" (1st element in a vector) and, when that doesn't work, it will report an error.