In this article, we’ll discuss how you can leverage various Drupal API functions to achieve more fine grained theming. We’ll cover template preprocessing and alter hooks using path patterns, types and args(). We’ll use the arg() function which returns parts of a current Drupal URL path and some pattern matching for instances when you want to match a pattern in a URL. We’ll also take a look at creating a variable for an array of content types.
Template preprocessing is a means to define variables for use within your page. For example, you can define a body class variable. In turn you can use the resulting class in your Sass or CSS. An alter or build hook is something that’s run before the page renders so you can do things such as adding JS or CSS to specific pages or content types.
I’ll explain and demonstrate these hooks and how you can use them to:
- Add a
<body>
class to a specific page for better theming - Add Javascript or CSS to specific pages and paths
- Use wildcard path arguments
- URL pattern matching using
preg_match
- Create an array of content types to use as a variable in your argument
- Using path arguments as parameters
The functions we discuss here will be added to your theme’s template.php file. Although you can also use these functions in a custom module, you’ll need to specify that the functions are not for admin pages unless that’s your intent, and I’ll cover how to do that.
Getting Started
When using preprocess or alter functions within your theme, you’ll want to be sure template.php exists but if not, you can go ahead and create this file in the root of your theme. So if my theme name is foobar, the path to template.php will be:
/sites/all/themes/foobar/template.php
API functions are prefaced by the machine name of your theme. For example, if you are using hook_page_alter
and your theme name is foobar, we’d write it as function foobar_page_alter()
. (The machine name is simply the theme’s folder name.)
Custom Body Classes Using a Content Types Array
A body class is a class that’s added to your HTML <body>
tag. For example, on a blog page, you might see something like this:
<body class="page-node page-node-blog">
You can leverage that class in your Sass or CSS to fine tune your theming by doing something like this just for blog pages on your site:
.page-node-blog h1 {
// custom Sass here
}
Out of the box, Drupal 7 comes with some pretty good body classes and usually these are fine for most use cases. In addition, Drupal contribution or Contrib themes such as Zen add enhanced and expanded classes.
In our case, we want to add a class to some pages which share some common attributes but may not necessarily derive from the same content type. Let’s say we have two content types that we want to add a specific class to in order to theme those alike but perhaps different from other pages on our website. We can build an array of Drupal content types we want to target and then use that array to add the class. Once we’ve defined the array, we just check to ensure that a given node exists and then pass the array in.
<?php
/**
* Implements template_preprocess_html().
*
* Define custom classes for theming.
*/
function foobar_preprocess_html(&$vars) {
// Build a node types array from our targeted content types.
$foo_types = array(
'landing_page',
'our_services',
);
// Define the node.
$node = menu_get_object();
// Use the array to add a class to those content types.
if (!empty($node) && in_array($node->type, $foo_types)) {
$vars['classes_array'][] = 'page-style-foobar';
}
}
This function preprocesses variables for anything that would typically be before the ending HTML </head>
tag which is in Drupal’s core template, html.tpl.php. We add the body class using $vars['classes_array']
. This variable gets rendered with <?php print $classes; ?>
in the <body>
tag. In our case, this class will only render in landing_page and our_services content types. Now we can use .page-style-foobar
in our Sass or CSS to style these pages.
URL Pattern Matching
You can also use URL pattern matching for adding useful custom classes. Let’s say we have an “Our Services” landing page and then some sub-pages under that path. The URL architecture might look like this:
example.com/our-services
- example.com/our-services/subpage-1
- example.com/our-services/subpage-2
We’ll add a custom body class to those pages using preg_match
, regex, PHP matches and Drupal’s request_uri
function. Once again, we’d put this in a foobar_preprocess_html
as above.
<?php
function foobar_preprocess_html(&$vars) {
// Define the URL path.
$path = request_uri();
// Add body classes to various pages for better theming.
if (preg_match('|^/our-services((?:/[a-zA-Z0-9_\-]*)*)?|', $path, $matches)) {
$vars['classes_array'][] = 'page-services';
}
}
Now you can use .page-services .some-common-element
for theming these “our-services” pages. Obviously this method has pitfalls if your URL structure changes so it may only fit some use cases.
Path Arguments
Another clever way of custom theming specific parts of your site is to partition those off using arg(). Drupal tends to get script and CSS heavy so ideally if you’re adding extra CSS or JS and you don’t need it for every page (which is normally done using your theme’s .info file), you can use path arg() to add these only to pages where they’re needed. For example, if I want to add a custom script to just the Drupal registration page, I can create a path arg() if statement and then add the script within that. The URL path we’ll focus on here is /user/register and you’ll see how the arg() breaks down the URL structure.
We’ll be using hook_page_alter
here which can apply alterations to a page before it’s rendered. First we define the theme path and use Drupal’s attached function.
<?php
/**
* Implements hook_page_alter().
*
* Add custom functions such as adding js or css.
*/
function foobar_page_alter(&$page, $form) {
// Define the module path for use below.
$theme_path = drupal_get_path('theme', 'foobar');
if (arg(0) == "user" && arg(1) == "register") {
$foobar_js = array(
'#attached' => array(
'js' => array(
$theme_path . '/js/custom.js' => array(
'group' => JS_THEME,
),
),
),
);
drupal_render($foobar_js);
}
}
In this function, note that we’ve substituted our theme name for hook so hook_page_alter
becomes foobar_page_alter
. The arg() number signifies the position in the URL path. Zero is first, one is second and so on. You can get pretty creative with these adding more parameters. Let’s say you wanted to add JS to just the user page but no paths underneath it. You could add a NULL arg() after the initial arg().
if (arg(0) == "user" && arg(1) == NULL) {
// code here
}
In the examples above, we’ve implemented various functions in our theme’s template.php file. You can also use these in a custom module as well and in that case you’d just preface your module name in the function rather than the theme name. When theming from a module, you’ll probably want to exclude admin paths since a module can target anywhere in your site. You can do that excluding admin paths.
if (!path_is_admin(current_path())) {
// code here
}
Conclusion
As you can see, leveraging the Drupal API Toolbox for theming extends your reach as a developer. The examples above are not definitive but they do give you a feel for what’s possible. As a Drupal Themer, using these has helped me expand my bag of tricks when theming and building a site. Comments? Feedback? Leave them below!