Bob and Sarah are coworkers and food lovers who’ve both built up impressive kitchens full of gadgets, pots and pans, and other cooking tools. Supporting a culinary habit can be expensive, though, and they usually turn to fellow foodies for advice before purchasing new gear. They’ve decided to set up Super Duper Chefs, a website where they and their friends can write recommendations about the cooking equipment they use, share tips, and brag about their latest culinary achievements. They’d like it to be the kind of site they wanted when they were getting started: a fun place that highlights the most useful products and advice.

After talking things over with their friends, Bob and Sarah think they have a handle on what the site should offer. The most important feature is that kitchen products reviewed by the site’s official contributors should be listed with ratings and quick summaries of their best and worst features. Each review should also provide up-to-date pricing information. In addition to the official reviews, visitors to the site should be able to offer their opinions on the products and compare the official ratings with the opinions of other visitors who’ve read the reviews. Everyone who uses the site should also be able to search for reviews that match certain criteria. For example, it should be easy to find reviews of products by a particular manufacturer, or products that mention waffles.

Implementation Notes

The next step is figuring out how to translate that set of features into a shopping list of Drupal functionality. Bob and Sarah are fortunate: the core Drupal software can provide most of what they’re looking for without any additions. We’ll use Drupal’s administrative tools to create a custom “Product review” content type, and set up special permissions for contributors. Those product reviews will be the meat of the site’s content. Core also provides a way to add custom fields to the “Product review” content type for the various bits of information we want to record, with the Field module. We’ll use the Views module to build a listing page of products for quick scanning.

Three requirements for Bob and Sarah’s website, though, will require functionality that we haven’t seen yet: importing product information from another website, allowing users to rate and review content, and building a custom search page.

Product information

First, the site will need to display information about the product that is being reviewed. Who manufactured it? How much does it cost? Where can a visitor to the website purchase it? Although it’s possible to set up custom fields for each of these pieces of information with the core Field module, it’s a real hassle for the site’s editors to fill out all of them for every review. In addition, keeping the pricing information up-to-date can be a chore as the site grows older.

The easiest solution is to let someone else do the work! Amazon.com provides access to its full database of product information, including kitchen gadgets (shown in Figure 5-2), using the Amazon Product Advertising API. The Amazon module lets sites access that product information. That means that writers on the site can fill out one field about the product, and the rest will be handled behind the scenes.

Figure 5-2. The Amazon.com website, displaying kitchen products

In addition to saving time and energy spent entering in the product details, using the Amazon API means that Bob and Sarah can get referral fees whenever someone clicks from their website and purchases an item on Amazon.com. It’s a simple way of earning revenue, and for high-traffic sites, the commissions can add up quickly.

Product ratings

The second challenge is product ratings. The site will need every product to have an official review by an editor, but visitors reading the site need to be able to rate the products as well. Displaying the official rating and the users’ ratings separately will give a more trustworthy representation of how the products perform, reassuring new visitors that the site’s ratings aren’t dominated by a one-sided editor.

The Drupal community has built dozens of plug-in modules that add rating and voting capabilities to sites. A full list is available at http://drupal.org/project/modules?filters=tid:60. Modules such as the Plus1 module add the ability to vote items up in a queue, like the popular sites Reddit and Digg. Others allow each reader to rate content on a scale, then display the average to new visitors. Because it is this average rating capability that we’re interested in, we’re going to use the Fivestar module.

In addition to letting users vote on content, Fivestar provides a Field to separate “official ratings” by a site editor from the normal ratings given by visitors. We can use the Views module to list the two kinds of ratings side by side for comparison. The Fivestar module, like most rating and evaluation modules, is based on Voting API, another Drupal module that handles storage and presentation of voting and rating information for content. We’ll need to install it to use Fivestar.

Custom searching

The third piece of the puzzle is the custom search page that will let visitors to the site find the product reviews they’re looking for. Drupal’s built-in Search module can index the contents of each post, and give visitors a general search page to find posts that contain specific keywords. However, it’s difficult to customize how search results are presented to users, and difficult to control exactly what kinds of content are searched. For example, finding reviews of kitchen appliances written by Bob and sorting them by price would be tricky. Fortunately, the Views module allows us to tie into that search index as well, giving full control over how the results are displayed. We’ll use it to build our custom product search page.

Before we get started, log into the site with the admin account. We’ll begin with a few things that we are going to need.

The first is a new content type for the product reviews. Based on the Super Duper Chefs requirements, we’ll need the following for each review:

Creating the Product Review Content Type

We’ll start by creating the base content type and adding the simplest pieces: the basic text fields needed for the Pros and Cons, grouping those fields together, and allowing comments:

1. First, in the administrative toolbar, click Modules (admin/modules) and enable the following modules:

   • Chaos Tools Suite package

     • Chaos tools

   • Fields package

     • Fieldgroup

2. Next, in the administrative toolbar, click Structure→“Content types” (admin/structure/types) and add a new content type called “Product review,” using the settings indicated in Table 5-1.

   Table 5-1. Settings for the “Product review” content type

   Setting	Value
   Name	Product review
   Description	A featured Product review by a contributing editor.
   Submission form settings
   Title field label	Headline
   Comment settings
   Allow comment title	Unchecked

3. Save the changes you’ve made by clicking the “Save and add fields” button, and you’ll be taken to the “Product review fields” screen to begin setting up the rest of our fields.

4. First, let’s change the label on the Body field to something that makes more sense for our editors. Click the “edit” link for the Body field and change the Label to Review. Click the “Save settings” button, and we’ll be returned to the fields listing.

5. Because we want to group several of the fields in this content type together (the Pros and Cons, ratings, and so on), we’ll first create a Field group to organize them. Under “Add new group,” create a new group with a label of Summary and a group name of “summary”; leave the widget at the default, Fieldset; and then save the form.

6. Next, create a new field using the settings indicated in Table 5-2 and click the Save button.

   Table 5-2. Settings for the Pros field

   Setting	Value
   Label	Pros
   Field name	pros
   Field type	Long text
   Widget type	Text area (multiple rows)

7. On the following screen, click the “Save field settings” button to move on to the full field settings screen. All of the additional settings for the new field can be left at their default values; click the “Save settings” button. Next, repeat the process to create a second field using the same settings, but using the label Cons and the field name “cons.”

8. We have added the fields and a group to the content type. Now let’s group the Pros and Cons together in the Summary group and move them to the top of the form. Drag the fields into the following order (make sure to drag Pros and Cons to the right in order to indent them):

   • Headline

   • Summary

     • Pros

     • Cons

   • Review

   When you’re finished, click the Save button. Your screen should look as pictured in Figure 5-3.

Figure 5-3. The Fieldgroup module allows grouping multiple fields together

Now that we have the “Product review” content type started, we need to add permissions to allow the right people to create them. Bob and Sarah’s friends will each have their own account and be able to post and edit their own reviews as editors of the site. Bob and Sarah themselves will be the administrators of the site and will therefore be able to edit or delete anyone’s posts so that they can keep the site tidy, if needed. In the administrative toolbar, click People, then the Permissions tab (admin/people/permissions), and fill in the values shown in Table 5-3. Click “Save permissions” when you are done.

Table 5-3. Permissions for the “Product review” content type

Permission	anonymous user	authenticated user	editor	administrator
Node
Product review: Create new content			Checked	Checked
Product review: Edit own content			Checked	Checked
Product review: Edit any content				Checked
Product review: Delete own content			Checked	Checked
Product review: Delete any content				Checked

Once you have everything set up, go to Create Content→“Product review” (node/add/review) and enter a simple review. Your new review creation form should look like Figure 5-4.

Figure 5-4. Creating a product review

The “Product review” content type is well on its way—it’s now possible to create a new review, fill out the pros and cons, and display the results on the front page of the site. The finished review should look something like Figure 5-5. In the next section, we’ll be adding more complete product information, straight from Amazon.com.

Figure 5-5. A completed review with basic information

Amazon.com is one of a large number of web-based businesses that have opened up their product information databases for other sites to access. In the case of Super Duper Chefs, we want to retrieve useful data like product photos, pricing, and manufacturer information for display on our own website. The Amazon module for Drupal allows us to do just that.

In the previous section of this chapter, we set up a content type for our product reviews. Now, we’re ready to add a field to store a link to the product on Amazon.com. We need to do a few things to get set up before we add the field to our content type:

Figure 5-7. AWS access credential information

Adding the Product Field

Having set up the Amazon module, we’re ready to continue customizing the “Product review” content type:

1. In the administrative toolbar, click Structure→“Content types” (admin/structure/types) and click the “manage fields” link (admin/structure/types/manage/product-review/fields) for the “Product review” content type. Create a new field using the settings indicated in Table 5-4.

   Table 5-4. Creating the Product ID field

   Setting	Value
   Label	Amazon Product ID
   Name	product_id
   Field type	Amazon item
   Widget	Amazon ASIN text field

2. Click the Save button to create the field and then click the “Save field settings” button to proceed. You’ll be taken to the next screen to fill out the product review field settings. Add some Help text, like “Enter the Amazon product ID of the item you’re reviewing. Often indicated by an ASIN, ISBN, or other field in the product details of an Amazon product page.”

Finding Product IDs

Our Amazon field will automatically load product photos and pricing information whenever we enter a product ID. That’s great—but how will the site’s reviewers find those product IDs in the first place?

The simplest way is to find the product on the Amazon.com website using its own search function. Each product has its own page on Amazon.com, and the product ID usually appears there in two locations: the URL of the page itself, and the “Product details” section of the page, listed as the ASIN (short for Amazon Standard Identification Number). See Figures 5-8 and 5-9 for examples.

Figure 5-8. An Amazon product page’s URL, with the product ID highlighted

Figure 5-9. An Amazon product page’s details section

1. Click the “Save settings” button to complete the process, and you’ll be returned to the “Manage fields” page for the “Product review” content type.

2. On the “Manage fields” page (admin/structure/types/manage/product-review/fields), rearrange the new Amazon field so that it is listed just above the Review field, like so:

   • Headline

   • Summary

     • Pros

     • Cons

   • Amazon product ID

   • Review

3. Click the Save button to save your ordering. In the administrative toolbar, click “Add content”→“Product review” (node/add/product-review) and add a new review. This time, fill out the Amazon Product field as well as the normal Headline, Pros and Cons, and Review fields. Your new review should look something like Figure 5-10 (showing Amazon product ID B0007GAWRS).

Figure 5-10. A review with Amazon.com product details

Later, we’ll use the field display settings to control what information is output by Amazon on these nodes, as well as the order in which it is displayed with the other review information.

For even more fine-grained control over the display of Amazon product data, particularly on more standard “media” products such as books and software, the Amazon Media module we touched on in Spotlight: Amazon Module includes a series of template files that can be customized to grab the specific fields you want for your site.

Our product reviews now contain fields for product pros and cons, and a link to Amazon.com for each product. What’s left? We need some way to capture the editorial rating for each product that’s reviewed, and a way for visitors to the site to add their own ratings as well. For that, we’ll take a look at the Voting API and Fivestar modules.

Giving visitors a chance to evaluate and rate content is an extremely common pattern on content-rich websites. In addition to giving visitors a way to jump to the best content, it can give you—the site’s administrator—a way to determine what content on your site is most effective.

Almost all rating and evaluation modules for Drupal rely on a shared module called Voting API. Though it offers no features for your site on its own, it gives developers a set of tools for building rating systems and provides a common format for storing votes and calculating the results. This allows developers to focus on what makes their work unique (presenting vote results in a novel way, for example) while Voting API handles the grunt work.

The Fivestar module offers numerous configuration options, from the style and color of stars that it uses to display ratings to how results are presented when visitors look at a new piece of content. Figure 5-11 shows the Fivestar module’s selection of rating widgets. The widget visitors use to rate each post can be displayed in the post itself, in a floating sidebar block, or even in the commenting form when visitors submit a reply.

Figure 5-11. The Fivestar module’s selection of rating widgets, available on its configuration screen

Despite what its name suggests, Fivestar can display any number of stars: 10 stars, 3 stars—even 1-star scales can be used. In addition, it provides a custom field type: a simple numeric field on any piece of content can be displayed using Fivestar’s custom widget, separate from the ratings cast with Voting API.

For the Super Duper Chefs site, we’ll be using both of the Fivestar module’s unique features: adding a static Rating field to the “Product review” content type for the editors to use, and attaching a voting widget to the comment form on each review for the site readers to use. That approach will keep the official rating on each review separate from the reader ratings.

First, in the administrative toolbar, click Modules (admin/modules) and enable the following modules:

Adding the Reader Rating Field

As we’ve pointed out elsewhere in the book, fields can be added to anything in Drupal that is exposed as an entity. Now we will make use of this in practice, by adding a Rating field to the comments, so visitors can comment and rate the products as well.

1. In the administrative toolbar, click Structure→“Content types” (admin/structure/types), click the “edit” link for the “Product review” content type (admin/structure/types/manage/product-review), and then click the Comment Fields tab (admin/structure/types/manage/product-review/comment/fields). Add a new field using the settings in Table 5-6.

   Table 5-6. Creating the Rating field for comments

   Setting	Value
   Label	Reader Rating
   Name	reader_rating
   Field type	Fivestar Rating
   Widget	Stars

2. Click the Save button. On the field settings screen, it is important to set the “Voting target” to “Parent node,” so that these votes will add ratings to the node; then, click the “Save field settings” button. We’ll use the defaults on the “Product review” comment settings page, so just click “Save settings” to finish.

3. When you return to the Comment Fields screen, reorder the fields so that the “Reader rating” field is at the top and then click Save.

   Note

   Remember that you can play with the settings by going to the administrative toolbar, then Configuration→Fivestar (admin/config/content/fivestar), to choose fun icons such as hearts or flames that readers can use to rate content. If you choose a widget listed under “Custom color widgets,” you can even choose a color scheme that matches your site.

4. With the ratings in place, we need to allow the site users to actually rate things. In the administrative toolbar, click People, then the Permissions tab (admin/people/permissions), and set the permissions shown in Table 5-7. Click the “Save permissions” button to finish up.

   Table 5-7. Permissions for Fivestar ratings

   Permission	anonymous user	authenticated user	editor	administrator
   Fivestar
   Rate content		Checked	Checked	Checked
   Use PHP for Fivestar target				Checked

   Note

   Recall from Hands-On: Configuring Permissions that any permission name with “PHP” in it should only be given to extremely trusted users.

All of the essentials for the reviews are now in place. Editors on the site can write reviews that include pros and cons about the product, rate the product using an intuitive five-star scale, and pull in product information from Amazon.com. In addition, visitors can post their own comments about the product and rate it themselves. Figure 5-12 shows our new Fivestar ratings in action.

Figure 5-12. A product with an editorial rating, along with a user review in progress

Drupal’s theming system gives designers complete control over how a site’s content is rendered for a web browser, and custom themes (like the Tarski theme that we’re using for the Super Duper Chefs site) can give any site a distinctive look. But sometimes it’s useful to make minor tweaks to a site’s appearance using nothing but CSS rules. They allow designers to tweak font sizes, colors, and so on without altering the underlying HTML that defines the site’s structure.

The CSS Injector module gives administrators the ability to add those snippets in an administration screen within your site, without having to make changes to the current theme’s files. This feature can be useful when a new version of your site’s theme is released on Drupal.org—if you change the theme to add your own CSS, it’s easy to lose those modifications when you download the new version. Keeping them in CSS Injector will preserve them even if you change themes.

CSS Injector offers a number of advanced options, including the ability to add the CSS rules conditionally on certain pages. If your CSS tweaks only apply to the front page, for example, you can ensure that it won’t add the unnecessary rules to the entire site. You can also specify a media type for your CSS, which makes it possible to add styling information that applies only when a page is being printed. Finally, each rule can use the Preprocess CSS checkbox to control whether Drupal should merge its rules with the current theme’s CSS. In most cases, this step saves time, because a visitor’s web browser makes only a single trip to your site’s web server to download all the stylesheets. If you’re adding extremely large amounts of CSS code that only apply to one or two pages, it can be more efficient to keep that code separate by turning preprocessing off. Otherwise, leave it enabled.

In this section, we’ll do some final tweaking to make the review display look nice and tidy, as pictured in Figure 5-13.

Figure 5-13. Completed review display

Setting Field Display Options

Although our “Product review” content type has all of the data we need, and our product listing pages are looking great, the individual reviews still look a bit untidy. Fortunately, we can use the Field module’s display settings to tweak how each type of field is displayed in the reviews.

1. In the administrative toolbar, click Structure→“Content types” (admin/structure/types) and click the “manage display” link for the “Product review” content type (admin/structure/types/manage/product-review/display).

2. The first thing we want to do is to add a field group to the display for our Editor Rating, Pros, and Cons fields, just like we did for the form input fields. This time, we’ll make the HTML element a <div> for tidy markup. Fill out the “Add new group” settings as shown in Table 5-8. Save the settings.

   Table 5-8. Settings for the Summary fieldset

   Field	Setting
   Label	Summary
   Group name	summary
   Format	Div

3. Click the gear icon next to the Summary format information and change the “Fieldgroup settings” to Open. Click the Update button and then the Save button to save the settings.

4. Drag the fields into the proper order so that they look like this:

   • Summary

     • Editor rating

     • Pros

     • Cons

   • Amazon Product ID

   • Review

5. Click the Teaser subtab (admin/structure/types/manage/product-review/display/teaser) and repeat the preceding steps to create a Summary div (set to “open”) on the teaser display as well. Then drag the fields so that you have the following fields displayed in this order (note that the Review field should be moved down to the Hidden part of the form):

   • Summary

     • Editor rating

     • Pros

     • Cons

   • Amazon Product ID

   • Review

6. Finally, fill out the settings as shown in Table 5-9 for the default and teaser displays, respectively. Figure 5-14 shows the default display settings after we’ve made these changes; the teaser display will look very similar. Click the Save button when you are done.

   Table 5-9. Display settings for the “Product review” content type

   Field	Label	Format
   Default
   Editor Rating	Inline	As Stars (default)
   Pros	Inline	Default (default)
   Cons	Inline	Default (default)
   Amazon Product ID	<Hidden>	Thumbnail with details
   Review	<Hidden> (default)	Default (default)
   Teaser
   Editor Rating	Inline	As Stars
   Pros	Inline	Default
   Cons	Inline	Default
   Amazon Product ID	<Hidden>	Thumbnail with title
   Review	<Hidden>	<Hidden>

Figure 5-14. Settings for the default product review display; the teaser display will look very similar

If you navigate back to one of your reviews, the node view will look essentially the same at this point. In the next section, though, we’ll add some fanciness!

Configuring CSS Injector

Changing the display settings for our reviews cleans things up quite a bit, but the Summary information still seems awkward. We can significantly improve things by adding some CSS rules using CSS Injector. We’ll use it to reduce the width of the Summary box and float it to the side of each review, turning it into a floating sidebar rather than a header at the top of each review. Here’s how:

1. In the administrative toolbar, click Modules (admin/modules) and enable the Other: CSS Injector module.

2. In the administrative toolbar, click Configuration→Development→CSS Injector (admin/config/development/css_injector) and click the “Create a new rule” link to add a new CSS rule.

1. Name the rule “Floating Summary fields,” and enter the following text into the CSS code field. You can see the completed form in Figure 5-15:

   div.group_summary {
     border: 1px solid lightgrey;
     float: right;
     padding: 10px;
     width: 250px;
     font-size: .9em;
   }
   
   div.group_summary div.field-label {
     font-weight: bold;
   }
   
   div.field-type-asin {
     clear: none;
     width: 400px;
     margin-bottom: 10px;
     border: none;
   }
   
   div.field-type-asin img {
     float: left;
     padding-right: 10px;
   }

   Note

   Not a fan of typing? Not to worry. This code is also available in the assets/ch05-reviews/amazon.css file in the book’s source code for easy copying and pasting.

2. Click the Save button to add the new rule.

Figure 5-15. Adding a new CSS Injector rule

Depending on your web browser’s settings, you may need to clear the browser’s cache to see the changes to the stylesheet. Once you’ve done that, return to one of the product reviews added earlier. It should look quite a bit more attractive, as shown earlier in Figure 5-13. What a difference a dash of CSS makes!

Now that we have a few products, we really ought to add a listing page that lets visitors look over all of the products that have been reviewed, comparing official ratings with visitor ratings and sorting by various criteria, as pictured in Figure 5-16. This page will be simple to build with the Views module.

Figure 5-16. Product Finder view

When all those steps have been completed, save the view, which should look like Figure 5-17.

Figure 5-17. Completed Product Finder view settings

With the settings we’ve used, you should now see a “Product finder” link (product-finder) in the site’s Navigation menu. Upon clicking it, you should see a tidy listing of all the reviews on the site, with official and reader ratings compared side by side, as shown earlier in Figure 5-16.

Only one feature remains from our to-do list: build searching capabilities into our product list so visitors can easily filter it down to find products that interest them.

Drupal’s built-in Search module offers powerful, flexible searching features and intelligent ranking of results. Behind the scenes, it’s silently building an index of all the words used in the site’s content. When users search for a phrase on the site, content is ranked using customizable rules and displayed in order of relevance. On any Drupal site, you can refine these rules by going to the administrative toolbar and clicking Configuration→“Search and Metadata”→Search Settings (admin/config/search/settings) and changing the Content Ranking weights, pictured in Figure 5-18.

Figure 5-18. The Search module’s content ranking settings

The Search module also offers more detailed options for sites with large amounts of content. The Advanced Search screen, pictured in Figure 5-19, allows users to choose exactly what content they want to search, filtering based on content type, free tagging terms, and other criteria.

Figure 5-19. The Advanced Search page in action

To transform the Product Finder page into a searchable index, we’ll be adding two new filters to the view: one that restricts the results by manufacturer and another that restricts results to reviews that mention specific words.

Normally, these filters are locked in place and can’t be modified except by the site’s administrator. We need users to enter their own criteria, however. Fortunately, Views allows us to “expose” any of its normal filters. Doing so adds a small form to the heading of the view’s display page. Visitors to the site can use it to change how Views filters its results, turning any view into a simple search tool, as pictured in Figure 5-20.

Figure 5-20. Searchable Product Finder view

Here are the steps to get your searchable list:

Figure 5-21. Completed Product Finder view settings

Before we test our new search feature, we need to make sure that we give search permissions to the users. We want everyone who visits the site to be able to search. In the administrative toolbar, click People, then the Permissions tab (admin/people/permissions), and set the permissions as indicated in Table 5-15, which will give the option to all users, both logged in and anonymous. Save the permissions.

If you search for a keyword like “whistle” that ought to be returning results but find that it is not, fear not! The last thing we need to do is make sure that our site has been indexed, so that when we do a search the keywords will be accessible. While testing things out, we will manually update our site so we can see that our search is working properly. In the administrative toolbar, click Configuration→System→Cron (admin/config/system/cron), and click the “Run cron” button.

Now go to our Product Finder page (http://example.com/product-finder). You should see the normal page full of products, this time with filter fields above the list. Enter a phrase that appears in one of your reviews, and click the Apply button. You should see an attractive list of the top results that contain the phrase, as we saw earlier in Figure 5-20.

We’re almost done! The only problem with our view now is that clicking the titles in the view links to Amazon.com instead of to our own website. Fortunately, Views provides a handy trick for just this sort of situation; we can “rewrite” the output of the Title field to create a link back to its referring node instead.

Doing this requires two steps: first, adding the field(s) you want to use as a replacement value, and then configuring the output settings for the field:

Figure 5-22. The Views module allows you to rewrite field output using dynamic values

Congratulations! All of the major features for the site are in place. If you’re interested in experimenting further, there are quite a few opportunities for additional enhancements using other Drupal modules:

After all that work, where have we arrived? We’ve hit all of the major pieces of functionality that Bob and Sarah wanted. Using Field, Amazon, and Fivestar, writers can post their reviews of cool kitchen products to the site. With Fivestar and Voting API, visitors to the site can offer their opinions on those same products and participate in the reviewing process. And with Views’ Search module integration, it’s easy for them to find the exact products that they’re interested in. Finally, the CSS Injector module allowed us to sprinkle on those finishing touches that make the site really shine.

Here are the modules that we referenced in this chapter:

Here are some other resources we referenced: