Review Foundry Review Engine User Manual REVIEW RECORDS

Adjust Text:  a a a a

« Table of Contents   |   Obtain Review Foundry »

• REVIEW RECORDS
• Mandatory Fields
• Optional Fields
• Custom Fields

REVIEW RECORDS

The core feature of Review Foundry, of course, is its ability to collect customer reviews (editorial reviews are discussed in another chapter: EDITORIAL REVIEWS). As we advance deeper into the information age, peer reviews from trusted sources (and from unbiased strangers) become increasingly important to our decision making processes. Especially when it comes to investment in goods of one type or another.

When you set up your Review Foundry site you will be forced to think a little about what it is that you want your visitors to do when they submit a review. You can decide to go with a vanilla implementation, in which the review fields are all standard. This option requires little thought from you. Or you can decide to extract extra information from your users by asking specific questions. You can then present this extra information in the displayed review if you consider that a sensible thing to do. Or you can simply use the information for your own purposes (perhaps you want to know best how to market to them).

The latter option, where you decide upon a set of extra review fields requires some thinking. This page will tell you how to implement those ideas.

Mandatory Fields

Customer reviews are now seen all across the web. But their form is not particularly varigated. They generally conform to a set format that involves a number of product attributes that one can rate (usually on a scale of 1 to 5), a one-line review summary, and the review itself, which consists of a block of text. Sometimes the reviewer is also asked to submit summarized pros and cons--one-line descriptions of the best and the worst that the product has to offer. In Review Foundry, all these fields are mandatory.

The mandatory review fields are represented by columns in the Review table.

When the review opens the review submission page, those mandatory field will look something like this:

Optional Fields

In addition to the mandatory fields, which must be filled in order for the review submission to be successful, there are a few optional fields that also get placed on a review form. The reviewer is not obligued to fill these out, but it does enhance their review. These fields convey something of the identity of the reviewer. They are also represented by columns in the Review table:

Custom Fields

Finally, there are the custom reviews fields. These were introduced in Review Foundry version 2.02. If there are questions you wish to ask each of your reviewers in addition to those covered by the mandatory and optional fields discussed above, you can now add extra columns to the relevant table to record the reviewers responses.

But these custom reviews fields are NOT represented by columns in the Review table. Instead, these new columns should be added to either the ReviewItem table, the ReviewMember table, or the ReviewSupplier table, depending on the kind of record for which you will be collecting reviews.

The process of adding custom review columns is exactly the same as for any other table in Review Foundry. One visits the Database control panel in the admin area, pulls up the ReviewItem, ReviewMember, or ReviewSupplier table in the top drop down menu on the left of the page, and selects Columns from the second drop down menu. The resulting page shows the table structure and an Add Column link can be found at the bottom of the page. See the section on ADDING COLUMNS TO A TABLE for explicit instructions on how to add columns of various types to a Review Foundry table.

When you do add a new column to represent a custom review field you need to keep in mind the caveats that go with this type of field:

1. The name of a custom review column must begin with the prefix custom_ so as to mark it for special treatment by Review Foundry. Columns added without the prefix will be ignored.


2. The form element associated with a custom review column will appear on every review submission page of the given type (Item reviews will bear the custom review questions present in the ReviewItem table, and so on). The appearance of these custom review questions will be independent of the container in which the reviewed thing appears. In other words, unlike rating attributes which can be container-dependent in Review Foundry, custom review columns have no container-dependent configuration whatsoever. Therefore, your custom questions need to be highly generic, and specific to the relevant thing type (Item, Member, or Supplier).


3. Custom review fields, once collected, become available to the detail_review_layout.ttml template, should you wish to display that data to your visitors. This means you can fold the information into the general layout of a review. To do so you access the [% custom_data %] hash, in a way analogous to the extraction of mandatory and optional review fields from the [% review_data %] hash.
   
   For example, if you added a ReviewItem.custom_dog_breed column because you wanted to know the breed of dog owned by the reviewer of a dog food product, you would be able to present this information with the review by using the [% custom_data.custom_dog_breed %] tag. Note: if you add custom review columns to more than one of the ReviewItem, ReviewMember, or ReviewSupplier tables, you MUST ensure the columns do not share the same name, so that you can distinguish between them when adding Template Toolkit code to present them in the detail_review_layout.ttml template (should you wish to display those values).
   
   The exception to [% custom_data.column_name %] formatting involves custom review columns that have a Form Type of DATE_SELECTABLE. In this case the date value is broken into year, month, and day values and these values are available as [% custom_data.column_name_year %], [% custom_data.column_name_month %], and [% custom_data.column_name_day %]. This is done so that you can re-order the components as you please. That is, you can write the string '2007-02-06', or '02-06-2007', or even '2007/02/06'. For example, if you added a ReviewItem.custom_purchase_date column and made the Form Type DATE_SELECTABLE, then you would access the year with the tag [% custom_data.custom_purchase_date_year %].


4. To add a corresponding question/instruction to appear above the form element--such as Please select the breed of your dog from the menu below, you should pull up the review.pl language template and add a new entry to be named after the column. For example, if ReviewItem.custom_dog_breed is the custom column name, the language variable should be named custom_dog_breed_question_item (the suffix is the lowercased thing type: item, member, or supplier) in the review.pl language template. If this entry is missing from the template, the Form Display attribute associated with the column will be used (which might be Dog Breed in this case).

As an example of a custom review column that has been added to collect the breed of a dog owned by the reviewer, see the following form element. In practice, the number of dog breeds shown in the drop down would be much greater, of course.

Notes On Adding Custom Fields
If you decide to add a custom column that requires the reviewer to select from 2 or more prefined values, such as with the dog breed example shown above, you will need to add 2 types of values to your column definition. One is the set of strings that make up the possible values that can be stored in, say, the ReviewItem table, for a given reviewer response. This is the Column Values attribute which appears in a column definition. These values (such as retriever_labrador, or german_shepherd, for example) are used in conjunction with multi-valued columns that are represented by drop down menus or a set of check boxes. More will be said below about your choice of a suitable set of storable values.

The other set of values that needs to be defined for the column makes up the Form Values attribute. These are the values displayed in the form element. They are the "human readable" ones which the reviewer will select from--they do not get stored when a selection is made (instead, one one more of the values from the Column Values attribute gets stored).

Here is an example of the list we might chose for the Column Values attribute:

retriever_labrador
retriever_golden
yorkshire_terrier
german_shepherd
beagle
dachshund

and here is the corresponding Form Values attribute:

Retriever (Labrador)
Retriever (Golden)
Yorkshire Terrier
German Shepherd
Beagle
Dachshund

These lists are in one-to-one correspondence. This in fact, is the way I set things up whenever I creat a multi-valued column. However...

There Is A Complication When You Use Lists That Differ
When it comes time to access the data, the value of a tag like [% custom_data.custom_dog_breed %] is going to be something like yorkshire_terrier, because that is the value actually stored in the table. If instead you want to place the string Yorkshire Terrier on the page, it means you have to determine where in the first list the value appears, and then look up the corresponding value in the second list.

You can in fact do this with a bit of Template Toolkit gymnastics by accessing the [% alias.reviewthing_def %] tag (which contains the structure of, say, the ReviewItem table as a hash) and plucking out the relevant info. Here is how you might do that (though see below for a way to avoid this problem entirely):

[%# figure out where the actual value appears in the Column Values list %]
[% index = 0 %]
[% matching_index = 0 %]
[% FOREACH value = alias.reviewthing_def.cols.custom_dog_breed.values %]
	[% IF custom_data.custom_dog_breed.match(value) %]
		[% matching_index = index %]
	[% END %]
	[% index = index + 1 %]
[% END %]

[%# display the matching Form Value %]
[% alias.reviewthing_def.cols.custom_dog_breed.form_values.$matching_index %]

While this is fairly straightforward, you might not want to deal with writing these extra sections of code to translate from one list of values to the other. To avoid having to do so, you can simply make your list of Column Values identical to your list of Form Values.

That way you can simply use [% custom_data.custom_dog_breed %] and the string Yorkshire Terrier will appear on the page. No need for the kind of translation shown above.

Keep considerations like this in mind when you set up your custom review fields. Test as you go. Also, it is not difficult to redefine your list of Column Values or Form Values after you have added a column. Just be sure that you settle on suitable sets before you begin collecting reviews in earnest.

One more thing. I personally prefer using column values that look like yorkshire_terrier rather than Yorkshire Terrier. This is because it reminds me that I am looking at a database value that I have pretty much set in stone. The strings in the Form Values attribute, on the other hand, can be changed at any time, because these are just labels that appear on the form elements. So, when I have implemented two sets of values that look distinctly different, I am not likely to edit the wrong list of values if I should decide one day that I want to change the strings that the user is seeing on the forms. But there is no doubt that editing templates is a whole look easier when the two lists are identical.

« Table of Contents   |   Obtain Review Foundry »