Welcome to the second episode in our new video series for Emulsify. Emulsify 2.x is a new release that embodies our commitment to component-driven design within Drupal. We’ve added Composer and Drush support, as well as open-source Twig functions and many other changes to increase ease-of-use.
In this video, we’re going to teach you how to create an Emulsify 2.0 starter kit with Drush. This blog post follows the video closely, so you can skip ahead or repeat sections in the video by referring to the timestamps for each section.
This screencast will specifically cover the Emulsify Drush command. The command’s purpose is to setup a new copy of the Emulsify theme.
Note: I used the word “copy” here and not “subtheme” intentionally. This is because the subtheme of your new copy is Drupal Core’s Stable theme, NOT Emulsify.
This new copy of Emulsify will use the human-readable name that your provide, and will build the necessary structure to get you on your way to developing a custom theme.
Before we dig in too deep I recommend that you have the following installed first:
- a Drupal 8 Core installation
- the Drush CLI command at least major version 8
- Node.js preferably the latest stable version
- a working copy of the Emulsify demo theme 2.X or greater
If you haven’t already watched the Emulsify 2.0 composer install presentation, please stop this video and go watch that one.
Note: If you aren’t already using Drush 9 you should consider upgrading as soon as possible because the next minor version release of Drupal Core 8.4.0 is only going to work with Drush 9 or greater.
We recommend that you use PHP7 or greater as you get some massive performance improvements for a very little amount of work.
We also recommend that you use composer to install Drupal and Emulsify. In fact, if you didn’t use Composer to install Emulsify—or at least run Composer install inside of Emulsify—you will get errors. You will also notice errors if
npm install failed on the Emulsify demo theme installation.
Now that we have everything setup and ready to go, this presentation will first discuss the theory behind the Drush script. Then we will show what you should expect if the installation was successful. After that I will give you some links to additional resources.
The general idea of the command is that it creates a new theme from Emulsify’s files but is actually based on Drupal Core’s Stable theme. Once you have run the command, the demo Emulsify theme is no longer required and you can uninstall it from your Drupal codebase.
WHEN, WHERE, and WHY? [02:44]
WHEN: You should run this command before writing any custom code but after your Drupal 8 site is working and Emulsify has been installed (via Composer).
WHERE: You should run the command from the Drupal root or use a Drush alias.
WHY: Why you should NOT edit the Emulsify theme’s files. If you installed Emulsify the recommended way (via Composer), next time you run
composer update ALL of your custom code changes will be wiped out. If this happens I really hope you are using version control.
HOW TO USE THE COMMAND? [03:24]
Well first it requires a single argument, the human-readable name. This name can contain spaces and capital letters.
The command has defaults set for options that you can override.
This first is the theme description which will appear within Drupal and in your .info file.
The second is the machine-name; this is the option that allows you to pick the directory name and the machine name as it appears within Drupal.
The third option is the path; this is the path that your theme will be installed to, it defaults to “themes/custom” but if you don’t like that you can change it to any directory relative to your web root.
Fourth and final option is the slim option. This allows advanced users who don’t need demo content or don’t want anything but the bare minimum required to create a new theme.
Only the human_readable_name is required, options don’t have to appear in any order, don’t have to appear at all, or you can only pass one if you just want to change one of the defaults.
If your new theme was successfully created you should see the successful output message. In the example below I used the slim option because it is a bit faster to run but again this is an option and is NOT required.
The success message contains information you may find helpful, including the name of the theme that was created, the path where it was installed, and the next required step for setup.
THEME SETUP [05:25]
Setting up your custom theme. Navigate to your custom theme on the command line. Type the
yarn and watch as pattern lab is downloaded and installed. If the installation was successful you should see a pattern lab successful message and your theme should now be visible within Drupal.
COMPILING YOUR STYLE GUIDE [05:51]
Now that we have pattern lab successfully installed and you committed it to you version control system, you are probably eager to use it. Emulsify uses npm scripts to setup a local pattern lab instance for display of your style guide.
The script you are interested in is
yarn start. Run this command for all of your local development. You do NOT have to have a working Drupal installation at this point to do development on your components.
If you need a designer who isn’t familiar with Drupal to make some tweaks, you will only have to give them your code base, have them use
yarn to install, and
yarn start to see your style guide.
It is however recommended the initial setup of your components is done by someone with background knowledge of Drupal templates and themes as the variables passed to each component will be different for each Drupal template.
For more information on components and templates keep an eye out for our soon to come demo components and screencasts on building components.
VIEWING YOUR STYLE GUIDE [07:05]
Now that you have run
yarn start you can open your browser and navigate to the localhost URL that appears in your console. If you get an error here you might already have something running on port 3000. If you need to cancel this script hit control + c.
ADDITIONAL RESOURCES [07:24]
Thank you for watching today’s screencast, we hope you found this presentation informative and enjoy working with Emulsify 2.0. If you would like to search for some additional resources you can go to emulsify.info or github.com/fourkitchens/emulsify.
Thanks for following our Emulsify 2.x tutorials. Miss a post? Read the full series is here.
Just need the videos? Watch them all on our channel.