com.fulcrologic.fulcro.routing.dynamic-routing — com.fulcrologic/fulcro 3.7.3

A router that uses Fulcro dynamic queries to optimize query performance on rendering and provides a number of useful features such as easy composition, control over route targeting, on-screen component vetoes of routing requests, etc.

NOTE: This router is not concerned with HTML5 history events or URL management. This router is intended to be usable in server-side rendering, React Native, and anywhere else Fulcro might be used. Therefore it is not tied to a particular rendering platform's idea of location management (i.e. URLs).

The structure of the route composition (and its representation as a sequence of string path components) is intended to be easy to integrate with HTML5 history and URL control.

*target-class* clj/s

INTERNAL USE ONLY. Not guaranteed to be available at runtime in production builds. This is used to aid in giving development-time warnings/errors.

Class of the routing target component, available in the notifications fns (:will-enter, :route-cancelled, :will-leave)

absolute-path clj/s

(absolute-path app-ish RouteTarget route-params)

(absolute-path app-ish
               RouteTarget
               route-params
               {:keys [ParentRouter] :as options})

Get the absolute path for the given route target.

NOTE: Using this on a route target that is on multiple paths of your application can lead to ambiguity and failure of general routing, since this will then return an unpredictable result. In those cases you must supply the options map with the ParentRouter of the RouteTarget, which will resolve the ambiguity.

accepts-route? clj/s

(accepts-route? component path)

(accepts-route? component path state-map)

Returns true if the given component is a router that manages a route target that will accept the given path. Requires state-map to work on dynamically-added routes.

active-routes clj/s

(active-routes app)

(active-routes app starting-from)

Return a sequence of the leaf router targets that are routed to in the given app using the active dynamic query and app state.

The return values are maps that currently contain a :path and :target-component key. Future versions of this function may include additional information.

Note that dynamic routing purposely supports the ability to have more than one UI path active at a time, as it is NOT a strict URL-style UI router. However, since your code is ultimately responsible for determining what parts of the active query are rendered, it is possible for this to return routes that are available (in the props of components) but are not being rendered by your logic. Thus, the return value of this function isn't necessarily proof that the routes listed are visible to the user.

WARNING: If you use disconnected roots (via hooks or otherwise), then you must specify a starting component that is well-connected (graph/state) from which to scan, and will get back paths relative to that starting-from (a component, element, or factory if you're using factory-based dynamic queries).

add-route-target clj/s

Mutation. Add a target to a router dynamically.

params:

• router - A router class or registry key
• target - A target class or registry key (must have :route-segment)
• initial-state-params - Parameters for the initial state for merging the target into state (if it has a stable ident)

See also add-route-target! and add-route-target*.

add-route-target! clj/s

(add-route-target! app-ish options)

Add a target to an existing router.

app-ish - An app or component options - A map:

• router - A router class or registry key
• target - A target class or registry key (must have :route-segment)
• initial-state-params - Parameters for the initial state for merging the target into state (if it has a stable ident)

add-route-target!! clj/s

(add-route-target!! app-ish options)

Add a target to an existing router synchronously. This will NOT show in Fulcro Inspect as a transaction.

app-ish - An app or component options - A map:

• router - A router class or registry key
• target - A target class or registry key (must have :route-segment)
• initial-state-params - Parameters for the initial state for merging the target into state (if it has a stable ident)

add-route-target* clj/s

(add-route-target* state-map {:keys [router target initial-state-params]})

Mutation helper. Add a target to a router dynamically.

router - A class or registry key target - A class or registry key initial-state-params - Parameters to pass to get-initial-state when merging the state of target (which is only done if that component has a stable ident).

all-reachable-routers clj/s

(all-reachable-routers state-map component-class)

Returns a sequence of all of the routers reachable in the query of the app.

allow-route-change? clj/s

(allow-route-change? c)

apply-route clj/s

Mutation: Indicate that a given route is ready and should show the result.

router - The ident of the router, with metadata :component that is the class of the router. target - The ident of the target route, with metadata :component that is the class of the target.

ast-node-for-live-router clj/s

(ast-node-for-live-router app {:keys [component children] :as ast-node})

Returns the AST node for a query that represents the closest "live" (on-screen) router

ast - A query AST node

Returns an AST node or nil if none is found.

ast-node-for-route clj/s

(ast-node-for-route {:keys [component children] :as ast-node} path)

(ast-node-for-route {:keys [component children] :as ast-node} path state-map)

Returns the AST node for a query that represents the router that has a target that can accept the given path. This is a breadth-first search.

ast - A query AST node path - A vector of the current URI segments. state-map - Application state map, required for support of dynamically-added routes.

Returns an AST node or nil if none is found.

can-change-route? clj/s

(can-change-route? this-or-app)

(can-change-route? this-or-app relative-class)

Returns true if the active on-screen targets indicate they will allow navigation.

NOTE: If your route targets have an :allow-route-change?, then that will be used to determine if the route can be abandoned; otherwise :will-leave will be called to answer the question; however, this USE of will-leave is DEPRECATED (though the hook is NOT because it serves another purpose). If you side-effect in :will-leave this could cause strange behavior throughout the application. It is recommended that your targets implement :allow-route-change? if they need to prevent routing, and only leverage :will-leave to do things like cancel in-progress loads.

change-route clj/s

change-route! clj/s

(change-route! this new-route)

(change-route! this new-route timeouts-and-params)

Trigger a route change.

• this - The component (or app) that is causing the route change.
• new-route - A vector of URI components to pass to the router.
• timeouts-and-params - A map of additional parameters and route timeouts that affect UI during deferred routes: {:error-timeout ms :deferred-timeout ms}. Anything extra will appear in the params of will-enter.

The error timeout is how long to wait (default 5000ms) before showing the error-ui of a route (which must be defined on the router that is having problems). The deferred-timeout (default 100ms) is how long to wait before showing the loading-ui of a deferred router (to prevent flicker).

Returns one of:

:already-there - The old and new route are the same, and there was no request to force an idempotent routing operation. :invalid - The new route didn't evaluate to a valid location :denied - One or more on-screen targets refused to allow the routing operation :routing - The routing operation is in progress, but deferred operations may still delay the route becoming visible.

change-route-relative clj/s

DEPRECATED NAME: Use change-route-relative!

change-route-relative! clj/s

(change-route-relative! this-or-app relative-class-or-instance new-route)

(change-route-relative! app-or-comp
                        relative-class-or-instance
                        new-route
                        timeouts-and-params)

Change the route, starting at the given Fulcro class or instance (scanning for the first router from there). new-route is a vector of string components to pass through to the nearest child router as the new path. The first argument is any live component or the app. The timeouts-and-params are as in change-route.

When possible (i.e. no circular references to components) you can maintain better code navigation by generating new-route via path-to. This will allow readers of your code to quickly jump to the actual components that implement the targets when reading the code.

You may include the special keyword :.. any number of times at the beginning of new-route to indicate the parent(s) of relative-class-or-instance, which allows you to do relative routing to a sibling.

(dr/change-route-relative this this [:.. "sibling-pattern"])

Returns one of:

:already-there - The old and new route are the same, and there was no request to force an idempotent routing operation. :invalid - The new route didn't evaluate to a valid location :denied - One or more on-screen targets refused to allow the routing operation :routing - The routing operation is in progress, but deferred operations may still delay the route becoming visible.

compile-error clj

(compile-error env form message)

current-route clj/s

(current-route this-or-app)

(current-route this-or-app relative-class-or-instance)

Returns the current active route, starting from the relative Fulcro class or instance.

Any component using this as a basis for rendering will need to add the following to their query to ensure the props of that component change on route changes:

[::uism/asm-id fq-router-kw]

where fq-router-kw is a keyword that has the exact namespace and name of the router you're interested in. If you want to just over-render you can use a quoted _ instead.

NOTE: This function is primarily meant to be used in mutation implementations or with global routing. It is not reliable to use this function during render because it relies on the router being mounted (and render gets called in order to determine what to render). If you want to know the current state of a particular router you should query for it's ASM as indicated above.

current-route-class clj/s

(current-route-class this)

Get the class of the component that is currently being routed to.

defrouter clj/s macro

(defrouter router-sym arglist options & body)

Define a router.

The arglist is [this props], which are just like defsc. The props will contains :current-state and :pending-path-segment.

The options are:

:router-targets - (REQUIRED) A vector (which may be empty if you want to only add targets at runtime) of ui components that are router targets. The first one is considered the "default" (purely for the purpose of initial state; you always need to explicitly route to a particular target). Other defsc options - (LIMITED) You may not specify query/initial-state/protocols/ident, but you can define things like react lifecycle methods. See defsc. :always-render-body? - (OPTIONAL) When true this router expects that you will supply a render body, and it will always be rendered. The props available in the body will include:

• :current-state - The state of the routing state machine. (:initial, :pending, :failed, :routed)
• :route-factory - A factory that can generate the current route.
• :route-props - The props that should be passed to the route factory. You can augment these with computed if you wish. The router normally passes computed through like so: (route-factory (comp/computed route-props (comp/get-computed this)))
• :pending-path-segment - The route that we're going to (when in pending state).
• :router-state - A map of the path management details of the router. Includes the pending path segment (if deferred), the target, and the path segment of the current route.

The optional body, if defined, will only be used if the router has the :always-render-body? option set or it is in one of the following states:

• :initial - No route is set.
• :pending - A deferred route is taking longer than expected (configurable timeout, default 100ms)
• :failed - A deferred route took longer than can reasonably be expected (configurable timeout, default 5s)

otherwise the actual active route target will be rendered.

defrouter* clj

(defrouter* env router-ns router-sym arglist options body)

dynamic-router clj/s

(dynamic-router registry-key targets)

(dynamic-router router-registry-key
                router-targets
                {:keys [render always-render-body?] :as options})

The functional version of defrouter. Generates a router (particularly useful at runtime for use with dynamically generated components) with the given Fulcro registry-key and list of router-targets. The options map can contain:

• :render - A (fn [this props] ...) that needs to function as described in defrouter.
• Any other options that defrouter supports in the component options map.

evaluate-relative-path clj/s

(evaluate-relative-path relative-instance new-route)

Takes an on-screen instance of a react element and a new route (vector of strings) and returns a vector containing either the original arguments, or an evaluation of relative navigation up the live routing tree.

If new-route starts with :.. (any number of times) then this function finds (and returns) the parent router and the new route stripped of :.. prefix.

For example, say you were in a target instance that has a parent router, which in turn has a parent router called SomeRouter. Then:

(dr/evaluate-relative-path this [:.. :.. "some-target"])
=> [SomeRouter ["some-target"]]

This function does not work on classes. It is meant for live evaluation of on-screen instances to enable relative routing based on the actual on-screen route targets.

CAN return nil for the router if no such parent is found.

Returns unmodified input argument if new-route does not begin with :...

fail-handler clj/s

(fail-handler env)

get-allow-route-change? clj/s

(get-allow-route-change? this)

Returns the function of a route target to be called with the current component and props. If it returns true then the routing operation can continue. If it returns false then whatever new route was requested will be completely abandoned. This handler MUST NOT side-effect, and may be called multiple times on a single route request.

get-route-cancelled clj/s

(get-route-cancelled class)

Returns the function that should be called if this target was in a deferred state and a different routing choice was made. Is given the same route parameters that were sent to will-enter.

get-targets clj/s

(get-targets router)

(get-targets router state-map)

Returns a set of classes to which this router routes, including dynamic ones if possible.

router - A router instance, class, or registry key, or ident. state-map - The current app state

If router is a class or registry key you'll get the static list from component options unless you also supply the state-map (it will attempt to use rc/query-state if it is bound).

get-will-enter clj/s

(get-will-enter class)

Returns the function that is called before a route target is activated (if the route segment of interest has changed and the target of the result is this target). MUST return (r/route-immediate ident) or (r/route-deferred ident) to indicate what ident should be used in app state to connect the router's join. If deferred, the router must cause a call to the r/target-ready mutation (or use the target-ready* mutation helper) with a {:target ident} parameter to indicate that the route target is loaded and ready for display.

params will be a map from any keywords found in route-segment to the string value of that path element.

WARNING: This method MUST be side-effect free.

get-will-leave clj/s

(get-will-leave this)

Returns the function of a route target to be called with the current component and props. If it returns true then the routing operation will continue. If it returns false then whatever new route was requested will be completely abandoned. If this component has a allow-route-change? then the return value of will-leave will be ignored.

immediate? clj/s

(immediate? ident)

initialize! clj/s

(initialize! app)

Initialize the routing system. This ensures that all routers have state machines in app state.

into-path clj/s

(into-path prefix TargetClass & path-args)

Returns the given prefix with the TargetClass segment appended onto it, replacing the final elements with the given (optional) path args.

(defsc X [_ _]
  {:route-segment ["a" :b]})

(into ["f" "g"] X "22") ; => ["f" "g" "a" "22"]

mark-route-pending* clj/s

(mark-route-pending* state-map {:keys [router target] :as params})

matching-prefix clj/s

(matching-prefix route-segment actual-path)

Returns the elements of actual-path that match the route-segment definition.

path-to clj/s

(path-to & targets-and-params)

Convert a sequence of router targets and parameters into a vector of strings that represents the target route. Parameters can be sequenced inline:

(defsc A [_ _]
  {:route-segment ["a" :a-param]})

(defsc B [_ _]
  {:route-segment ["b" :b-param]})

(route-segment A a-param1 B b-param ...)

where the parameters for a target immediately follow the component that requires them. Alternatively one can specify all of the parameters at the end as a single map using the parameter names that are used in the component :route-segment itself:

(defsc A [_ _]
  {:route-segment ["a" :a-param]})

(route-segment A B C D {:a-param 1})

proposed-new-path clj/s

(proposed-new-path this-or-app relative-class-or-instance new-route)

(proposed-new-path this-or-app
                   relative-class-or-instance
                   new-route
                   timeouts-and-params)

Internal algorithm: Returns a sequence of idents of the targets that the new-route goes through by analyzing the current application query and state.

ready-handler clj/s

(ready-handler env)

resolve-path clj/s

(resolve-path resolved-components params)

(resolve-path StartingClass RouteTarget params)

(resolve-path StartingClass
              RouteTarget
              params
              {:keys [ParentRouter] :as options})

Attempts to resolve a path from StartingClass to the given RouteTarget. Can also be passed resolved-components, which is the output of resolve-path-components. If ParentRouter is supplied, then if RouteTarget is in multiple places in the UI this function will only consider the path that includes ParentRouter as the immediate parent of the target.

NOTE: This function works against static queries UNLESS you bind rc/*query-state* to app/current-state.

Returns a vector of route segments. Any keywords in the result will be replaced by the values from params, if present.

Returns nil if no path can be found. Be sure rc/query-state is bound to current app state if you want to include dynamic queries.

resolve-path-components clj/s

(resolve-path-components StartingClass RouteTarget)

(resolve-path-components StartingClass RouteTarget base-path)

(resolve-path-components StartingClass
                         RouteTarget
                         base-path
                         {:keys [ParentRouter] :as options})

resolve-target clj/s

(resolve-target app new-route)

Given a new-route path (vector of strings): resolves the target (class) that is the ultimate target of that path.

retry-route! clj/s

(retry-route! denied-target-instance relative-root path)

(retry-route! denied-target-instance relative-root path timeouts-and-params)

Retry a route that the receiving component just denied, and ignore this target's answer. All other targets will still be asked. This is primarily used when you want to be able to use js/confirm in a component to ask the user if they "really mean to navigate away". You MUST pass the arguments that :route-denied received or you can easily cause an infinite loop. Other on-screen targets can still potentially abort the route.

route-cancelled clj/s

(route-cancelled class route-params)

Universal CLJC version of route-cancelled. Don't use the protocol method in CLJ.

route-deferred clj/s

(route-deferred ident completion-fn)

Used as a return value from will-enter. Instructs the router to run the completion-fn. The completion function must use the mutation target-ready or function target-ready! to indicate when it is ready for the target to appear on-screen.

route-handler clj/s

(route-handler {:com.fulcrologic.fulcro.ui-state-machines/keys [app event-data]
                :as env})

route-immediate clj/s

(route-immediate ident)

Used as a return value from will-enter. Instructs the routing system that you would like this target to be routed to as soon as possible. UI switching defaults to depth-first to prevent flicker.

route-lifecycle? clj/s

(route-lifecycle? component)

route-segment clj/s

(route-segment class)

Returns a vector that describes the sub-path that a given route target represents. String elements represent explicit path elements, and keywords represent variable values (which are always pulled as strings).

route-target clj/s

(route-target router-class path)

(route-target router-class path state-map)

Given a router class and a path segment, returns the class of that router's target that accepts the given URI path, which is a vector of (string) URI components. state-map is required if you want it to work with dynamic targets.

Returns nil if there is no target that accepts the path, or a map containing:

{:target class :matching-prefix prefix}

where class is the component class that accepts the path (the target, NOT the router), and matching-prefix is the portion of the path that is accepted by that class.

NOTE: If more than one target matches, then the target with the longest match will be returned. A warning will be printed if more than one match of equal length is found.

route-target? clj/s

(route-target? component)

route-to! clj/s

(route-to! app-ish
           {Router :router
            :keys [target route-params auto-add? after-load before-change
                   initial-state-params load-from]
            :as options})

Route to a specific target of the given Router. This is different from change-route! in that it makes the code a bit more navigable (though a bit less easily refactored), and supports some additional dynamic features:

• Dynamically adding the target to the router if it isn't there
• Loading a module that contains the router (dynamic code load through cljs.loader) and adding it to the router

app-ish - An app or component instance

The options map can contain:

• router (OPTIONAL/REQUIRED) - A router class or registry key for that router. Required if you want auto-add or loading to work.
• target (REQUIRED) - A target class or registry key.
• :route-params - A map from keywords to values for any of the route parameters expected for the given target.
• :auto-add? - Default false. Automatically add the target to the router if it isn't already there.
• :load-from <module-name> - Default nil. Check to see if <module-name> is loaded. If not, load it, IMPLIES auto-add? true.
• :initial-state-params - Parameters to use for the merge with get-initial-state if the component is added, and has a stable ident.
• after-load (fn [app] ...) - IF dynamically loaded, this function will be called before attempting to add the target, allowing you to dynamically generate the component from the loaded code if necessary. Such generation MUST be synchronous.
• before-change (fn [app {:keys [target path route-params]}] ...) - If the routing is possible and is not denied, this will be called just before the route is put into effect.

route-with-path-ordered-transaction clj/s

(route-with-path-ordered-transaction ident txn)

(route-with-path-ordered-transaction ident
                                     txn
                                     {:keys [optimistic? route-immediate?]
                                      :as options})

Used as a return value from will-enter. Instructs the routing system to execute the txn in routing path order, and optionally couples these operations into a single transaction. This can be used in cases where you need the side-effects (potentially full-stack) to complete for a parent target before those of a nested target.

The options can contain:

• :optimistic? (default false) - When true, don't wait for this transaction to (full-stack) complete before starting child target effects.
• :route-immediate? (default false) - When true, apply the UI routing immediately instead of waiting for the transaction to finish. Of course the UI of the target should then be willing to tolerate the lack of any full-stack result.
• :show-early? - (default false) - When true each transaction that completes will cause that target to appear. When false the target won't appear until after all children have completed their non-optimistic path-based transactions.

router-for-pending-target clj/s

(router-for-pending-target state-map target)

router? clj/s

(router? component)

RouterStateMachine clj/s

signal-router-leaving clj/s

(signal-router-leaving app-or-comp relative-class-or-instance new-route)

(signal-router-leaving app-or-comp
                       relative-class-or-instance
                       new-route
                       timeouts-and-params)

Tell active routers that they are about to leave the screen. Returns false if any of them deny the route change.

subpath clj/s

(subpath TargetClass & path-args)

Returns the route segment of the given TargetClass with the trailing elements replaced by path-args.

(defsc X [_ _]
  {:route-segment ["a" :b]})

(subpath X "22") ; => ["a" "22"]

target-denying-route-changes clj/s

(target-denying-route-changes this-or-app)

(target-denying-route-changes this-or-app relative-class)

This function will return the first mounted instance of a route target that is currently indicating it would deny a route change. If a relative-class is given then it only looks for targets that would deny a change within that router's subtree.

target-ready clj/s

Mutation: Indicate that a target is ready.

target-ready! clj/s

(target-ready! component-or-app target)

Indicate a target is ready. Safe to use from within mutations.

target - The ident that was originally listed as a deferred target.

validate-route-targets clj/s

(validate-route-targets router-instance)

Run a runtime validation on route targets to verify that they at least declare a route-segment that is a vector.

will-enter clj/s

(will-enter class app params)

Universal CLJC version of will-enter.

will-leave clj/s

(will-leave c props)