URL Routing and Single-Page Applications
SuiteCommerce solutions use Backbone to power their single-page application (SPA) architecture. A SuiteCommerce website is built using three SPAs linked together. One of the reasons SuiteCommerce uses SPAs is to cache the code structure of the site and its resources and associated data so that when a user navigates around the site, performance is fast. This means everything happens internally within the SPA so a page does not need to send a request to the server for a new page every time a user wants to move around a site—the page only needs to fetch new resources or data.
Because of the SPA architecture of SuiteCommerce websites, you need to use special mechanisms to manage user navigation. Read the following sections to learn more:
Avoid Standard JavaScript Mechanisms
When working with a site outside of an SPA framework, you can use standard JavaScript to change location with code like this:
var url = '/search';
// Non-fancy
window.location.href = url;
// Fancy
window.location.assign(url);
The problem with this approach is that it’s equivalent to a user entering a URL into their browser’s address bar. Therefore, the user’s request will have to flow through the entire process detailed in the flow chart in URL Routing in Commerce Websites. This means you are terminating the SPA and reloading it, which is bad for performance and not ideal for the majority of use cases.
Rely on Backbone
There are numerous times you might process a user’s location in the SPA. For example, when:
-
The SPA is passed a URL path to process
-
A user clicks a navigation link generated in a template
-
A user has completed a wizard (such as filling out a form) and needs an exit URL
There are additional cases and so you need a mechanism within the framework to handle this type of processing.
When you create a route in Backbone by using the routes array in a router or page type, you are creating a link between a URL path and a callback. That callback determines what to do when that route is triggered. From a simplistic point of view, that callback will usually fetch data and then render a specific view.
You can trigger these routes using a method attached to the Backbone.history class called navigate(). The navigate() method accepts a route and an options object. Normally, the only option you have to pass to the navigate() method is a request to trigger the navigation immediately. For example:
Backbone.history.navigate('/search', {trigger: true})
The code in the preceding sample relocates the user to the /search path, which is typically the route of the main search PLP.
List All Backbone Routes
To learn more about Backbone and how it routes the URL fragments it receives, read the Backbone.js documentation (including their annotated source file). You can also get a sense of how Backbone routes URL fragments by looking through your site using your browser's developer tools. For example, you may want to retrieve a list of all routes registered with the current SPA. To do so, load your site on your favorite browser and then in the browser’s developer console, type:
Backbone.history.handlers
The browser developer tools return an array of objects, each one with a route and its associated callback. Note the following about these objects:
-
Routes are stored as regular expressions (regexes). Regexes are a way of defining a search pattern for strings. In other words, rather than storing an exact string, Backbone stores an abstract pattern of that string so that it can catch variations. When you pass a character string, Backbone evaluates that string against a regex to determine whether there’s a match. If, during evaluation, one of the strings matches and returns true, then it triggers that route's callback and starts the navigation process.
-
When Backbone receives a request to process a URL path, it runs the string against each of the regexes (routes) in order until it finds a match. It is not uncommon for mature sites to have hundreds of routes, particularly if they have many categories and landing pages. When all routes are exhausted, the default route initiates, which is to direct the user to a 404 page.
However, on the shopping application there is one final check for product pages before the default route initiates. Because of the sheer number of possible URL paths for product detail pages (PDPs), they are not individually included in the list of routes. Instead, the shopping SPA is set up to try fetching product data with the items API using the specified URL prior to returning a 404. If that call succeeds, the user is navigated to the PDP for that URL. If it fails, then all routes have been exhausted and the user is directed to the 404 page. This is why a 404 page coincides with a failed items API call.