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!!!
- System Requirements
- Example Setup
- Development Workflow
- More Information
To be able to use this theme you will need these as a minimum to be sure that everything goes smoothly in development.
- MAMP, LAMP or WAMP type stack to run Drupal
- A Drupal Installation
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
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.
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
- Question One
- Question Two
- 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.
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.
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:
And here are folders you should leave alone:
Working With Files
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.
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 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.
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:
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- Runs the default Grunt task which is
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
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.
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 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:
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.