A Yeoman generator that scaffolds a starter kit theme for Drupal.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
test
.editorconfig
.gitattributes
.gitignore
.jshintrc
.travis.yml
.yo-rc.json
README.md
TODO.md
package.json

README.md

Drupal Starter Theme Kit

This Yeoman generator provides everything that the Access team hold dear for creating a consistent starting base for Drupal themes. Users of this theme should be comfortable with the command line, tools like yo, grunt and bower as well as being able to tackle dragons head on!!!

Getting Started

Introduction

System Requirements

To be able to use this theme you will need these as a minimum to be sure that everything goes smoothly in development.

The installation instructions are on each of these websites. You can install them manually or using Homebrew if you're on Mac. With these simple commands all the dependencies you'll need will be installed for you.

# Make sure brew is up to date and working
brew update
brew doctor

# Install Node.js, NPM along with Yeoman, Grunt and Bower
brew install node
npm install -g yo grunt-cli bower

# Install Ruby, Ruby Gems along with Sass and Susy
brew install ruby
git clone https://github.com/rubygems/rubygems.git
cd rubygems
rm -rf .git/
ruby setup.rb
gem install sass susy

Installing

To install this generator is very simple but please check the system requirements to make sure everything you'll need is installed then it's a case of running these two lines of code:

npm install -g generator-access-drupal-theme

And that is all you need to do to be able to access this generator from anyway in your system! Move on to this section to understand setting up theme.

Example Setup

Development Workflow

When starting ot working with this theme there should be very little config to handle after the Yeoman part has finished. So continuation of the theme will be simple and take a progressive approach. There should be little need to remove parts in this project unless parts are not needed or swapped.

There will be projects which have this theme already underway, read the instructions for in progress workflow here.

In Progress Workflow

If you have cloned this theme repository from a project that is already in progress there will be one step you need to take before being able to work with this theme.

npm install
grunt update

Because node modules are not committed into the repository this command simply installs the modules and then runs a grunt task to install bower dependencies and clean the filesystem. After this step general instructions for running grunt in development follow.

Fresh Start Workflow

If you are starting a new Drupal project then you'll need to open up a terminal window and navigate to the root of the Drupal repository. From there you should cd down to the theme level and with the Access Drupal Theme generator already installed run the yo command like so:

cd sites/all/themes
yo access-drupal-theme

You'll be asked a few questions in order for Yeoman to do some heavy lifting for you and to get you on your way. Here is a list of the questions and typical answers:

TODO: Finish the questions section

  1. Question One
  2. Question Two
  3. Question Three

Once the matrix stops loading in everything it needs then you'll be ready to start making Drupal-ly goodness! Moving to this section will show you the typical commands needed when working with the theme.

General Workflow

In Development

When working in development and you just want to compile assets, live reload amongst other things, you only need to have a terminal open at the theme folder and run.

grunt run

This task will listen for changes in the file system and compile any necessary assets and reload your chosen browser if livereload is available. Once the command is run once you don't need to run it again until you exit the command, Grunt will watch for changes and compile things, it's magic ;D

When working on this theme it is important to note the folders that you should be making changes in and one you should leave alone. Here is a list of places where you should be working:

  • styles/
  • js/
  • images/
  • fonts/
  • templates/
  • includes/

And here are folders you should leave alone:

  • css/
  • img/
  • bower_components/
  • node_modules/

Working With Files

CSS

Folder: styles/

This is where all Sass partials and files are stored. Sass is the pre-compiler language we use to create normal CSS. These assets are compiled with the Sass gem and the Autoprefixer library. This means that when working with stylesheets you should rarely need to vendor prefix anything, this will be decided by Autoprefixer.

The settings for Autoprefixer can be changed in the Gruntfile.js to cover more older browsers or only the most recent browsers. Read here for more on the syntax for the config.

Any references to images in stylesheets should use the image-url() mixin to avoid any problems with image paths. there is also a image-url-src() mixin which will use the none optimised version of the image in case that the optimisation ruins the quality of the image.

One last note is that any Bower dependencies that can injected into Sass will be added automatically by grunt in the the default Sass stylesheet and removed if the dependency is ever removed from the project. Any Bower dependencies that are purely CSS will be bundled into a vendor.scss file at the root of the styles folder to be compiled separately.

Javascript

Folder: js/

This is where all Javascript files are kept for the project. Unlike the styles there is no precompiler in this project for Javascript. All scripts bar Bower dependencies will be run through JSHint to check for quality of Javascript code and for any potential errors.

Like the Sass stylesheets though any Bower dependencies that are installed and are Javascript driven will be installed automatically into a vendor.js file at the top of the js folder. NOTE do not add anything into this file manually because it will be overridden next time grunt runs the dependency task.

Images

Folder: images/

Images here are for use of design and for CSS and should not contain any content based imagery. The images in here will be run through optimisers and output with the same name in the img/ folder. You can still make reference to the original image in Sass using the image-url-src() mixin in case the optimised version compresses poorly.

PHP

Folders: templates/, includes/

All the files for Drupal templating are contained in these folders. Basic examples of common template files can be found in here along with functions that override default Drupal behaviours.

Ready To Commit

So you've made your changes, styled up some shizzle, scripted some amazing events and templated the heck out of that page so now its time to commit to git. Don't worry simply run the grunt command to compile assets ready for being pushed into the respository by running:

grunt build

When the command has finished then you're all set to commit your changes. That's about it for development workflow. We've deliberately kept it simple so that there will be less bugs and problems when updating and adding features in the future.

Grunt Tasks

  • grunt - Runs the default Grunt task which is grunt run
  • grunt run - Watches for local changes and compiles, optimises and lints code
  • grunt build - Builds code perfect to be committed to git
  • grunt update - Cleans the system files in case there are any stary unused files and updates Bower dependencies and Node modules

Git Ignores

Not many ignores in this theme, for the sake of simplicity we commit compiled assets such as CSS, Javascript and optimised images/svgs due to save on the complexity of deployment procedures and systems. Also we don't create minified code because we let Drupal's (Advanced Aggregator)[https://www.drupal.org/project/advagg] to do the environment type differences (eg development, staging and production).

We do ignore anything that won't be used by the actual theme (excluding sass) which include Bower components and Node modules. They can make repositories extremely large and should be installed per system anyway so that versions of these dependencies can be accounted for.

More Information

What is Yeoman?

Trick question. It's not a thing. It's this guy:

Basically, he wears a top hat, lives in your computer, and waits for you to tell him what kind of application you wish to create.

Not every new computer comes with a Yeoman pre-installed. He lives in the npm package repository. You only have to ask for him once, then he packs up and moves into your hard drive. Make sure you clean up, he likes new and shiny things.

npm install -g yo

Yeoman Generators

Yeoman travels light. He didn't pack any generators when he moved in. You can think of a generator like a plug-in. You get to choose what type of application you wish to create, such as a Backbone application or even a Chrome extension.

To install generator-access-drupal-theme from npm, run:

npm install -g generator-access-drupal-theme

Finally, initiate the generator:

yo access-drupal-theme

Getting To Know Yeoman

Yeoman has a heart of gold. He's a person with feelings and opinions, but he's very easy to work with. If you think he's too opinionated, he can be easily convinced.

If you'd like to get to know Yeoman better and meet some of his friends, Grunt and Bower, check out the complete Getting Started Guide.

License

MIT