Writing theme .info files
The .info file is a static text file for defining and configuring a theme. Each line in the .info file is a key-value pair with the key on the left and the value on the right, with an "equals sign" between them (e.g.
name = my_theme). Semicolons are used to comment out a line. Some keys use a special syntax with square brackets for building a list of associated values, referred to as an "array". If you are unfamiliar with arrays, have a look at the default .info files that come with Drupal and read the explanations of the examples that follow. Even though the .info file extension is not natively opened by an Application, you can use TextEdit on a Mac or Notepad on a Windows computer in order to view, edit, and save your changes.
Note that this page describes .info files used for Drupal themes, and not modules. For information about the structure of .info files for Drupal modules, see Writing .info files in the Module developer's guide.
The following example shows the Drupal 6 .info file for the Garland theme:
name = Garland description = Tableless, recolorable, multi-column, fluid width theme (default). version = VERSION core = 6.x engine = phptemplate stylesheets[all] = style.css stylesheets[print] = print.css
Theme name requirements
The name should start with an alphabetic character, can contain numbers and underscores, but not hyphens, spaces or punctuation. The name will be used by Drupal in forming various functions in PHP and therefore it has the same limitations.
Do not choose names that are already used by installed modules, as all installed components must have unique names.
One of the best practices is to use prefixes when naming a site's custom theme, to guarantee unique names for themes. A site named example.com might use theme names such as ex_themename.
Because the .info file is cached, you must clear the cache before any changes are displayed in your site.
The .info file can also specify which theme settings should be accessed from the Drupal administration interface, as you will soon see.
The file must be saved as UTF-8 without a Byte Order Mark (BOM).
- name required
- description recommended
- version discouraged
- core required
- engine required in Drupal 6
- base theme
- theme settings
- name (required)
The human readable name can now be set independently from the internal "machine" readable name. This imposes fewer restrictions on the allowed characters.
name = A fantasy name
- description (recommended)
A short description of the theme. This description is displayed on the theme select page at "Administer > Site building > themes".
description = Tableless multi-column theme designed for blogs.
The optional screenshot key tells Drupal where to find the theme's thumbnail image, used on the theme selection page (admin/build/themes). If this key is omitted from the .info file, Drupal uses the "screenshot.png" file in the theme's directory.
Use this key only if your thumbnail file is not called "screenshot.png" or if you want to place it in a directory outside of your theme's base directory (e.g.
screenshot = images/screenshot.png).
screenshot = screenshot.png
More details on creating a screenshot for the administration page.
- version (discouraged)
The version string will automatically be added by drupal.org when a release is created and a tarball packaged. So you may omit this value for contributed themes. However, if your theme is not being hosted on the drupal.org infrastructure, you can give your theme whatever version string makes sense.
version = 1.0
- core (required)
From 6.x onward, all .info files for modules and themes must indicate what major version of Drupal core they are compatible with. The value set here is compared with the DRUPAL_CORE_COMPATIBILITY constant. If it does not match, the theme will be disabled.
core = 6.x
The drupal.org packaging script automatically sets this value based on the Drupal core compatibility setting on each release node. So people downloading packaged themes from drupal.org will always get the right thing. However, for sites that deploy Drupal directly from git, it helps if you commit this change to the .info file for your theme. This is also a good way to indicate to users of each theme what version of core the HEAD of git is compatible with at any given time.
- engine (required in Drupal 6)
The theme engine, which is used by the theme.
Drupal 6: If none is provided, the theme is assumed to be stand alone, i.e., implemented with a ".theme" file. Most themes should use "phptemplate" as the default engine.
Drupal 7: In Drupal 7, this line is no longer necessary because PHPTemplate is assumed by default.
PHPTemplate's job is to discover theme functions and templates for the behavior of the theme. Omit this entry only if you know what you are doing.
engine = phptemplate
- base theme
Sub-themes can declare a base theme. This allows for theme inheritance, meaning the resources from the "base theme" will cascade and be reused inside the sub-theme. Sub-themes can declare other sub-themes as their base, allowing multiple levels of inheritance. Use the internal "machine" readable name of the base theme. The following is used in Minnelli, the sub-theme of Garland.
base theme = garland
More details are available on the page Sub-themes, their structure and inheritance.
The block regions available to the theme are defined by specifying the key of '
regions' followed by the internal "machine" readable name in square brackets and the human readable name as the value, e.g.,
regions[theRegion] = The region name.
If no regions are defined, the following values are assumed.
Drupal 6 default regions:
regions[left] = Left sidebar regions[right] = Right sidebar regions[content] = Content regions[header] = Header regions[footer] = Footer
Drupal 7 default regions:
regions[header] = Header regions[highlighted] = Highlighted regions[help] = Help regions[content] = Content regions[sidebar_first] = Left sidebar regions[sidebar_second] = Right sidebar regions[footer] = Footer
You can override the values for your specific needs.
If you override regions in D7, you are obliged to declare the line regions[content] = Content. If you want any of the default regions in your theme, you have to declare them as well.
More details are available on the page Blocks, content and their regions.
Various page elements output by the theme can be toggled on and off on the theme's configuration page. The "features" keys control which of these check boxes display on the theme's configuration page. This is useful for suppressing check boxes for elements not defined or used by a theme. To suppress a check box, omit the entry for it. However, if none are defined, all the check boxes will display due to the assumed defaults.
The example below lists all the available elements controlled by the features key.
Drupal 6 features
By commenting out the
secondary_linkselements, their check boxes are suppressed and are not seen by site administrators.
features = logo features = name features = slogan features = mission features = node_user_picture features = comment_user_picture features = search features = favicon ; These last two disabled by redefining the ; above defaults with only the needed features. ; features = primary_links ; features = secondary_links
Drupal 7 features
features = logo features = name features = slogan features = node_user_picture features = comment_user_picture features = comment_user_verification features = favicon features = main_menu features = secondary_menu
More details are available on the page Custom theme settings.
- theme settings
You can use theme settings placed in .info file, to set the features by default "checked" or "unchecked" in your theme. By placing:
settings[toggle_"feature"] = 0to uncheck setting
Where "feature" is example logo, favicon etc. that where mentioned earlier.
Example default settings:
settings[toggle_logo] = 1 settings[toggle_name] = 1 settings[toggle_slogan] = 1 settings[toggle_node_user_picture] = 1 settings[toggle_comment_user_picture] = 1 settings[toggle_comment_user_verification] = 1 settings[toggle_favicon] = 1 settings[toggle_main_menu] = 1 settings[toggle_secondary_menu] = 1
More details about Advanced theme settings.
Traditionally, themes default to using style.css automatically and could add additional stylesheets by calling drupal_add_css() in their template.php file. Starting in Drupal 6, themes can also add style sheets through their .info file.
stylesheets[all] = theStyle.css
Starting in Drupal 7, themes no longer default to using style.css if it is not specified in the .info file.
More details are available in the style sheets section.
scripts = myscript.js
This defines the minimum PHP version the theme will support. The default value is derived from the DRUPAL_MINIMUM_PHP constant, which is the minimum required version for the rest of core. This can be redefined for a newer version if needed. For most themes, this should not be added.
php = 4.3.3
Example .info files from core themes
name = Garland description = Tableless, recolorable, multi-column, fluid width theme (default). version = VERSION core = 6.x engine = phptemplate stylesheets[all] = style.css stylesheets[print] = print.css ; Information added by drupal.org packaging script on 2008-02-13 version = "6.0" project = "drupal" datestamp = "1202913006"
Minnelli sub-theme of Garland.:
name = Minnelli description = Tableless, recolorable, multi-column, fixed width theme. version = VERSION core = 6.x base theme = garland stylesheets[all] = minnelli.css ; Information added by drupal.org packaging script on 2008-02-13 version = "6.0" project = "drupal" datestamp = "1202913006"
Note that everything from the line "; Information added by drupal.org packaging script on 2008-02-13" and down is added by the drupal.org packaging script. You should never manually add the project and datestamp keys. The version key added manually (in the first section) allows sites to use your theme when taken directly from git.