A blog by the Brick Factory The Brick Factory
Drupal Blog Post Header

A step-by-step guide to configuration management in Drupal 8

One of the best improvements in Drupal 8 is the new configuration management system. This post explains how things have changed from Drupal 7, and provides a step-by-step walk of Drupal 8 configuration management.

Configuration in Drupal 7

If you’ve spent much time site building or programming in Drupal 7, you probably have worked with the Features module. This module was originally created as a way to package config to easily create reusable functionality on multiple Drupal sites. But it evolved to be used for a much larger task: deploying configuration that is stored in the database between environments for the same site (commonly pushed to a code repository like git).

Our Brick Factory team started using Features for our Drupal 7 builds around four years ago, and it has saved us a bunch of time and headaches.  Before Features, we had to remember the configuration changes we made on the dev environment so we could manually re-apply them on the staging and live servers (which is loads of fun!). Features made it very simple to do this and not have to remember all of the config changes.

The Features module did fill a huge need, but it also came with some unique problems:

  • Learning Curve: The learning curve was steep. For us to get comfortable with the concepts and the flow, it took around a year of experience using the module across different projects.
  • Organization: It seemed like people had different ideas in how Feature modules should be organized across the Drupal community. From my experience, I think grouping into small feature modules prevents a lot of issues in the future, especially with large sites.
  • Overwritten Status: The overwritten status could mean multiple things. Did someone update config on live manually? Or did someone push changes to the feature modules and forget to revert? What was changed? This led to a lot of confusion.


How We Built It: International Youth Foundation Annual Report

A few weeks ago I wrote a post about changes we have made to our Brick Factory design process over the last few years.  Check out the full piece if you have time, but the gist is that we haved moved away from designing pages and towards creating systems.  We are trying to design overall styles and repeating elements that make up the pages, instead of the pages themselves.

Showing is always better than telling, so I wanted to write a follow up post using the Annual Report micro-site we built for the International Youth Foundation as an example.  What follows is an explanation of our design and build process for the project, with actual deliverables included to make things more concrete. (more…)

design system

Design Systems, Not Pages

For most of the web’s short lifetime, the primary way to design a website has been to create  wireframes and comps (design compositions) of a site’s key pages.  Oversimplifying a bit, designers  identify these key pages and essentially create pictures of what the pages  look like when presented on the web.   The designs are typically done with desktop computers in mind and at a fixed screen width.

The client or product owner provides feedback on the work and eventually approves the page designs.  The comps then get converted into HTML/CSS and built out as templates in whatever Content Management System is being used. And done! Like magic!

While not exactly easy, this process more or less worked for a long time and was the primary method most firms used to design websites.  For a variety of reasons, over the last few years this page-centric design approach has proven to be irrevocably broken.  The page-based approach is simultaneously time consuming and ineffective at showing what the end product will actually look like.

Following we explain the problems with page-based design and how our Brick Factory team has transitioned to a system-based design approach.

Why page-based design doesn’t work

Rise of Smartphones and tablets.  

Five years ago, nearly all website traffic came from desktop and laptop computers.  If 10% of a site’s traffic came from phones and tablets that was a lot.  Today it isn’t unusual for a site to see 50% of traffic coming from phones and tablets.

And within each of the main device categories (phones, tablets, desktops and laptops) there is a ton of variance in screen sizes.  For our average site, the  most popular screen size (usually 1366 * 768) is used by only 10% of visitors.  For the highly trafficked websites we work on, we might see as many as 1,500 unique screen resolutions each month.  A single site design must  provide a good experience on gigantic desktop monitors (2560 * 1600) and tiny mobile screens (230 * 270).  As you can see, these are two very different balls of wax.



Given the range of screen resolutions, creating designs comps of a bunch of pages at arbitrary screen sizes just doesn’t make a lot of sense.

Increased Complexity of Interfaces

Web design has gotten a lot more sophisticated over the last few years.  The projects we complete for our larger clients feel more like applications than simple websites, with user inputs often driving how the site looks and behaves.  Designing these interactions out as “pages” requires a ton of page comps.  For example, a donation system for a nonprofit client could easily require 10-20 page comps by itself.

Even simple websites are much more complex than they were four or five years ago.  A four or five page promotional website today is likely to include sophisticated transitions and animations that are difficult to convey in a page comp.

It just isn’t efficient to demonstrate this sort of complexity via flat, page-based design comps.

Page-Based Design Doesn’t Scale

Due to the proliferation of screen resolutions and increase in complexity, on large projects we have ended up doing a staggering number of wireframes and design comps when using a page-based design approach.  Whereas four or five years ago a complex project might have meant twenty page designs, today it can easily mean 50-100.

The sheer volume of comps that we have ended up producing has lead to consistency problems.  If every page is designed separately, unnecessary and redundant design elements are very likely to get introduced.  This makes the resulting site harder to build and maintain, and the overall quality of the work is compromised.

Page-based design just doesn’t scale.

Bottom Line

Perhaps the biggest problem with page-based design is that it creates an inaccurate representation of how the end user will experience the resulting website.  The designs a client approves don’t really reflect what the site ends up looking like.

Once those pixel perfect PSDs are turned into HTML/CSS and viewed in different browsers at different screen resolutions, they often look pretty different.  All that painstaking design work is sort of wasted, as you still end up spending a ton of time polishing the site once you have a working draft.

Ultimately with page-based design there is a fundamental disconnect between the way the site is designed (flat PSDs) and the way it is built (HTML, CSS, Javascript, etc.).

So What’s the Solution?

While it has been a bit of a struggle, over the last few years we have made a conscious effort to move away from page-based design.  Along with many other designers, we are trying to design systems instead of pages.

While we are still refining our approach, for us this means creating a design process that is in tune with the way websites are actually built and function.  We design overall styles and repeating elements that make up the pages, instead of the pages themselves.  So instead of fifty design comps, for a project today we might produce the following design deliverables instead:

  • An overall style guide that defines palette and typography and the look/feel for critical, repeated site elements such as buttons, bullets, forms, images and icons.
  • Designs for key components that will be used repeatedly on the website.  For our clients, typical repeating components might include a site navigation system, page header, email sign-up, photo gallery, news headline grid and donation system.  For components that require interactivity, we will produce  HTML prototypes in addition to or instead of a set a of flat design comps.
  • Content hierarchy and/or wireframes that define what components make up each of the page templates we create.
  • Wireframes and design comps for a few important pages so the product owner or client can get a sense of what the end product will look like.  We aim to limit this to a handful of key pages instead of creating a design for every unique page and template.

After we get these key building blocks designed and approved, we start creating the site templates in HTML/CSS and see what things look like.  We then allow ourselves plenty of time for refinement and polish.  Instead of front loading all the design work, we take a more agile approach and fine tune the design after we see what the working draft looks like.

We haven’t perfected our process yet and by the time we do everything is likely to change again.  But, at least to us, this system-based approach makes a lot more sense than producing an endless series of page comps.

We wrote a follow up to this post walking through a project that uses a systems-based approach.

Ten Reasons We Moved Into a New Office

We moved into a new office space in the McPherson Square area of Washington, DC on May 1. The 5th floor on 925 15th Street NW to be exact. Here are the top ten reasons for our big four block move.


Nine Ways to Improve the Drupal Administrative Experience

In the open source world, you often hear people observe that Drupal was built for developers while WordPress was built for content managers.  This observation contains thinly veiled criticism of both platforms.  For Drupal the implication is that the platform doesn’t provide a great user experience for content managers.

The criticism sticks because it is sort of true.  Right out of the box Drupal’s administrative tools aren’t intuitive or easy-to-use.  With the release of Drupal 8, Drupal out of the box is better than it used to be, but is still somewhat baffling to folks that aren’t familiar with the platform’s quirks.

As someone who builds sites in both WordPress and Drupal, I have to admit that I have contributed to Drupal’s bad content management reputation.  I am guilty of not focusing enough on the experience of people that do the day-to-day work in Drupal: content managers.  The fact is, with a little effort you can create a good content management experience in Drupal.  Below are some tips on how you can improve the Drupal administrative experience.

(1) Create Custom User Roles

By default Drupal creates an Administrator user role that has access to the entire backend administrative system (content, theme, blocks, views, etc.). When setting up a site, all administrative users ware often given access to the full suite of backend tools.  This is confusing to many users as they have access to lots of features they aren’t familiar with and really shouldn’t be using.  It can also lead to bugs as admins experiment with backend tools they haven’t been trained on.

Drupal features a powerful user role system that allows for the creation of custom user roles.  Once a custom role is created, super administrators can pick and choose what backend features and functionality the role has access to.    At the beginning of a new project user roles should be set up for the different types of administrators.  People who are just going to be managing content should only have access to the content editing tools.  If someone is just posting press releases, they should just have the ability to post press release.

This approach both makes the administrative tools easier to use and prevents mistakes caused by people using features they haven’t been trained on.

(2) Customize the Look of the Administrative Section

The default Drupal administrative themes that come with Drupal 6 and 7  aren’t very attractive or usable.  Fortunately there are a myriad of slick administrative themes you can install to improve the Drupal administrative experience.  We are partial to Ember for Drupal 7 sites.

Drupal 8 actually has a pretty nice default administrative theme, although you can use a different theme (or create your own) if you want to.

Take the time to make sure your Drupal administrative section looks as nice as the site’s frontend.

(3) Customize the Options in Your Administrative Menu

If you have used a Drupal site you are undoubtedly familiar with the menu options that are available by default.  Content.  Structure.  Appearance.  People.  Modules.  Configuration.

While these options make pretty good sense for people that have full administrative rights and know Drupal, they aren’t relevant for all users on all projects.  We recommend customizing the menu options based on your site’s workflow/needs.

Some tips:

  • Minimize clicks by having frequently used administrative pages accessible via the top level navigation system.  If 90% of the site’s content involves creating and editing blog content, have “Create Blog Entry” and “Edit Blog Entries” be two of your top level options.  Give admins easy access to the functions they perform frequently.
  • Don’t be afraid to rename things.  If you think “Theme” makes more sense than “Appearance” then simply rename the tab.
  • Add links to other resources you use in managing your site that may not be part of Drupal.  Add links to documentation, style guides, Analytics accounts, etc. so that the Drupal administrative section can serve as the definitive resource for your web program.

(4) Create Custom Administrative Views

By default Drupal features a “Find Content” section that allows for users to filter results by content type.  On more complex sites this section becomes inadequate as your administrators will want to search using different criteria based on the content type they are reviewing.  For example, an administrator may want to filter the content type blog post by author.  This author filter may not be relevant for a content type such as press releases.

It is easy in Drupal to customize the options available on that main Find Content page and to create custom views for specific content types.  Take the time to customize the backend content view pages so they are truly useful to administrators.

(5) Take the Time to Set Up the Dashboard

Drupal comes with an administrative dashboard section that allows you to create quick links to the most frequently used content.  Take the time to set up and customize your site’s administrative dashboard.  Here are some ideas on how the dashboard can be used:

  • Create quick links to functions that are performed all the time.  This would include things like Add Press Releases, Edit Press Releases, etc..
  • Create quick links to third party resources the client may want to access.  This might include links to Google Analytics, Mailchimp, Client Reports, Style Guide, etc.
  • Include a list of recent content the user has edited.
  • Include a list of content updated by other users.

(6) Write Instructions

When building large Drupal sites it is inevitable that some content types end up with a ton of fields.  These fields can be mysterious to people not familiar with the site..  We recommend grouping these fields into logical field collections and writing clear instructions as to what the fields are used for as a way to avoid confusion.

As an example, say you have a content type called Research that includes a checkbox called Featured Research.  On the backend you should explain that clicking this checkbox causes the research node to be featured prominently on the main Research page.  Write clear instructions so that administrators always know the ramifications of the choices they make.

(7) Document Image Sizes

Over the years our Drupal sites have gotten more and more image intensive.  And with the rise of mobile we also find ourselves having to upload multiple versions of images to ensure they look good on phones and tablets as well as desktops.

It sounds simple, but on the backend you should provide specs to content administrators regarding the file size, dimensions and format of images.  If you want a square jpg that is no more than 500*500 to be uploaded, tell the administrators that up front.  It will save a lot of trial and error.

(8) Install and/or Customize the WYSIWYG

It sounds crazy, but Drupal 8 is the first version of Drupal to include a WYSIWYG in core. (I told you Drupal was built for developers).  So if your site is in Drupal 7, as a first step you will need to install a WYSIWYG module such as CKEditor if you don’t want your content editors to have to write straight code.

Once you have a WYSIWYG installed take the the time to customize the options that are available based on what your content managers will be doing.  If you know your content managers will be copying a lot of content from Word, include the Paste from Word option.  If you don’t want content editors to change fonts, don’t include the font selector option.

While we encourage the installation of WYSIWYG’s for basic formatting, we advise against providing too many options.  If you have set up your Drupal site in an intelligent way, content managers should only be doing basic editing work (adding links, bullets, etc.) in the WYSIWYG.

(9) Don’t Forget to Do Spring Cleaning

A lot of the sites we manage have been in Drupal for years.  In many cases the backends of our sites have gotten really messy as a result.  Take the time a few times a year to go in and clean up to make sure the administrative tools remain easy-to-use.

Are there fields, taxonomies or content types that are no longer in use?  Remove them.  Are there new materials that should be featured in the overall administrative menu?  Add them.  Are there materials that are no longer relevant?  Delete the links.

Periodic clean up is important.  Without it the administrative section can get really confusing for new people who come on board who may not have historical knowledge of a site.