file Theme Registry

<!-- @file Overview of the theme registry workflow in Drupal Bootstrap. -->
<!-- @defgroup registry -->
# Theme Registry

- [File Structure](#file-structure)
- [Theme Functions](#theme-functions)
- [Theme Process and Preprocess Functions (.vars.php)](#theme-preprocess)
- [Theme Templates](#theme-templates)
- [Theme Hook Naming Conventions](#theme-hook-naming-conventions)

## File Structure
The [Drupal Bootstrap] base theme handles some very complex theme registry
alterations to assist with the organization and maintenance of its source code.

By leveraging Drupal's ability to include files only when a specific theme hook
is invoked, this base theme is able to reduce its per page PHP memory footprint.
It also allows for easier maintenance and organization with as many overrides as
this base theme implements.

This base theme provides a multitude of [pre]process functions, theme functions
and templates stored inside the `./bootstrap/templates` folder. The base
theme will traverse all folders inside this folder as well as a subtheme's
`./subtheme/templates` folder.

Over time this base theme has grown exponentially and this type of change will
help ensure future growth, without sacrificing performance. It's an easy and
hierarchical folder structure based on the module they originated from.

Sub-themes, while not required to do so, can emulate this same type of file
structure and take advantage of this base theme's unique ability.

Rest assured though, there is no need to structure your sub-theme this way. If
you feel more comfortable storing everything in your sub-theme's '`template.php`
file, feel free to do so.

It's highly recommended, however, that you at least understand how the base
theme structures its functions and templates so you can easily copy them over
to your sub-theme should the need arise.

## Theme Functions (.func.php) {#theme-functions}
Theme functions can be be stored in a dedicated file. These files should end in
a `.func.php` extension where the name of the file relates to the base "theme
hook" being invoked. For example: the theme hook `breadcrumb` is rendered by
the `bootstrap_breadcrumb()` theme function located in the
`./bootstrap/templates/system/breadcrumb.func.php` file.

{.help-block} See related sub-topic below for a list of functions.

## Theme Process and Preprocess Functions (.vars.php) {#theme-preprocess}
Theme process and preprocess functions can be stored in a dedicated file. These
files must end with a `.vars.php` extension where the name of the file relates
to the base "theme hook" being invoked.

For example: the theme hook `page` has both the process function
`bootstrap_process_page()` and the preprocess function
`bootstrap_preprocess_page()` which are located in the
`./bootstrap/templates/system/page.vars.php` file.

This file should also contain any helper functions that are specific to the
theme hook as well. If a function becomes too large, break it apart so it can
become more legible.

{.help-block} See related sub-topic below for a list of functions.

## Theme Templates (.tpl.php)  {#theme-templates}
Theme template files should end with a `.tpl.php` extension where the name of
the file relates to the base "theme hook" being invoked. For example: the
template for the theme hook `page` is located at
`./bootstrap/templates/system/page.tpl.php`.

{.help-block} See related sub-topic below for a list of templates.

## Theme Hook Naming Conventions
As a general rule, theme hooks must convert all underscores (`_`) to hyphens
(`-`) for the file name. This can sometimes be especially confusing for some at
first. Any time a file name has been changed, you must also rebuild the theme
registry. The easiest way to do this is to "Clear all caches" on the
`admin/config/development/performance` page.

The exception for this rule would be theme function (`.func.php`) and
\[pre\]process function (`.vars.php`) files. These file names should only be
named using the base theme hook (using the general rule).

Theme hook suggestions should not be used in the file name, but rather their
suggestion functions placed inside the base theme hook `.func.php` or
`.vars.php` file. An example of this would be the
`bootstrap_menu_tree__primary()` theme function where the base theme hook is
`menu_tree` (the hook name before `__`) and located in the
`./bootstrap/templates/menu/menu-tree.func.php` file.

[Drupal Bootstrap]: https://www.drupal.org/project/bootstrap