useHistory(history)

Integrates Scrivito’s routing with that of an existing React application.

Here is a basic example of how to use this function together with react-router. Add this code after the call to Scrivito.configure:

Copy
import { createBrowserHistory } from 'history';
import { Router, Route, Switch } from 'react-router'

// Create the shared history
const history = createBrowserHistory();

// Make Scrivito use this history
Scrivito.useHistory(history);

// Define the routing
<Router history={ history }>
  <Switch>
    <Route path="/" render={() => <Scrivito.CurrentPage /> }/>
    <Route path="/login" render={() => <MyLoginComponent /> }/>
  </Switch>
</Router>

When integrating the Scrivito CMS into an existing React application, you are most probably faced with two different approaches to routing, the one in the app, and the one included in Scrivito.

Since Scrivito cannot detect changes to the URL in the browser, it cannot determine whether or not it is responsible for displaying the page. A routing solution common to both parties would remedy this. Here Scrivito.useHistory comes into play.

This API lets you create a common routing strategy based on the history package, a library that abstracts the browser's location and history API and is widely used when it comes to routing in JavaScript applications. The Scrivito SDK supports routing integration with all applications that are built on top of the history library, i.e., all applications that either use the history library directly, or through a history-based library. The best known of the latter kind is react-router.

Quick integration steps (tl;dr):

  1. Create a common history object.
  2. Pass the object to Scrivito.useHistory.
  3. Pass the object to your routing solution.

Scrivito now automatically detects changes to the URL, and both applications can act together.

Note that Scrivito.useHistory expects a history without a preconfigured base name.

Params

  • history (Object) - The history object from the history package.

How to integrate with React Router

When integrating Scrivito.useHistory with React Router, don't use the <BrowserRouter> component directly. Instead, explicitly create a history object using createBrowserHistory, and pass it to React Router’s generic <Router> as well as to Scrivito.useHistory

Before using React Router, please notice the differences between static routing (you might know from Ruby on Rails or Angular) and React Router’s dynamic approach: https://reacttraining.com/react-router/web/guides/philosophy.

Note that the following examples require that Scrivito.configure has been called before.

In its most basic form, the routing would direct all URLs to Scrivito:

Copy
import { createBrowserHistory } from 'history';
import { Router, Route } from 'react-router'

// Create the shared history
const history = createBrowserHistory();

// Make Scrivito use this history
Scrivito.useHistory(history);

<Router history={ history }>
  <Route path="/" render={() => <Scrivito.CurrentPage /> }/>
</Router>

If you want to add a non-Scrivito page you can do this with:

Copy
import { createBrowserHistory } from 'history';

// Create the shared history
const history = createBrowserHistory();

// Make Scrivito use this history
Scrivito.useHistory(history);

<Router history={ history }>
  <Route path="/" render={() => <Scrivito.CurrentPage /> }/>
  <Route path="/login" render={() => <MyLoginComponent /> }/>
</Router>

React Router applies multiple-match semantics by default; instead of using the first matching URL, it uses all matching URLs. To change this behavior, wrap the Route Components into a Switch Component. This forces React Router to select one of the two routes. If you don't use the Switch and a user visits the “/login” URL, both routes will match, causing MyLoginComponent and Scrivito.CurrentPage to be rendered; Scrivito.CurrentPage will try to display the page with the “/login” permalink.

Copy
import { createBrowserHistory } from 'history';
import { Router, Route, Switch } from 'react-router'

// Create the shared history
const history = createBrowserHistory();

// Make Scrivito use this history
Scrivito.useHistory(history);

// Define the routing
<Router history={ history }>
  <Switch>
    <Route path="/" render={() => <Scrivito.CurrentPage /> }/>
    <Route path="/login" render={() => <MyLoginComponent /> }/>
  </Switch>
</Router>

If you want to use Scrivito.NotFoundErrorPage to have an error page displayed, it should be integrated alongside Scrivito.CurrentPage:

Copy
import { createBrowserHistory } from 'history';
import { Router, Route, Switch } from 'react-router'

// Create the shared history
const history = createBrowserHistory();

// Make Scrivito use this history
Scrivito.useHistory(history);

// Define the routing
<Router history={ history }>
  <Switch>
    <Route path="/" render={() =>
      <>
        <Scrivito.CurrentPage />
        <Scrivito.NotFoundErrorPage />
      </>
    }/>
    <Route path="/login" render={() => <MyLoginComponent /> }/>
  </Switch>
</Router>

React Router and the routing base path

If you want your Scrivito pages to live under their own URL path, you can configure a routingBasePath. Please make sure that the routingBasePath and your configured routes match.

Copy
import { createBrowserHistory } from 'history';
import { Router, Route, Switch } from 'react-router'

Scrivito.configure({
  routingBasePath: '/my-scrivito',
  ...,
});

// Create the shared history
const history = createBrowserHistory();

// Make Scrivito use this history
Scrivito.useHistory(history);

// Define the routing
<Router history={ history }>
  <Switch>
    <Route path="/my-scrivito" render={() =>
      <>
        <Scrivito.CurrentPage />
        <Scrivito.NotFoundErrorPage />
      </>
    }/>
    <Route path="/login" render={() => <MyLoginComponent /> }/>
  </Switch>
</Router>

See React Router Integration with Scrivito for further usage examples.