Navigation Data

Passing Data

When it comes to passing data between views, the Navigation router isn't like other routers. Other routers make you define your routes and parameters up front. The Navigation router thinks in terms of States and data so you don't need to think about routes and parameters until your application's working.

You can use the NavigationLink component to build Hyperlinks that navigate between States. As well as a stateKey prop that holds the destination State, the NavigationLink component has a navigationData prop that holds the data to pass. You don't have to convert data to strings because it accepts numbers, booleans and dates. In an email application, for example, a Hyperlink that opens an email might pass along the email id together with a flag that indicates the thread's history should be initially collapsed.

<NavigationReact.NavigationLink 
  stateKey="mail"
  navigationData={{id: 12, expand: false}}>
  Open Mail
</NavigationReact.NavigationLink>

For navigating without Hyperlinks, you can pass data in the second parameter of the navigate function on the stateNavigator.

<NavigationReact.NavigationContext.Consumer>
  {({ stateNavigator }) => (
    <div onClick={() => stateNavigator.navigate('mail', {id: 12, expand: false})}>
      Open Mail
    </div>
  )}
</NavigationReact.NavigationContext.Consumer>

You can even pass along arrays of strings, numbers, booleans or dates. So, instead of expanding and collapsing the whole thread in our email application, we could pass along an array of ids that identify which mails in the thread to expand.

Receiving Data

You'll recall that the NavigationContext Consumer notifies you when a State becomes active. Along with the new State, the Consumer passes you the associated navigation data. It’s your job to call the function assigned to the renderView property of the active State and pass in the navigation data. In the email example, when the mail State is active we use the id and expand data items passed in to set the respective props on our Mail component.

stateNavigator.states.mail.renderView = function(data) {
  return <Mail id={data.id} expand={data.expand} />;
};

You don't have to convert the data from strings because the Navigation router remembers their original types. Adding prop type validation to the Mail component, for example, wouldn't raise an exception.

var Mail = React.createClass({
  propTypes: {
    id: React.propTypes.number,
    expand: React.propTypes.bool
  },
  /* ... */
});

Setting Default Values

The Navigation router lets you define default navigation data values for each State. The data passed into a State's navigated function includes these default values for any item that you don't supply with a value when navigating. If we give the expand item in the email example a default value of false then we don't have to explicitly pass it in navigation data when the mail's opened.

var stateNavigator = new Navigation.StateNavigator([
  {key: 'inbox', route: ''},
  {key: 'mail', defaults: {expand: false}},
  {key: 'compose'}
]);

Setting Constraints

You can also define navigation data constraints in a function attached to the validate property of the State. This function receives the navigation data as a parameter and you return true only if the data meets your constraints. The Navigation router will only navigate to a State if the constraints are met. For example, we could create a constraint to ensure that the mail id is greater than zero.

stateNavigator.states.mail.validate = function(data) {
  return data.id > 0;
};