Home       Trees       Indices       Help   
Package base :: Package includes :: Module theme
[hide private]

Module theme

source code

The theme system, which controls the output of Drupal. The theme system allows for nearly all output of the Drupy system to be customized by user themes.
See Also:
Drupy Homepage, Drupal Homepage, Drupal Theme system
Notes:

Author: Brendon Crawford

Copyright: 2008 Brendon Crawford

Contact: message144 at users dot sourceforge dot net

Version: 0.1

Functions [hide private]
 
init_theme()
Initialize the theme system by loading the theme.		 source code
 
_init_theme(theme_, base_theme=[], registry_callback='_theme_load_registry')
Initialize the theme system given already loaded information.		 source code
 
get_registry(registry=None)
Retrieve the stored theme registry.		 source code
 
_set_registry(registry)
Store the theme registry in memory.		 source code
 
_load_registry(theme_, base_theme=None, theme_engine=None)
Get the theme_registry cache from the database; if it doesn't exist, build it.		 source code
 
_theme_save_registry(theme_, registry)
Write the theme_registry cache into the database.		 source code
 
drupal_theme_rebuild()
Force the system to rebuild the theme registry; this should be called when plugins are added to the system, or when a dynamic system needs to add more theme hooks.		 source code
 
_process_registry(cache, name, type_, theme_, path)
Process a single invocation of the theme hook.		 source code
 
_build_registry(theme_, base_theme, theme_engine)
Rebuild the hook theme_registry cache.		 source code
 
list_themes(refresh=False)
Provides a list of currently available themes.		 source code
 
theme(*args)
Generate the themed output.		 source code
 
drupal_discover_template(paths, suggestions, extension='.tpl.php')
Choose which template file to actually render.		 source code
 
path_to_theme()
Return the path to the currently selected theme.		 source code
 
drupal_find_theme_functions(cache, prefixes)
Find overridden theme functions.		 source code
 
drupal_find_theme_templates(cache, extension, path)
Find overridden theme templates.		 source code
 
get_settings(key=None)
Retrieve an associative array containing the settings for a theme+ *...		 source code
 
get_setting(setting_name, refresh=False)
Retrieve a setting for the current theme+...		 source code
 
render_template(file, variables)
Render a system default template, which is essentially a PHP template+ *		 source code
 
placeholder(text)
Functions and templates that present output to the user, and can be...		 source code
 
status_messages(display=None)
Return a themed set of status and/or error messages...		 source code
 
links(links, attributes={'class': 'links'})
Return a themed set of links+ *		 source code
 
image(path, alt='', title='', attributes=None, getsize=True)
Return a themed image+ *		 source code
 
breadcrumb(breadcrumb)
Return a themed breadcrumb trail+ *		 source code
 
help_()
Return a themed help message+ *		 source code
 
submenu(links)
Return a themed submenu, typically displayed under the tabs+ *		 source code
 
table(header_, rows, attributes={}, caption=None, colgroups={})
Return a themed table.		 source code
 
table_select_header_cell()
Returns a php.header cell for tables that have a select all functionality+		 source code
 
tablesort_indicator(style)
Return a themed sort icon+ *		 source code
 
box(title, content, region='main')
Return a themed box+ *		 source code
 
mark(type=1)
Return a themed marker, useful for marking new or updated...		 source code
 
item_list(items=[], title=None, type='ul', attributes=[])
Return a themed list of items+ *		 source code
 
more_help_link(url)
Returns code that emits the 'more help'-link+		 source code
 
xml_icon(url)
Return code that emits an XML icon+ *...		 source code
 
feed_icon(url, title)
Return code that emits an feed icon+ *		 source code
 
more_link(url, title)
Returns code that emits the 'more' link used on blocks+ *		 source code
 
closure(main_=0)
Execute hook_footer() which is run at the end of the page right before the...		 source code
 
blocks(region)
Return a set of blocks available for the current user+ *		 source code
 
username(object_)
Format a username+ *		 source code
 
progress_bar(percent, message)
Return a themed progress bar+ *		 source code
 
indentation(size=1)
Create a standard indentation div+ Used for drag and drop tables+ *		 source code
 
_table_cell(cell, header_=False) source code
 
template_preprocess(variables_, hook)
Adds a default set of helper variables for preprocess functions and...		 source code
 
template_preprocess_page(variables_)
Process variables for page.tpl.php...		 source code
 
template_preprocess_node(variables_)
Process variables for node.tpl.php...		 source code
 
template_preprocess_block(variables_)
Process variables for block.tpl.php...		 source code
Variables [hide private]
  __version__ = '$Revision: 1 $'
  MARK_READ = 0
  MARK_NEW = 1
  MARK_UPDATED = 2
  processors = {}
Function Details [hide private]

_init_theme(theme_, base_theme=[], registry_callback='_theme_load_registry')

source code 
Initialize the theme system given already loaded information. This function is useful to initialize a theme when no database is present.
Parameters:
  • this_theme - An object with the following information: filename The .info file for this theme. The 'path' to the theme will be in this file's directory. (Required) owner The path to the .theme file or the .engine file to load for the theme. (Required) stylesheet The primary stylesheet for the theme. (Optional) engine The name of theme engine to use. (Optional)
  • base_theme - An optional array of objects that represent the 'base theme' if the theme is meant to be derivative of another theme. It requires the same information as the theme object. It should be in 'oldest first' order, meaning the top level of the chain will be first.
  • registry_callback - The callback to invoke to set the theme registry.

get_registry(registry=None)

source code 
Retrieve the stored theme registry. If the theme registry is already in memory it will be returned; otherwise it will attempt to load the registry from cache. If this fails, it will construct the registry and cache it.

_load_registry(theme_, base_theme=None, theme_engine=None)

source code 
Get the theme_registry cache from the database; if it doesn't exist, build it.
Parameters:
  • theme - The loaded theme object.
  • base_theme - An array of loaded theme objects representing the ancestor themes in oldest first order.
  • theme_engine - The name of the theme engine.

_process_registry(cache, name, type_, theme_, path)

source code 
Process a single invocation of the theme hook. type will be one of 'plugin', 'theme_engine' or 'theme' and it tells us some important information. Because cache is a reference, the cache will be continually expanded upon; new entries will replace old entries in the array_merge, but we are careful to ensure some data is carried forward, such as the arguments a theme hook needs. An override flag can be set for preprocess functions. When detected the cached preprocessors for the hook will not be merged with the newly set. This can be useful to themes and theme engines by giving them more control over how and when the preprocess functions are run.

_build_registry(theme_, base_theme, theme_engine)

source code 
Rebuild the hook theme_registry cache.
Parameters:
  • theme - The loaded theme object.
  • base_theme - An array of loaded theme objects representing the ancestor themes in oldest first order.
  • theme_engine - The name of the theme engine.

list_themes(refresh=False)

source code 
Provides a list of currently available themes. If the database is active then it will be retrieved from the database. Otherwise it will retrieve a new list.
Parameters:
  • refresh - Whether to reload the list of themes from the database.
Returns:
An array of the currently available themes.

theme(*args)

source code 
Generate the themed output. All requests for theme hooks must go through this function. It examines the request and routes it to the appropriate theme function. The theme registry is checked to determine which implementation to use, which may be a function or a template. If the implementation is a function, it is executed and its return value passed along. If the implementation is a template, the arguments are converted to a variables array. This array is then modified by the plugin implementing the hook, theme engine (if applicable) and the theme. The following functions may be used to modify the variables array. They are processed in this order when available: - template_preprocess(&variables) This sets a default set of variables for all template implementations. - template_preprocess_HOOK(&variables) This is the first preprocessor called specific to the hook; it should be implemented by the plugin that registers it. - MODULE_preprocess(&variables) This will be called for all templates; it should only be used if there is a real need. It's purpose is similar to template_preprocess(). - MODULE_preprocess_HOOK(&variables) This is for plugins that want to alter or provide extra variables for theming hooks not registered to itself. For example, if a plugin named "foo" wanted to alter the submitted variable for the hook "node" a preprocess function of foo_preprocess_node() can be created to intercept and alter the variable. - ENGINE_engine_preprocess(&variables) This function should only be implemented by theme engines and exists so that it can set necessary variables for all hooks. - ENGINE_engine_preprocess_HOOK(&variables) This is the same as the previous function, but it is called for a single theming hook. - ENGINE_preprocess(&variables) This is meant to be used by themes that utilize a theme engine. It is provided so that the preprocessor is not locked into a specific theme. This makes it easy to share and transport code but theme authors must be careful to prevent fatal re-declaration errors when using sub-themes that have their own preprocessor named exactly the same as its base theme. In the default theme engine (PHPTemplate), sub-themes will load their own template.php file in addition to the one used for its parent theme. This increases the risk for these errors. A good practice is to use the engine name for the base theme and the theme name for the sub-themes to minimize this possibility. - ENGINE_preprocess_HOOK(&variables) The same applies from the previous function, but it is called for a specific hook. - THEME_preprocess(&variables) These functions are based upon the raw theme; they should primarily be used by themes that do not use an engine or by sub-themes. It serves the same purpose as ENGINE_preprocess(). - THEME_preprocess_HOOK(&variables) The same applies from the previous function, but it is called for a specific hook. There are two special variables that these hooks can set: 'template_file' and 'template_files'. These will be merged together to form a list of 'suggested' alternate template files to use, in reverse order of priority. template_file will always be a higher priority than items in template_files. theme() will then look for these files, one at a time, and use the first one that exists.
Parameters:
  • hook - The name of the theme function to call. May be an array, in which case the first hook that actually has an implementation registered will be used. This can be used to choose 'fallback' theme implementations, so that if the specific theme hook isn't implemented anywhere, a more generic one will be used. This can allow themes to create specific theme implementations for named objects.
  • ... - Additional arguments to pass along to the theme function.
Returns:
An HTML string that generates the themed output.

drupal_discover_template(paths, suggestions, extension='.tpl.php')

source code 
Choose which template file to actually render. These are all suggested templates from themes and plugins. Theming implementations can occur on multiple levels. All paths are checked to account for this.

drupal_find_theme_functions(cache, prefixes)

source code 
Find overridden theme functions. Called by themes and/or theme engines to easily discover theme functions.
Parameters:
  • cache - The existing cache of theme hooks to test against.
  • prefixes - An array of prefixes to test, in reverse order of importance.
Returns:
templates The functions found, suitable for returning from hook_theme;

drupal_find_theme_templates(cache, extension, path)

source code 
Find overridden theme templates. Called by themes and/or theme engines to easily discover templates.
Parameters:
  • cache - The existing cache of theme hooks to test against.
  • extension - The extension that these templates will have.
  • path - The path to search.

get_settings(key=None)

source code 
Retrieve an associative array containing the settings for a theme+ * The final settings are arrived at by merging the default settings, the site-wide settings, and the settings defined for the specific theme+ * If no key was specified, only the site-wide theme defaults are retrieved+ * The default values for each of settings are also defined in this function+ To add new settings, add their default values here, and then add form elements to system_theme_settings() in system.plugin+ *
Parameters:
  • key - The template/style value for a given theme+ *
Returns:
An associative array containing theme settings

get_setting(setting_name, refresh=False)

source code 
Retrieve a setting for the current theme+ This function is designed for use from within themes & engines to determine theme settings made in the admin interface+ * Caches values for speed (use refresh = True to refresh cache)
Parameters:
  • setting_name - The name of the setting to be retrieved+ *
  • refresh - Whether to reload the cache of settings+ *
Returns:
The value of the requested setting, None if the setting does not exist

render_template(file, variables)

source code 
Render a system default template, which is essentially a PHP template+ *
Parameters:
  • file - The filename of the template to render
  • variables - A keyed array of variables that will appear in the output+ *
Returns:
The output generated by the template

placeholder(text)

source code 
Functions and templates that present output to the user, and can be implemented by themes Drupal's presentation layer is a pluggable system known as the theme layer+ Each theme can take control over most of Drupal's output, and has complete control over the CSS Inside Drupal, the theme layer is utilized by the use of the theme() function, which is passed the name of a component (the theme hook) and several arguments+ For example, theme('table', php.header, rows); Additionally, the theme() function can take an array of theme hooks, which can be used to provide 'fallback' implementations to allow for more specific control of output+ For example, the function: theme(array('table__foo', 'table'), php.header, rows) would look to see if 'table__foo' is registered anywhere; if it is not, it would 'fall back' to the generic 'table' implementation+ This can be used to attach specific theme functions to named objects, allowing the themer more control over specific types of output As of Drupal 6, every theme hook is required to be registered by the plugin that owns it, so that Drupal can tell what to do with it and to make it simple for themes to identify and override the behavior for these calls The theme hooks are registered via hook_theme(), which returns an array of arrays with information about the hook+ It describes the arguments the function or template will need, and provides defaults for the template in case they are not filled in+ If the default implementation is a function, by convention it is named theme_HOOK() Each plugin should provide a default implementation for theme_hooks that it registers This implementation may be either a function or a template; if it is a function it must be specified via hook_theme()+ By convention, default implementations of theme hooks are named theme_HOOK+ Default template implementations are stored in the plugin directory+ * Drupal's default template renderer is a simple PHP parsing engine that includes the template and stores the output+ Drupal's theme engines can provide alternate template engines, such as XTemplate, Smarty and PHPTal+ The most common template engine is PHPTemplate (included with Drupal and implemented in phptemplate.engine, which uses Drupal's default template renderer In order to create theme-specific implementations of these hooks, themes can implement their own version of theme hooks, either as functions or templates+ These implementations will be used instead of the default implementation+ If using a pure +theme without an engine, the +theme is required to implement its own version of hook_theme() to tell Drupal what it is implementing; themes utilizing an engine will have their well-named theming functions automatically registered for them+ While this can vary based upon the theme engine, the standard set by phptemplate is that theme functions should be named either phptemplate_HOOK or THEMENAME_HOOK+ For example, for Drupal's default theme (Garland) to implement the 'table' hook, the phptemplate.engine would find phptemplate_table() or garland_table() The ENGINE_HOOK() syntax is preferred, as this can be used by sub-themes (which are themes that share code but use different stylesheets) The theme system is described and defined in theme.inc+ *
Parameters:
  • text - The text to format (plain-text)
Returns:
The formatted text (html)
See Also:
,  

status_messages(display=None)

source code 
Return a themed set of status and/or error messages The messages are grouped by type
Parameters:
  • display - (optional) Set to 'status' or 'error' to display only messages of that type+ *
Returns:
A string containing the messages+

links(links, attributes={'class': 'links'})

source code 
Return a themed set of links+ *
Parameters:
  • links - A keyed array of links to be themed+ * @param attributes A keyed array of attributes
Returns:
A string containing an unordered list of links+

image(path, alt='', title='', attributes=None, getsize=True)

source code 
Return a themed image+ *
Parameters:
  • path - Either the path of the image file (relative to base_path()) or a full URL
  • alt - The alternative text for text-based browsers
  • title - The title text is displayed when the image is hovered in some popular browsers
  • attributes - Associative array of attributes to be placed in the img tag
  • getsize - If set to True, the image's dimension are fetched and added as width/height attributes
Returns:
A string containing the image tag+

breadcrumb(breadcrumb)

source code 
Return a themed breadcrumb trail+ *
Parameters:
  • breadcrumb - An array containing the breadcrumb links
Returns:
a string containing the breadcrumb output

help_()

source code 
Return a themed help message+ *
Returns:
a string containing the helptext for the current page+

submenu(links)

source code 
Return a themed submenu, typically displayed under the tabs+ *
Parameters:
  • links - An array of links+

table(header_, rows, attributes={}, caption=None, colgroups={})

source code 
Return a themed table.
Parameters:
  • php.header - An array containing the table headers. Each element of the array can be either a localized string or an associative array with the following keys: - "data": The localized title of the table column. - "field": The database field represented in the table column (required if user is to be able to sort on this column). - "sort": A default sort order for this column ("asc" or "desc"). - Any HTML attributes, such as "colspan", to apply to the column php.header cell.
  • rows - An array of table rows. Every row is an array of cells, or an associative array with the following keys: - "data": an array of cells - Any HTML attributes, such as "class", to apply to the table row. Each cell can be either a string or an associative array with the following keys: - "data": The string to display in the table cell. - "php.header": Indicates this cell is a php.header. - Any HTML attributes, such as "colspan", to apply to the table cell. Here's an example for rows:
  • attributes - An array of HTML attributes to apply to the table tag.
  • caption - A localized string to use for the
tag.
  • colgroups - An array of column groups. Each element of the array can be either: - An array of columns, each of which is an associative array of HTML attributes applied to the COL element. - An array of attributes applied to the COLGROUP element, which must include a "data" attribute. To add attributes to COL elements, set the "data" attribute with an array of columns, each of which is an associative array of HTML attributes. Here's an example for colgroup:
    • Returns:
    An HTML string representing the table.

    tablesort_indicator(style)

    		source code 
    Return a themed sort icon+ *
    Parameters:
    • style - Set to either asc or desc+ This sets which icon to show+
    Returns:
    A themed sort icon+

    box(title, content, region='main')

    		source code 
    Return a themed box+ *
    Parameters:
    • title - The subject of the box+
    • content - The content of the box+
    • region - The region in which the box is displayed+
    Returns:
    A string containing the box output+

    mark(type=1)

    		source code 
    Return a themed marker, useful for marking new or updated content+ *
    Parameters:
    • type - Number representing the marker type to display
    Returns:
    A string containing the marker+

    See Also:  

    item_list(items=[], title=None, type='ul', attributes=[])

    		source code 
    Return a themed list of items+ *
    Parameters:
    • items - An array of items to be displayed in the list+ If an item is a string, then it is used as is+ If an item is an array, then the "data" element of the array is used as the contents of the list item+ If an item is an array with a "children" element, those children are displayed in a nested list+ All other elements are treated as attributes of the list item element+
    • title - The title of the list+
    • attributes - The attributes applied to the list element+
    • type - The type of list to return (e.g+ "ul", "ol")
    Returns:
    A string containing the list output+

    xml_icon(url)

    		source code 
    Return code that emits an XML icon+ * For most use cases, this function has been superseded by theme_feed_icon()
    Parameters:
    • url - The url of the feed

    See Also:

    feed_icon(url, title)

    		source code 
    Return code that emits an feed icon+ *
    Parameters:
    • url - The url of the feed+ * @param title A descriptive title of the feed+

    more_link(url, title)

    		source code 
    Returns code that emits the 'more' link used on blocks+ *
    Parameters:
    • url - The url of the main page
    • title - A descriptive verb for the link, like 'Read more'

    closure(main_=0)

    		source code 
    Execute hook_footer() which is run at the end of the page right before the close of the body tag+ *
    Parameters:
    • main - (optional) Whether the current page is the front page of the site+ * @return A string containing the results of the hook_footer() calls+

    blocks(region)

    		source code 
    Return a set of blocks available for the current user+ *
    Parameters:
    • region - Which set of blocks to retrieve+ * @return A string containing the themed blocks for this region+

    username(object_)

    		source code 
    Format a username+ *
    Parameters:
    • object - The user object to format, usually returned from user_load()+ * @return A string containing an HTML link to the user's page if the passed object suggests that this is a site user+ Otherwise, only the username is returned

    progress_bar(percent, message)

    		source code 
    Return a themed progress bar+ *
    Parameters:
    • percent - The percentage of the progress+
    • message - A string containing information to be displayed+
    Returns:
    A themed HTML string representing the progress bar

    indentation(size=1)

    		source code 
    Create a standard indentation div+ Used for drag and drop tables+ *
    Parameters:
    • size - Optional+ The number of indentations to create+
    Returns:
    A string containing indentations+

    template_preprocess(variables_, hook)

    		source code 
    Adds a default set of helper variables for preprocess functions and templates+ This comes in before any other preprocess function which makes it possible to be used in default theme implementations (non-overriden theme functions)+

    template_preprocess_page(variables_)

    		source code 
    Process variables for page.tpl.php Most themes utilize their own copy of page.tpl.php+ The default is located inside "plugins/system/page.tpl.php"+ Look in there for the full list of variables+ * Uses the arg() function to generate a series of page template suggestions based on the current path+ * Any changes to variables in this preprocessor should also be changed inside template_preprocess_maintenance_page() to keep all them consistent+ * The variables array contains the following arguments: - content - show_blocks

    See Also: page.tpl.php

    template_preprocess_node(variables_)

    		source code 
    Process variables for node.tpl.php Most themes utilize their own copy of node.tpl.php+ The default is located inside "plugins/node/node.tpl.php"+ Look in there for the full list of variables+ * The variables array contains the following arguments: - node - teaser - page

    See Also: node.tpl.php

    template_preprocess_block(variables_)

    		source code 
    Process variables for block.tpl.php Prepare the values passed to the theme_block function to be passed into a pluggable template engine+ Uses block properties to generate a series of template file suggestions+ If none are found, the default block.tpl.php is used+ * Most themes utilize their own copy of block.tpl.php+ The default is located inside "plugins/system/block.tpl.php"+ Look in there for the full list of variables+ * The variables array contains the following arguments: - block

    See Also: block.tpl.php


       Home       Trees       Indices       Help   
    Generated by Epydoc 3.0.1 on Fri Sep 19 19:58:41 2008 http://epydoc.sourceforge.net