com.fulcrologic.fulcro.components — com.fulcrologic/fulcro 3.0.0

*app* clj/s

*blindly-render* clj/s

*depth* clj/s

*parent* clj/s

*query-state* clj/s

*shared* clj/s

-legal-keys clj

(-legal-keys query)

PRIVATE. Find the legal keys in a query. NOTE: This is at compile time, so the get-query calls are still embedded (thus cannot use the AST)

any->app clj/s

(any->app x)

Attempt to coerce x to an app. Legal inputs are a fulcro application, a mounted component, or an atom holding any of the above.

children clj/s

(children component)

Get the sequence of react children of the given component.

class->all clj/s

(class->all x class)

Get all of the on-screen component instances from the indexes that have the type of the component class. x can be anything any->app is ok with.

class->any clj/s

(class->any x cls)

Get a (random) on-screen component instance from the indexes that has type of the given component class. x can be anything any->app is ok with.

class->registry-key clj/s

(class->registry-key class)

Returns the registry key for the given component class.

cljs? clj

(cljs? env)

A CLJ macro helper. env is the macro's &env value. Returns true when expanding a macro while compiling CLJS.

component->state-map clj/s

(component->state-map this)

Returns the current value of the state map via a component instance. Note that it is not safe to render arbitrary data from the state map since Fulcro will have no idea that it should refresh a component that does so; however, it is sometimes useful to look at the state map for information that doesn't change over time.

component-class? clj/s

(component-class? x)

Returns true if the argument is a component class.

component-instance? clj/s

(component-instance? x)

Returns true if the argument is a component. A component is defined as a mounted component. This function returns false for component classes, and also returns false for the output of a Fulcro component factory.

component-name clj/s

(component-name class)

Returns a string version of the given react component's name. Works on component instances and classes.

component-options clj/s

(component-options instance-or-class & ks)

Returns the map of options that was specified (via defsc) for the component class.

component? clj/s

Returns true if the argument is a component instance.

DEPRECATED for terminology clarity. Use component-instance? instead.

compressible-transact! clj/s

(compressible-transact! app-ish tx)

(compressible-transact! app-ish ref tx)

Identical to transact! with :compressible? true option. This means that if more than one adjacent history transition edge is compressible, only the more recent of the sequence of them is kept. This is useful for things like form input fields, where storing every keystoke in history is undesirable. This also compress the transactions in Fulcro Inspect.

NOTE: history events that trigger remote interactions are not compressible, since they may be needed for automatic network error recovery handling.

computed clj/s

(computed props computed-map)

Add computed properties to props. This will replace any pre-existing computed properties. Computed props are necessary when a parent component wishes to pass callbacks or other data to children that have a query. This is not necessary for "stateless" components, though it will work properly for both.

Computed props are "remembered" so that a targeted update (which can only happen on a component with a query and ident) can use new props from the database without "losing" the computed props that were originally passed from the parent. If you pass things like callbacks through normal props, then targeted updates will seem to "lose track of" them.

computed-factory clj/s

(computed-factory class)

(computed-factory class options)

Similar to factory, but returns a function with the signature [props computed & children] instead of default [props & children]. This makes easier to send computed.

computed-initial-state? clj/s

(computed-initial-state? s)

Returns true if the given initial state was returned from a call to get-initial-state. This is used by internal algorithms when interpreting initial state shorthand in defsc.

configure-component! clj/s

(configure-component! cls fqkw options)

Configure the given cls (a function) to act as a react component within the Fulcro ecosystem.

cls - A js function (in clj, this is ignored) fqkw - A keyword that shares the exact fully-qualified name of the component class options - A component options map (no magic) containing things like :query and :ident.

NOTE: the options map expects proper function signatures for:

:query - (fn [this] ...) :ident - (fn [this props] ...) :initial-state - (fn [cls params] ...)

Returns (and registers) a new react class.

defsc clj/s macro

(defsc & args)

Define a stateful component. This macro emits a React UI class with a query, optional ident (if :ident is specified in options), optional initial state, optional css, lifecycle methods, and a render method. It can also cause the class to implement additional protocols that you specify. Destructuring is supported in the argument list.

The template (data-only) versions do not have any arguments in scope The lambda versions have arguments in scope that make sense for those lambdas, as listed below:

(defsc Component [this {:keys [db/id x] :as props} {:keys [onSelect] :as computed} extended-args]
  {
   ;; stateful component options
   ;; query template is literal. Use the lambda if you have ident-joins or unions.
   :query [:db/id :x] ; OR (fn [] [:db/id :x]) ; this in scope
   ;; ident template is table name and ID property name
   :ident [:table/by-id :id] ; OR (fn [] [:table/by-id id]) ; this and props in scope
   ;; initial-state template is magic..see dev guide. Lambda version is normal.
   :initial-state {:x :param/x} ; OR (fn [params] {:x (:x params)}) ; nothing is in scope
   ;; pre-merge, use a lamba to modify new merged data with component needs
   :pre-merge (fn [{:keys [...]}] (merge {:ui/default-value :start} tree))

   ; React Lifecycle Methods
   :initLocalState            (fn [this props] ...) ; CAN BE used to call things as you might in a constructor. Return value is initial state.
   :shouldComponentUpdate     (fn [this next-props next-state] ...)

   :componentDidUpdate        (fn [this prev-props prev-state snapshot] ...) ; snapshot is optional, and is 16+. Is context for 15
   :componentDidMount         (fn [this] ...)
   :componentWillUnmount      (fn [this] ...)

   ;; DEPRECATED IN REACT 16 (to be removed in 17):
   :componentWillReceiveProps        (fn [this next-props] ...)
   :componentWillUpdate              (fn [this next-props next-state] ...)
   :componentWillMount               (fn [this] ...)

   ;; Replacements for deprecated methods in React 16.3+
   :UNSAFE_componentWillReceiveProps (fn [this next-props] ...)
   :UNSAFE_componentWillUpdate       (fn [this next-props next-state] ...)
   :UNSAFE_componentWillMount        (fn [this] ...)

   ;; ADDED for React 16:
   :componentDidCatch         (fn [this error info] ...)
   :getSnapshotBeforeUpdate   (fn [this prevProps prevState] ...)

   ;; static
   :getDerivedStateFromProps  (fn [props state] ...)

   ;; ADDED for React 16.6:
   :getDerivedStateFromError  (fn [error] ...)  **NOTE**: OVERWRITES entire state. This differs slightly from React.

   NOTE: shouldComponentUpdate should generally not be overridden other than to force it false so
   that other libraries can control the sub-dom. If you do want to implement it, then old props can
   be obtained from (prim/props this), and old state via (gobj/get (. this -state) "fulcro$state").

   ; BODY forms. May be omitted IFF there is an options map, in order to generate a component that is used only for queries/normalization.
   (dom/div #js {:onClick onSelect} x))

NOTE: The options map is "open". That is: you can add whatever extra stuff you want to in order to co-locate data for component-related concerns. This is exactly what component-local css, the dynamic router, and form-state do. The data that you add is available from comp/component-options on the component class and instances (i.e. this).

See the Developer's Guide at book.fulcrologic.com for more details.

defsc* clj

(defsc* env args)

denormalize-query clj/s

(denormalize-query state-map ID)

Takes a state map that may contain normalized queries and a query ID. Returns the stored query or nil.

depth clj/s

(depth this)

factory clj/s

(factory class)

(factory class {:keys [keyfn qualifier] :as opts})

Create a factory constructor from a component class created with defsc.

force-children clj/s

(force-children x)

Utility function that will force a lazy sequence of children (recursively) into realized vectors (React cannot deal with lazy seqs in production mode)

fragment clj/s

(fragment & args)

Wraps children in a React.Fragment. Props are optional, like normal DOM elements.

get-computed clj/s

(get-computed x)

(get-computed x k-or-ks)

Return the computed properties on a component or its props.

get-extra-props clj/s

(get-extra-props this)

Get any data (as a map) that props extensions have associated with the given Fulcro component. Extra props will be empty unless you've installed props-middleware (on your app) that sets them.

get-ident clj/s

(get-ident x)

(get-ident class props)

Get the ident for a mounted component OR using a component class.

That arity-2 will return the ident using the supplied props map.

The single-arity version should only be used with a mounted component (e.g. this from render), and will derive the props that were sent to it most recently.

get-indexes clj/s

(get-indexes x)

Get all of the indexes from a component instance or app. See also ident->any, class->any, etc.

get-initial-state clj/s

(get-initial-state class)

(get-initial-state class params)

Get the declared :initial-state value for a component.

get-query clj/s

(get-query class-or-factory)

(get-query class-or-factory state-map)

Get the query for the given class or factory. If called without a state map, then you'll get the declared static query of the class. If a state map is supplied, then the dynamically set queries in that state will result in the current dynamically-set query according to that state.

get-query-by-id clj/s

(get-query-by-id state-map class queryid)

get-raw-react-prop clj/s

(get-raw-react-prop c k)

GET a RAW react prop. Used internally.

get-state clj/s

(get-state component)

(get-state component k-or-ks)

Get a component's local state. May provide a single key or a sequential collection of keys for indexed access into the component's local state. NOTE: This is Fulcro's wrapped component local state. The low-level React state is as described in the React docs (e.g. (.-state this)).

has-feature? clj/s

(has-feature? component option-key)

has-ident? clj/s

(has-ident? component)

has-initial-app-state? clj/s

(has-initial-app-state? component)

has-pre-merge? clj/s

(has-pre-merge? component)

has-query? clj/s

(has-query? component)

ident clj/s

(ident this props)

ident->any clj/s

(ident->any x ident)

Return some (random) on-screen components that uses the given ident. x is anything any->app accepts.

ident->components clj/s

(ident->components x ident)

Return all on-screen component instances that are rendering the data for a given ident. x is anything any->app accepts.

initial-state clj/s

(initial-state clz params)

is-factory? clj/s

(is-factory? class-or-factory)

Returns true if the given argument is a component factory.

isoget clj/s

(isoget obj k)

(isoget obj k default)

Like get, but for js objects, and in CLJC. In clj, it is just get. In cljs it is gobj/get.

isoget-in clj/s

(isoget-in obj kvs)

(isoget-in obj kvs default)

Like get-in, but for js objects, and in CLJC. In clj, it is just get-in. In cljs it is gobj/getValueByKeys.

link-element clj/s

(link-element element)

Part of internal implementation of dynamic queries.

link-query clj/s

(link-query query)

Part of dyn query implementation. Find all of the elements (only at the top level) of the given query and replace them with their query ID.

make-state-map clj/s

(make-state-map initial-state children-by-query-key params)

Build a component's initial state using the defsc initial-state-data from options, the children from options, and the params from the invocation of get-initial-state.

mounted? clj/s

(mounted? this)

Returns true if the given component instance is mounted on the DOM.

newer-props clj/s

(newer-props props-a props-b)

Returns whichever of the given Fulcro props were most recently generated according to denormalization-time. This is part of props 'tunnelling', an optimization to get updated props to instances without going through the root.

normalize-query clj/s

(normalize-query state-map query)

Given a state map and a query, returns a state map with the query normalized into the database. Query fragments that already appear in the state will not be added. Part of dynamic query implementation.

normalize-query-elements clj/s

(normalize-query-elements state-map query)

Part of internal implementation of dynamic queries.

Determines if there are query elements in the query that need to be normalized. If so, it does so.

Returns the new state map containing potentially-updated normalized queries.

pre-merge clj/s

(pre-merge this data)

prop->classes clj/s

(prop->classes x prop)

Get all component classes that query for the given prop. x can be anything any->app is ok with.

Returns all classes that query for that prop (or ident)

props clj/s

(props component)

Return a component's props.

ptransact! clj/s

(ptransact! component-or-app tx)

(ptransact! component-or-app ref tx)

DEPRECATED: Generally use result-action in mutations to chain sequences instead. This call is equivalent to transact! with an :optimistic? false option.

Like transact!, but ensures each call completes (in a full-stack, pessimistic manner) before the next call starts in any way. Note that two calls of this function have no guaranteed relationship to each other. They could end up intermingled at runtime. The only guarantee is that for a single call to ptransact!, the calls in the given tx will run pessimistically (one at a time) in the order given. Follow-on reads in the given transaction will be repeated after each remote interaction.

component-or-app a mounted component or the app tx the tx to run ref the ident (ref context) in which to run the transaction (including all deferrals)

query clj/s

(query this)

query-id clj/s

(query-id class qualifier)

Returns a string ID for the query of the given class with qualifier.

raw->newest-props clj/s

(raw->newest-props raw-props raw-state)

Using raw react props/state returns the newest Fulcro props. This is part of "props tunneling", where component local state is leveraged as a communication mechanism of updated props directly to a component that has an ident. This function will return the correct version of props based on timestamps.

react-type clj/s

(react-type x)

Returns the component type, regardless of whether the component has been mounted

register-component! clj/s

(register-component! k component-class)

Add a component to Fulcro's component registry. This is used by defsc to ensure that all Fulcro classes that have been compiled (transitively required) will be accessible for lookup by fully-qualified symbol/keyword. Not meant for public use, unless you're creating your own component macro that doesn't directly leverage defsc.

registry-key->class clj/s

(registry-key->class classname)

Look up the given component in Fulcro's global component registry. Will only be able to find components that have been (transitively) required by your application.

classname can be a fully-qualified keyword or symbol.

set-query! clj/s

(set-query! x class-or-factory {:keys [query params] :as opts})

Public API for setting a dynamic query on a component. This function alters the query and rebuilds internal indexes.

• x : is anything that any->app accepts.
• class-or-factory : A component class or factory for that class (if using query qualifiers)
• opts : A map with query and optionally params (substitutions on queries)

set-query* clj/s

(set-query* state-map class-or-factory {:keys [query] :as args})

Put a query in app state.

NOTE: Indexes must be rebuilt after setting a query, so this function should primarily be used to build up an initial app state.

set-state! clj/s

(set-state! component new-state)

(set-state! component new-state callback)

Set React component-local state. The new-state is actually merged with the existing state (as per React docs), but is wrapped so that cljs maps are used (instead of js objs). callback is an optional callback that will be called as per the React docs on setState.

shared clj/s

(shared component)

(shared component k-or-ks)

Return the global shared properties of the root. See :shared and :shared-fn app options. NOTE: Shared props only update on root render and by explicit calls to app/update-shared!

transact! clj/s

(transact! app-or-comp tx)

(transact! app-or-component tx options)

Submit a transaction for processing.

The underlying transaction system is pluggable, but the default supported options are:

• :optimistic? - boolean. Should the transaction be processed optimistically?
• :ref - ident. The ident of the component used to submit this transaction. This is set automatically if you use a component to call this function.
• :component - React element. Set automatically if you call this function using a component.
• :refresh - Vector containing idents (of components) and keywords (of props). Things that have changed and should be re-rendered on screen. Only necessary when the underlying rendering algorithm won't auto-detect, such as when UI is derived from the state of other components or outside of the directly queried props. Interpretation depends on the renderer selected: The ident-optimized render treats these as "extras".
• :only-refresh - Vector of idents/keywords. If the underlying rendering configured algorithm supports it: The components using these are the only things that will be refreshed in the UI. This can be used to avoid the overhead of looking for stale data when you know exactly what you want to refresh on screen as an extra optimization. Idents are not checked against queries.
• :abort-id - An ID (you make up) that makes it possible (if the plugins you're using support it) to cancel the network portion of the transaction (assuming it has not already completed).
• :compressible? - boolean. Check compressible-transact! docs.

NOTE: This function calls the application's tx! function (which is configurable). Fulcro 2 'follow-on reads' are supported by the default version and are added to the :refresh entries. Your choice of rendering algorithm will influence their necessity.

Returns the transaction ID of the submitted transaction.

update-state! clj/s

(update-state! component f)

(update-state! component f & args)

Update a component's local state. Similar to Clojure(Script)'s swap!

This function affects a managed cljs map maintained in React state. If you want to affect the low-level js state itself use React's own .setState directly on the component.

with-parent-context clj/s macro

(with-parent-context outer-parent & body)

Wraps the given body with the correct internal bindings of the parent so that Fulcro internals will work when that body is embedded in unusual ways (e.g. as the body in a child-as-a-function React pattern).

(defsc X [this props]
  ...
  ;; WRONG:
  (some-react-thing {:child (fn [] (ui-fulcro-thing ...))})
  ;; CORRECT:
  (some-react-thing {:child (fn [] (with-parent-context this (ui-fulcro-thing ...)))})

wrap-update-extra-props clj/s

(wrap-update-extra-props f)

(wrap-update-extra-props handler f)

Wrap the props middleware such that f is called to get extra props that should be placed in the extra-props arg of the component.

handler - (optional) The next item in the props middleware chain. f - A (fn [cls extra-props] new-extra-props)

f will be passed the class being rendered and the current map of extra props. It should augment those and return a new version.

wrapped-render clj/s

(wrapped-render this real-render)

Run real-render, possibly through :render-middleware configured on your app.