|author||JohnAlbin||2011-11-28 22:03:39 +0800|
|committer||JohnAlbin||2011-11-28 22:03:39 +0800|
Update the docs in template.php for Drupal 7
1 files changed, 63 insertions, 20 deletions
diff --git a/STARTERKIT/template.php b/STARTERKIT/template.php
index 6f37349..b2aded9 100644
@@ -1,36 +1,80 @@
- * Contains theme override functions and preprocess functions for the theme.
+ * Contains the theme's functions to manipulate Drupal's default markup.
+ * A QUICK OVERVIEW OF DRUPAL THEMING
+ * The default HTML for all of Drupal's markup is specified by its modules.
+ * For example, the comment.module provides the default HTML markup and CSS
+ * styling that is wrapped around each comment. Fortunately, each piece of
+ * markup can optionally be overridden by the theme.
+ * Drupal deals with each chunk of content using a "theme hook". The raw
+ * content is placed in PHP variables and passed through the theme hook, which
+ * can either be a template file (which you should already be familiary with)
+ * or a theme function. For example, the "comment" theme hook is implemented
+ * with a comment.tpl.php template file, but the "breadcrumb" theme hooks is
+ * implemented with a theme_breadcrumb() theme function. Regardless if the
+ * theme hook uses a template file or theme function, the template or function
+ * does the same kind of work; it takes the PHP variables passed to it and
+ * wraps the raw content with the desired HTML markup.
+ * Most theme hooks are implemented with template files. Theme hooks that use
+ * theme functions do so for performance reasons - theme_field() is faster
+ * than a field.tpl.php - or for legacy reasons - theme_breadcrumb() has "been
+ * that way forever."
+ * The variables used by theme functions or template files come from a handful
+ * of sources:
+ * - the contents of other theme hooks that have already been rendered into
+ * HTML. For example, the HTML from theme_breadcrumb() is put into the
+ * $breadcrumb variable of the page.tpl.php template file.
+ * - raw data provided directly by a module (often pulled from a database)
+ * - a "render element" provided directly by a module. A render element is a
+ * nested PHP array which contains both content and meta data with hints on
+ * how the content should be rendered. If a variable in a template file is a
+ * render element, it needs to be rendered with the render() function and
+ * then printed using:
+ * <?php print render($variable); ?>
* ABOUT THE TEMPLATE.PHP FILE
* The template.php file is one of the most useful files when creating or
- * modifying Drupal themes. You can modify or override Drupal's theme
- * functions, intercept or make additional variables available to your theme,
- * and create custom PHP logic. For more information, please visit the Theme
- * Developer's Guide on Drupal.org: http://drupal.org/theme-guide
+ * modifying Drupal themes. With this file you can do three things:
+ * - Modify any theme hooks variables or add your own variables, using
+ * preprocess or process functions.
+ * - Override any theme function. That is, replace a module's default theme
+ * function with one you write.
+ * - Call hook_*_alter() functions which allow you to alter various parts of
+ * Drupal's internals, including the render elements in forms. The most
+ * useful of which include hook_form_alter(), hook_form_FORM_ID_alter(),
+ * and hook_page_alter(). See api.drupal.org for more information about
+ * _alter functions.
* OVERRIDING THEME FUNCTIONS
- * The Drupal theme system uses special theme functions to generate HTML
- * output automatically. Often we wish to customize this HTML output. To do
- * this, we have to override the theme function. You have to first find the
- * theme function that generates the output, and then "catch" it and modify it
- * here. The easiest way to do it is to copy the original function in its
- * entirety and paste it here, changing the prefix from theme_ to STARTERKIT_.
- * For example:
+ * If a theme hook uses a theme function, Drupal will use the default theme
+ * function unless your theme overrides it. To override a theme function, you
+ * have to first find the theme function that generates the output. (The
+ * api.drupal.org website is a good place to find which file contains which
+ * function.) Then you can copy the original function in its entirety and
+ * paste it in this template.php file, changing the prefix from theme_ to
+ * STARTERKIT_. For example:
- * original: theme_breadcrumb()
- * theme override: STARTERKIT_breadcrumb()
+ * original, found in modules/field/field.module: theme_field()
+ * theme override, found in template.php: STARTERKIT_field()
* where STARTERKIT is the name of your sub-theme. For example, the
- * zen_classic theme would define a zen_classic_breadcrumb() function.
+ * zen_classic theme would define a zen_classic_field() function.
- * If you would like to override either of the two theme functions used in Zen
- * core, you should first look at how Zen core implements those functions:
+ * Note that base themes can also override theme functions. And those
+ * overrides will be used by sub-themes unless the sub-theme chooses to
+ * override again.
+ * Zen core only overrides one theme function. If you wish to override it, you
+ * should first look at how Zen core implements this function:
* theme_breadcrumbs() in zen/template.php
- * theme_menu_local_tasks() in zen/template.php
* For more information, please visit the Theme Developer's Guide on
* Drupal.org: http://drupal.org/node/173880
@@ -54,8 +98,7 @@
* For more information on preprocess functions and theme hook suggestions,
* please visit the Theme Developer's Guide on Drupal.org:
- * http://drupal.org/node/223440
- * and http://drupal.org/node/190815#template-suggestions
+ * http://drupal.org/node/223440 and http://drupal.org/node/1089656