README.txt

   1 // $Id$
   2
   3 Full documentation on the Zen theme can be found in Drupal's Handbook:
   4   http://drupal.org/node/193318
   5
   6 Excellent documentation on Drupal theming can be found in the Theme Guide:
   7   http://drupal.org/theme-guide
   8
   9
  10 INSTALLATION
  11 ------------
  12
  13  1. Download Zen from http://drupal.org/project/zen
  14
  15  2. Unpack the downloaded file, take the entire zen folder (which includes the
  16     README.txt file, a STARTERKIT folder, etc.) and place it in your Drupal
  17     installation under one of the following locations:
  18       sites/all/themes
  19         making it available to the default Drupal site and to all Drupal sites
  20         in a multi-site configuration
  21       sites/default/themes
  22         making it available to only the default Drupal site
  23       sites/example.com/themes
  24         making it available to only the example.com site if there is a
  25         sites/example.com/settings.php configuration file
  26
  27     For more information about acceptable theme installation directories, read
  28     the sites/default/default.settings.php file in your Drupal installation.
  29
  30  3. Log in as an administrator on your Drupal site and go to Administer > Site
  31     building > Themes (admin/build/themes). You will see the Zen theme there
  32     with links on how to create your own sub-theme. You can optionally make Zen
  33     the default theme.
  34
  35
  36 BUILD YOUR OWN SUB-THEME
  37 ------------------------
  38
  39 *** IMPORTANT ***
  40
  41 * In Drupal 6, the theme system caches template files and which theme functions
  42   should be called. What that means is if you add a new theme or preprocess
  43   function to your template.php file or add a new template (.tpl.php) file to
  44   your sub-theme, you will need to rebuild the "theme registry." See
  45   http://drupal.org/node/173880#theme-registry
  46
  47 * Drupal 6 also stores a cache of the data in .info files. If you modify any
  48   lines in your sub-theme's .info file, you MUST refresh Drupal 6's cache by
  49   simply visiting the admin/build/themes page.
  50
  51
  52 The base Zen theme is designed to be easily extended by its sub-themes. You
  53 shouldn't modify any of the CSS or PHP files in the zen/ folder; but instead you
  54 should create a sub-theme of zen which is located in a folder outside of the
  55 root zen/ folder. The examples below assume zen and your sub-theme will be
  56 installed in sites/all/themes/, but any valid theme directory is acceptable
  57 (read the sites/default/default.settings.php for more info.)
  58
  59   Why? To learn why you shouldn't modify any of the files in the zen/ folder,
  60   see http://drupal.org/node/245802
  61
  62  1. Copy the STARTERKIT folder out of the zen/ folder and rename it to be your
  63     new sub-theme. IMPORTANT: Only lowercase letters and underscores should be
  64     used for the name of your sub-theme.
  65
  66     For example, copy the sites/all/themes/zen/STARTERKIT folder and rename it
  67     as sites/all/themes/foo.
  68
  69       Why? Each theme should reside in its own folder. Unlike in Drupal 5,
  70       sub-themes can (and should) reside in a folder separate from their base
  71       theme.
  72
  73  2. In your new sub-theme folder, rename the STARTERKIT.info.txt file to include
  74     the name of your new sub-theme and remove the ".txt" extension. Then edit
  75     the .info file by changing any occurrence of STARTERKIT with the name of
  76     your sub-theme and editing the name and description field.
  77
  78     For example, rename the foo/STARTERKIT.info file to foo/foo.info. Edit the
  79     foo.info file and change "STARTERKIT.css" to "foo.css", change "name = Zen
  80     Sub-theme Starter Kit" to "name = Foo", and change "description = Read..."
  81     to "description = A Zen sub-theme".
  82
  83       Why? The .info file describes the basic things about your theme: its
  84       name, description, features, template regions, CSS files, and JavaScript
  85       files. See the Drupal 6 Theme Guide for more info:
  86       http://drupal.org/node/171205
  87
  88     Then, visit your site's admin/build/themes to refresh Drupal 6's cache of
  89     .info file data.
  90
  91  3. If you want a liquid layout for your theme, copy the layout-liquid.css from
  92     the zen/zen folder and place it in your sub-theme's folder. If you want a
  93     fixed-width layout for your theme, copy the layout-fixed.css from the
  94     zen/zen folder and place it in your sub-theme's folder. Rename the layout
  95     stylesheet to "layout.css".
  96
  97     For example, copy zen/zen/layout-fixed.css and rename it as foo/layout.css.
  98     Note that the .info file already has an entry for your layout.css file.
  99
 100       Why? In Drupal 6 theming, if you want to modify a stylesheet included by
 101       the base theme or by a module, you should copy the stylesheet from the
 102       base theme or module's directory to your sub-theme's directory and then
 103       add the stylesheet to your .info file. See the Drupal 6 Theme Guide for
 104       more info: http://drupal.org/node/171209
 105
 106  4. Copy the zen stylesheet from the zen folder and place it in your sub-theme's
 107     folder. Rename it to be the name of your sub-theme.
 108
 109     For example, copy zen/zen/zen.css and rename it as foo/foo.css. Note that
 110     the .info file already has an entry for your foo.css file and that your
 111     .info file removes the base theme's zen.css file.
 112
 113  5. Copy the print stylesheet from the zen folder and place it in your
 114     sub-theme's folder.
 115
 116     For example, copy zen/zen/print.css to foo/print.css. Note that the .info
 117     file already has an entry for your print.css file.
 118
 119  6. Copy the html-elements stylesheet from the zen folder and place it in your
 120     sub-theme's folder.
 121
 122     For example, copy zen/zen/html-elements.css to foo/html-elements.css. Note
 123     that the .info file already has an entry for your html-elements.css file.
 124
 125  7. Edit the template.php and theme-settings.php files in your sub-theme's
 126     folder; replace ALL occurrences of "STARTERKIT" with the name of your
 127     sub-theme.
 128
 129     For example, edit foo/template.php and foo/theme-settings.php and replace
 130     "STARTERKIT" with "foo".
 131
 132  8. Log in as an administrator on your Drupal site and go to Administer > Site
 133     building > Themes (admin/build/themes) and enable your new sub-theme.
 134
 135
 136 Optional:
 137
 138  9. MODIFYING ZEN CORE STYLESHEETS:
 139     If you decide you want to modify any of the other stylesheets in the zen
 140     folder, copy them to your sub-theme's folder before making any changes.
 141     Also, be sure the new stylesheet is included in your .info file, that you
 142     have rebuilt the theme registry, and that you have refreshed the .info
 143     cache.
 144
 145     For example, copy zen/zen/block-editing.css to foo/block-editing.css. Then
 146     edit foo/foo.info and uncomment this line to activate it:
 147       ;stylesheets[all][]  = block-editing.css
 148     to:
 149       stylesheets[all][]   = block-editing.css
 150     Then, visit your site's admin/build/themes to refresh Drupal 6's cache of
 151     .info file data.
 152
 153 10. MODIFYING ZEN CORE TEMPLATE FILES:
 154     If you decide you want to modify any of the .tpl.php template files in the
 155     zen folder, copy them to your sub-theme's folder before making any changes.
 156     And then rebuild the theme registry.
 157
 158     For example, copy zen/zen/page.tpl.php to foo/page.tpl.php.
 159
 160 11. THEMEING DRUPAL'S SEARCH FORM:
 161     Copy the search-theme-form.tpl.php template file from the modules/search/
 162     folder and place it in your sub-theme's folder. And then rebuild the theme
 163     registry.
 164
 165     You can find a full list of Drupal templates that you can override on:
 166     http://drupal.org/node/190815
 167
 168       Why? In Drupal 6 theming, if you want to modify a template included by a
 169       module, you should copy the template file from the module's directory to
 170       your sub-theme's directory and then rebuild the theme registry. See the
 171       Drupal 6 Theme Guide for more info: http://drupal.org/node/173880
 172
 173 12. FURTHER EXTENSIONS OF YOUR SUB-THEME:
 174     Discover further ways to extend your sub-theme by reading Zen's
 175     documentation online at:
 176       http://drupal.org/node/193318
 177     and Drupal 6's Theme Guide online at:
 178       http://drupal.org/theme-guide