The default taxonomy term page provided by Drupal leaves much to be desired. If a taxonomy vocabulary has multiple levels, but content is only tagged with only the child term and not the parent, parent term pages are left with no content listed on them, despite the fact that there is content tagged with terms below it.
In this lesson...
- Create a taxonomy vocabulary with two levels of hierarchy
- Enable the Taxonomy Term Template
- Build a custom term page for each level of hierarchy
By the end of this lesson, you'll know how to create better taxonomy term pages using Views, contextual filters, and Panels.
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
With mini-panels, you can build portable panels components and place them as blocks in regions of your theme.
In this lesson...
- Build a 3-column mini-panel
- Place a menu in each column
- Place the mini-panel in the footer region as a block
By the end of this lesson, you will be able to build a mini-panel and understand how to place it in a region using the block administration page.
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
Panel Nodes module comes packaged with Panels and provides a new content type called Panel.
In this lesson...
- Enable Panel Nodes module
- Create a new node using Panel content type
- Build a simple multi-column page
By the end of this lesson, you will understand the basic functionality of Panel Nodes and why you may or may not want to use it to build one-off pages on your site.
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
Panelizer is a powerful module that allows you to attach panels to any entity and view mode in Drupal. You can create default templates for all content in a content type, for example, or you can create one-off pages with unique layouts and content panes.
In this lesson...
- Walk through Panelizer admin UI
- Panelize Article content
- Set up default Panelizer template
- Override versus Update Default Template
By the end of this lesson, you should be able to configure Panelizer settings, enable Panelizer for a content type, and understand the benefits and limitations of creating one-off pages that override the default template versus updating the default template.
Enabling the Panels In-Place Editor is recommended for this lesson.
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
You can create your Panels layouts with HTML and CSS that can then be selected in the Panels UI.
In this lesson...
- Create a two-column, 60/40 layout
- Use existing layout to quickly get started
- Apply new layout to custom home page
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
Creating pages with Panels involves a lot of configuration which can take a lot of time and effort. In order to avoid re-doing all that work on another instance of the site, we can export this configuration into code using Features and deploy it in the usual way (using git or FTP).
In this lesson, we will:
- Export a custom panels page
- Take inventory of all panes
- Create a new Feature to export configuration
By the end of this lesson, you will be able to export a basic panel page configuration that contains a View using Features.
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
Panelizer configuration involves several layers of configuration. It can be challenging to find all the corners of configuration to export, without needing to still perform some extra manual steps after deployment. With Strongarm module, we can export the related settings that make Panelizer work, avoiding the need for extra manual steps.
In this lesson, we will:
- Enable Strongarm module
- Create new feature
- Export and Deploy Panelizer settings
By the end of this lesson, you should understand how to export all of Panelizer's settings plus the related settings that support its functionality.
Demo site log in:
- Navigate to /user
- Login with admin/admin
Additional resources
Panels provides export code that you can copy and paste into a module or directly import into another instance of the site.
In this lesson, we will:
- Export a panels page using Panels UI
- Import a panels page into another instance of site
By the end of this lesson, you will understand where to find the export code for a panel and be able to simply and quickly import it into another copy of your site.
Demo site log in:
- Navigate to /user
- Login with admin/admin
A CTools Style Plugin allows a developer to provide a settings form and a template file that can be chosen and configured by a site administrator using the Panels "Style" interface.
In this lesson, we will:
- Explore Panels' Style Interface
- Identify Default Panels Styles
- Introduce Demo Style Plugin
By the end of this lesson, you will understand how to access Styles in Panels and why you might want to create your own custom Styles interface for your site's editors to use.
Additional resources
The code for this plugin and module is located in sites/all/modules/demo_panestyles. See Companion Files to download the Files export, which also contains a demo site for Lessons 8-19 of Building Websites in Drupal 7 with Panels. Log in at /user with username "admin" and password "admin."
Before we dive into the code of the module and plugins, let's set up the files and directories in a meaningful structure that's both scalable and one that will ensure that our plugin is disoverable by the CTools API.
In this lesson, we will:
- Create module files and directories
- Create plugin files and directories
By the end of this lesson, you will have all of the files created with a proper structure, ready for editing.
Additional resources
The code for this plugin and module is located in sites/all/modules/demo_panestyles. See Companion Files to download the Files export, which also contains a demo site for Lessons 8-19 of Building Websites in Drupal 7 with Panels. Log in at /user with username "admin" and password "admin."
The sole purpose of our custom module is to implement a hook that will tell the CTools API that we have a plugin. Next, in our plugin's ".inc" file, we'll walk through the extensive $plugin array, understanding how the keys and values of this array correspond to functions and parameters inside the plugin.
In this lesson, we will:
- Hook into CTools inside custom module
- Explore
$pluginarray
By the end of this lesson, you should be able to implement the correct hook for CTools and understand how to customize your own $plugin array.
Additional resources
The code for this plugin and module is located in sites/all/modules/demo_panestyles. See Companion Files to download the Files export, which also contains a demo site for Lessons 8-19 of Building Websites in Drupal 7 with Panels. Log in at /user with username "admin" and password "admin."
In order to print out the pane title and settings form values as class names in our pane template file, we need to thread the pane object and settings array through a theme function so that they will be available to print out in our pane's template file.
In this lesson, we will:
- Walk through the pane theme function
By the end of this lesson, you should be able to implement a theme function for a panel pane.
Additional resources
The code for this plugin and module is located in sites/all/modules/demo_panestyles. See Companion Files to download the Files export, which also contains a demo site for Lessons 8-19 of Building Websites in Drupal 7 with Panels. Log in at /user with username "admin" and password "admin."
The selling point of a CTools Style Plugin is the settings form. By providing a settings form to the site editor who can then change the style of the page using a pre-approved set of styles, you can both empower and provide appropriate constraints.
In this lesson, we will:
- Use the Form API
- Build a Styles Settings Form
By the end of this lesson, you should be able to build a settings form for your CTools Style Plugin.
Additional resources
The code for this plugin and module is located in sites/all/modules/demo_panestyles. See Companion Files to download the Files export, which also contains a demo site for Lessons 8-19 of Building Websites in Drupal 7 with Panels. Log in at /user with username "admin" and password "admin."
Now we have all the code in place for both our custom module and our style plugin. It's time to put it all together into our pane template file.
In this lesson...
- Connect values from settings form to template file
- Utilize values from pane object
- Utilize values from submitted settings form
All the code for the module and plugin is contained in the Resources section of this lesson. It's now your turn to create your own CTools Style Plugin!
Additional resources
The code for this plugin and module is located in sites/all/modules/demo_panestyles. See Companion Files to download the Files export, which also contains a demo site for Lessons 8-19 of Building Websites in Drupal 7 with Panels. Log in at /user with username "admin" and password "admin."
Tokens are simple strings of text that serve as placeholders for a dynamic value. This is such a common task for modules that, rather than have every module developer reinvent the wheel, Drupal's token API allows for this kind of placeholder replacement using a unified syntax and a set of hooks and functions, which we'll cover throughout the series.
This video gives an overview of the six lessons in this series, from background to a sample installation of modules we’ll need, implementing tokens using hooks, and looking at the relationships between core and token modules.
After watching this series, you should have a firm grasp on the Drupal token API and be able to use it in your own custom modules in order to provide your users with static placeholder tokens that can be replaced with a dynamically calculated value.
Additional resources
There just a couple of components that make up the token system in Drupal 7, which is nice because it means fewer new things we have to learn. But, it's important to understand what those components are and some of the fundamentals of how tokens work in order to make the most of Drupal's Token API. In this lesson we'll take a look the use case for tokens, talk about token types, and the concept of global tokens vs. those that require some additional context in order to have their dynamic values calculated.
What are tokens?
Tokens are specially formatted chunks of text that serve as placeholders for a dynamically generated value. Here's a really simple example: You want to display a welcome message to user's of your site, and you want it to be personalized so how about you add their name and instead of just saying "Welcome", you can say "Welcome, Joe". In order to avoid having to hard-code a welcome string for every single user of the site it would be nice to dynamically generate the string. So you use a one like the following, "Welcome, [current-user:name]".
The [current-user:name] here is what Drupal refers to as a token. A string of static text that will be located and replaced with a dynamic value. This token is made up of a few parts, inside of the mandatory square brackets that signify that this is a token. The first part current-user: in this case is the token type.
Token types are used to group like things together into a namespace. User's for example have name, mail, and last-login properties. Nodes have title, nid, and author properties. Token type also plays an important role in determining what tokens are available in what context. User tokens for example might be available when sending an email to a specific user but node type tokens might be irrelevant in this use case. We need to be able to tell end user's what types of tokens can be used in what context so that they don't use a node token (which has no value) in a user context.
The second part, after the colon (:) is the token itself. This signifies what value will be substituted into the string containing the token. :name in this case indicates we want the current user's username. This also brings up another important point. Global vs. contextual tokens. Some tokens like this one [system:date] can be calculated without any additional information. Simply call the PHP date function and you've got a value. This token [current-user:name], on the other hand, requires knowledge about the currently logged-in user in order to be able to determine that user's name. This token requires additional context in order to be useful.
Additional resources
Before we can get started creating our own tokens we'll need a basic Drupal site setup and module to start from. This lesson will walk through the prerequisites for the rest of the series including having Drupal installed, downloading and installing the databasics module, creation of some dummy content, and a quick tour of what the module does.
In order to follow along in this series you'll want to have a copy of Drupal 7 installed. If you need a refresher on installing Drupal check out this series on getting up and running with Drupal 7.
Once you've got Drupal 7 installed you'll want to download and install a copy of the databasics module that was created as part of the Drupal 7 module development series. We'll use this as a starting point for adding custom tokens so that we have some new data to play with. You can grab a copy of the files attached to this page.
Finally, we'll create some dummy content on our site and walk through what the databasics module does and talk about the problem we're trying to solve.
The databasics module has a string of text that's displayed at the bottom of each node that displays some dynamic information. We would like this text to be configurable by an administrator, so we'll add some new tokens and then update both the form where text is entered and the code that displays the text to allow for use of the newly created tokens.
Additional resources
The first of two steps required to add new tokens to Drupal 7 is implementing hook_token_info() in order to give Drupal a list of the placeholders your module provides. Placeholders can be grouped together by creating a new token type and placing new tokens under that grouping or by adding new tokens to an existing token type provided by another module like the node module. Token types can be defined as global meaning their value can be calculated without any additional context, or as 'needs-data' tokens that require additional information about the context in which they are being used in order to calculate their value. For example, a [node:title] token needs to know which node is being referenced, whereas a [system:date] token doesn't need any additional reference to calculate the current date. In this lesson we will be adding the following token types:
[databasics-totals]- For tokens that can be calculated without any additional context.[databasics-page]- For tokens that require additional context in order to be rendered. In this case, they need to know which page is currently being viewed and are thus only useful in the context of viewing a page.
And these tokens:
[databasics-totals:count]- Total page views for the entire site.[databasics-page:view-count]- Number of times the current page has been viewed by the current user..[databasics-page:last-viewed]- Date the current page was last viewed..
We use hook_token_info() to provide Drupal with information about available placeholder tokens and their types. Here's an example hook_token_info() implementation:
/**
* Implements hook_token_info().
*/
function databasics_token_info() {
$info = array();
$info['types'] = array(
'databasics-totals' => array(
'name' => t('Databasics totals'),
'description' => t('Global databasics tokens.'),
),
// [databasics-page:]
'databasics-page' => array(
'name' => t('Databasics'),
'description' => t('Tokens for databasics page counts.'),
'needs-data' => array('databasics_record'),
),
);
$info['tokens'] = array(
'databasics-totals' => array(
// [databasics-totals:count]
'count' => array(
'name' => t('Total page views'),
'description' => t('Total page views for entire site.'),
),
),
// Page specific tokens.
'databasics-page' => array(
// Add a token for the view count.
// [databasics-page:view-count]
'view-count' => array(
'name' => t('View count'),
'description' => t('Number of times the page has been viewed by the current user.'),
),
// [databasics-page:last-viewed]
'last-viewed' => array(
'name' => t('Last viewed'),
'description' => t('Date the page was last viewed.'),
),
),
);
// [node:view-count], [node:view-count:last-viewed]
$info['tokens']['node'] = array(
'view-count' => array(
'name' => t('View count'),
'description' => t('Number of times the current node has been viewed by the current user.'),
'type' => 'databasics-page',
),
);
return $info;
}
Additional resources
Note: In the video, around 9:30, we added at the :uid argument to the query, but did not add the corresponding portion to the WHERE clause of the query. The final query should look like the one in the code sample below.
Now that we've got placeholder tokens that we can enter into a string of text we need to provide the actual values that should be used to replace those placeholders. In this lesson we'll implement hook_tokens() in order to provide the Drupal Token API with the values that correspond to the placeholders our module provides.
Implementations of hook_tokens() are called once for every token type that's in scope for the current string that's being processed. So, one for all user tokens, once for all node tokens, and once for all global tokens. Each time the hook is passed an array which contains all the tokens of that specific type that where found in the string being processed as well as any additional contextual information such as the current $user or $node object.
hook_tokens() is expected to return an array of values for each of the tokens in question that your module is responsible for. In our case, since we added the [databasics-page:*] and [databasics-totals:*] tokens we're responsible for calculating and returning their value whenever they are requested.
We'll also look at using the token_find_with_prefix() function which will allow us to detect and provide values for any chained tokens. Like for example [node:view-count:last-viewed].
Example:
/**
* Implements hook_tokens().
*/
function databasics_tokens($type, $tokens, array $data = array(), array $options = array()) {
$replacements = array();
if ($type == 'databasics-totals') {
foreach($tokens as $name => $original) {
switch($name) {
case 'count':
$count = db_query('SELECT SUM(view_count) FROM {databasics}')->fetchField();
$replacements[$original] = $count;
break;
}
}
}
if ($type == 'databasics-page' && !empty($data['databasics_record'])) {
$record = $data['databasics_record'];
foreach ($tokens as $name => $original) {
switch ($name) {
case 'view-count':
$replacements[$original] = $record->view_count;
break;
case 'last-viewed':
$replacements[$original] = $record->last_viewed;
break;
}
}
}
if ($type == 'node' && isset($tokens['view-count']) && !empty($data['node'])) {
$node = $data['node'];
global $user;
$count = db_query('SELECT SUM(view_count) FROM {databasics} WHERE nid = :nid AND uid = :uid', array(':nid' => $node->nid, ':uid' => $user->uid))->fetchField();
$replacements[$tokens['view-count']] = $count;
// [node:view-count:last-viewed]
if ($count_tokens = token_find_with_prefix($tokens, 'view-count')) {
$record = databasics_get_record($node->nid, $user->uid);
$replacements += token_generate('databasics-page', $count_tokens, array('databasics_record' => $record), $options);
}
}
return $replacements;
}