com.fulcrologic.fulcro.routing.legacy-ui-routers — com.fulcrologic/fulcro 3.0.0-beta-16

Routers from Fulcro 2. These are a bit harder to use than the new dynamic router, and should probably not be used in new applications; however, they will be supported for the forseeable future.

-get-missing-routes clj/s

(-get-missing-routes app state-map {:keys [handler route-params] :as params})

Returns a sequence of routes that need to be loaded in order for routing to succeed.

-is-dynamic-router? clj/s

(-is-dynamic-router? component)

Returns true if the given component (instance) is a DynamicRouter.

-load-dynamic-route clj/s

(-load-dynamic-route state-atom pending-route-handler route-to-load finish-fn)

(-load-dynamic-route state-atom
                     pending-route-handler
                     route-to-load
                     finish
                     attempt
                     delay)

Triggers the actual load of a route, and retries if the networking is down. If the pending route (in state) has changed between retries, then no further retries will be attempted. Exponential backoff with a 10 second max is used as long as retries are being done.

-load-routes clj/s

(-load-routes {:keys [state] :as env} routes)

-process-pending-route! clj/s

(-process-pending-route! {:keys [state app] :as env})

Finish doing the routing after a module completes loading

-route-target-missing? clj/s

(-route-target-missing? ident)

Returns true iff the given ident has no component loaded into the dynamic routing multimethod.

-update-routing-queries clj/s

(-update-routing-queries state app {:keys [handler route-params]})

PRIVATE.

Given the reconciler, state, and a routing tree route: finds and sets all of the dynamic queries needed to accomplish that route. Returns the updated state. reconciler can be nil, in which case UI refresh may not happen, but that is useful for SSR.

add-route-state clj/s

(add-route-state state-map target-kw component)

bad-route clj/s

(bad-route page)

coerce-param clj/s multimethod

compile-error clj

(compile-error env form message ex)

current-route clj/s

(current-route state-map-or-router-table router-id)

Get the current route (an ident) from the router with the given id. You can pass the entire app database, the routers table, or the props of a component that has queried for the router table as the first argument to this function. Thus, it can be used easily from within a mutation or in a component to find (and display) the current route:

(defmutation do-something-with-routes [params]
  (action [{:keys [state]}]
    (let [current (r/current-route state :top-router)]
    ...)))

(defsc NavBar [this props]
  {:query (fn [] [[r/routers-table '_]])
   :initial-state (fn [params] {})}
  (let [current (r/current-route props :top-router)]
    ...))

defsc-router clj/s macro

(defsc-router sym arglist options & body)

Define a router component.

This is just like defsc, BUT generates a pair of components that optimize query performance and allow for efficient UI changes. The options are identical to defsc, except:

Required Options:

• :router-id - An ID for the router
• :ident - An ident that works across all of the routing targets. This kind of router generates a union query, so this ident function must work on ALL router targets, and MUST vary the FIRST elements of the ident to identiy which screen to show.
• :default-route - The Class of the router target that is the default (initial) route.
• :router-targets - A map of ident tables to router targets. This map MUST correspond to the TABLE name that the router target lives in, and the Class of the router target component.

You may NOT define a :query or :initial-state for a router.

All other defsc options are supported.

(defsc-router TopRouter [this props]
  {
   ;; REQUIRED for router:
   :router-id :top-router
   :ident (fn [this props] [(:table props) (:id props)]
   :router-targets  {:A A :B B :C C}
   :default-route A

   :css [] ; garden css rules
   :css-include [] ; list of components that have CSS to compose towards root.

   ; React Lifecycle Methods (this in scope)
   :initLocalState            (fn [this] ...) ; 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 [prevProps prevState] ...)
   :getDerivedStateFromProps  (fn [props state] ...)

defsc-router* clj

(defsc-router* env router-sym arglist options body)

defsc-router-router-element* clj

(defsc-router-router-element* env router-sym union-sym arglist options)

dynamic-route-key clj/s

DynamicRouter clj/s

get-dynamic-router-query clj/s

(get-dynamic-router-query router-id)

Get the query for the router with the given router-id.

get-dynamic-router-target clj/s multimethod

Get the component that renders the given screen type. The parameter is simply the keyword of the module/component. Note that all have to match: the module name in the compiler that contains the code for the component, the first element of the ident returned by the component, and the keyword passed to this multimethod to retrieve the component.

install-route clj/s

Fulcro mutation: Install support for a dynamic route. target-kw is the keyword that represents the table name of the target screen (first elemenet of the ident of the component), which must also match internal data in the state of that component at fulcro.client.routing/dynamic-route-key. component is the class of the UI component that will be shown by the router. It must implement InitialAppState to provide at least the value of target-kw at the predefined fulcro.client.routing/dynamic-route-key key.

An example would be that you've defined a component like this:

(ns app.component (:require fulcro.client.routing))

(def target-kw :my-component)

(defsc Component [this props] {:initial-state (fn [p] {fulcro.client.routing/dynamic-route-key target-kw}) :ident (fn [this props] [target-kw :singleton])} ...)

and during startup you install this route as:

(transact! this `[(install-route {:target-kw :my-component :component Component})])

install-route* clj/s

(install-route* state-map target-kw component)

Implementation of mutation. Useful for SSR setup.

make-route clj/s

(make-route name routing-instructions)

Make a route name that executes the provided routing instructions to change which screen in on the UI. routing-instructions must be a vector. Returns an item that can be passed to routing-tree to generate your overall application's routing plan.

(make-route :route/a [(router-instruction ...) ...])

route-to clj/s

Mutation (use in transact! only):

Change the application's overall UI route to the given route by handler. Handler must be a single keyword that indicates an entry in your routing tree (which must be in the initial app state of your UI root). route-params is a map of key-value pairs that will be substituted in the target screen idents of the routing tree.

If any of the routers are dynamic, then this mutation will check to see if the target routes are loaded. If any are not present, then module load(s) will be triggered for them, and the route will be pending until the code arrives.

If a new route-to is run before pending routes are installed, then the pending route will be cancelled, but the code loading will continue.

You may use a link query to get [:fulcro.client.routing/pending-route '_] in your application. If it is not nil then a route is pending, and you can show UI indicators of this.

Server-side rendering should require all dynamic portions of the UI and use route-to*.

route-to* clj/s

(route-to* state-map bidi-match)

Implementation of routing tree data manipulations on app state. Returns an updated app state.

WARNING: This function will not trigger dynamic module loading, as it is only responsible for returning a state-map that has been set (as far as is possible) to the given route. You typically do not want to use this on a client, but exists a separate function for server-side rendering to be easily able to route, since no dynamic code loading will be needed.

route-to-impl! clj/s

(route-to-impl! {:keys [state app] :as env} bidi-match)

Mutation implementation, for use as a composition into other mutations. This function can be used from within mutations. If a DynamicRouter is used in your routes, then this function may trigger code loading. Once the loading is complete (if any is needed), it will trigger the actual UI routing.

If routes are being loaded, then the root property in your app state :fulcro.client.routing/pending-route will be your bidi-match. You can use a link query to pull this into your UI to show some kind of indicator.

NOTE: this function updates application state and must not be used from within a swap on that state.

router-instruction clj/s

(router-instruction router-id target-screen-ident)

Return the definition of a change-route instruction.

routers-table clj/s

routing-tree clj/s

(routing-tree & routes)

Generate initial state for your application's routing tree. The return value of this should be merged into your overall app state in your Root UI component

(defsc Root [this props]
  {:initial-state (fn [params]  (merge {:child-key (comp/get-initial-state Child)}
                                  (routing-tree
                                    (make-route :route/a [(router-instruction ...)])
                                    ...)))
  ...

routing-tree-key clj/s

set-ident-route-params clj/s

(set-ident-route-params ident route-params)

Replace any keywords of the form :params/X with the value of (get route-params :X) in the given ident. By default the value of the parameter (which comes in as a string) will be converted to an int if it is all digits, and will be converted to a keyword if it is all letters. If you want to customize the coercion, just:

(defmethod r/coerce-param :param/NAME [k v] (transform-it v))

set-route clj/s

Mutation: Explicitly set the route of a given router to the target screen ident.

set-route* clj/s

(set-route* state-map router-id screen-ident)

Set the given screen-ident as the current route on the router with the given ID. Returns a new application state map.

ui-dynamic-router clj/s

(ui-dynamic-router props)

update-routing-links clj/s

(update-routing-links state-map {:keys [handler route-params]})

Given the app state map, returns a new map that has the routing graph links updated for the given route/params as a bidi match.

This function should only be used if you only use static UI routing.

If you use DynamicRouter then you must use route-to-impl! instead.