.info files for themes

New to Drupal 6, .info configuration files are now required for each theme. This file should reside in your theme's directory. Without this file, your theme will not be visible by Drupal. The .info file must end with the ".info" extension.

The internal "machine" readable name of the theme is derived from this file. For example, if it is named "drop.info", then Drupal will see the name of the theme as "drop". Be sure that no odd characters are used since it informs Drupal on how to form various functions in PHP and therefore it will have the same limitations. The name should start with an alphabetic character, no spaces or punctuation. Underscores are allowed but no hyphens. Numbers are allowed as long as it is not the first character.

Notes:

• Warning! Modules bearing the same internal name as your theme can prevent your site from functioning. This may happen from duplicate function names which is illegal in PHP. All installed components must have unique names.
• The contents of the .info file is cached in the database so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To clear it, do one of the following:
  1. Clear button located at "Administer > Site configuration > Performance".
  2. With devel block enabled (comes with devel module), click the "Empty cache" link.
  3. Simply visit the theme select page at "Administer > Site building > Themes".

The syntax is similar to INI files. It is basically a static text file for configuring the theme. Each line in the text file is a key-value pair with the key on the left and the value on the right, with an "equals sign" between them. (example: key = value) 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, using them should be apparent enough by following the example of the default .info files that come with Drupal and reading the explanations of the examples that follow.

Drupal understands the keys listed below. Drupal will use default values for the optional keys not present in the .info file. See the examples set for core themes.

• name !
• description *
• screenshot
• version *
• core !
• engine *
• base theme
• regions
• features
• stylesheets
• scripts
• php

name (required)

The human readable name can now be set independently from the internal "machine" readable name. This imposes less restrictions on the allowed characters.

name = Un tema nombre de fantasía
   

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.
   

screenshot

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
   

version (recommended)

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
   

Note that 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 CVS, 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 CVS is compatibile with at any given time.

engine (recommended)

The theme engine, which is used by the theme. If none is provided then it is assumed the theme is stand alone, i.e., implemented with a ".theme" file. Most themes should use "phptemplate" as the default engine.

PHPTemplates job is to discover theme functions and templates on behave 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 its 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 in the page, Sub-themes, their structure and inheritance.

regions

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. You can override the values for your specific needs.

regions[left] = Left sidebar
regions[right] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer
   

More details are available in the page, Blocks, content and their regions.

features

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. By commenting out the primary_links and secondary_links elements, 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
   

More details are available in the page, Custom theme settings.

stylesheets

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 6, themes can also add style sheets through their .info file.

stylesheets[all][] = theStyle.css
   

More details are available in the style sheets section.

Example .info files from core themes

Garland:

Minnelli sub-theme of Garland.:

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 CVS.