Drupal Multimedia: Create media-rich Drupal sites by learning to embed and manipulate images, video, and audio

Most content in Drupal is stored in the form of nodes. In general, if you are new to the concept, you can begin by thinking of a node as what would normally be thought of as a blog, post, or article in more static sites. The reality is that nodes can be far more complex yet flexible than this and may be extended in novel ways, as we'll explore throughout this book:

All nodes have an associated node type. This can be defined by a module such as the built-in page and blog types, contributed image, or video node types. In addition, using Content Construction Kit (CCK), you may define your own custom types and store specific information based on the needs of your site. We will explore this soon.

The basic node will have a title and a body. In general, the body will store the text, although it can be used to display multimedia in line with the text. Modules may allow other types of data known as fields, which may display a set type of multimedia in a specific place in the content, for instance. In addition, some modules such as Image attach may allow multimedia or other data to be attached to any node type.

Nodes are usually displayed in one of these three ways: as teasers, as full pages, and in views. There may be other ways of displaying node content, especially when writing custom code, but we will explore these options, which should suffice in most of the cases.

Teasers are generally smaller or shorter versions of the full content. For instance, a teaser might display the first paragraph or two with a thumbnail. On a basic default Drupal installation, once you have created some nodes, you will see an example of teasers on the front page of the site. By theming, developers may alter how a teaser is displayed.

All nodes may be viewed in full at their respective node pages, usually accessed by clicking on the title of a teaser. By default, this will display all the data stored in a node, although that may be overridden or altered in any of several ways.

The Views module (touched upon later in this chapter) opens up many new ways of displaying information from nodes. Views may display nodes as teasers, full views, or slide shows, or may take specific parts of the data and display them in a list or

a table. There are many other ways a view can display content and we will explore the more common methods in this book.

A page is divided into several regions, each of which can be used to display content using blocks. By default, the main content of a page is displayed in the content region.For instance, the node content when displaying a node's page or the listing of recently published and promoted nodes on the front page. The left sidebar on a default Drupal installation is another region, as are the header, footer, and right sidebar.

You may determine what content will be displayed in what regions on the Blocks administration page by browsing to Administer | Site Building | Blocks (at /admin/build/block). Active blocks are shown here grouped by region, with the remainder shown in the Disabled section of the page.

After setting a block into a region, you can further determine its placement in the region by dragging and dropping it. Finally, by clicking on the configure link next to a block, you may change block-specific settings such as controlling what pages a block will be displayed on, or changing the block's title:

Drupal and installed modules will define many useful blocks of information such as a listing of users who are currently online (Who's Online), or the main Navigation menu. You may create custom blocks (using the Add block tab on the Blocks administration page) where you can add static text or even a short PHP script (assuming you've enabled the PHP filter module) for something dynamic. Using the Views module, you may also create blocks listing nodes that are filtered and sorted by your own criteria.

Most developers will want to format the content of their site in a manner that is different from what comes out-of-the-box. We will cover some of these methods in detail throughout the book. This is referred to as "theming", and many Drupal developers specialize as themers.

As an administrator, you may have noticed the theme section of the site. At Administer | Site building | Themes (at /admin/build/themes), you will see several themes that are available. These may be themes that are included with Drupal, contributed themes available from Drupal.org or other sources, and/or custom themes created specifically for the site:

It is this third possibility of custom themes that will be of most interest to us during the course of this book. So we will need to know the basics of overriding a theme. If you are interested in learning the theming techniques that will be covered, you

should probably have a custom theme to play with. For most of the examples in this book, we'll modify a copy of the Garland theme that comes shipped with Drupal and is enabled by default.

We will make much use of the various contributed modules throughout this book. Some of these modules, such as Image and Embedded Media Field, are specialized enough to be covered in their relevant sections. Others, such as the Content and Views modules, are essential throughout several sections. We will examine them in this chapter and explore them in more detail as needed later.

One of the strengths of Drupal is its expandability using contributed modules, and no single book could fully cover more than what many might consider the most essential, let alone the hundreds of currently available modules. This is especially so because new modules are constantly being added and old modules updated.

The modules presented in this book have been selected based on their relevance to the required tasks, their code stability, and high level of support and maintenance. All of these modules are used in production to power sites that may be small or large, and have sometimes dozens or hundreds of volunteers actively troubleshooting and maintaining them.

As you continue to explore the world of Drupal, make certain to continuously examine the available contributed modules. You can find nearly all of them at http://drupal.org/project. You can further find ongoing discussions of the development and use of the modules at http://groups.drupal.org/ in various discussion groups.

Now you will be able to create your own custom content types. Continuing with the example of an Article type, you would browse to Administer | Content management | Content types | Add content type (at /admin/content/types/add) and fill in the appropriate fields on that page. After submitting, you would have a new content type with a title and an optional body:

The strength of CCK is that it allows custom fields to be defined and added to the content types. Fields allow you to add any additional information to a type such as subtitles, images, and videos. Some basic fields, such as text and numbers, are included with the module. But others, such as images and files, require additional contributed modules.

To add fields, you will need to click on the add field link next to the new type on the resulting page from our ongoing example:

In this example, that would bring you to /admin/content/node-type/article/add_field). You'll name the field, select the type of field such as text or image, and submit the page to see the configuration page for the field. Here you can further define things such as setting a maximum image resolution or allowed values. In this example, we'll create a text field named Subtitle:

The resulting page contains sections that will affect the specific field. Additionally, because created fields can be shared among content types, you can further define settings that will affect all similarly shared fields.

Once a field has been created, you may change the order of its display by dragging the icon to the left of the field on the resulting page, which you can also find by browsing to Administer | Content management | Article | Manage fields (at admin/content/node-type/article/fields ):

We can define permissions for our users, who can be grouped by roles. For instance, we might have an edit role, whose users are able to create article content. First, we'll define a new role by going to Administer | User management | Roles (at /admin/user/roles ):

You would then visit the User Permissions settings browsing to Administer | User management | Permissions (at /admin/user/permissions), where you can set permissions for various roles such as allowing editors to create article content. You will see the permissions for all content types under the node module section of the form.

To give a user the new role, we would then need to edit his or her user account. We can find a list of recent users at Administer | User management | Users (at admin/user/user), where we can edit them:

Once you have created a new content type and set its permissions, you may create new content of that type by browsing to Create content and clicking on the new type (in this case at /node/add/article ):

As with the Content module (and all other contributed modules), you will need to first upload the module directory into the /sites/all/modules folder. The Views module is available at http://drupal.org/project/views. Once present, you will activate it at Administer | Site building | Modules (at /admin/build/modules). On that page, you'll note that several other related modules are also available in the Views package. For the examples in this book, you will need at a minimum to activate Views and Views UI.

When you browse to Administer | Site building | Administer views (at /admin/build/views), you will see the system default views interspersed with any custom views you've created:

You can easily create a new view from scratch by clicking on the Add tab, which brings you to /admin/build/views/add. However, for this example, we're going to clone an existing view so that we can see how they're set up while building it.

Click on the Enable link to the far right of the frontpage view. This enables the view on your site. Then click on the Clone link associated with that view, which will show you how the front page is created by default. You will be brought to the Clone view frontpage page (at /admin/build/views/clone/frontpage ):

On the resultant screen, you'll be able to change the name and description of your new view and the tag, if desired. Although you can't change the type when cloning a view, when creating a view from scratch, you'll be able to select one of many View types such as Node, Comment, or User. This means you can create a view that is a listing of users just as easily as a listing of nodes or comments.

Change the name to articles_recent and describe the view appropriately. If you like, you can change the View tag to articles, to make sorting views easier in the future. Then click Next:

On the left of the configuration screen, you'll see drawers for Defaults, Page, Feed, and some form elements to add new displays and analyze our view. By clicking on each drawer in turn you'll be able to see the different displays for our view, each of which can override the defaults to format a view in a specific way.

TheBasic settings section controls things such as the Title displayed for the view, the Style to display the data, for example, a List or Table, the number of Items per page, who can Access a particular view, and similar items. We'll leave these alone for now.

Using the Filters section on the right, we can specify which nodes will be returned for our view. In this particular case, we want to filter nodes by their type, as we only want to display the Article nodes we created earlier:

Press the "+" button next to Filters to add a new filter. This will show all available filters. We can select Node from the Groups selector to make it easier to find the Node: Type box, which we will select before pressing Add.

The section will be replaced with further options to specify how to filter the view. We will select our Article type and press Update here:

Next, click on the link for Node: Promoted to front page and then press the Remove button, as we want this view to retrieve all articles, regardless of whether they have been promoted.

Finally, change the title (in the Basic settings) to Articles by clicking on None, entering the new title in the new text field below, and pressing Update.

Now we'll set up the page. Click on the Page drawer to the left, just below Defaults. This section will determine how the view is selected and displayed as a page, in this case from /frontpage, as seen in the Page settings section:

Click on frontpage next to Path within Page settings, and change the path to articles. After you press Update, do the same for the feed by visiting the Feed drawer and changing the path from rss.xml to articles/rss.xml:

Then you can select Block from the selector above Add display, and press that button. This will create a new display for the view similar to Page and Feed. The only changes we need to make there are to set it to four items per page, rather than the default of 10, add a More link (which will allow users to click through to the page when there are more than four items), and to turn off the pager.

When doing each of these, we'll need to override the default values by clicking on the Override button that will appear in the information area (which will add the message Status: using overridden values above that area).

You may then Save the view, so we can see the results.

The Arguments fieldset is used to create some flexibility from the URL. Thus, by setting the arguments here, you might have a gallery of all recently posted videos with a URL of /videos, and further display of only videos in a certain vocabulary with /videos/[vocabulary-id], and finally only videos in a certain taxonomy term with /videos/[vocabulary-id]/[term-id]. Note that if there are Arguments set for the view, then those will be combined with Filters when selecting the nodes to display.

It is certainly possible and sometimes preferable to start a new theme from scratch. However, for this book, we'll modify an existing theme to give ourselves a jumpstart.

From your FTP client, you'll need to make a copy of the Garland theme directory. You'll need to copy the entire Garland directory from /themes/garland to /sites/all/themes. Then rename the new Garland directory, for example to mytheme. This folder name will be used as the machine name of your new theme.

If you don't already have a themes directory in /sites/all, you'll need to make one first. When checking for themes, Drupal will look in the appropriate site directory such as /sites/example.com/themes. Then it will look in /sites/all/themes, and finally in the root /themes directory.

By placing contributed, custom, and overridden themes in the /sites directory, you can accomplish several things. First, it will override a theme in the root /themes directory. Secondly, if it is placed in /sites/all/themes, it will be made available to sites sharing the same codebase. (Conversely, it will only show up for a specific site if it isin something like /sites/example.com/themes.) Finally, it will be easier to update the site as Drupal evolves, since you will be able to simply update to a later version of Drupal without worrying about theme overrides in the root directory.

You will also need to change the garland.info file to mytheme.info (or whatever name you have chosen). Also, edit that file and change the line that reads name = Garland to read something like name = My Theme. (You will not have a .info file for your theme in Drupal 5, so this will not apply in that case.)

After creating your new folder and making the necessary changes, you will browse to Administer | Site Building | Themes (at /admin/build/themes) on your site and enable the theme. You will also make the theme the default and disable the other themes. However, you may wish to keep another theme (such as the original Garland) as the default theme during the development and instead set the new theme on your user account edit page.

Finally, you may wish to keep a different theme layout for administration pages, particularly if your theme will not lend itself to the wide tables sometimes seen on those pages. In that case, you will browse to the Administration theme settings page at Administer | Site Configuration | Administration theme (at /admin/settings/admin) and set it to something basic like Garland.

Once you have enabled your new theme, you'll be ready to begin development on it. This is largely achieved by writing template files, which are contained in the theme directory and end with .tpl.php in their filenames. We will cover the basics of this in the template files section of this chapter, and in more detail throughout the book.

By default, Drupal uses PHPTemplate to power its themes. This flexible and powerful engine allows themers to wrap specific content in HTML snippets contained in specific files and functions. Themers can do all their work without knowing how to program, but if they are willing to explore the world of PHP, they have all the power of that scripting language to bring to bear on their themes.

At its most basic, a theme will contain a page.tpl.php file. This file will wrap all the content to be displayed in the required HTML tags to feed to the user's browser. Several PHP variables are made available for theming, which generally contain either content to be displayed or directives to tell us how to display content.

Also, a theme folder will contain one or more stylesheets such as Garland's style.css, which is the basic stylesheet to be used by that theme. The theme's .info file will contain a list of stylesheets to be included on a page. We will explore Cascading Style Sheets (CSS), which are necessary to control the output of our media.

Nodes are generally displayed using special template files in the themes folder. In addition to the default node.tpl.php, each node type may have its own template file, which will be used to wrap node content when provided. These are named by appending the node's machine-readable name to the filename. For instance, we might have a node-image.tpl.php file to wrap Image nodes, node-external_video.tpl.php for a custom External Video node type, and node-article.tpl.php for the Article content type we created earlier.

The template.php file contains functions made available to the theme, many of which are used to provide files to override the default theme functions offered by Drupal modules. This is an important concept that will be explained soon.

Other template files may be created in this folder to override how content is displayed. For instance, block.tpl.php and comment.tpl.php will respectively wrap blocks and comments with HTML. Any theme function available in Drupal may be overridden in this fashion, although some more obscure functions will require more of an understanding on how content is created in Drupal. Fortunately, there are tools available such as the Theme Developer Module (which we'll see in Images for Themers, chapter 4) to make this task easier.

So you've created a new theme as outlined in the Themes section earlier. You've explored the files there, and are ready to begin overriding your theme.

One of your first tasks might be creating custom regions for blocks. Let's say you want a new block above the main content where you'll highlight articles and videos on the front page.

By default, you already have a content region. However, any blocks you activate in this region will be displayed below the page's main content.

This requires that you override your theme's region. To do this, you will need to edit the theme's .info file, in our case mytheme.info.

You will need to redefine all your regions, and enter your new region(s) by adding the following to the file:

	regions[left] = Left sidebar
	regions[right] = Right sidebar
	regions[upper] = Upper
	regions[content] = Content
	regions[header] = Header
	regions[footer] = Footer

In order to register this change (or any change in the info file), you will need to visit Administer | Site building | Themes (at /admin/build/themes). Also note that you must enter all the desired regions when adding a new one even if the defaults are not listed originally in the file, as an override to the regions will remove the defaults entirely. For instance, if we were only to add regions[upper] = Upper, then only that region and the content would appear on a page with none of the other desired regions.

This will make any new regions available to Drupal, in our case creating an additional region labeled upper. The keys on the left of the array ('upper', 'right', and so on) define the variable names for the regions in your page.tpl.php file. The values on the right side Upper, Right sidebar, and so on will be the names for the regions as displayed on the Blocks administration page.

Once you have defined your regions in the template.php file, you need to also make sure that any new regions are displayed in the page.tpl.php file. You'll be able to display a region simply by printing its associated variable (as defined in the region array). For instance, our new upper region will be displayed by printing the $upper variable.

If you are following this example and have overridden the Garland theme, then next you will find the text <?php if ($breadcrumb): print $breadcrumb; endif; ?> in the file. Now add the following just below it:

	<?php if ($upper): ?>
	      <div id="upper">
		<?php print $upper; ?>
	      </div>
	<?php endif; ?>

This will ensure that the upper region is displayed only if there is a value in that variable, which will only be true if you set blocks to display in that region. It will further enclose this region in a unique HTML div that may be customized using the CSS stylesheets.

You will be able to add blocks into this region from Administer | Site building | Blocks (at /admin/build/block). This new region will appear below the breadcrumb on a page, but before any help messages, titles, content, and so on:

Any content provided by modules in Drupal may be overridden in the theme. If you know in general what theme function is creating the content, you will also know the template file or function to create.

For instance, if you want to display individual comments with reply/edit/delete links just below the comment's title rather than after its content, you would edit comment.tpl.php in /sites/all/themes/mytheme to move the code printing the links to just below the title line, so it reads:

	<h3><?php print $title ?></h3>
	<?php if ($links): ?>
	        <div class="links"><?php print $links ?></div>
	<?php endif; ?>

Often you may wish to override a theme that is not provided as a file in the default theme. In these cases, you will need to find the function in the code, and either create a template file (tpl.php) for the markup or create a theme function override in template.php. In some cases, especially for a short snippet of code, it may be easier to create the theme function override. If you make it available as a tpl.php file, this may be easier for themers to work with, particularly if they don't have much coding experience. Also, some theme functions may be more suitable in that format such as when they create a lot of markup in their output.

This is suitable for a theme function override and, in fact, is already available in Garland's template.php. The code for this follows after first searching the Internet to see that the HTML character code for» is ». Simply rewrite the included function as follows:

	function phptemplate_breadcrumb($breadcrumb) 
	{
	    if (!empty($breadcrumb)) 
	    {
	      return '<div class="breadcrumb">'. implode(' &raquo; ', $breadcrumb) .'</div>';
	    }
	}

Our next request is to change the text that reads Comment viewing options above comments to read Comment Controls. (Comment viewing options are set by browsing to Administer | Content management | Content types —admin/content/types and selecting the content type to configure. In Drupal 5, they're set globally at Administer | Content management | Comments| Settings—admin/content/types

Garland has no built-in override for comment controls, so we'll need to hunt through our code to find this. We know that comments are displayed using the comment module, which is found in the /modules/comment directory. So we open the comment.module file in our editor. Searching for the text Comment viewing options, we see the output is generated with the theme_comment_controls function.

To override a theme function, we simply rewrite our new function in template.php, replacing the theme_ in the function name with phptemplate_. So for this example, we will copy the code from the function, place it in template.php in our new theme directory, and make our changes:

function phptemplate_comment_controls($form) {$output = '<div class="container-inline">';
$output .= drupal_render($form);
$output .= '</div>';
$output .= '<div class="description">'. t('Select your preferred way to display the comments and click "Save settings" to activate your changes.') .'</div>';
return theme('box', t('Super-Duper Comment Controls'), $output);
}

You could also have named this function something like mytheme_comment_controls. In fact, though the Garland theme doesn't follow this advice, the official policy is to do that and avoid conflicts when using sub-themes. However, there is also a strong case for using a phptemplate_ prefix. Using the phptemplate_ prefix makes your theme more portable. So if you later change the name of the theme or copy it to another directory for further development, you won't need to change all your mytheme_ references to newtheme_.

Some theme functions lend themselves well to being overridden using a template (.tpl.php) file. Our emboldened editor now asks us to make some overrides to the forum page, so that the link that says Post new Forum topic is repeated at the bottom of the screen.

All modules (as of Drupal 6) must register their themeable functions using a hook_theme function. This means that you can scan that function to quickly find themes that may be overridden.

Thus, we read the forum_theme function at http://api.drupal.org/api/function/forum_theme/6 and see the following:

'forums' => array('template' => 'forums',
'arguments' => array('forums' => NULL, 'topics' => NULL, 'parents' => NULL, 'tid' => NULL, 'sortby' => NULL, 'forum_per_page' => NULL),
),

This looks promising, so we look up theme_forums at the Drupal API. However, it turns up nothing, so we double-check by searching for that function in the forum module. No luck!

It turns out that modules (starting with Drupal 6) may also define their own template files. Knowing this, we scan the forum module directory at /modules/forum and discover several template files there, including forums.tpl.php.

Finally, we copy forums.tpl.php to our theme directory and override it as follows, duplicating our links:

<?php if ($forums_defined): ?><div id="forum">
<?php print theme('links', $links); ?>
<?php print $forums; ?>
<?php print $topics; ?>
<?php print theme('links', $links); ?>
</div>
<?php endif; ?>