Getting Started with Neato in Drupal 8
Since our first post on it a few months ago, Neato has been downloaded 2,300 times and reportedly installed on 87 sites. So first off, thank you to all of the supporters out there! We're excited to see the viability and popularity of this theme framework among purists and power themers alike. Even if you are a beginner the hands-off approach of Neato will allow you to pick it up and learn how the Drupal theming system works, with ease.
This post will take a look at how you can get started with Neato in Drupal 8. But first, let's recap why you would want to use Neato in the first place.
So, Why Neato?
If you are familiar with the Neat/Bourbon grid and mixin system, nothing has changed here. You can run wild on your prototypes and the transition into Drupal should be very smooth. Implementing prebuilt components using their Refills section is very simple - you can get started right away by building a set of reusable components that transcend your sub-theme and can be applied to any Neato generated sub-theme. Have a list component or flexbox style you like? Copy the SCSS file out and drop it in! The Neat grid system is responsive as well, reducing the effort required to support cross-device functionality. There is some need to use the command line but it's simple enough to pick up and run with.
Neato in Drupal 8
Here's what you will need to get started:
- The latest release of Drupal 8
- Drush 8 (optional, but really helps with generating a subtheme)
- A package manager like Homebrew (OSX), Chocolatey (Windows), or apt-get (Linux)
- Git
- A good terminal application - For OSX/Linux users, the native terminal application is sufficient. Windows users should use PowerShell, Git Bash, or Console2. You don't need to be a command line wizard, you just need to know some basic commands like navigating directories and npm specific commands which I will cover in this post.
- Virtual environment stack - A virtual environment will allow you to work locally. You can use pre-packaged software like the Acquia DevDesktop, or for more advanced users, the DrupalVM (which also works on Windows). For the former, the installer is pretty straight forward.
Installing Packages
First, we're going to need some packages to make developing a Neato theme a breeze. Install the following packages (I suggest installing them with the global flag):
Once npm has installed successfully, you should have the npm command available in the command line window. Next, we are going to use npm to install node packages and open up two more commands to us, Bower and Gulp. Bower helps us stay up to date with upstream changes on the Neat/Bourbon/Bitters source (which Neato is based on), and Gulp is a JavaScript-based task runner that will serve as an extra set of hands for you while developing. Neato comes with a Gulpfile to aid in theming.
Fire Up the Console
npm install -g bower gulp gulp-cli
Sweet! Once you have installed Drupal 8, download Neato to your /themes directory and enable the Neato base theme from the Drupal admin screen (you do not need to set it as the default).
From here, we are going to pull in assets with Bower. Note, you should add bower_components to your .gitignore file as it will not be necessary to commit all those files - you will see why. Navigate to the 'neato' directory in your command line and run:
bower install
Presto! We are almost there!
Next, we need to generate a sub-theme. All sub-themes inherit the base Neato theme, which is why we use bower to install core assets. All generated sub-themes will benefit from these in one location, instead of copied into each generated sub-theme. Neato comes with a Drush command to make generating a theme very easy:
drush ngt SUBTHEMENAME
'ngt' stands for 'neato generate theme'. This Drush command will copy out the STARTER folder in Neato to the theme name you supply and rename all functions and references in the directory accordingly.
Set your new theme as the site default. You'll notice the styles are not present - we need to run Gulp to generate the CSS from our SASS files.
Navigate to the theme directory in the command line to install the packages needed to run the gulp script, and then to actually run gulp.
npm install
gulp
The Gulpfile.js in your sub theme is fully ready to rock from the start. It will watch for changes to .scss, .js, or .twig files and act accordingly.
If the default settings need tweaking, make a copy of the example.config.js file to config.js and change any settings from there. For instance, you may want to enable the Drush integration (to clear CSS and JS cache automatically) and specify the site alias to use, if any. You'll notice that config.js is excluded in .gitignore. This allows you to work on a theme or theme(s) with multiple people and have a different configuration for Gulp without affecting anyone's workflow.
What is Gulp doing?
Gulp has a lot of handy tasks already defined for you. Namely, it can watch for changes to files in the SCSS/JS/templates folder and react to these changes. For instance, if you change a .scss file, it will trigger the Sass task to generate a CSS file of the Sass output and compress/minify it. It will also trigger a browser refresh for all browsers connected in and listening via BrowserSync. It can also call a Drush cache rebuild of CSS/JS files, so you can develop with caching enabled locally for speed. You can run these tasks on their own by typing them into the console or you can let Gulp watch indefinitely with just 'gulp'. Map files are also generated for CSS and JS files, for the Chrome Debug Console/Firebug to quickly pinpoint where CSS/JS statements were declared in their source files.
Take a look at your new theme directory and familiarize yourself with some of the conventions of working with Neato as a base theme. There is a templates folder with an example page--front.html.twig file, showing you an example of what can be done with Neat & Bourbon when you visit the site homepage. Any template overrides should go in the templates/ directory. We are inheriting default template files from themes/neato/templates. For example, if you want to change the default markup of page.html.twig, copy that file into SUBTHEMENAME/templates/base/page.html.twig and make your changes.
I like to maintain conventions when theming, particularly with template files. Specific overrides (like a template for a node type) I keep in templates/node, fields in templates/fields, and views in templates/views. This designation helps maintain order for sites that might have a lot of overrides.
What about Panels? Panelizer? Display Suite?
You are free to use any of these decorator/layout modules. Neato on its own does not come with pre-built templates for them so this is left up to the developer to solve. I myself am a purist and prefer using view modes and templates for maximum control over HTML output. There are other considerations as well, such as overall application performance, but I won't go into those in this post.
The above covers all the information you need to get started. You're now ready to download Drupal 8 and take Neato for a spin! Feel free to comment below with any questions or feedback on your experiences doing so.