Kevin's Blog

Sooner or later, it's going to happen.  You'll apply a module update or do some other under-the-hood task and the next thing you know, your Drupal 8 site is no longer responding (often called whitescreening).  While whitescreening is a good security practice (as opposed to the site spewing error messages to the browser that might reveal sensitive details), it's a royal pain when you just want your site to work and you have no idea what's wrong or where to start with fixing it.

What follows are some tips and advice that might get you back in action again without (completely) losing your sanity.

Backup, Backup, Backup (and Restore)

I'll go ahead and get this one out of the way, even though it may be too late at this point to be of any help.  In the future, always have an automatic backup generation plan in place.  The typical advice is to always make a backup before doing anything dangerous to your site, like applying patches and updates, but it's often when you don't think your action could be very dangerous that it ends up frying the whole site.

For some reason, the new internal page caching system has been the hardest thing for me to wrap my head around in Drupal 8, and dealing with it properly has eluded me for the better part of two years.  I think part of the problem is a lack of clear, understandable documentation about how it all works, so here's my attempt to sort it all out:

A Whole Host of Caching Tools

One of the more confusing parts to Drupal 8 is that there are now several ways to control caching, but the names of these components are not terribly intuitive and documentation is still kind of sparse.

External Caching Controls

Drupal 8 has an external cache control, on the Development -> Performance page, named confusingly "Page cache maximum age" (in Drupal 7, it was called "Expiration of cached pages", and the visible description included the phrase "external cache").  Contrary to what you might think, all this control does is to set an HTTP header that systems like Varnish can read and use to decide how long to cache that page.  The setting has absolutely no effect on the internal page cache.

Introduction

Recently, I released a framework that I call a Web Theming Infrastructure, and I think it's worth dissecting and exploring here given the potential that I see in it.  But first, I have to explain how I got to this point.

For more than a decade, web theming at Georgia Tech has been the domain of Institute Communications, and they have handled both specifications and implementation.  Unfortunately, they've never been funded to act as a true central web development unit, so they have struggled to manage the implementation side of the equation.  I would imagine that Georgia Tech is not alone in facing this kind of problem, but like most universities, we have been applying early 2000's techniques to a rather complex problem that needs a more sophisticated approach.

A little over a year ago, I wrote about the usability of the Migrate tool in Drupal 8.1.  We're now up to Drupal 8.3, and while Migrate has improved a little bit, it's still officially an experimental module, and still has some notable gaps.  This doesn't mean that you can't successfully use it, but you do have to understand what you're getting from it and prepare yourself to bridge those gaps by hand.

The instructions I gave in my previous post are still valid, so I won't waste space repeating them here.  Instead, I want to start by explaining how the Migrate tool works, so that you can better understand its limitations.

Having worked on new ways of doing layouts with the Paragraphs module and worked with Institute Communications on the development of a new version of the Georgia Tech web theme, I realized that there was still one component of website visual design that I had yet to address:  a visual building block toolkit for content creators and editors.  Custom layouts are a part of this puzzle, but they do not address the need for custom styled headings, buttons, introductory text, etc. that need to be part of the actual content of a page.

The challenge here is that you want to make these custom styles easy to use and easy to maintain.  The most obvious approach is to add them to your chosen WYSIWYG editor, but figuring out how to do that can be tricky.  Here at Georgia Tech we use Drupal and in turn the preferred Drupal editor, CKEditor.  This is helpful, as there are lots of guides out there for extending both Drupal and CKEditor, but it can take time to dig through them and figure out how to make it all work.