com.fulcrologic.fulcro.raw.components — com.fulcrologic/fulcro 3.7.6

Fulcro base component functions. This namespace has no hard dependency on React, and includes all of the core routines found in components (that ns just aliases to this one). There is no support in this namespace for creating standard defsc components that work in React-based Fulcro, but instead this namespace includes support for building "normalizing component" from EQL and sample instances. This gives you all of the general data management power with no ties to React.

*after-render* clj/s

Dynamic var that affects the activation of transactions run via transact!. Defaults to false. When set to true this option prevents a transaction from running until after the next render is complete. This typically should not be set to true in scenarios where you are unsure if a render will occur, since that could make the transaction appear to "hang".

*query-state* clj/s

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.

ast-id-key clj/s

(ast-id-key children)

Returns the first child from a list of EQL AST nodes that looks like an entity ID key.

check-component-registry! clj/s

(check-component-registry!)

Walks the complete list of components in the component registry and looks for problems. Used during dev mode to detect common problems that can cause runtime misbehavior.

children clj/s

(children component)

Get the sequence of react children of the given component.

class->registry-key clj/s

(class->registry-key class)

Returns the registry key for the given component class.

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-type clj/s

(component-type x)

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

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.

configure-anonymous-component! clj/s

(configure-anonymous-component! render-fn component-options)

Make a given render-fn (a plain fn) act like a a Fulcro component with the given component options map. Registers the new component in the component-registry. Component options MUST contain :componentName as be a fully-qualified keyword to name the component in the registry.

component-options must include a unique :componentName (keyword) that will be used for registering the given function as the faux class in the component registry.

IMPORTANT: In CLJS this function adds extra things to the mutable js fn. In CLJ, components are just maps, and this side-effect cannot modify it. As such it returns the configured component so you can use it in CLJ.

defnc clj/s macro

(defnc sym query)

(defnc sym query options)

Create a normalizing component (NO rendering support). This component will be usable anywhere a defsc component can be used, except in rendering factories. Sets the :componentName using sym, and accepts addition component options if you want to supply them.

If you supply an :ident option (which is normally an arity-2 function), then the following special values are legal:

• A keyword: Works like the defsc shortcut: means (fn [this props] [keyword (get props keyword)])
• The special value :constant: means (fn [_ _] [:Constant/id <fully-qualified-keyword-of-sym>]). The capitalized letter causes these to sort earlier in Inspect's db viewer.

(defnc A [:person/id :person/name])

is the same as:

(def A (rc/nc [:person/id :person/name]
         {:componentName :the.full-namespace/A})) ; ident is inferred to be [:person/id <value-of-person-id>]

(defnc A [:person/id :person/name]
  {:ident (fn [_ p] [:PEOPLE (:person/id p)])})

is the same as:

(def A (rc/nc
        [:person/id :person/name]
        {:ident (fn [_ p] [:PEOPLE (:person/id p)])
         :componentName :the.full-namespace/A}))`

(defnc A [:ui/stuff] {:ident :constant})

means

(def A (rc/nc
        [:ui/stuff]
        {:ident (fn [_ p] [:Constant/id ::A])
         :componentName ::A}))`

NOTES:

A recursive query is supported just like nc. If you want to compose defnc queries, then do it like you would for defsc and you'll have full dynamic query support at each level.

If you just want the top-level component and don't care about anything other than the normalization, then you can just specify the query as raw EDN (assuming your keywords follow the naming conventions of nc).

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.

entity->component clj/s

(entity->component entity-data-tree)

(entity->component entity-data-tree top-level-options)

Creates a normalizing component from an entity tree. Every sub-element of the tree provided will generate an anonymous normalizing component if that element has an ID field. For to-many relations only the first item is used for query/ident generation.

The returned anonymous component will have initial state that matches the provided entity data tree.

This means you can use a sample tree to generate both the initial state for a subtree of your app and the components necessary to do I/O on that tree.

This kind of component will not be registered in the component registry unless you pass a :componentName via the top-level-options. A registry entry is necessary for things that require the registry, such as dynamic queries and UI state machines).

external-config clj/s

(external-config app-ish k)

Get any custom external configuration that was added to the app at creation-time.

get-class clj/s

(get-class instance)

Returns the react type (component class) of the given React element (instance). Is identity if used on a class.

get-computed clj/s

(get-computed x)

(get-computed x k-or-ks)

Return the computed properties on a component or its props. Note that it requires that the normal properties are not nil.

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-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-subquery-component clj/s

(get-subquery-component component query-path)

(get-subquery-component component query-path state-map)

Obtains the normalizing component that is associated with the given query path on the given component.

For example (get-subquery-component Person [:person/addresses]) would return the component for the :person/addresses join. If state-map is supplied then dynamic query support is possible; otherwise it will be the original static query.

get-traced-props clj/s

(get-traced-props state-map component ident prior-props)

Uses fdn/traced-db->tree to get the props of the component at ident, and leverages those optimizations to return prior-props if they are not stale.

A subsequent call (e.g. on next render frame) of this function with the prior return value (as prior-props) thus gives you an efficient non-react replacement for shouldComponentUpdate, etc.

has-active-state? clj/s

(has-active-state? state-map ident)

Returns true if there is already data at a component's ident

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)

id-key clj/s

(id-key props)

Returns the keyword of the most likely ID attribute in the given props (the first one with the name "id"). Returns nil if there isn't one. This is useful when trying to derive an ident from a sample tree of data, for example.

ident clj/s

(ident this props)

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.

legal-registry-lookup-key? clj/s

(legal-registry-lookup-key? k)

Returns true if k is a legal thing to with registry-key->class. The registry contains keywords, but that helper function accepts (and converts) strings or symbols as well.

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.

nc clj/s

(nc query)

(nc query {:keys [componentName] :as top-component-options})

Create an anonymous normalizing query component. By default the normalization will be auto-detected based on there being a prop at each entity level that has (any) namespace, and a name of id. For example:

[:list/id :list/name {:list/items [:item/id :item/complete? :item/label]}]

will create a normalizing query that expects the top-level values to be normalized by :list/id and the nested items to be normalized by :item/id. If there is more than one ID in your props, make sure the first one is the one to use for normalization.

The top-component-options becomes the options map of the component.

You can include :componentName to push the resulting anonymous component definition into the component registry, which is needed by some parts of Fulcro, like UISM.

NOTE: nc is recursive, and does compose if you want to name the components at various levels. It can be used with queries from other defsc components:

(def query (nc [:user/id
                :user/name
                ;; Generate an anonymous component that is available in the registry under ::Session
                {:user/session-details (nc [:session/id :session/last-login] {:componentName ::Session})}
                ;; Use a defsc query as the source
                {:user/settings (comp/get-query Settings)}
                ;; Autogenerates an anonymous address query component that has no name
                {:user/address [:address/id :address/street]}]))

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)

props clj/s

(props component)

Return a component's props.

query clj/s

(query this)

query->component clj/s

(query->component query)

Return the component class that was used to generate a given query. e.g. ( = (query->component (get-query Component)) Component).

query-id clj/s

(query-id class qualifier)

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

refresh-dynamic-queries! clj/s

(refresh-dynamic-queries! app-ish)

(refresh-dynamic-queries! app-ish cls force?)

Refresh the current dynamic queries in app state to reflect any updates to the static queries of the components.

This can be used at development time to update queries that have changed but that hot code reload does not reflect (because there is a current saved query in state). This is not always what you want, since a component may have a custom query whose prop-level elements are set to a particular thing on purpose.

An component that has :preserve-dynamic-query? true in its component options will be ignored by this function.

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.

registered-components clj/s

(registered-components)

Returns a map from registry key (keyword) to the fulcro components that have registered. Registration is automatic for many of the component generation facilities (macros) as long as they were assigned a registry name.

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, string, symbol, or component class. In the latter case this function just acts as identity. This allows this function to act as a coercion that ensures you have a class.

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.

shared clj/s

(shared comp-or-app)

(shared comp-or-app 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!.

This version does not rely on the dynamic var shared, which is only available from the react-based components ns.

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.
• :synchronous? - boolean. When turned on the transaction will run immediately on the calling thread. If run against a component then the props will be immediately tunneled back to the calling component, allowing for React (raw) input event handlers to behave as described in standard React Forms docs (uses setState behind the scenes). Any remote operations will still be queued as normal. Calling transact!! is a shorthand for this option. WARNING: ONLY the given component will be refreshed in the UI. If you have dependent data elsewhere in the UI you must either use transact! or schedule your own global render using app/schedule-render!.
• :after-render? - Wait until the next render completes before allowing this transaction to run. This can be used when calling transact! from within another mutation to ensure that the effects of the current mutation finish before this transaction takes control of the CPU. This option defaults to false, but defmutation causes it to be set to true for any transactions run within mutation action sections. You can affect the default for this value in a dynamic scope by binding *after-render* to true
• :parallel? - Boolean. If true, the mutation(s) in the transaction will NOT go into a network queue, nor will it block later mutations or queries.

You may add any additional keys to the option map (namespaced is ideal), and any value is legal in the options map, including functions. The options will appear in the env of all mutations run in the transaction as :com.fulcrologic.fulcro.algorithms.tx-processing/options. This is the preferred way of passing things like lambdas (if you wanted something like a callback) to mutations. Note that mutation symbols are perfectly legal as mutation arguments, so chaining mutations can already be done via the normal transaction mechanism, and callbacks, while sometimes necessary/useful, should be limited to usages where there is no other clean way to accomplish the goal.

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.

transact!! clj/s

(transact!! component tx)

(transact!! component tx options)

Shorthand for exactly (transact! component tx (merge options {:synchronous? true})).

Runs a synchronous transaction, which is an optimized mode where the optimistic behaviors of the mutations in the transaction run on the calling thread, and new props are immediately made available to the calling component via "props tunneling" (a behind-the-scenes mechanism using js/setState).

This mode is meant to be used in form input event handlers, since React is designed to only work properly with raw DOM inputs via component-local state. This prevents things like the cursor jumping to the end of inputs unexpectedly.

WARNING: Using an app instead of a component in synchronous transactions makes no sense. You must pass a component that has an ident.

If you're using this, you can also set the compiler option:

:compiler-options {:external-config {:fulcro     {:wrap-inputs? false}}}

to turn off Fulcro DOM's generation of wrapped inputs (which try to solve this problem in a less-effective way).

WARNING: Synchronous rendering does not refresh the full UI, only the component.

union-child-for-props clj/s

(union-child-for-props instance)

(union-child-for-props cls-or-instance props)

(union-child-for-props cls-or-instance props state-map)

Gets the component class that should be used for the specific entity (props) supplied.

union-component? clj/s

(union-component? c)

(union-component? c state-map)

Returns true if the given component class or instance has a query that represents a union query.