Make a 7.x-3.x sub-theme with Zenophile

Last updated on

7 December 2017

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

2012.09.11

Note: The "Zenophile" module is Not being developed for Zen-7.x-5.x

The module Zenophile 7.x-1.1 works with theme Zen 7.x-3.x,
but Not with Zen 7.x-5.x. See...

There won't be a new release of Zenophile for Zen 5, But thanks for using Zenophile in the past.

Zenophile allows themers to very easily create Zen sub-themes without all the tedious file copying and find-and-replacing required when creating sub-themes by hand. See Zenophile's project page for more information.

Installation and usage

Install the Zen theme, if you haven’t already.
Install and enable the Zenophile module like any other module. (Note that installing Zenophile is only necessary to create themes with it; it is not necessary to enable Zenophile to use a theme that Zenophile has already created, and Zenophile may be disabled and uninstalled after themes are created.)
If necessary, grant roles the permission to use Zenophile.
- Drupal 7: “Administration” > “People,” and click the “Permissions” tab. Grant the “Create Zen themes with Zenophile” permission to the desired roles.
- Drupal 6: “Administration” > “Users” > “Permissions.” Grant the “Create Zen themes with Zenophile” permission to the desired roles.
Go to the theme list page.
- Drupal 7: “Administration” > “Appearance.”
- Drupal 6: “Administration” > “Site building” > “Themes.”
Click the “Create Zen sub-theme” tab.
Fill out the form elements on this page. Initially you will only see some basic controls, but you can open up the “More options” fieldset for more tasty options. Click “Submit.” If all goes well, Zenophile will automatically copy and tweak the necessary files, and you will be told that your new theme was created. For more details on each of the form element choices, go to this page's child page Zenophile Create Zen Subtheme Options.
If speed is of high concern for the site to which you have installed Zenophile, you may wish to deactivate the module after you're done creating new themes.

Filesystem permissions issues

Without going too in-depth into the issue of Unix filesystem permissions, suffice it to say that you may encounter problems related to permissions with the themes you create with Zenophile.

Zenophile is intended to be used on testing servers which you have full control over (root access). In some environments, particularly shared hosting servers where you do not have root access, you may have difficulty accessing or editing the files and directories Zenophile creates. This is because those files will be “owned” by the user account that the PHP or web server process runs as, which is probably not the same user account that you use to access the server. If you have root access to the server, this is not a problem, as you can simply change the ownership of the theme directory and recursive files to yourself (hint: sudo chown -R <username> <theme directory>) and then go about your business.

If your shared hosting provider provides some sort of file management tool which operates through a web browser, you may be able to use this to change permissions on the theme’s files, since that tool will likely be running through the web server under the same user which “owns” the theme’s files.

However, basically, if you're trying to use Zenophile on a server which is not a testing server and you don’t have complete control over, you’re not using Zenophile in the manner it was intended to be used…

Zenophile has not been tested on Windows-based servers, but it will probably work.

Programming for Zenophile

If you want to modify Zenophile’s behavior, you can use its very simple API. Check out the comments in the zenophile_midnight.module file for all you'll need to know (probably). Besides a solid understanding of Drupal module coding fundamentals, you will probably need at least a basic understanding of regular expressions to build a Zenophile add-on module.

Zenophile allows you to specify either a 'liquid' or a 'fixed' layout; the width and positioning of each of two sidebars; the width of the page if you choose a 'fixed' layout; and gives you the option of starting with a black background theme.

For a brief overview of the benefits of using Zenophile and of the options that Zenophile incorporates, see Zenophile Module Automates D6 And D7 Zen Sub-Theme Creation (Opens in new tab/ window)

Note: If after creating your new sub-theme, you then decide that you want different widths or relative-placement of either sidebar, create a new subtheme with zenophile specifying those changes, and then simply add your previous "fresh.css" file to the newly created theme. That will save you from having to calculate and change multiple CSS declarations on your own.

Prerequisites: Before you create your sub-theme, you need to have done the following.

Install the Zen theme from the link found at the bottom of the drupal.org Zen theme project page. (Opens in new tab/ window)
It is Not necessary to 'Enable' the Zen theme to create and use your new Zenophile sub-theme.

Do Not delete or move the Zen base-theme directory at [root]/sites/all/themes/zen after the Zenophile sub-theme is created, or the sub-theme will no longer work.
Install the Zenophile module from the link found at the bottom of the Zenophile module project page. (Opens in new tab/ window)
Enable the Zenophile modules.
On your site's “Modules” page, look under the heading “Development” and enable:
- Zenophile.
- Zenophile Midnight.
  This is only needed if you intend to create your sub-theme with a black background instead of using the default white background.
- Zenophile Sidebars.
D6 only: Grant role permissions to use Zenophile.
Drupal 7 automatically grants the administrator permission to use any newly installed module the first time that the module is enabled.
Go to the “Appearance” (D7) or “Themes” (D6) page, and click the tab “Create Zen Subtheme”.

Additional details for those five prerequisites are at this page's parent-page “Zenophile module” and under the heading “Installation and usage” (Opens in new tab/ window)

Zenophile “Create Zen Sub-Theme” Form Elements Options

The Zenophile module creates your new Zen sub-theme in a directory outside of the Zen base-theme directory at [drupal-root]/sites/all/themes/sample_subtheme, but the new Zenophile sub-theme is dependent upon the Zen base-theme; so do Not delete or move the Zen base-theme directory at [root]/sites/all/themes/zen after the Zenophile sub-theme is created.

Your Zenophile sub-theme is based strictly upon the Zen base-theme version that you use when you create your Zenophile sub-theme.

The files in your Zenophile sub-theme directory will Not be changed Nor automatically updated if you in-the-future update the Zen base-theme.

If you want your Zenophile sub-theme to be updated according to a newer version of the Zen base-theme (if and when available), I suggest you create a newer Zenophile sub-theme using the newer Zen base-theme.

You can then simply copy and paste the single file called “fresh.css” from your older Zenophile sub-theme directory into your newer Zenophile sub-theme folder assuming you have all of your CSS modifications in that single file according to that recommendation detailed below.

System name * (less-than 40-characters)
This name will be the name of the directory (folder) that Zenophile creates containing all of your new sub-theme files and directories.
- By default the 'System name' that is displayed in this field-box is based on your site's name plus the name of the sub-directory of your Drupal root (if applicable). For example, “www_samplesite_com_sample_drupal_root_sub_directory”.
- This name must be unique in that it can Not be the same name as any other pre-existing theme folder name within [drupal-root]/themes nor within any one of several other “themes” directories inside of [drupal-root]/sites/...
- The 'System name' must begin with a lower-case alphabetic character (a-z).
- The 'System name' may only consist of lower-case alphabetic characters (a-z), numerals (0-9), and the underscore character (_).
Eg. "zen731_zeno711_liq_sbr_2011_12_23".

That example name above is based on Zen 7.x-3.1; Zenophile 7.x-1.1; my intent to use a liquid layout; my intent to have both sidebars on the right of the main content; and the date of this Zeno sub-themes creation.
- Warning: Do Not use more than 39-characters for the “System name”.
  If the default “Sytem name” exceeds 39-characters, change the name so that is has no more than 39-characters.
  
  I have found while using Drupal 7 that if I use 40 or more characters for the system name and then I set the sub-theme as the administrative theme, the site crashes every time. Issue page (Opens in new tab/ window)
  
  This happens both on “local” (on my computer) installations, as well as “online” (at shared webhost) installations.
  
  The default name will exceed 39-characters if the number of characters in your site's domain name plus the number of characters in the names of any sub-directories on the way to the Drupal 7 root directory total 35 characters or more (and add 4 for the “wwww_” prefix to total 39).
  
  If you create a sub-theme using 40-characters or more for the system name, you Will be able to use this Zenophile sub-themes as your site's default theme without a problem as long as you do Not try to use it as the administrative theme; but I recommend against your doing that because if you should ever accidentally set it as the admin theme... crash.
  
  If your site becomes inaccessible because you make the error of using more that 39-characters for the system name, and you set the sub-theme as the administrative theme, you can recover from that error. Delete (or possibly just re-name??) the entire sub-theme directory. Then simply try to visit any page on your site, like the Home Page, and refresh that page (once or twice if necessary). You should regain access to your site although it will display errors at the page top. Set one of your other themes as the site's “Default”/ “Administrative” theme, and you should be alright.
Human name *
This is the theme name that you will see on your site's main theme page listing all of the themes (D7: “Appearance” page: default “List” tab).

(D7) It is also the name that will be within the sub-tab at the top of the “Appearance” page > tab: “Settings”.

You might want to make the “Human name” as short as possible because a large number of enabled themes will make it crowded in the sub-tab area on the "settings" tab page. I have seen really long human names in those sub-tabs run off the page while using different themes as administrative themes.

Eg. "Zeno Liq SB-R Mid".
Description *
This is the text that you will see under the sub-theme's name on the theme list page.
The description is the best place to list for yourself all of the details that are specific to the sub-theme to differentiate it from all of the other sub-themes you might create.

Eg. "Zenophile Midnight theme, liquid layout, both sidebars on the right 175/225 pixels wide. -2011.12.23".
Site directory *
This is the location where your sub-theme directory will be created. Keep in mind that your sub-theme directory will be named according to whatever you have above in the field-box “system name”.

By default the site directory location is “all”. That means that it will be created at [drupal-root]/sites/all/themes/sample_system_name.

I do not know the difference between using the “all” and the “default” folders except to say that it relates to using files for multiple Drupal sites to make the administration of multiple sites quicker and easier.

In any case, I always use the “all” folder for my contributed (non-Core) modules and themes; and I have had no problems with the single site that they are used for.

---
Click “More options” to expand that section for additional options.
---

Starter theme *
I always leave this as the default “Zen Sub-theme Starter Kit (sites/all/zen/STARTERKIT)”. This is a location within the Zen base-theme from which Zenophile gathers and copies all of the files and directories that it needs to generate your new sub-theme's files and directories.
Layout type *
- Fixed
  If you create a fixed theme, your site's page will have a fixed width.
  
  Your pages will be centered within a browser window anytime the browser window is at least as wide or wider than your designated fixed layout pixel width.
  
  When the browser window is too thin to accommodate your page width, a scroll bar will appear at the page bottom allowing users to scroll to the right to view the rest of your page.
  
  The sidebars' (if and when displayed on a page) widths and the main content column width will not vary unless a user uses their browser's option to zoom in or zoom out.
- Liquid
  If you create your theme with a liquid layout, the pages will expand left and right to fill the entire browser window.
  
  The sidebars will each always remain a fixed pixel width.
  
  If the browser window is thinner than your page's “minimum width”, a scroll bar will appear at the page bottom allowing users to scroll to the right to view the rest of your page.
  
  If a user uses their browser's zoom in or zoom out feature, the sidebars (when displayed) and the main content column will all expand or contract proportionally.
Create fresh CSS file
Yes, yes, yes. In other words, put a check-mark in this box. This is a brilliant feature of Zenophile.

This option will create a blank file named “fresh.css”, and that file will also be the last CSS file to be analyzed by a browser.

That means that you can confidently over-ride any CSS declaration that may exist in any of the other multiple CSS files even when your new declaration uses identically named “selectors”.

Since all of your CSS changes can be put into the single “fresh.css” file, if you want to use those CSS changes in another Zenophile sub-theme, the fresh.css file will be the only file you will need to remember to copy and paste into another Zenophile sub-theme.

Additionally, the Zen base-theme is presently still evolving, and so Zenophile sub-themes I create today might be outdated tomorrow. Since newer Zen base-themes might involve changes to its CSS files, I might not be able to reuse the older CSS files that I may have modified. The simplest solution is to simply use “fresh.css” for all CSS modifications.
Override sidebar and page widths and placement
This too is a beautiful option.

Changing a Zen page's width, or sidebar widths/ relative placement by hand in the CSS files involves multiple calculations and declaration changes. It is a nightmare I do not even want to consider doing by hand. It is not fun, nor easy. --At least not as easy as using Zenophile.

By checking this “Override...” option, you will be able to set a different fixed layout page width, and you will be able to specify different fixed widths for each of the sidebars.

You will also be able to specify the placement of the sidebars either one-on-each-side of the main content column, or you can specify them both to be together on either side of the main column.

(2011.12.23 Zenophile 7.1.1 - Presently you will Not be able to set the liquid layout page minimum-width at the time of your sub-theme creation, and it will always be set at 960 pixels for a liquid layout. However, that 'min-width' is easily to change later with only a single CSS declaration change as discussed further below.)

If in the future you want to change the fixed layout page width, or the sidebars' relative placement or width I recommend that you do this by simply creating another Zenophile sub-theme instead of trying to change these parameters by hand in the CSS files. It is for this reason that I again encourage you to use the option further above “Create fresh CSS file”; and I encourage you to put ALL of your CSS modifications in the fresh.css file so that it is the only file you have to copy into any newly created Zenophile sub-theme.
Page wrapper width (#page)
By default the fixed layout page width and the liquid layout page minimum width (min-width) will be 960 pixels.

To change the fixed layout page width, just change the “960” to whatever pixel width you desire.

The liquid layout page's minimum width will be specified in your Zenophile CSS liquid-layout.css file [sample-sub-theme/css/liquid-layout.css] near the top of the page with the code...
```
#page-wrapper,
.region-bottom {
  min-width: 960px;
}
```
To change the min-width, copy the above code into your fresh.css file, and change the “960” to whatever pixel width you desire. --but not right now. You have to wait until the sub-theme has been created.
First sidebar width (div.region-sidebar-first)
The sidebars will be a fixed pixel width. Each sidebar's default width is 200 pixels.

This sidebar-first will be left of the sidebar-second on your pages in standard English ltr (left to right) web pages regardless of whether the sidebars are together or on separate sides of the page.

Simply change the “200” to whatever pixel width you desire.
Second sidebar width (div.region-sidebar-second)
Simply change the “200” to whatever pixel width you desire.
Sidebar positioning
You can set the relative placement of the sidebars so that they are one-on-each-side of the main-column (default), or you can have both sidebars be together on either side of the main-column.
Include Zen Midnight stylesheet and images
Check this Midnight option to have the Zenophile sub-theme background-color as black and the text color as white instead of your Zenophile sub-theme having the default Zen base-theme white background color (background-color) and black text color (color).

This will create a CSS file called 'zen_midnight.css' at [drupal-root}/sites/all/themes/sample_zeno_subtheme/css/zen_midnight.css.

(D7) Do Not use the Midnight theme nor any other dark background theme as an administrative theme.

At present, the Midnight theme has not been modified to render the core administrative pages properly and you will find much of those pages' text illegible. And even if you modify the Midnight theme CSS to properly render the administrative pages associated with the Drupal 7 core, you will find that contributed modules often specify only one of either the background-color or text color which then renders portions of their configuration pages illegible.

I highly recommend that you use your new Zenophile sub-theme when editing or creating content.

(D7) Go to the bottom of the “Appearance” page (on the default “List” tab page) and remove the check-mark from the box for “Use the administration theme when editing or creating content”.

Click the button “Save configuration”.