reacl2.core — reacl 2.2.3

clj

Supporting macros for Reacl.

cljs

This namespace contains the Reacl core functionality.

Define classes with the macros defclass or class.

Create return values for a message handler or livecycle methods with return and merge-returned. The auxiliary functions for return values returned-actions, returned-app-state, returned-local-state, returned-messages, returned? will usually only be needed in unit tests.

In event handlers you will usually need to call send-message!.

To instantiate classes that have app-state you need to create bindings with bind, bind-local, use-reaction or use-app-state, and sometimes reactions with reaction or pass-through-reaction.

Sometimes modifications of the created elements are needed via keyed, refer, [[redirect-actions]], reduce-action, action-to-message or map-action.

To finally render a class to the DOM use render-component and handle-toplevel-action.

An older API consists of the functions opt, opt?, no-reaction.

action-to-message cljs

(action-to-message elem target)

(action-to-message elem target pred)

Clones the given element so that actions are sent as messages to the given target component. If a function pred is given, then it is applied to each action, and if it returns a truthy value that value is sent as a message to target. Otherwise the action is passed upwards.

bind cljs

(bind parent)

(bind parent lens)

Returns a binding that embeds a child's app-state into the app-state of the given parent component using the given lens, which defaults to the identity lens.

bind-local cljs

(bind-local parent)

(bind-local parent lens)

Returns a binding that embeds a child's app-state into the local-state of the given parent component using the given lens, which defaults to the identity lens.

binding? cljs

(binding? v)

Returns true if v is a binding.

class clj macro

(class ?name & ?stuff)

Create a Reacl class.

The syntax is

(class <name> <this-name> <app-state-name>? [<param> ...]
  <clause> ...)

<name> is a name for the class, for debugging purposes.

This is equivalent to defclass but without binding the new class to a variable. The name specified here should be a string instead, and is used as the display name of the class.

class-name cljs

(class-name class)

Returns the display name of the given Reacl class

defclass clj macro

(defclass ?name & ?stuff)

Defines a Reacl class.

The syntax is

(defclass <name> <this-name> <app-state-name>? [<param> ...]
  <clause> ...)

<name> is the symbol the class is bound to, and is used together with the current namespace as the display name of the class for debugging purposes.

The presence of app-state-name determines if the class has an app-state or not.

Each <clause> has the format <clause-name> <clause-arg>. More specifically, it can be one of the following:

 render <renderer-exp>
 local [<local-name> <local-expr>] ...]
 local-state [<local-state-name> <initial-state-exp>]
 refs [<ref-name> ...]
 validate <validation-expr>
 handle-message <messager-handler-exp>
 <lifecycle-method-name> <lifecycle-method-exp>

Of these, only the render clause is mandatory, all the others are optional.

A number of names are bound in the various clauses:

• <this-name> is bound to the component object itself
• <app-state-name> is bound to the app-state of the component
• the <param> ... names are the explicit arguments of instantiations
• the <local-name> names are bound to the values of the <local-expr> expressions, which can refer to the variables above
• <local-state-name> is bound to the component-local state if there is a local-state clause

A local clause allows binding additional local variables upon instantiation. The syntax is analogous to let.

A local-state clause allows specifying a variable for the component's local state, along with an expression for the value of its initial value.

A refs clause specifies names for references to sub-components, which can be associated with components via ref attributes or refer in the render expression.

<renderer-exp> is an expression that renders the component, and hence must return a virtual dom node.

<validation-exp> is evaluated on each instantiation of the class for its side-effects, which may be raising an error or an assertion, if the app-state or the arguments violate some invariant.

The handle-message function accepts a message sent to the component via send-message! or return. It's expected to return a value specifying a new application state, a new component-local state, actions or new messages, or a combination there of, via return.

A class can be invoked as a function to yield a component. If the class does not have an app-state, it just takes values for the paramters, like ordinary function applications:

(<class> <arg> ...)

If the class has an app-state, then a binding has to be specified as the first argument, followed by values for the paramters:

(<class> <binding> <arg> ...)

The binding specifies what the app-state of the component will be, as well as how to handle changes to the app-state by that component. Bindings are created with bind, [[bind-locally]] and use-reaction, and rarely with use-app-state.

A lifecycle method can be one of:

component-will-mount component-did-mount component-will-receive-args should-component-update? component-will-update component-did-update component-will-unmount

These correspond to React's lifecycle methods, see here:

http://facebook.github.io/react/docs/component-specs.html

(component-will-receive-args is similar to componentWillReceiveProps.)

Each right-hand-side <lifecycle-method-exp>s should evaluate to a function. The arguments, which slightly differ from the corresponding React methods, can be seen in the following list:

(component-will-mount) The component can send itself messages in this method, or optionally return a new state via return. If that changes the state, the component will only render once.

(component-did-mount) The component can update its DOM in this method. It can also return a new state via return, but you should take extra care to not create an endless loop of updates here.

(component-will-receive-args next-arg1 next-arg2 ...) The component has the chance to update its local state in this method by sending itself a message or optionally return a new state via return.

(should-component-update? next-app-state next-local-state next-arg1 next-arg2 ...) This method should return if the given new values should cause an update of the component (if render should be evaluated again). If it's not specified, a default implementation will do a (=) comparison with the current values. Implement this, if you want to prevent an update on every app-state change for example.

(component-will-update next-app-state next-local-state next-arg1 next-arg2 ...) Called immediately before an update.

(component-did-update prev-app-state prev-local-state prev-arg1 prev-arg2 ...) Called immediately after an update. The component can update its DOM here.

(component-will-unmount) The component can cleanup it's DOM here for example.

Note that for classes that don't have an app-state or local-state, the corresponding arguments to these livecycle methods will simply be nil.

Example:

  (defrecord New-text [text])
  (defrecord Submit [])
  (defrecord Change [todo])

  (reacl/defclass to-do-app
    this app-state []

    local-state [local-state ""]

    render
    (dom/div
     (dom/h3 "TODO")
     (dom/div (map (fn [todo]
                     (-> (to-do-item (reacl/reactive todo (reacl/reaction this ->Change) this)
                         (reacl/keyed (str (:id todo)))))
                   (:todos app-state)))
     (dom/form
      {:onsubmit (fn [e _]
                   (.preventDefault e)
                   (reacl/send-message! this (Submit.)))}
      (dom/input {:onchange 
                  (fn [e]
                    (reacl/send-message!
                     this
                     (New-text. (.. e -target -value))))
                  :value local-state})
      (dom/button
       (str "Add #" (:next-id app-state)))))

    handle-message
    (fn [msg]
      (cond
       (instance? New-text msg)
       (reacl/return :local-state (:text msg))

       (instance? Submit msg)
       (let [next-id (:next-id app-state)]
         (reacl/return :local-state ""
                       :app-state
                       (assoc app-state
                         :todos
                         (concat (:todos app-state)
                                 [(Todo. next-id local-state false)])
                         :next-id (+ 1 next-id))))

       (instance? Delete msg)
       (let [id (:id (:todo msg))]
         (reacl/return :app-state
                       (assoc app-state
                         :todos 
                         (remove (fn [todo] (= id (:id todo)))
                                 (:todos app-state)))))

       (instance? Change msg)
       (let [changed-todo (:todo msg)
             changed-id (:id changed-todo)]
         (reacl/return :app-state
                       (assoc app-state
                         :todos (mapv (fn [todo]
                                        (if (= changed-id (:id todo) )
                                          changed-todo
                                          todo))
                                      (:todos app-state))))))))

focus cljs

(focus binding lens)

Returns a binding that appends the given lens to the given binding, so that a child component only uses a smaller part of the bound value as its app-state.

get-dom cljs

(get-dom thing)

Get a (real) DOM node from an object that contains one, typically a reference.

handle-toplevel-action cljs

(handle-toplevel-action f)

Returns a value to be passed to render-component, which specifies how to handle toplevel actions.

All actions reaching the toplevel are passed to (f app-state action):

• with the current state of the application, where
• f may have a side effect on the browser or initiate some Ajax request etc., and
• must use return to return a modified application state or to send some message back to a component.

Note that you must only use return so send a message immediately to a component (like the id of an Ajax request), and send-message! only to send a message later, from an asynchronous context, to a component (like the result of an Ajax request).

has-app-state? cljs

(has-app-state? class)

Returns if the given class creates components with an app-state or not.

has-class? cljs

(has-class? clazz element)

Find out if an element was generated from a certain Reacl class.

instantiate-toplevel cljs

(instantiate-toplevel clazz & args)

(instantiate-toplevel clazz app-state & args)

(instantiate-toplevel clazz opts & args)

(instantiate-toplevel clazz opts app-state & args)

Creates an instance (a React component) of the given class. For testing purposes mostly.

keep-state cljs

Singleton value which can be used in return to indicate no (application or local) state change, which is different from setting it to nil.

keep-state? cljs

(keep-state? x)

Check if an object is the keep-state object.

keyed cljs

(keyed elem key)

Returns an element identical to the given elem, but replacing its key property.

map-action cljs

(map-action elem f & args)

Clones the given element so that all actions coming out of it are piped through f.

merge-returned cljs

(merge-returned & rets)

Merge the given return values from left to right. Actions and messages are appended, states are replaced unless they are keep-state.

mixin clj macro

(mixin & ?stuff)

Define a mixin. Mixins let you provide additional lifecycle method expressions that you can mix into your components.

The syntax is

(mixin [<this> [<app-state> [<local-state>]]] [<param> ...]
  [<lifecycle-method-name> <lifecycle-method-exp> ...])

In order to use the mixin you can use the mixins clause in defclass

(defclass foo ...
  mixins [(<your-mixin-var> [<param> ...])]
  ...)

The lifecycle method expressions in the mixins will be called in order. Only after all mixin lifecycle methods have been handled the component's own lifecycle method will be called.

no-reaction cljs

Use this as a reaction if you don't want to react to an app-state change.

opt cljs

(opt & {:as mp})

Create options for component instantiation.

Takes the following keyword arguments:

• :reaction must be a reaction to an app-state change, typically created via reaction, no-reaction, or pass-through-reaction. -
• :embed-app-state can be specified as an alternative to :reaction and specifies, that the app state of this component is embedded in the parent component's app state. This must be a function of two arguments, the parent app state and this component's app-state. It must return a new parent app state.
• :embed-local-state is similar to :embed-app-state, but changes of the app state are instead embedded into the local state of the parent component.
• :app-state can be specified as an alternative to passing the app state as the next parameter of a class instantiation.
• :bind [parent lens] specifies, that lens applied to the current app state of parent is used as the app state of the component, and that changes to the app state of the component are integrated into the parent's app state via (lens parent-app-state new-child-app-state). lens can also be nil, a keyword or an index into a sequential collection.
• :bind-local [parent lens] is similar to :bind, but the app state of the component is instead bound to the local state of the parent.
• :reduce-action takes arguments [app-state action] where app-state is the app state of the component being instantiated, and action is an action. This should call return to handle the action. By default, it is a function with body (return :action action) returning the action unchanged. This is called on every action generated by the child component. Local-state changes through this function are ignored.
• :parent takes a component as an argument, which is used as the parent for the flow of actions and reactions.
• :ref take a ref declared in the refs clause of a class, so that the instance of this class is bound to the ref at any time. Note that this cannot be specified on the toplevel.

Only one of :reaction, :embed-app-state, :embed-local-state, :bind and :bind-local should be specified, and when using :bind or :bind-local then do not specify an :app-state either.

opt? cljs

(opt? v)

Returns true if v is the result of opt.

pass-through-reaction cljs

(pass-through-reaction component)

Use this if you want to pass the app-state as the message.

component must be the component to send the message to

reacl-class? cljs

(reacl-class? x)

Is an object a Reacl class?

reaction cljs

(reaction component make-message & args)

A reaction that says how to deal with a new app state in a subcomponent.

• component component to send a message to
• make-message function to apply to the new app state and any additional args, to make the message.

Common specialized reactions are no-reaction and pass-through-reaction.

reduce-action cljs

(reduce-action elem f & args)

Clone the given element, wrapping (composing) its action reducer with the given action reducer f.

refer cljs

(refer elem ref)

Returns an element identical to the given elem, but replacing its ref property, so that the given ref reflects the dom element created for it.

render-component cljs

(render-component element clazz & args)

(render-component element clazz app-state & args)

(render-component element clazz opts & args)

(render-component element clazz opts app-state & args)

Instantiate and render a component into the DOM.

• element is the DOM element
• clazz is the Reacl class
• opts is an object created with handle-toplevel-action or opt
• app-state is the initial application state
• args is a seq of class arguments

return cljs

(return & args)

Return state from a Reacl message handler or livecycle methods.

Has optional keyword arguments:

• :app-state is for a new app state (only once).
• :local-state is for a new component-local state (only once).
• :action is for an action (may be present multiple times)
• :message is for a tuple [target message] to be queued (may be present multiple times)

A state can be set to nil. To keep a state unchanged, do not specify that option, or specify the value keep-state.

returned-actions cljs

(returned-actions ret)

Returns the actions from the given return value.

returned-app-state cljs

(returned-app-state ret)

Returns the app-state from the given return value.

returned-local-state cljs

(returned-local-state ret)

Returns the local-state from the given return value.

returned-messages cljs

(returned-messages ret)

Returns the messages from the given return value.

returned? cljs

(returned? x)

reveal cljs

(reveal binding)

Returns the value provided by the given binding to be used as the app-state of a child component.

Do not use this outside the evaluation of the render clause in which the binding was constructed (e.g. in an event handler); that may lead to hard to track bugs in your component.

send-message! cljs

(send-message! comp msg)

Send a message to a Reacl component.

Returns the Returned object returned by the message handler.

send-message-allowed? cljs

(send-message-allowed?)

Returns if calling send-message! is allowed at this point; it's basically only allowed in event handlers, outside a Reacl update cycle.

set-parent cljs

(set-parent elem target)

Clones the given element, but replaces the parent component used in the reaction and action processing, which is the first component higher in the rendering tree by default - its rendering parent. If target is nil, the default behavior is restored.

use-app-state cljs

(use-app-state app-state)

Returns a binding that uses the given value as the app-state of a child component, ignoring all updates the child component returns.

use-reaction cljs

(use-reaction app-state reaction)

Returns a binding the uses the given value app-state as the child's app-state, and triggers the given reaction when the child wants to update it. See reaction for creating reactions.