fulcro.client.data-fetch — fulcrologic/fulcro 2.8.0-pre-merge-SNAPSHOT

append-to clj/s

(append-to target)

bool? clj/s

(bool? v)

clj->js clj

(clj->js m)

data-state? clj/s

(data-state? state)

elide-query-nodes clj/s

(elide-query-nodes query elision-set)

Remove items from a query that have a key listed in the elision-set

failed? clj/s

(failed? state)

fallback clj/s

(fallback {:keys [action]})

Mutation: Add a fallback to the current tx. action is the symbol of the mutation to run if this tx fails due to network or server errors (bad status codes).

get-remotes clj/s

(get-remotes state-map dispatch-symbol)

(get-remotes state-map dispatch-symbol legal-remotes)

Returns the remote against which the given mutation will try to execute. Returns nil if it is not a remote mutation. legal-remotes is a set of legal remote names. Defaults to #{:remote}.

Returns a set of the remotes that will be triggered for this mutation, which may be empty.

DEPRECATED. Do not use. Use mutation-remotes instead.

lazily-loaded clj/s

(lazily-loaded data-render
               props
               &
               {:keys [ready-render loading-render failed-render
                       not-present-render]
                :or {loading-render (fn [_] "Loading...")
                     ready-render (fn [_] "Queued")
                     failed-render (fn [_] "Loading error!")}})

Custom rendering for use while data is being lazily loaded using the data fetch methods load-collection and load-field.

data-render : the render method to call once the data has been successfully loaded from the server. Can be a factory method or a React rendering function.

props : the React properties for the element to be loaded.

Optional:

ready-render : the render method to call when the desired data has been marked as ready to load, but the server request has not yet been sent.

loading-render : render method once the server request has been sent, and UI is waiting on the response

failed-render : render method when the server returns a failure state for the requested data

not-present-render : called when props is nil (helpful for differentiating between a nil and empty response from the server).

Example Usage:

(defui Thing
  static prim/IQuery
  (query [this] [{:thing2 (prim/get-query Thing2)}])
  Object
  (componentDidMount [this]
     (load-field this :thing2))

  (render [this]
    (let [thing2 (:thing2 (prim/props this))]
      (lazily-loaded ui-thing2 thing2))))

(defui Thing2
  static prim/IQuery
  (query [this] [:ui/fetch-state])
  Object
  (render [this]
    (display-thing-2))

(def ui-thing2 (prim/factory Thing2))

load clj/s

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

(load app-or-comp-or-reconciler
      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 (prim/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-or-reconciler : A component instance, Fulcro application, or reconciler
• 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 - Optional. If true, uses get-initial-state on class-or-factory to get a basis for merge of the result. This allows you to use initial state to pre-populate loads with things like UI concerns. If :initialize is passed a map, then it uses that as the base target merge value for class-or-factory instead.

• remote - Optional. Keyword name of the remote that this load should come from.

• params - Optional parameters to add to the generated query

• marker - Boolean to determine if you want a fetch-state marker in your app state. Defaults to true. Add :ui/fetch-state to the target component in order to see this data in your component.

• refresh - A vector of keywords that will cause component re-renders after the final load/mutations. Same as follow-on reads in normal transact!

• parallel - If true, indicates that this load does not have to go through the sequential network queue. Defaults to false.

• 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. May only contain raw data, not code!

• fallback - A mutation (symbol) to run if there is a server/network error. The env of the fallback will be the env of the load (if available), but will also include :load-request.

• update-query - A optional function that can transform the component query before sending to remote. For example, to focus a subquery using update-query: {:update-query #(prim/focus-subquery % [:my {:sub [:query]}])}

  Removing properties (like previous :without option): {:update-query #(df/elide-query-nodes % #{:my :elisions})}

• focus - An optional subquery to focus on some parts of the original query.

• without - An optional set of keywords that should (recursively) be removed from the query.

• abort-id - An ID (typically a keyword) that you can use to cancel the load via fulcro.client/abort.

Notes on UI Refresh: The refresh list will automatically include what you load (as a non-duplicate):

• When target is set and has 2+ elements: refresh will include an ident of the first two elements
  • e.g. :target [:a 1 :thing] -> :refresh [[:a 1]]
• When target has a single element, refresh will include that element as a keyword
  • e.g. :target [:thing] -> :refresh [:thing]
• When there is no target:
  • If prop-or-ident is a kw -> :refresh [kw]
  • If prop-or-ident is an ident -> :refresh [ident] In all cases, any explicit refresh things you include will not be dropped. The computed refresh list is essentially a (-> original-refresh-list set add-computed-bits vec).

load-action clj/s≠

clj

cljs

(load-action env server-property-or-ident SubqueryClass)

(load-action env server-property-or-ident SubqueryClass config)

See load for descriptions of parameters and config.

Queue up a remote load from within an already-running mutation. Similar to load, but usable from within a mutation. IMPORTANT: Make sure you specify the :remote parameter to this function, as well as including a remote-load for that remote.

Note the :refresh parameter is supported, and defaults to empty. If you want anything to refresh other than the targeted component you will want to include the :refresh parameter.

To use this function make sure your mutation specifies a return value with a remote. The remote should use the helper function remote-load as it's value:

{ :remote (df/remote-load env) ; NOTE: :remote must be the keyword name of a legal remote in your system; however, ; You must still name the remote in the load-action if it is something other than default. :action (fn [] (load-action env ...) ; other optimistic updates/state changes)}

env is the mutation's environment parameter.

load-field clj/s

(load-field component field & params)

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.

• parameters : A map of: (will also accept as named parameters)

  • without: See load
  • params: See load
  • post-mutation: See load
  • post-mutation-params: See load
  • parallel: See load
  • fallback: See load
  • marker: See load
  • remote: See load
  • refresh: See load
  • abort-id: See load

NOTE: The :ui/loading-data attribute is always included in refresh. This means you probably don't want to query for that attribute near the root of your UI. Instead, create some leaf component with an ident that queries for :ui/loading-data using a link query (e.g. [:ui/loading-data '_]). The presence of the ident on components will enable query optimization, which can improve your frame rate because we will not have to run a full root query.

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 (which is what this function will use).

load-field-action clj/s

(load-field-action env-or-app-state component-class ident field & params)

Queue up a remote load of a component's field from within an already-running mutation. Similar to load-field but usable from within a mutation. Note the :refresh parameter is supported, and defaults to nothing, even for fields, in actions. If you want anything to refresh other than the targeted component you will want to use the :refresh parameter.

params can be a map or named parameters, just like in load-field.

To use this function make sure your mutation specifies a return value with a remote. The remote should use the helper function remote-load as it's value:

{ :remote (df/remote-load env) ; NOTE: :remote must be the keyword name of a legal remote in your system; however, ; You must still name the remote in the load-action if it is something other than default. :action (fn [] (load-field-action ...) ; other optimistic updates/state changes)}

It is preferable that you use env instead of app-state for the first argument, as this allows more details to be available for post mutations and fallbacks.

load-mutation clj/s

(load-mutation load-args)

Generates a transaction expression for a load mutation. It includes a follow-on read for :ui/loading-data. The args must be a map of the parameters usable from load. Returns a complete tx (as a vector), not just the mutation since follow-on reads are part of the mutation. You may use concat to join this with additional expressions.

load-params* clj/s

(load-params* state-map
              server-property-or-ident
              class-or-factory
              {:keys [target params marker refresh parallel post-mutation
                      post-mutation-params fallback remote focus without
                      initialize abort-id update-query]
               :or {remote :remote
                    marker true
                    parallel false
                    refresh []
                    without #{}
                    initialize false}})

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

loading? clj/s

(loading? state)

marker-table clj/s

The name of the table in which fulcro load markers are stored

multiple-targets clj/s

(multiple-targets & targets)

mutation-remotes clj/s

(mutation-remotes state-map
                  {:keys [dispatch-key params] :as dispatch-ast}
                  legal-remotes)

Returns the remote against which the given mutation will try to execute. Returns nil if it is not a remote mutation. legal-remotes is a set of legal remote names. Defaults to #{:remote}.

Returns a set of the remotes that will be triggered for this mutation, which may be empty.

prepend-to clj/s

(prepend-to target)

ready? clj/s

(ready? state)

refresh! clj/s

(refresh! component)

(refresh! component load-options)

remote-load clj/s

(remote-load parsing-env)

Returns the correct value for the :remote side of a mutation that should act as a trigger for remote loads. Must be used in conjunction with running load-action or load-field-action in the :action side of the mutation (which queues the exact things to load).

replace-at clj/s

(replace-at target)