Make a 7.x-6.x sub-theme
Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites
The base Zen theme is designed to be easily extended by its sub-themes. You shouldn't modify any of the CSS or PHP files in the zen/
folder; but instead you should create a sub-theme of zen which is located in a folder outside of the root zen/
folder. The examples below assume zen and your sub-theme will be installed in sites/all/themes/
, but any valid theme directory is acceptable (read the sites/example.sites.php for more info.)
IMPORTANT NOTE: In Drupal 7, the theme system caches which template files and which theme functions should be called. This means that if you add a new theme, preprocess or process function to your template.php file or add a new template (.tpl.php) file to your sub-theme, you will need to rebuild the "theme registry." See http://drupal.org/node/173880#theme-registry
Drupal 7 also stores a cache of the data in .info files. If you modify any lines in your sub-theme's .info file, you MUST refresh Drupal 7's cache by simply visiting the Appearance page at admin/appearance.
There are 2 ways to create a Zen sub-theme:
- An automated way using Drush
- The manual way
Creating a sub-theme with Drush
-
Ensure drush knows about the zen command.
After you have installed Zen, Drush requires you to enable the Zen theme before using Zen's Drush commands. To make the drush zen command available to use, type:
drush en zen -y
-
See the options available to the drush zen command by typing:
drush help zen
Here's the output of that command:
Create a theme using Zen. Examples: drush zen "Amazing name" Create a sub-theme, using the default options. drush zen zomg_amazing "Amazing name" Create a sub-theme with a specific machine name. drush zen "Amazing name" Create a sub-theme in the specified --path=sites/default/themes directory with a custom description. --description="So amazing." Arguments: machine_name [optional] A machine-readable name for your theme. name A name for your theme. Options: --description A description of your theme. --machine-name [a-z, 0-9, _] A machine-readable name for your theme. --name A name for your theme. --path The path where your theme will be created. Defaults to: sites/all/themes
-
Create a sub-theme by running the drush zen command with the desired parameters. IMPORTANT: The machine name of your sub-theme must start with an alphabetic character and can only contain lowercase letters, numbers and underscores.
Type:
drush zen [machine_name] [name] [options]
Here are some examples:
- Use
drush zen "Amazing name"
to create a sub-theme named "Amazing name" with a machine name (automatically determined) of amazing_name, using the default options. - Use
drush zen zomg_amazing "Amazing name"
to create a sub-theme named "Amazing name" with a machine name of zomg_amazing, using the default options. - Use
drush zen "Amazing name" --path=sites/default/themes --description="So amazing."
to create a sub-theme in the specified directory with a custom description.
- Use
-
Check your website to see what themes are used as the default and admin themes.
Type:
drush status theme
-
Set your website's default theme to be the new sub-theme.
Type:
drush vset theme_default zomg_amazing
(Replace
zomg_amazing
with the actual machine name of your sub-theme.) -
Skip to the "Additional setup" section below to finish creating your sub-theme.
Creating a sub-theme manually
-
Setup the location for your new sub-theme.
Copy the
STARTERKIT
folder out of thezen/
folder and rename it to be your new sub-theme. IMPORTANT: The name of your sub-theme must start with an alphabetic character and can only contain lowercase letters, numbers and underscores.For example, copy the
sites/all/themes/zen/STARTERKIT
folder and rename it assites/all/themes/foo
.Why? Each theme should reside in its own folder. To make it easier to upgrade Zen, sub-themes should reside in a folder separate from the base theme.
-
Setup the basic information for your sub-theme.
In your new sub-theme folder, rename the
STARTERKIT.info.txt
file to include the name of your new sub-theme and remove the ".txt" extension. Then edit the .info file by editing the name and description field.For example, rename the
foo/STARTERKIT.info
file tofoo/foo.info
. Edit thefoo.info
file and changename = Zen Sub-theme Starter Kit
toname = Foo
anddescription = Read...
todescription = A Zen sub-theme
.Why? The .info file describes the basic things about your theme: its name, description, features, template regions, CSS files, and JavaScript files. See the Drupal Theme Guide for more info.
Remember to visit your site's Appearance page at admin/appearance to refresh Drupal 7's cache of .info file data.
-
Edit your sub-theme to use the proper function names.
Edit the
template.php
andtheme-settings.php
files in your sub-theme's folder; replace ALL occurrences ofSTARTERKIT
with the name of your sub-theme.For example, edit
foo/template.php
andfoo/theme-settings.php
and replace every occurrence ofSTARTERKIT
withfoo
.It is recommended to use a text editing application with search and "replace all" functionality.
-
Set your website's default theme.
Log in as an administrator on your Drupal site, go to the Appearance page at
admin/appearance
and click the "Enable and set default" link next to your new sub-theme.
Additional setup
Your new Zen sub-theme uses Gulp.js as a task runner, so that it can do many
different tasks automatically:
- Build your CSS from your Sass using libSass and node-sass.
- Add vendor prefixes for the browsers you want to support using Autoprefixer.
- Build a style guide of your components based on the KSS comments in your Sass source files.
- Lint your Sass using scss-lint.
- Lint your JavaScript using eslint.
- Watch all of your files as you develop and re-build everything on the fly.
Set up your front-end development build tools:
-
Install Node.js and npm, the Node.js package manager.
If you're new to this read the detailed instructions on the npm quick start guide. These instructions include steps how to install on Mac OS X. Linux users might find Installing Node.js via package manager more useful for the installation part. Make sure you're installing a version that isn't too old to ensure Gulp works properly.
-
The
package.json
file in your new sub-theme contains the versions of all the Node.js software you need. To install them run:npm install
-
Install the gulp-cli tool globally. Normally, installing a Node.js globally is not recommended, which is why both Gulp and Grunt have created wrapper commands that will allow you to run "gulp" or "grunt" from anywhere, while using the local version of gulp or grunt that is installed in your project. To install gulp's global wrapper, run:
sudo npm install -g gulp-cli
-
Set the URL used to access the Drupal website under development. Edit your
gulpfile.js
file and change the following line depending on your local Drupal site configuration:options.drupalURL = 'http://localhost';
options.drupalURL = 'http://mydomain.local';
-
The default gulp task will build your CSS, build your style guide, and lint your Sass and JavaScript. To run the default gulp task, type:
gulp
If successful you'll see output written out similar to this:
$ gulp [21:52:49] Using gulpfile /var/www/html/svgprkos/sites/all/themes/malamica/gulpfile.js [21:52:49] Starting 'clean:css'... [21:52:49] Starting 'clean:styleguide'... [21:52:49] Starting 'styleguide:kss-example-chroma'... [21:52:49] Starting 'lint:sass'... [21:52:49] Starting 'lint:js'... [21:52:49] Finished 'clean:css' after 306 ms ...[more output]...
To watch all your files as you develop, type:
gulp watch
This will also open the site in your default browser, by proxying (because of Browsersync):
...[more output]... [21:54:53] Finished 'watch' after 1.29 μs [BS] Proxying: http://mydomain.local [BS] Access URLs: ------------------------------------ Local: http://localhost:3000 External: http://192.168.1.6:3000 ------------------------------------ ...[more output]...
Note: BrowserSync doesn't support CSS @import. In order for BrowserSync to automatically refresh, install and enable https://www.drupal.org/project/link_css.
To better understand the recommended development process for your Zen sub-theme, watch the Drupalcon presentation, Style Guide Driven Development: All hail the robot overlords!
Optional steps:
-
Modify the box component styling.
The
sass/components/box/_box.scss
file describes the styles of the "box" component. The code comments in that file reiterate the naming conventions use in our CSS and also describe how the nested Sass selectors compile into CSS.Try running
gulp watch
, modifying the Sass, and then looking at how the style guide page at styleguide/section-components.html is automatically updated with the new CSS.Now try uncommenting the example ruleset under the "Drupal selectors" heading, recompiling the Sass, and then looking at your Drupal site (not the style guide) to see how the box component is applying to your sidebar blocks.
-
Choose your preferred page layout method or grid system.
By default your new sub-theme is using a responsive layout using Zen Grids.
If you are more familiar with a different CSS layout method, such as Susy, Foundation, etc., you can replace the
layouts/layout-
line in yourstyles.scss
file with a line pointing at your choice of layout CSS file. -
Modify the markup in Zen core's template files.
If you decide you want to modify any of the .tpl.php template files in the zen folder, copy them to your sub-theme's folder before making any changes. And then rebuild the theme registry.
For example, copy
zen/templates/page.tpl.php
tofoo/templates/page.tpl.php
. -
Modify the markup in Drupal's search form.
Copy the
search-block-form.tpl.php
template file from themodules/search/
folder and place it in your sub-theme's template folder. And then rebuild the theme registry.You can find a full list of Drupal templates that you can override in the
templates/README.txt
file or on the core templates page.Why? In Drupal 7 theming, if you want to modify a template included by a module, you should copy the template file from the module's directory to your sub-theme's template directory and then rebuild the theme registry. See the Drupal 7 Theme Guide for more info.
-
Further extend your sub-theme.
Discover further ways to extend your sub-theme by reading:
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion