Serializing Data

So far in the examples in this book, we have used cookies, path and query parameters, and hardcoded defaults. In the real world, applications also rely on data from remote sources such as REST or GraphQL services. In JavaScript apps, this data is ultimately stored in a POJO, or plain old JavaScript object. The data is used in conjunction with HTML and DOM event handlers to create user interfaces. On the server only the HTML portion of the interface is created because the DOM bindings cannot be done until the server response has been received and processed by the client. The processing, rehydration, and DOM binding on the client often relies on this state data from the server. Additionally, user interactions that trigger events after the rehydration and binding typically need access to this data to modify it or make decisions. Therefore, it’s important that the data be accessible by the client during rehydration and afterward. Unfortunately, the POJO cannot be sent across the network as part of an HTTP request. The POJO needs to be serialized to a string that can be passed to the template, parsed by the client, and assigned to a global variable.

The serialization is accomplished using JSON.stringify, which creates a string representation of the POJO. This is the standard method for serializing a POJO, but we still need to add a method to our Controller class from Example 7-3 that can be executed on the server and that returns this stringified POJO:

serialize() {
  return JSON.stringify(this.context.data || {});
}

For our application the default implementation is serializing the this.context.data property from ./src/lib/controller.js. However, this default behavior could be easily overridden to handle different use cases. Sometimes there are APIs for setting and getting data in a POJO, such as Backbone models or Redux stores (store.getState). For these and other client data stores the serialize function can be easily overridden to implement custom behavior for serializing these objects.

Next we need to update the document function from Example 8-15 (./src/options.js) to call the new serialize function, as seen in Example 10-1.

export default {
  nunjucks: './dist',
  server: server,
  document: function (application, controller, request, reply, body, callback) {
    nunjucks.render('./index.html', {
      body: body,
      application: APP_FILE_PATH,
      state: controller.serialize(),
    }, (err, html) => {
      if (err) {
        return callback(err, null);
      }
      callback(null, html);
    });
  }
};

Finally, we create a global variable in our template (./src/index.html) that can be accessed during rehydration on the client:

<script type="text/javascript">
  window.__STATE__ = '{{state}}';
</script>

Creating a Controller Instance

The next step in the rehydration process is to create a controller instance on the client for the current route. This instance will be assigned the serialized data and bound to the DOM, which will enable the user to interact with the HTML interface returned by the server. Fortunately, we have already written the code to look up a Controller class using the router and create a controller instance. We just need to reorganize the code a bit so that we can reuse it.

In the navigate function we created in Example 8-4 we used the URL to look up the Controller class in the application route table. If one was found, we then created a controller instance. This code can be moved to a new function in the Application class (./src/lib/index.client.js) that can be called by the navigate function, defined in Example 10-2.

createController(url) {
  // split the path and search string
  let urlParts = url.split('?');
  // destructure URL parts array
  let [path, search] = urlParts;
  // see if URL path matches route in router
  let match = this.router.route('get', path);
  // destructure the route path and params
  let { route, params } = match;
  // look up Controller class in routes table
  let Controller = this.routes[route];

  return Controller ?
    new Controller({
      // parse search string into object
      query: query.parse(search),
      params: params,
      cookie: cookie
    }) : undefined;
}

Now we can use the createController function in the navigate function and a function that we are about to create, rehydrate (Example 10-3).

// encapsulates code that is used in the rehydrate method and
// the popStateListener in the start method
getUrl() {
  let { pathname, search} = window.location;
  return `${pathname}${search}`;
}

rehydrate() {
  this.controller = this.createController(this.getUrl());
}

navigate(url, push=true) {
  // if browser does not support the History API
  // then set location and return
  if (!history.pushState) {
    window.location = url;
    return;
  }

  let previousController = this.controller;
  this.controller = this.createController(url)

  // REMAINDER OF FUNCTION BODY OMITTED FOR BREVITY
  // see the complete example in the "Attaching DOM Event
  // Handlers" section of this chapter
}

The rehydrate function can then be called by the start function (Example 10-4).

start() {
  // PREVIOUS CODE OMITTED FOR BREVITY
  // the rehydrate call has been added to the bottom
  // of the function body
  this.rehydrate();
}

Deserializing Data

In the previous section we created an instance of the controller during the application rehydrate process on the client. Now we need to transfer the state that was created on the server and serialized as part of the server page response to the controller instance on the client. This is necessary because routes can have different states, and the application will depend upon these states. For instance, if the route rendered on the server has any sort of interface for interacting with or manipulating data, such as an “add to cart” button, a form, a graph with a range selector, etc., then the user will likely need that data to interact with the page, rerender the page, or persist a change.

In “Serializing Data” we included the state data in the page response, so now all we have to do is implement a deserialize method on the base controller (./src/lib/controller.js):

deserialize() {
  this.context.data = JSON.parse(window.__STATE__);
}

This method can now be used as part of the rehydration process to assign the data to the controller instance. We can add data rehydration to the client Application class’s rehydrate method (in ./src/lib/index.client.js) as follows:

rehydrate() {
  this.controller = this.createController(this.getUrl());
  this.controller.deserialize();
}

Attaching DOM Event Handlers

The last part of the rehydration process is attaching event handlers to the DOM. In its simplest form, event binding is done by calling the native method, addEventListener, as shown here:

document.querySelector('body').addEventListener('click', function (e) {
  console.log(e);
}, false);

Some libraries set the context for the event listener functions to the view or controller object that created the listener. Some libraries, like Backbone, have an interface for defining event listeners. These event listeners are bound to the containing view element using event delegation to reduce overhead in the browser. In our case we are just going to add an empty method, attach, to the controller that is called during the rehydration process. It will be up to the application developer to implement the method details:

attach(el) {
  // to be implemented by the application
}

In addition to the rehydration process, the attach method should be called as part of the client-side route response lifecycle. This ensures that a route handler will be bound to the DOM regardless of whether it was executed on the client or the server. Example 10-5 shows how we add DOM binding to the client Application class’s rehydrate method.

rehydrate() {
  let targetEl = document.querySelector(this.options.target);

  this.controller = this.createController(this.getUrl());
  this.controller.deserialize();
  this.controller.attach(targetEl);
}

These two calls to the attach method ensure that a route handler is always bound to the DOM. However, there is a bit of an issue with this code—there is not a yin for our yang. If we continually attach handlers to the DOM without detaching a previous handler, we could end up with a memory leak. Adding a detach method to the base controller and calling it as part of the client-side route handler lifecycle, as shown in Example 10-6, can help prevent this problem. detach will be an empty method like attach, leaving the implementation details up to the application developer:

detach(el) {
  // to be implemented by the application
}

navigate(url, push=true) {
  // if browser does not support the History API
  // then set location and return
  if (!history.pushState) {
    window.location = url;
    return;
  }

  let previousController = this.controller;
  this.controller = this.createController(url)

  // if a controller was created then proceed with navigating
  if (this.controller) {
    // request and reply stubs
    const request = () => {};
    const reply = replyFactory(this);

    if (push) {
      history.pushState({}, null, url);
    }

    // execute controller action
    this.controller.index(this, request, reply, (err) => {
      if (err) {
        return reply(err);
      }

      let targetEl = document.querySelector(this.options.target);
      if (previousController) {
        previousController.detach(targetEl);
      }
      // render controller response
      this.controller.render(this.options.target, (err, response) => {
        if (err) {
          return reply(err);
        }

        reply(response);
        this.controller.attach(targetEl);
      });
    });
  }
}

Verifying the Rehydration Process

Now that we have the core pieces in place that enable an application to recall state and attach itself to the DOM, we should be able to rehydrate our app. To test recalling state, first let’s generate a random number in the index method of the HelloController class (Example 7-7) and store it as a property in this.context.data:

index(application, request, reply, callback) {
  this.context.cookie.set('random', '_' + (Math.floor(Math.random() * 1000) + 1),
    { path: '/' });
  this.context.data = { random: Math.floor(Math.random() * 1000) + 1 };
  callback(null);
}

Next, we need to add this.context.data to the rendering context for the toString method in HelloController:

toString(callback) {
  // this can be handled more eloquently using Object.assign
  // but we are not including the polyfill dependency
  // for the sake of simplicity
  let context = getName(this.context);
  context.data = this.context.data;

  nunjucks.render('hello.html', context, (err, html) => {
    if (err) {
      return callback(err, null);
    }

    callback(null, html);
  });
}

We can now render this random number in the hello.html template:

<p>hello {{fname}} {{lname}}</p>
<p>Random Number in Context: {{data.random}}</p>
<ul>
  <li><a href="/hello/mortimer/smith" data-navigate>Mortimer Smith</a></li>
  <li><a href="/hello/bird/person" data-navigate>Bird Person</a></li>
  <li><a href="/hello/revolio/clockberg" data-navigate>Revolio Clockberg</a></li>
  <li><a href="/" data-navigate>Home Redirect</a></li>
</ul>

Next, we can log this.context.data in our attach method and compare the values:

attach(el) {
  console.log(this.context.data.random);
}

We can also add a click listener in our attach method to verify that the correct target is being passed to this method and that an event listener can be bound to it:

attach(el) {
  console.log(this.context.data.random);
  el.addEventListener('click', function (e) {
    console.log(e.currentTarget);
  }, false);
}

Next, we need to ensure that we clean up the event handler we added in our attach method. If we don’t do this, then we will have an event handler for each navigation to the /hello/{name*} route. First we need to move the event listener function from the attach method to a named function, so that we can pass a reference to the function when we remove it. At the top of the HelloController class, let’s create a function expression:

function onClick(e) {
  console.log(e.currentTarget);
}

Now we can update our attach method and add a detach method:

attach(el) {
  console.log(this.context.data.random);
  this.clickHandler = el.addEventListener('click', onClick, false);
}

detach(el) {
  el.removeEventListener('click', onClick, false);
}

If you reload the page and click anywhere, you should see the body element in the console. If you navigate, clear the console, and click again, you should only see one log statement because our detach method removed the event listener from the previous route.

Figure 10-1 shows a high-level overview of what we’re aiming for.

Figure 10-1. Client rehydration

Summary

We learned a lot in this chapter. Here’s a quick recap of what we walked through:

• Serializing the route data in the server page response

• Creating an instance of the route handler on the client

• Deserializing the data

• Attaching the route handler to the DOM

These rehydration steps ensure that an application functions the same for a user regardless of whether the route was rendered on the client or the server, with the added performance benefit of not refetching the data.