Tasks and Portals in React

Modals are arguably one of the most common UI patterns in single page app development, and there are many, many ways to implement them. We use React for our rendering layer in our Moneyhub client apps, and this article shows you how we skinned this particular cat.

The problem

We recently had a design change that meant we wanted to be able to perform critical user journeys as a set of discrete tasks. For example, let’s say I’m using the Moneyhub client app to manage my various bank accounts, and my financial adviser has set up a new cash ISA on my behalf. They would want to make sure that they can share this cash ISA with me via the Moneyhub app so that I can see its balance. To achieve this, my IFA as a user of our enterprise platform would want to connect to my ISA provider, retrieve my ISA data and then share that data with me.

As you can imagine each of these flows should keep my IFA user updated, giving them feedback and prompting them for input as they progress. The idea isn’t so much to handhold through each task, rather to prompt them into making choices that are simple and intuitive. Remember that we’re talking about an enterprise user, so they probably have lots of clients that they want to manage. It’s really important that we make their job as simple as possible.

Tasks

Once we had identified the tasks that needed to be performed e.g. connecting to an ISA provider, or retrieving client account data, we needed a solution that would give the user the correct outcome as they progress. We decided to model a simple state machine, wrapping its logic inside a React component. In our case this component is known as a `<Task />`.

Each task is very simple, it takes an array of screens to iterate over, as well as an identifier for the current screen (status) that is being displayed. This can be set out simply using the following Pseudo code.

Next we wrap the task, itself, inside a <TaskProvider /> component, that would bind events to progress the user through the screens.

While the example is a little rough around the edges, it shows you the core pattern. Also the screens, the task and handlers are nicely decoupled and broken into separate parts.

This is really useful as it means that we started to separate our components between those that are responsible for arranging data and orchestrating callbacks and actions (Containers), and those that should present content to the user (Presentational). You can read a more detailed explanation of this here : https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0

Now the real problem

Having a pattern to solve the problem of the user journey through a task however is only part of the solution. We quickly realised that our implementation had to take into account animating between screens, and more importantly rendering those screens as part of a Modal pattern. This meant that we now had to solve two additional problems:

- Create a set of predefined screens that would compose a single task

- Render each task outside of the main app

The first part was fairly straight forward. We knew upfront the types of screens that we required, these were divided into two groups: the first would take user input and the second would inform the user of the task’s progress. As the differences between the two groups was so small we decided to abstract a lot of the core functionality for a given screen away into a core Presentational <Modal /> component that would perform all of the common tasks for us e.g. positioning, cancelling a task and animating between screens.

So following on from this architectural division of components, our <TaskProvider /> component is clearly a Container component. Its sole purpose is to orchestrate the mapping of screens to a given task.

As our presentation is abstracted away into the Modal component, our screens then take on the role of Container components. They are very simple stateless components that have a common API. They are only concerned with delegating handlers and data into our Modals, who in turn are responsible for capturing user input (when user input is needed) and displaying a message to the user. A good example would be a screen that prompts the user to take one of two actions. We decided to call this a <Prompt /> component. Here’s its API:

You can see that the actual positioning and managing of the task flow has nothing whatsoever to do with the screen components. The <Modal /> which the <Prompt /> is an abstraction of, is the one that is concerned with positioning etc. At its most basic the <Modal /> component would look something like:

I’ve put together a working example to show the container and presentational components work together : http://codepen.io/jeanpaulgorman/pen/RpPjVJ

What becomes clear, is that the actual content of the task screens can be anything that you want it to be, which means that you can render a task into the app at any point that you need. Which leads onto the final problem: as we are using a Modal to render our screens, we really don’t want to rely on the css property `position: fixed` to jump the Modal to the top of the DOM stacking order. Really we should continue to utilise the container/presentational pattern so that we can render a Modal outside of the main app, even if that Modal is invoked deep down within the main app.

Not only will this give us a cleaner, simpler DOM structure, it will also allow us to pass our handlers into the Modal from the main app, without having to pass those handlers out of the app.

In short we would want the following:

gives us:

This type of relocation of content, or rather transportation of where content is rendered to is known as a Portal within the React community. Looking at the code you can see why. As a developer you define your content and place it into your <Modal /> and the result is transported via a portal to be rendered elsewhere.

So how would the portal actually work? Firstly it should have no boilerplate, it should be a simple wrapping or higher order component that takes children as its main props. If you aren’t familiar with high order components (HOCs), you can read more about them here https://facebook.github.io/react/docs/higher-order-components.html , however the basic principle is that they are a function that takes a component as at least one argument and returns a new component that wraps the first, augmenting its behaviour. Here’s a simple example of an HOC that logs new props as they come into a component e.g.

You can see from this example that our higher order component is only adding the minimum functionality to our wrapped component by utilising the React lifecycle methods. That’s something that is pretty common for higher order components and something that we’ll use now to attach our Modal component to the correct DOM node.

Let’s start by creating our HOC and giving it a name.

Great! Now that we have our basic structure we know how to generate new components that will be appended to the document.

```
const Portal = createPortal(Modal)
```

Our usage would then be as follows, and we can pass any props onto this component, safe in the knowledge that they will find their way to our Wrapped Component, in this case the Modal :

```
<Portal />
```

Now we need to get our HOC to actually carry out the task of loading our wrapped component into the DOM location of our choosing. To do this, we’ll utilise the ReactDOM.render method. This method allows for our component to be attached to a given DOM node, and if that component is then re-rendered, it will carry out the React diffing and shadow DOM rendering that we’d expect of any other react component. Let’s add this in.

You can see a working example here: http://codepen.io/jeanpaulgorman/pen/MpwqmE

If you open up the dev tools, you’ll see that the Modal is being rendered into the `append-to-container` DOM node, completely separate from the main app. This is great as we’re now free to style that DOM node as we please, without having to deal with CSS specificity or relying on `position: fixed` to push our Modal to the top of the stack.

However we’ve still got a few things that would stop this from being really useful. Firstly, we have to hand crank a new DOM node each time we want to attach a different type of element, for example we wouldn’t want to load a chat app into the same DOM node as our Modal, things would soon get complicated. Really we want to be able to name each DOM node that we want to render into, and if it’s not present, create it.

Secondly, we can currently only render one component at a time. This is fine for many situations, but would soon become unmanageable in a production SPA. Really we need a registry of components that we want to render outside of the main app and we’d want to map each of these to the correct DOM node to load into.

Finally we’ll need to tidy up the DOM nodes as we go. There’s no point having an empty DOM node sat in place when we have no components to render into it.

So with these things in mind we need to divide this code into three separate parts:

1. Methods to handle DOM reconciliation.

2. A registry of components to render.

3. Methods that will iterate over our registry and render each component into the correct DOM node.

Luckily we’ve already done this for you. You can checkout the source code here and run a DEMO : https://github.com/jpgorman/react-append-to-body

If you enjoyed reading this post, follow us on Twitter @MoneyhubEnterpr and LinkedIn or go to our website https://www.moneyhubenterprise.com/, to keep up to date with our news and insight.

Written by Jean-Paul Gorman (@_jpgorman), Software Engineer at Moneyhub Enterprise