Add better support for smaller devices with maximum-scale = 1.0
[project/zurb-foundation.git] / STARTER / README.txt
1 DOCUMENTATION
2 ----------------------------------
3 Please refer also to the community documentation:
4   http://drupal.org/node/1948260
5
6 BUILD A THEME WITH ZURB FOUNDATION
7 ----------------------------------
8
9 The base Foundation theme is designed to be easily extended by its sub-themes.
10 You shouldn't modify any of the CSS or PHP files in the zurb_foundation/ folder;
11 but instead you should create a sub-theme of zurb_foundation which is located in
12 a folder outside of the root zurb_foundation/ folder. The examples below assume
13 zurb_foundation and your sub-theme will be installed in sites/all/themes/,
14 but any valid theme directory is acceptable. Read the
15 sites/default/default.settings.php for more info.
16
17 This theme does not support IE7. If you need it downgrade to Foundation 2 see
18 http://foundation.zurb.com/docs/faq.php or use the script in the starter
19 template.php THEMENAME_preprocess_html function.
20
21 *** IMPORTANT NOTE ***
22 *
23 * In Drupal 7, the theme system caches which template files and which theme
24 * functions should be called. This means that if you add a new theme,
25 * preprocess or process function to your template.php file or add a new template
26 * (.tpl.php) file to your sub-theme, you will need to rebuild the "theme
27 * registry." See http://drupal.org/node/173880#theme-registry
28 *
29 * Drupal 7 also stores a cache of the data in .info files. If you modify any
30 * lines in your sub-theme's .info file, you MUST refresh Drupal 7's cache by
31 * simply visiting the Appearance page at admin/appearance or at
32   admin/config/development/performance.
33
34 BUILD A THEME WITH DRUSH
35 ----------------------------------
36 If you have drush and the zurb foundation theme enabled you can create a
37 subtheme easily with a drush.
38
39 The command to do this is simply:
40   drush fst [THEMENAME] [Description !Optional]
41
42 MANUALLY BUILD A THEME
43 ----------------------------------
44  1. Setup the location for your new sub-theme.
45
46     Copy the STARTER folder out of the zurb_foundation/ folder and rename it to
47     be your new sub-theme. IMPORTANT: The name of your sub-theme must start with
48     an alphabetic character and can only contain lowercase letters, numbers and
49     underscores.
50
51     For example, copy the sites/all/themes/zurb_foundation/STARTER folder and
52     rename it as sites/all/themes/foo.
53
54       Why? Each theme should reside in its own folder. To make it easier to
55       upgrade Foundation, sub-themes should reside in a folder separate from the
56       base theme.
57
58  2. Setup the basic information for your sub-theme.
59
60     In your new sub-theme folder, rename the STARTERKIT.info.txt file to include
61     the name of your new sub-theme and remove the ".txt" extension. Then edit
62     the .info file by editing the name and description field.
63
64     For example, rename the foo/STARTER.info.txt file to foo/foo.info. Edit the
65     foo.info file and change "name = Foundation Sub-theme Starter" to
66     "name = Foo" and "description = Read..." to "description = A sub-theme".
67
68       Why? The .info file describes the basic things about your theme: its
69       name, description, features, template regions, CSS files, and JavaScript
70       files. See the Drupal 7 Theme Guide for more info:
71       http://drupal.org/node/171205
72
73     Then, visit your site's Appearance page at admin/appearance to refresh
74     Drupal 7's cache of .info file data.
75
76  3. Edit your sub-theme to use the proper function names.
77
78     Edit the template.php and theme-settings.php files in your sub-theme's
79     folder; replace ALL occurrences of "STARTER" with the name of your
80     sub-theme.
81
82     For example, edit foo/template.php and foo/theme-settings.php and replace
83     every occurrence of "STARTER" with "foo".
84
85     It is recommended to use a text editing application with search and
86     "replace all" functionality.
87
88  5. Set your website's default theme.
89
90     Log in as an administrator on your Drupal site, go to the Appearance page at
91     admin/appearance and click the "Enable and set default" link next to your
92     new sub-theme.
93
94
95 Optional steps:
96
97  6. Modify the markup in Foundation core's template files.
98
99     If you decide you want to modify any of the .tpl.php template files in the
100     zurb_foundation folder, copy them to your sub-theme's folder before
101     making any changes.And then rebuild the theme registry.
102
103     For example, copy zurb_foundation/templates/page.tpl.php to
104     THEMENAME/templates/page.tpl.php.
105
106  7. Modify the markup in Drupal's search form.
107
108     Copy the search-block-form.tpl.php template file from the modules/search/
109     folder and place it in your sub-theme's template folder. And then rebuild
110     the theme registry.
111
112     You can find a full list of Drupal templates that you can override in the
113     templates/README.txt file or http://drupal.org/node/190815
114
115       Why? In Drupal 7 theming, if you want to modify a template included by a
116       module, you should copy the template file from the module's directory to
117       your sub-theme's template directory and then rebuild the theme registry.
118       See the Drupal 7 Theme Guide for more info: http://drupal.org/node/173880
119
120  8. Further extend your sub-theme.
121
122     Discover further ways to extend your sub-theme by reading
123     Drupal 7's Theme Guide online at: http://drupal.org/theme-guide
124
125 CHANGING FOUNDATION DEFAULT SETTINGS
126 ------------------------------------
127 In order to avoid overwriting your customizations in _settings.scss when
128 updating Zurb Foundation, subthemes default to placing the standard Foundation
129 settings in [subtheme-name]/scss/_variables.scss.
130
131 If you prefer to do it the standard Foundation way (at your own risk), you can
132 rename _variables.scss to _settings.scss in your subtheme and then load
133 "settings" instead of "variables" in [subtheme-name]/scss/base/_init.scss.