1 |
caf16a48
|
Assos Assos
|
<!-- @file Overview of the theme registry workflow in Drupal Bootstrap. -->
|
2 |
|
|
<!-- @defgroup registry -->
|
3 |
|
|
# Theme Registry
|
4 |
|
|
|
5 |
|
|
- [File Structure](#file-structure)
|
6 |
|
|
- [Theme Functions](#theme-functions)
|
7 |
|
|
- [Theme Process and Preprocess Functions (.vars.php)](#theme-preprocess)
|
8 |
|
|
- [Theme Templates](#theme-templates)
|
9 |
|
|
- [Theme Hook Naming Conventions](#theme-hook-naming-conventions)
|
10 |
|
|
|
11 |
|
|
## File Structure
|
12 |
|
|
The [Drupal Bootstrap] base theme handles some very complex theme registry
|
13 |
|
|
alterations to assist with the organization and maintenance of its source code.
|
14 |
|
|
|
15 |
|
|
By leveraging Drupal's ability to include files only when a specific theme hook
|
16 |
|
|
is invoked, this base theme is able to reduce its per page PHP memory footprint.
|
17 |
|
|
It also allows for easier maintenance and organization with as many overrides as
|
18 |
|
|
this base theme implements.
|
19 |
|
|
|
20 |
|
|
This base theme provides a multitude of [pre]process functions, theme functions
|
21 |
|
|
and templates stored inside the `./bootstrap/templates` folder. The base
|
22 |
|
|
theme will traverse all folders inside this folder as well as a subtheme's
|
23 |
|
|
`./subtheme/templates` folder.
|
24 |
|
|
|
25 |
|
|
Over time this base theme has grown exponentially and this type of change will
|
26 |
|
|
help ensure future growth, without sacrificing performance. It's an easy and
|
27 |
|
|
hierarchical folder structure based on the module they originated from.
|
28 |
|
|
|
29 |
|
|
Sub-themes, while not required to do so, can emulate this same type of file
|
30 |
|
|
structure and take advantage of this base theme's unique ability.
|
31 |
|
|
|
32 |
|
|
Rest assured though, there is no need to structure your sub-theme this way. If
|
33 |
|
|
you feel more comfortable storing everything in your sub-theme's '`template.php`
|
34 |
|
|
file, feel free to do so.
|
35 |
|
|
|
36 |
|
|
It's highly recommended, however, that you at least understand how the base
|
37 |
|
|
theme structures its functions and templates so you can easily copy them over
|
38 |
|
|
to your sub-theme should the need arise.
|
39 |
|
|
|
40 |
|
|
## Theme Functions (.func.php) {#theme-functions}
|
41 |
|
|
Theme functions can be be stored in a dedicated file. These files should end in
|
42 |
|
|
a `.func.php` extension where the name of the file relates to the base "theme
|
43 |
|
|
hook" being invoked. For example: the theme hook `breadcrumb` is rendered by
|
44 |
|
|
the `bootstrap_breadcrumb()` theme function located in the
|
45 |
|
|
`./bootstrap/templates/system/breadcrumb.func.php` file.
|
46 |
|
|
|
47 |
|
|
{.help-block} See related sub-topic below for a list of functions.
|
48 |
|
|
|
49 |
|
|
## Theme Process and Preprocess Functions (.vars.php) {#theme-preprocess}
|
50 |
|
|
Theme process and preprocess functions can be stored in a dedicated file. These
|
51 |
|
|
files must end with a `.vars.php` extension where the name of the file relates
|
52 |
|
|
to the base "theme hook" being invoked.
|
53 |
|
|
|
54 |
|
|
For example: the theme hook `page` has both the process function
|
55 |
eefc2ac0
|
Assos Assos
|
`bootstrap_process_page()` and the preprocess function
|
56 |
|
|
`bootstrap_preprocess_page()` which are located in the
|
57 |
|
|
`./bootstrap/templates/system/page.vars.php` file.
|
58 |
caf16a48
|
Assos Assos
|
|
59 |
|
|
This file should also contain any helper functions that are specific to the
|
60 |
|
|
theme hook as well. If a function becomes too large, break it apart so it can
|
61 |
|
|
become more legible.
|
62 |
|
|
|
63 |
|
|
{.help-block} See related sub-topic below for a list of functions.
|
64 |
|
|
|
65 |
|
|
## Theme Templates (.tpl.php) {#theme-templates}
|
66 |
|
|
Theme template files should end with a `.tpl.php` extension where the name of
|
67 |
|
|
the file relates to the base "theme hook" being invoked. For example: the
|
68 |
|
|
template for the theme hook `page` is located at
|
69 |
|
|
`./bootstrap/templates/system/page.tpl.php`.
|
70 |
|
|
|
71 |
|
|
{.help-block} See related sub-topic below for a list of templates.
|
72 |
|
|
|
73 |
|
|
## Theme Hook Naming Conventions
|
74 |
|
|
As a general rule, theme hooks must convert all underscores (`_`) to hyphens
|
75 |
|
|
(`-`) for the file name. This can sometimes be especially confusing for some at
|
76 |
|
|
first. Any time a file name has been changed, you must also rebuild the theme
|
77 |
|
|
registry. The easiest way to do this is to "Clear all caches" on the
|
78 |
|
|
`admin/config/development/performance` page.
|
79 |
|
|
|
80 |
|
|
The exception for this rule would be theme function (`.func.php`) and
|
81 |
|
|
\[pre\]process function (`.vars.php`) files. These file names should only be
|
82 |
|
|
named using the base theme hook (using the general rule).
|
83 |
|
|
|
84 |
|
|
Theme hook suggestions should not be used in the file name, but rather their
|
85 |
eefc2ac0
|
Assos Assos
|
suggestion functions placed inside the base theme hook `.func.php` or
|
86 |
|
|
`.vars.php` file. An example of this would be the
|
87 |
|
|
`bootstrap_menu_tree__primary()` theme function where the base theme hook is
|
88 |
|
|
`menu_tree` (the hook name before `__`) and located in the
|
89 |
|
|
`./bootstrap/templates/menu/menu-tree.func.php` file.
|
90 |
caf16a48
|
Assos Assos
|
|
91 |
|
|
[Drupal Bootstrap]: https://www.drupal.org/project/bootstrap |