com.fulcrologic.fulcro.data-fetch — com.fulcrologic/fulcro 3.7.6

Functions for issuing loads of subgraphs of data for your application. The primary functions of interest are load! and load-field!. Fulcro's composed queries and idents allow these loads to automatically be normalized and merged into your database. The data targeting support allows you to then join that new subgraph to the existing UI data graph. This process is the central topic to understand in Fulcro, and it is to your advantage to study the concepts of Fulcro idents and query composition carefully.

data-state? clj/s

(data-state? state)

Is the given parameter a load marker?

elide-ast-nodes clj/s

(elide-ast-nodes {:keys [key union-key children] :as ast} elision-predicate)

Remove items from a query (AST) that have a key that returns true for the elision-predicate

elide-query-nodes clj/s

(elide-query-nodes query node-predicate)

Remove items from a query when the query element where the (node-predicate key) returns true. Commonly used with a set as a predicate to elide specific well-known UI-only paths.

failed? clj/s

(failed? marker)

Is the given load marker indicate failed?

WARNING: This function is current unimplemented and will be removed. The new way of dealing with failure is to define an error-action for the load in question and modify your own state. You can also override

finish-load! clj/s

(finish-load! {:keys [app result transmitted-ast] :as env}
              {:keys [query ok-action post-mutation post-mutation-params
                      post-action target marker source-key]
               :as params})

Default processing when a load finishes successfully (called internally).

Removes any load marker, then either:

• Runs the ok-action (if defined).
• Does normal post-processing (if the was no ok-action):
  • Merges the load result
  • Processes desired targets
  • Runs the post-mutation (if defined)
  • Runs the post-action (if defined)

load clj/s

DEPRECATED. Use load!

load! clj/s

(load! app-or-comp server-property-or-ident class-or-factory)

(load! app-or-comp server-property-or-ident class-or-factory config)

Load data from the server.

This function triggers a server interaction and normalizes the server response into your app state database. During operation it also adds (by default) fetch markers into the app state so you can show busy indicators on the UI components that are waiting for data. The :target parameter can be used to place the data somewhere besides app state root (which is the default).

The server will receive a query of the form: [({server-property (comp/get-query class-or-factory)} params)], which a Fulcro parser will correctly parse as a join on server-property with the given subquery and params. See the AST and instructions on parsing queries in the developer's guide.

Parameters:

• app-or-comp : A component instance or Fulcro application
• server-property-or-ident : A keyword or ident that represents the root of the query to send to the server. If this is an ident you are loading a specific entity from the database into a local app db table. A custom target will be ignored.
• class-or-factory : A component that implements IQuery, or a factory for it (if using dynamic queries). This will be combined with server-property into a join for the server query. Needed to normalize results. class-or-factory can be nil, in which case the resulting server query will not be a join.
• config : A map of load configuration parameters.

Config (all optional):

• target - An assoc-in path at which to put the result of the Subquery (as an edge (normalized) or value (not normalized)). Can also be special targets (multiple-targets, append-to, prepend-to, or replace-at). If you are loading by keyword (into root), then this relocates the result (ident or value) after load. When loading an entity (by ident), then this option will place additional idents at the target path(s) that point to that entity.
• initialize - REMOVED. Use component pre-merge instead.
• remote - Optional. Keyword name of the remote that this load should come from.
• params - Optional parameters to add to the generated query
• marker - ID of marker. Normalizes a load marker into app state so you can see progress.
• refresh - A list of things in the UI to refresh. Depends on rendering optimization.
• focus - Focus the query along a path. See eql/focus-subquery.
• without - A set of keys to remove (recursively) from the query.
• update-query - A general-purpose function that can transform the component query before sending to remote. See also the application's :global-eql-transform option. For example, to focus a subquery using update-query: {:update-query #(eql/focus-subquery % [:my {:sub [:query]}])} Removing properties (like previous :without option): {:update-query #(df/elide-query-nodes % #{:my :elisions})}
• abort-id - Set a unique key. If supplied, then the load can be cancelled via that abort ID.
• parallel - Send the load out-of-order (immediately) without waiting for other loads in progress.
• post-mutation - A mutation (symbol) to run after the data is merged. Note, if target is supplied be sure your post mutation should expect the data at the targeted location. The env of that mutation will be the env of the load (if available), but will also include :load-request.
• post-mutation-params - An optional map that will be passed to the post-mutation when it is called.
• post-action - A lambda that will get a mutation env parameter (fn [env] ...). Called after success, like post-mutation (and after post-mutation if also defined). env will include the original :load-params and raw network layer :result. If you want the post behavior to act as a top-level mutation, then prefer post-mutation. The action can also call transact!.
• fallback - A mutation (symbol) to run if there is a server/network error. The env of the fallback will be like a mutation env, and will include a :result key with the real result from the server, along with the original :load-params.

Special-purpose config options:

The config options can also include the following things that completely override behaviors of other (respons-processing) options, and should only be used in very advanced situations where you know what you are doing:

• ok-action - WARNING: OVERRIDES ALL DEFAULT OK BEHAVIOR (except load marker removal)! A lambda that will receive an env parameter (fn [env] ...) that includes the :result and original :load-params.
• error-action - WARNING: OVERRIDES ALL DEFAULT ERROR BEHAVIOR (except load marker update). A lambda that will receive an env that includes the :result and original :load-params.

load-failed! clj/s

(load-failed! {:keys [app] :as env}
              {:keys [error-action marker fallback] :as params})

The normal internal processing of a load that has failed (error returned true).

Sets the load marker, if present, to :failed.

If an error-action was desired, it is used to process the rest of the failure.

The env will include the network :result and the original load options as :load-params.

Otherwise, this function will:

• Trigger the global error action (if defined on the app) (arg is env as described above)
• Trigger any fallback for the load. (params are the env described above)

load-field clj/s

DEPRECATED. Use load-field!

load-field! clj/s

(load-field! component field-or-fields)

(load-field! component field-or-fields options)

Load a field of the current component. Runs prim/transact!.

Parameters

• component: The component (instance, not class). This component MUST have an Ident.
• field: A field on the component's query that you wish to load. If field is a vector of keywords then this function will load all of the fields specified.
• options : A map of load options. See load.

WARNING: If you're using dynamic queries, you won't really know what factory your parent is using, nor can you pass it as a parameter to this function. Therefore, it is not recommended to use load-field from within a component that has a dynamic query unless you can base it on the original static query.

load-marker? clj/s

(load-marker? x)

Is the given parameter a load marker?

load-params* clj/s

(load-params* app
              server-property-or-ident
              class-or-factory
              {:keys [target params marker post-mutation post-mutation-params
                      without fallback focus ok-action post-action error-action
                      remote abort-id update-query]
               :or {remote :remote marker false}})

Internal function to validate and process the parameters of load and load-action.

loading? clj/s

(loading? marker)

Is the given load marker loading?

marker-table clj/s

The name of the table in which fulcro load markers are stored. You must query for this via a link query [df/marker-table '_] in any component that needs to use them (and refresh) during loads.

ready? clj/s

(ready? marker)

Is the given load marker ready for loading?

refresh! clj/s

(refresh! component)

(refresh! component load-options)

remove-load-marker! clj/s

(remove-load-marker! app marker)

Removes the load marker with the given marker id from the df/marker-table.

set-load-marker! clj/s

(set-load-marker! app marker status)

Adds a load marker at the given marker id to df/marker-table with the given status.

NOTE: You must query for the marker table in any component that wants to show activity.