March 17, 2021
In May 2020, a team of Episerver’s developers released a project called “Foundation Spa React”. The exemplary Foundation SPA React project consists of two parts: Back-end and front-end. You can think of it as an exemplary or boilerplate project of a SPA website. It features a SPA JS library, also created by Episerver’s team. Spa-core is basically a framework that aims to streamline the Episerver SPA website creation.
We decided to analyse this whole project more thoroughly in this blog post. Here, we are going to focus on technicalities – the project’s structure and configuration. Let’s dive in!
The exemplary Foundation SPA React project consists of two parts: Back-end and front-end. The front-end part of the project is built mainly on React, Redux and the foundation-lib-spa-core library. The foundation-lib-spa-core is a library (or even a framework) also created by the authors of the Foundation SPA React, and it also uses React and Redux. This library takes care of a lot of standard SPA problems (e.g., routing and dynamically content loading). It also includes the React components for the Episerver CMS properties (e.g., content area, XHTML, etc.). Those components also ensure that the WYSWYG (on-site editing) experience works correctly.
When the browser opens the page, a prerendered version will be fetched from the server and displayed to the user. The rest of the data will be loaded dynamically via XRH requests made to the CDA. It is worth mentioning that the Episerver's project implements some custom controllers that extend the CDA functionality and execute custom actions.
Developers can customise a page by defining proper models, views, custom service and states. The framework will then render proper views depending on the content that needs to be displayed. A nice feature provided by the Episerver developers is the possibility of synchronising back-end Episerver content models with the front-end application code. At this point, we have to note that the front-end content models should exactly match the ones on the server, as the foundation-lib-spa-core framework expects them to be identical.
In fact, the Foundation SPA React page solution consists of several projects. Almost all of them are back-end-related. Only one of them is strictly front-end-related (Spa.Frontend). However, we reckon it shouldn’t be too hard to extract it to a different solution and keep it separated from the back-end code.
The front-end part of the foundation project relies heavily on the lib-spa-webpack:
The second one (foundation-lib-spa-core) implements a lot of features that aim to help with SPA development.
Now, let’s take a closer look at the structure:
A welcomed feature provided by the developers is the possibility (or, in this case, rather a need) of synchronising the back-end Episerver content models with the front-end application code. This synchronisation comprises elements like pages, blocks, media, categories etc.
The foundation-lib-spa-core element contains a script that makes an HTTP call to the Episerver content delivery API, to pull the models’ definition. Then it generates typescript models based on the response. Mind you; the generated models should not be altered manually. The reason is twofold:
Extending the project with a new page type and the view is relatively straightforward. You need to do two things:
Your page type should be present in the Models folder:
The next step is to create the page view class:
In this straightforward example, we used the Property component (which is just one of many things provided by the spa-core library). This component is responsible for: 3. Rendering a particular property (it will handle various property types, e.g., strings, numbers, XHTML, references and content areas differently). 4. Adding proper attributes that enable the on-page editing experience.
In these few steps, we’ve created a new page type and a corresponding view. As you can see, the framework deals with many things for you. For instance:
As you can also see in the picture above, a global layout is applied to your page. You can easily change it by modifying the MoseyLayout.tsx file or, even better, replacing it in the Config.tsx file (the next section).
The Config.tsx file in the SPA.Fronted project contains the page configuration. The AppConfig has some amazing properties, like, for instance:
It also allows you to define custom modules that should be implemented in the IInitializableModule module interface.
Of course, these are just some of the basic things about the SPA foundation project. There is a lot more you can do with it.
Daniel is a developer at Noa Ignite with a background in backend, fronted and devops technologies. Currently he's working mostly with Optimizely, Umbraco, React and Azure. After work Daniel spends most of his time being a parent, playing boardgames, painting miniatures and running D&D sessions.
More blog posts for you