How To Convert Your Dynamic Full Page Refresh Website To A WebRocketX SPA

Converting your old full page dynamic website to a SPA is straight forward. Outlined below is the conversion process. For the conversion of static websites, go to the Static App Tutorial menu item above.

Conversion Overview

Classic dynamic websites render full pages of HTML markup with dynamic data integrated into the layout. This means that every time a navigation is made the entire page is refreshed. The most common server side frameworks doing this in the industry today are PHP, Struts, Spring MVC, and JSF.

The great thing about an HTML injection SPA framework, like WebRocketX, is that none of your delivery mechanisms on the server have to change. You can continue to use your server side frameworks, but you can greatly simplify the code they are running, as well as reduce the number and size of the trips made to the server. Many of the pages on the server will be broken into smaller stand alone units, and most of the file includes needed to pull in elements, repeated across pages, will be eliminated. Fewer controller calls will be needed as well because there will no longer be the need to persist data to the server session that would have been lost during navigation, because it needed to be saved, but was not yet ready to be committed to the database (this is the achilles heel of full page refresh).

Contrast how easily you can convert your website to an HTML injection SPA, to how much more difficult it is to convert it to a JSON based SPA, like Angular. Converting to a JSON based SPA requires a full rewrite, from scratch, on both the client and the server. Therefore a JSON SPA conversion is a much more complicated and expensive endeavor. Further more, the industry as a whole is coming around to the fact that service calls belong on the webserver, not on the browser.


Step 1 - Don't Change Your Login Page

Keep your current login page the way it is. SPA frameworks don't typically include the login page, and it is really most convenient to keep the login page independent and completely separate. This is especially true since many companies are going to single sign on software (SSO) where the login page is managed by that system instead of the protected web application.


Step 2 - Create Your SPA Welcome/Landing Page

Take your current web application landing page and paste its contents into the WebRocketX landing page template. You shouldn't have to change your backend controller code that leads to this page. Of course, you will change the welcome page to whichever framework and syntax your currently use, but the HTML rendered will need to have the required WebRocketX welcome page framework elements in it. Keep in mind that WebRocketX only exists on the browser and by the time this page makes it there, it is just a bunch of HTML text ready to be rendered and it is not important how this HTML got written on the server.

Typically in your landing page you will have parts of the page that you do not expect to change while the user is navigating your application, like the header, footer, and main menu. You will most likely want to mark, with an id, a div that will be your injection point (aka targetDiv) for you main pages. Keep in mind that even though the SPA page is structured, the developer is still free to inject into the header and the footer, and even subinject anywhere in the page. So, the freedom to update the page is still unlimited. Modal dialogs are of course also supported.

One other point worth making is that the application does not have to be a single SPA. It can also be made up a collection of SPA's. For example, if there are very large flows spawned by menu items, each one of these flows could be a SPA, and each one of these "modules" will need to start with a landing page. Users will not be aware that they are switching SPA's.


Step 3 - Reduce Internal Pages To Content Only

All of the pages in your SPA, other than the welcome page should have the body tag and everything outside of it removed. All of the javascript file references in these pages will be moved to your welcome page. It will be important to make sure the javascript method names between the pages in your application do not have name collisions since they will be all running out of one page now. All style sheet references will all need to be made in the welcome page as well. The content for each page will need to be wrapped in a capsule and any page onload methods that were formerly on the body tag will now be referenced in the jsOnload attribute. Capsule attributes will need to be set up accordingly. Many of the URL's that mapped to these pages can stay the same but they will be called through asynchronous webApi calls now.


Step 4 - Map All Server Side Errors To A Single Error Page View

All major server side frameworks contain a mechanism for mapping unhandled or even typed exceptions to a single failure or error page. Set up this mechanism on your server to return an error page capsule. It should be configured to return only a description when your application is running in production mode and additionally include a stack trace when running in development or QA mode.


Benefits Of Your Web Application Now Being A WebRocketX SPA

For a detailed description of the benefits go here Benefits Of Using A WebRocketX SPA


Contact Us

 If you have questions about WebRocketX, please feel free to contact us at: