Frontend Navigation with Re-frame

This document covers how to handle client-side navigation in the application using Re-frame events.

Overview

The application uses Reititarrow-up-right for routing in combination with Re-framearrow-up-right 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:

  1. :router/navigate - A regular event that triggers navigation

  2. :router/navigate! - An effect that performs immediate navigation

  3. :router/redirect - An event triggered when a route has a :redirect-to property

Basic Navigation

Using :router/navigate

The most common way to trigger navigation is with the :router/navigate event:

(rf/dispatch [:router/navigate {:route ::routes/dashboard}])

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).

Direct Navigation Effect

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.

Handling Navigation Results

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:

Common Navigation Patterns

A common pattern is to navigate after an API call succeeds:

Conditional Navigation in an Event Handler

Redirecting to Login

When an unauthorized action is attempted, it's common to redirect to the login page:

Route Definition

Routes are defined in src/cljc/saas/common/routes.cljc using Reitit's routing syntax. Here's a simplified example:

SEO Considerations

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.

Route Redirects

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.

How It Works

  1. Define a route with the :redirect-to property in src/cljc/saas/common/routes.cljc:

  1. 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).

  2. The redirection is handled by the :router/redirect event, which is dispatched when a route with :redirect-to is matched.

Common Use Cases

  • 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

Implementation Details

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

Example Usage

Basic Navigation Button

Last updated