Mediacurrent's Drupal Theme Generator

In a fast-moving industry like ours, it is imperative that we have tools that allow us to build environments (front and back-end) quickly while providing consistency. The same way we have DevOps processes for quickly spinning off a complete Drupal website built with composer, drush, Drupal console and more, we need a system that automated Drupal theme generator process which includes all the essential tools needed for a modern, best practices, and standards-compliant environment.

The old way

In the past, we tried several approaches for creating themes but most of those approaches included manual tasks such as copying and pasting files or code snippets from previous themes we had created.  

Another approach we tried was creating a base theme that we would use as a starting point for all new themes.  Due to the frequency of front end changes, we would always end up performing manual tasks to ensure our newly created sub theme was up to date with the latest tools and standards.  In addition to inconsistencies, these approaches were time-consuming and hard to maintain.

The new way

So needless to say, after much trial and error, we started looking at other ways to automate the process of creating themes.  With automation, however, comes the need to standardize on files/directories structure, naming conventions and workflow.  The idea is to pick a process, whatever it is, and stick with it for as long as you can.  This does not mean you can’t change things if you see the need for it, as long as your team is on board, you can update and improve your workflow whenever possible.  We realize our process is not perfect but as a team we all contribute to improving it by filing issues, making recommendations or discussing the items that no longer work for us.  In a fast-paced environment like ours, this has paid off tremendously.

Introducing Mediacurrent’s Theme Generator

Let me first describe the tools we currently use and their purpose before we get into the details of how the theme generator works.

You can use the theme generator even if you are not using Drupal.  The generator allows you to kickstart your web development environment, which applies to any platform you may work with.

From a coding point of view, these are some of the main tools we use among others:

• Sass (LibSass), for writing all styles
• ES6, for writing Javascript
• KSS, Node for creating components and styleguides
• Breakpoints plugin, for creating media queries in Sass
• SingularityGS, when we need to use a grid system
• Autoprefixer, for managing browser prefixes
• BrowserSync, for automatically reloading your browser when Sass changes are saved.
• Compressing tools, linting tools for Sass and Javascript, concatenation tools, sourcemaps
• And more

The tools above are typical of most front end environments. Imagine trying to manage all those tools by hand?  This is where theme generator comes in.  The theme generator is nothing more than a scaffolding system that lays out the structure and standards of your theme.  It also allows for easy management of the tools we described above.

1. Gulp:  Gulp is a task runner much like Grunt.  Through Gulp we are able to automate many of the repetitive tasks we perform on a regular basis.  Things like compiling Sass into CSS, Compiling and minifying Javascript, compressing images, and more.  By creating a task or set of tasks with Gulp you can manage when and how those tasks run.
2. NodeJS:  We moved from Ruby Sass to LibSass.  This provided better and faster performance when compiling Sass.  In fact, we no longer use Ruby at all.  All of our coding tools are Node-based.
3. Node Version Manager (NVM):  NVM is critical for us because most of us work on multiple projects at any given time.  Each project is set to use a specific version of Node.  A project could use an old version of Node while another project may use the latest version of node.  With NVM, all developers use the same Node version, per project, and this prevents incompatibility issues.
4. Node Package Manager (NPM): Since our environment is primarily Node-based, most tools you saw on the first list above are considered Node dependencies. NPM is used for dependency management so that you no longer have to manually download and manage your scripts.
5. Yeoman:  Yeoman is a task generator, which puts all these tools together and scaffolds a theme for us using predefined requirements such as naming conventions, file structure and more. The generator is set up so you are prompted to select only the tools and configuration you need for your project.  We will see this shortly.

Getting and Using the Theme Generator

Now that we learned a little about the theme generator and the tools it uses, let’s take it for a test drive to see how it works.

Note:  Before using the theme generator, you need to install NodeJS, NPM, NVM, and Gulp.  Here are some helpful resources:

• Install NodeJS & NPM with Homebrew on MacOS
• How to install NodeJS & NPM on Windows
• Install NVM with Homebrew
• Getting started with Gulp

Once these tools are installed, you’ll be set to start using the theme generator.

Using the theme generator

Note:  The theme generator is not something you download or clone unless you want to see how it was built or wish to make changes to it. Instead, you use it to generate your theme by running a few commands.

Creating a Drupal 8 theme:

1. In your project, create a new directory:  DRUPAL_ROOT/themes/custom/my_awesome_theme; where my_awesome_theme will be the name of your new theme.  Feel free to name your folder anything you want.   It’s better if your folder name is in lowercase and no spaces.
2. Navigate to the new folder within the command line.  You will execute all the following commands from within your new folder
3. All commands below can be found in the project’s repo page: https://github.com/mediacurrent/theme_generator_8.
4. In the command line run
   nvm install stable | grep -ohe 'v[0-9]*\\.[0-9]*\\.[0-9]*' | head -1 > .nvmrc && nvm use  
   This command installs the latest stable version of node for your project.  Each project can potentially have a different version of node.
5. Now let’s install Yeoman and the theme generator by running:
   npm install -g yo generator-mc-d8-theme
   You should receive a confirmation message that everything looks all right.
6. We are now ready to create our first theme, run: yo mc-d8-theme
   
   You have the option to leave the human readable name as is or change it to something more user friendly.  Press return after you have made a decision.
    
7. This step is extremely important.  The theme’s machine name should match the name of the folder you created in step 1.
   
   This name in addition to being the theme’s machine name, also determines the names of your theme’s working files (i.e. my_awesome_theme.info.yml, my_awesome_theme.libraries.yml, etc.).
8. Next, type a description for your theme.  Feel free to write as much or little as you want and then press Return.
9. Next, moving your up/down arrows on your keyboard, choose a base theme.  Personally, I choose the Stable theme but learn more about Drupal core themes.  For now, let’s select Stable and press return.
10. Now it’s time to select some of the tools which will help you as you build your theme.
    1. KSS Node is used to build components and styleguides. Select it by moving up/down and pressing the spacebar on your keyboard.
    2.  Breakpoint plugin is used to create media queries in Sass.  Select it.
    3.  Singularity Grid System and Breakpoint is used to create grid system for content layouts.  Select it.
    4. Press return after you have made all the selections above

11. Type Y and press return when prompted if you want a sample styleguide section/component.  This will only come up if you chose KSS Node.

12. If all goes well, you should see the screenshot above and your new theme is ready.

Compiling the theme for the first time

Remember: if you are using NPM 5 or higher (npm --v), first delete package-lock.json from your theme’s directory before proceeding with steps below.  (See note above for more details).

Now that our new theme is built, let’s build our codebase so Sass and Styleguide are compiled.

1. Still within your theme’s folder (i.e. my_awesome_theme), run npm install.  This command will look at package.json and install all the dependencies your theme needs.  A single command allows us to install and configure a number of tools that you would normally do by hand otherwise.  This could take a few minutes to run
2. Now run npm run build.  This command will compile Sass, JS and Styleguide.  
3. Now you can head to your site and navigate to http://your-site/themes/custom/my_awesome_theme/dist/style-guide/
4. You should see a basic styleguide for your theme.
   
5. If you plan to use this as a Drupal 8 theme, head over to the Appearance page (admin/appearance), and install and make it your default theme.
6. Finally, for a list of all the commands and tasks you can run, please read your theme’s or repo’s README.

One last thing …

The theme generator, in addition to helping you create your new Drupal theme, also provides commands for generating components and even Drupal JS behaviors for your components.  Let’s take a look at these commands.

• Run yo mc-d8-theme:component 'Card' (where Card is the name of the component you want to create).
  
• The files this commands creates in src/components are as follows:
  • Card.json: Used to create component’s variables and values such as stock content.  Variables are used when integrating component with Drupal.
  • Card.scss:  Where styles for this component will be authored.
  • Card.twig:  This is where the component markup is authored.  Also, this file will read variables and stock content provided by JSON file.
• If your component requires Javascript for interaction, the generator can also help with that.
• Run yo mc-d8-theme:js-behavior 'Card'. The generator will detect if the component “Card” already exist and will place the newly created JS file in it.  Otherwise, it will create the folder for you and place the JS file in it.
  
  As you can see, the JS file is created using ES6 format. In addition, it also creates the skeleton of your JS behavior block.  

Check it out:

In closing

Yes, there are a few steps to getting things set up, but they’re well documented and most of them only need to be done once and you’re ready to go.  Using the theme generator, or a similar tool for that matter, to create your theme, components, and manage your dependencies, can save you a lot of time and frustration, in addition to providing consistency across your team and projects.

We will post more updates on this project including screencasts of upcoming talks I am scheduled to give on the generator.  Stay tuned.