DXA HTML design decisions

You all know that DXA comes with a white label HTML design based on Twitter Bootstrap, which you can style according to our own wishes and then publish these changes via the CMS. In this article I will discuss the reasoning behind all of this, and also the different options you have in case you want to change it.

Let us start with the beginning, for DXA we wanted to deliver a production ready website out of the box, that automatically means we needed HTML and an HTML design (i.e. CSS styling and some JavaScript functionality to accompany it with). So we choose a whitelabel HTML design, created especially for us, and since we wanted the HTML to be fixed we choose for a proven framework, namely Bootstrap. You can find the sources of our HTML design on GitHub and you can see an example of the built whitelabel design here: http://sdl.github.io/dxa-html-design/ (both are also available in the DXA downloads on https://appstore.sdl.com/web-content-management/list/digital-experience-accelerator/).

Now the reasoning for having HTML out of the box available, and not letting you pick and choose your own was simple. If we create a module on top of DXA, we want it to work, out of the box, simple install and just work. That means we need to supply you with HTML. Does this mean you are stuck with what we deliver? Absolutely not, you still have every option to change this, but when you do, that means a little less acceleration when you install one of the new modules. Since then you might also need to modify the HTML in the views of that module when you want to use it.

The official DXA documentation has a complete topic on the HTML design, http://docs.sdl.com/LiveContent/content/en-US/SDL%20DXA-v2/GUID-77D92E01-F6CD-45E7-A0C9-776F600364EE. This explains you all about how you can change the styling and even how you can completely swap out the HTML design with your own. But all of this assumes you are still sticking with the Bootstrap HTML, since it does not discuss anything about the HTML in the views.

So having the HTML design assets in the CMS and allowing you to modify them via the Bootstrap Configuration Component, or even by swapping out the raw assets completely in the html-design.zip is a nice feature on most demo and development environments, but I can see that this might introduce a serious risk on a production environment. Which is yet another reason why you might want to ditch this process, and make the HTML design a part of your web application and deploy it together with that.

For a while now, I have a story on the backlog that would allow you to easily remove the complete HTML design from the CMS, and allow you to build your own. But because there are other stories that have a higher priority (like adding SDL Web 8 support in our current sprints), this story keeps getting pushed to the back. I'll use this article as a guide for you, in case you want to do it anyways, so you are not impacted by the fact my story does not have enough priority to make it in the next release.

How the HTML design currently works is quite simple, we have all the raw assets for building a Bootstrap based website in our html-design.zip file. This is built via node.js and Grunt through a Template Building Block at publishing time (which simply executes the node command to let Grunt build it as instructed via the package.json and Gruntfile.js). Now because we don't care about the HTML that comes out of the Grunt build, but only need the CSS, fonts and JavaScript, we use a separate package.json and Gruntfile.js, and also we don't want the publisher to have to download all the node dependencies, so we have included all these additional files (with node.js itself) in our build-files.zip. If you want to know more details about the build process, I recommend you take a look at the source code of the Publish HTML Design TBB in GitHub.

So what do we need to do if we want to remove the HTML design build process from the CMS?

  1. delete the Publish HTML Design Page (you can also delete the Component on it and its references, but simply unpublishing and deleting this page, makes the HTML design unavailable from the Broker database).
  2. deploy a version.json file to the /system/assets folder of your Web application, which contains the version number which is added to the URLs for static assets, i.e.: {"version":"v0.1"}
  3. deploy your CSS, fonts and JavaScript files to the to the /system/assets folder (as part of the deploy of the web application with its views)
  4. update the views in case you need the HTML to be non Bootstrap

Note step #2 is very important, this is also something which comes up when people forget to publish the HTML design initially and find out DXA does not work without a version.json. The /system/assets folder is versions through the value inside the version.json file to prevent unwanted browser caching of our design assets when we update the HTML design. So keep in mind that when you deploy your HTML design manually, you will have to update the version string in the version.json file for it to become available direct without client caching issues.

I hope this article gives you more insight and I wish you all a merry x-mas!

  • that is not really related to the HTML design, but indeed flagged as an issue. Initially we ignored any kind of caching in the DXA web application, because we considered caching strategies something each implementation will want different, so no common ground for us to build upon. However, there is a default cache in DD4T, which automatically gets exposed and also because DXA does not set any cache headers in its HTTP response, the behaviour of the browser for client side caching can be unexpected and unwanted. We are currently revising this for DXA 1.3, and plan to do more in upcoming releases around performance and caching.

  • I don't like DXA checking each and every request of binary whether its stale or new. its slowdown the loading of assets. it should be separate thread doing all this stuff,  rather than intercepting all the calls.

  • maybe not the HTML itself (apart from fixes perhaps), but yeah it would be nice if the community could come up with some decent "skins" making the design a bit more attractive in demo scenarios. This is also something we will need in the future when we deliver DXA in the cloud in a multi tennant scenario, but I won't go into too much detail there yet ;o).
    How to collaborate on that, well these skins could be packed as a module and uploaded to the eXtensions area of the Tridion Developer community https://community.sdl.com/developers/tridion_developer/m/mediagallery

  • Nice, Bart. Do you see the HTML side of DXA evolving in the community (or even in other communities)? I know of a few DXA HTML variants for training and demos, but how could we collaborate here?

    One idea we had for Spark 45, a DXA precursor was a context for the HTML design. Think that or a hackathon might fit your open source DXA model?