Frontend Navigation with Re-frame
Last updated
Last updated
This document covers how to handle client-side navigation in the application using Re-frame events.
The application uses for routing in combination with for state management. This provides a powerful and flexible way to handle navigation in your Single Page Application (SPA).
There are two main navigation events available:
:router/navigate
- A regular event that triggers navigation
:router/navigate!
- An effect that performs immediate navigation
:router/redirect
- An event triggered when a route has a :redirect-to
property
:router/navigate
The most common way to trigger navigation is with the :router/navigate
event:
This will navigate the user to the dashboard route defined in your routes configuration.
You can include path parameters and query parameters in your navigation:
This will navigate to a URL like /user/123?tab=settings
(assuming your route is defined as something like /user/:user-id
).
In some cases, you might want to use the navigation effect directly in a custom event handler:
The :router/navigate!
effect performs the navigation immediately as a side effect.
When a navigation occurs, the :router/navigated
event is dispatched with the new route details. This event updates the application state with the current route information and sets any SEO-related metadata.
The route information is stored in the app db under :router/current-route
and can be accessed with a subscription:
A common pattern is to navigate after an API call succeeds:
When an unauthorized action is attempted, it's common to redirect to the login page:
Routes are defined in src/cljc/saas/common/routes.cljc
using Reitit's routing syntax. Here's a simplified example:
When navigating to a new route, the :router/navigated
event will automatically update the page title and meta description based on the :seo/title
and :seo/description
properties defined in your route data.
The application supports automatic redirects through the :redirect-to
route property. This allows you to define routes that automatically redirect to another route when accessed.
Define a route with the :redirect-to
property in src/cljc/saas/common/routes.cljc
:
When a user navigates to /settings
, the router detects the :redirect-to
property and automatically redirects to the specified route (:routes.settings/profile
in this example).
The redirection is handled by the :router/redirect
event, which is dispatched when a route with :redirect-to
is matched.
Default pages for sections (e.g., redirecting /settings
to /settings/profile
)
Legacy URLs that should redirect to new locations
Creating logical groupings of routes with a default landing page
The navigation system is implemented in:
src/cljs/saas/core.cljs
: Sets up the router and initializes route handling
src/cljs/saas/db/events.cljs
: Defines the navigation events and effects
src/cljc/saas/common/routes.cljc
: Defines the application routes
src/cljs/saas/routing.cljs
: Handles route matching and redirection logic