Create Custom Views and Routes

Flex is built using React, so it's a single page application by default. While you can easily add, replace or remove components to the Flex UI, you may find that workers need an entirely separate page to effectively get their work done in the Flex UI. Flex allows you to create these views and route workers to them.

The Flex UI uses the react-router, react-router-redux and history libraries for client-side routing.

Add, Replace, or Remove a View

Flex organizes views within the ViewCollection dynamic component. You can manipulate Flex views in the same manner as a dynamic component.

Flex.ViewCollection.Content.add(
  <Flex.View name="my-custom-page" key="my-custom-page-key">
    <div>My custom page</div>
  </Flex.View>
);

This will add a new view that's available under a path that corresponds to the name prop (i.e., https://localhost:3000/my-custom-page in this example.)

If you require more control over mounting your view, refer to the Mounting a View to Multiple Routes section.

You can also create a link to your view in the side navigation bar:

 Flex.SideNav.Content.add(
  <Flex.SideLink
    showLabel={ true }
    icon="DefaultAvatar"
    isActive={true}
    onClick={() => { Flex.Actions.invokeAction("HistoryPush", `/my-custom-page/`); } }
    key="MyCustomPageSideLink"
  >
    My custom page
  </Flex.SideLink>
);

Configuration Options

The configuration interface for routing-related functionality in Flex has the following shape:

router?: {
  type: "browser" | "memory"; // either a web-browser address or a reference implementation
  history?: HistoryBuildOptions; // build options for a `history` NPM package
  isolate?: boolean; // isolate Flex routing from other routing, forces Flex to use memory router.
};

You can use actions to navigate to different "locations" in the Flex UI. Actions work similarly to the HTML5 History API. Flex actions include:

Action	Payload	Description
NavigateToView	`{viewName: string}`	Navigates the user to a view defined by the provided view name
HistoryPush	URL path as a String or an Object matching the shape of the history location `({pathname: string, search: string, hash: string, state: {[key: string]: any}})`	Adds a history entry, leading to view change or redirect
HistoryReplace	URL path as a String or an Object matching the shape of the history location `({pathname: string, search: string, hash: string, state: {[key: string]: any}})`	Replaces current history entry, leading to view change or redirect
HistoryGo	`Integer`	Goes to a specific history entry, identified by its relative position to the current page. The current page is index 0.
HistoryGoBack	`None`	Goes back to the previous history entry
HistoryGoForward	`None`	Goes forward to the next history entry

Browser and In-Memory History

Support for browser and memory history that is configurable through the configuration object.

Mounting a view to multiple routes

You may want your page's path to be separate from the name, or to expose multiple paths that lead to the same View. The View component has a route property that you can use to add an alternative route. The route property has a shape similar to props of Route component of react-router package.

Flex.ViewCollection.Content.add(
  <Flex.View name="some-name" key="my-custom-page-key" route={{path: "/custom-route"}}>
    <div>My custom page</div>
  </Flex.View>
);

The custom page will be visible at the/custom-route and /some-name paths.

You can also use an array to add even more paths:

<View key="teams" name="teams" route={{ path: ["/supervisor", "/something"] }}>

The view will be visible at the /teams /supervisor and /something paths.

Coordinating Flex UI with your application's routing

If you are using routing libraries like react-router-redux or connected-react-router, you can sync history between your application and Flex by providing the history object that you are using for your Router as a parameter to the Flex store enhancer:

The router application configuration options will have no effect when a custom history object is provided.

import { createStore, combineReducers, applyMiddleware, compose } from "redux";
import { createBrowserHistory } from "history";
import { Provider } from "react-redux";
import { ConnectedRouter } from "react-router-redux";
import { Switch, Route } from "react-router";
import { configuration } from "/appConfig";
import { myReducer } from "/myReducer";

const reducers = combineReducers({
    flex: Flex.FlexReducer,
    app: myReducer
});

const history = createHistory();

const middleware = applyMiddleware();

const store = createStore(
    reducers,
    compose(
        middleware,
        Flex.applyFlexMiddleware(history)
    )
);

Flex
    .Manager.create(configuration, store)
    .then(manager => {        
        ReactDOM.render(
            <Provider store={store}>
                <ConnectedRouter history={history}>
                    <Switch>
                        <Route path="/hi" component={() => {
                            setTimeout(() => { history.push("/"); }, 5000);
                            return (
                                <div>Hi! I will redirect to Flex in 5 seconds flat!</div>
                            );
                        }}></Route>
                        <Route component={() => {
                            return (<Flex.ContextProvider manager={manager}>
                                <Flex.RootContainer />
                            </Flex.ContextProvider>);
                        }}></Route>
                    </Switch>
                </ConnectedRouter>
            </Provider>,
            container
        );
    })

Prepend routes

If you are using Flex alongside other applications, you may wish to prepend the Flex URL path with a prefix so that Flex routing won't interfere with other registered endpoints. For example, let's make our Flex path relative to /foobar. To do so, apply the following configuration settings:

window.appConfig = {
  <...>
  router: {
    type: "browser",
    history: {
      basename: "/foobar"
    }
  }
  <...>
};

The window.appConfig.router.history.basename field tells Flex to make the Agent Desktop available under http://mysite.com/foobar/agent-desktop/.

Implementing route prefixing creates several important side effects for other systems that interact with Flex.

Your server must take the prefix into account in its own routing. The server needs a catch-all fallback route matching the prefix (/foobar in the above example). Otherwise, visiting http://mysite.com/foobar/agent-desktop/ will return a 404. An application's webpack-dev-server config that handles the route might look like the following:

devServer: {
    historyApiFallback: {
        rewrites: [{ from: /^\/foobar/, to: '/foobar/index.html' }]
    }
}

Additionally, the prefix is only for browser routing and is not applicable to memory. Finally, make sure to adjust paths to your assets files, like configuration or CSS!

Learn more in the history node package documentation.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Need some help?

Thank you for your feedback!

Thanks for your feedback!