API Reference

API Reference

• Components

  • <GroundControl>

• Route Components

  • <Route>
  • Injected Props

• Universal Data Fetching API

• Utilities

  • loadStateOnServer()
  • loadStateOnClient()
  • getNestedState()

Components

<GroundControl>

Primary component of GroundControl. It sits beneath the router & above your application. Controls data fetching, store structure, and how your application renders.

Props

{...props} from React-Router (required).

render((
  <Router
      routes={routes}
      history={browserHistory}
      render={(props) => (
        <GroundControl
            {...props}
            store={store}
            />
      )}/>
), document.getElementById('app'));

store (required)

Object. Create an initial Redux store and pass it in as prop.

initialData

Object. For universal applications, pass in initialData from loadStateOnServer / loadStateOnClient.

reducers

Object. If you want additional top level reducers (ex: redux-simple-router), pass in object with reducers so that we can properly call store.replaceReducers. If you don't have extra reducers, skip this entirely and just send in the store.

{ groundcontrol: (s = {}) => s, otherReducer: (s = {}) => s }

serializer(data, route)

Function. If using a lib like Immutable.js, and want an app level serializer to handle data before it is send to components, add a serializer.

const serializer = (data, route) => {
  if (route.immutable) return data.toJS();
  return data;
};

Route Components

<Route>

We extend React-Router <Route> components with a few additional props.

Props

reducer(state, action)

Function. Reducers defined on your routes will automatically be used to create your global application state, in line with route hierarchy. When someone navigates to a new route, the old routes state is cleared, and the old reducer is replaced with the new reducer in the store.

const reducer = (state = {}, action) => state;

asyncEnter(done, opts)

Function. If asyncEnter is a set on a route, the route component doesn't resolve until a callback is called. See Universal Route API for details.

onLeave(opts)

Function. Clean up, etc before leaving route.

loader

Component. For synchronous client side transitions, set a loader (like a spinner) until the route component is rendered.

deserializer(data)

Function. For universal apps that use custom data (immutable), deserialize data from __INITIAL_DATA__ to the reducers.

const deserializer = (data) => data;

serializer(data)

Function. For apps that use custom data (immutable), serialize data from reducers before it gets to components.

const serializer = (data) => data;

customProps

Add whatever custom props you'd like, ex: route.immutable, so that you can manipulate data in application serializer / deserializer.

Injected Props

All props from React Router.

This includes location, params, route, etc. Please see React-Router documentation.

data

Object. Data from your route reducer is automatically passed to your component as data.

rootData

Object. Data from top level component is passed to all route components as a convenience. This is a common place to persist data.

getParentData(relativeDepth = -1)

Function. Helper to get any level of parentData if deeply nested.

loading

Bool. For async transitions, whether the route is still loading.

loadingError

Null/Object. If asyncEnter called the err() callback.

Universal Data Fetching API

asyncEnter(done, options)

done()

Function. Call done when route is completely done fetching data.

options.params

Object. Route params to help fetch data.

options.dispatch(action)

Function. Returns null. Dispatch actions to your store.

options.getState()

Function. Returns object. getState of your store, if needed.

options.clientRender()

Function. Returns null. Tell your client to stop blocking and handle loading with preview template.

options.serverRender()

Function. Returns null. Tell your server to stop blocking and render page. Useful if you want to render the top half of page server side, bottom half of page client side.

options.err({})

Function. Returns null. Call to signify an error to pass loadingErr on client render; and handle error on server (with a 500, etc).

options.redirect({ pathname, query, state })

Function. Returns null. Call to redirect on client, and to redirect on server (with a 302, etc).

options.isMounted()

Function. Returns bool for whether the current route is still active. Useful for avoiding race conditions on quick route changes.

options.isInitialLoad()

Function. Returns bool for whether we can assume the data we have is accurate on initial page load.

options.reducerData()

Function. Returns object with hydrated data. Useful if we want to cache client side.

options.isClient()

Function. Returns bool for client render.

options.isServer()

Function. Returns bool for server render.

Utilities

loadStateOnServer({ props, store, reducers }, (err, redirect, initialData, scriptString))

Function for universal rendering (server side). Takes in props from React-Router match, store, and reducers (optional). Calls callback with error (/null) for server side error handling; redirect (/null); initialData to send into GroundControl and scriptString so that we can hydrate the client.

loadStateOnClient({ routes, deserializer }, (initialData))

Function for universal rendering (client side). Takes in routes, and an optional deserializer, and calls callback with initialData to pass into GroundControl.

getNestedState(store, level = 0)

Pass in current store, and level you'd like to receive (without traversing self / child hierarchy manually).