Review Foundry Review Engine User Manual

GETTING STARTED WITH REVIEW FOUNDRY
Adjust Text:  a a a a
« Table of Contents   |   Obtain Review Foundry »

GETTING STARTED WITH REVIEW FOUNDRY

How To Avoid Reading The User Manual

Say what? Any time the author of a piece of complex software tells you that the software is so good it doesn't require you to read the user manual you just know it's too good to be true.

That's certainly the case with Review Foundry. As this program has grown in complexity, so has the manual. No one, including me, knows how to manage the program without reading the manual on occasion. Well, usually it's the Template Toolkit component that I have to turn to. But the same will apply to you when you decide you need to add columns to your tables, or figure out how best to organize your review pages.

So if you find yourself confused by something, don't fret. That's the normal state of affairs for a first time user. I have spent a great deal of time compiling the user manual and adding tutorials to it to make the process of learning Review Foundry as painless as possible. Don't ignore the documentation. You paid for it, and as far as software documentation goes, this user manual ranks as more than decent (hell, I'll just say it: this manual is pretty darn good!).

Moreover, I don't like repeating myself, and if you email me a question about something that is clearly covered in the manual, well, I'll very likely answer it, but I'll also make a mental note of the fact that you're a lazy customer, and I'll try to be just as lazy in my next response, if you do it a second time. So be warned. Besides, there's a good chance that I'm just going to refer you to the user manual anyway.

That said, don't hesitate to ask me questions about things not covered in the manual. Suggestions for improvements are welcomed, but be realistic. I often get requests to completely change the functionality and direction of the program to coincide with a pet project that someone is fantasizing about. For some reason these people are shocked to learn that I'm not interested in their vision, and that I seem to have my own stubborn vision about the future of the software. Keep that in mind when you make requests for improvement. I like good ideas, but I am very selective.

Now, I return you to the regular user documentation channel...

Debranding/Disguising Review Foundry BEFORE Installing

Each time Review Foundry generates a public page it adds a "powered by" link to the bottom of the page. This is a form of advertising for the software that helps keep the price of a key relatively low. However, you have the option of removing the powered by link by purchasing a "non powered by" key.

The advantage to purchasing the non powered by key is that if you have competitors that visit your site, they need not learn that your newly-acquired review pages are produced by an off-the-shelf product that they also can purchase. The upgraded key takes care of removing the powered by links from your pages. However, you will still have the phrase 'foundry' appearing in the path to your Review Foundry executables. If you want to change this, here is what you do. Note that you can do this debranding of the paths even if you intend initially to use the powered by key. If you think you might be purchasing a non powered by key later on, this path debranding will already have been taken care of.

When you download and unpack the software you will be presented with a directory structure that contains the files to upload to your server. One file in particular--the main public Review Foundry executable--will be on a path like this:

/cgi-bin/rs/foundry/do/reviews.cgi

To debrand (or disguise) the fact that the software is Review Foundry, decide on a string other than 'foundry'. Let's say you settled on 'boundry' (to make this easy to follow). We'll also suppose you want to change the string 'rs' in the path to 'fence' (substitute whatever you like or leave as 'rs'). To debrand before installation rename the above path to remove the instances of 'rs' and 'foundry', like so:

/cgi-bin/fence/boundry/do/reviews.cgi

You also have a path in the HTML area which is normally named like so:

/rs/foundry

This needs to be renamed as well, before the install, to:

/fence/boundry

Now, when it comes to installing the software, wherever you would have used the string 'foundry' in a path, you'll now use 'boundry' (or whatever string you settled on, maybe you chose 'reviews'). Likewise for th 'rs' string if you decided to change that too. So, to install, now you will point your browser at

/cgi-bin/fence/boundry/do/admin/install.cgi

During the course of the install, you will be asked to provide or confirm paths and URLs. Make sure they reflect the new path you have selected. In particular, and following our 'boundry' debranding example, you would provide these values:

site_html_path: /fence

site_app_path: /boundry

site_app_script: reviews.cgi (change name if you want to)

These 3 variables are the only ones that need to be adjusted in order to debrand the path. Do remember, however, that in all documentation, any references to paths will use the standard non-debranded paths which contain the strings 'rs' and 'foundry'.

Debranding/Disguising Review Foundry AFTER Installation

WARNING
The above instructions for debranding apply to the case where you are installing the software for the FIRST time. If you have the software installed and you then decide to rebrand, the situation is far more complicated. Here's what you do. Do NOT try to replace the software and do an upgrade in which you rebrand at the same time. That isn't going to work, because the path you want to debrand is embedded into the configuration file AND it appears in executable files, and other places too. So you have to do more work.

In this case, leave the software in place, and make the following changes in the order specified:

  1. Open up /cgi-bin/rs/foundry/my/Foundry/ConfigData.pm in a text editor and make the needed replacements of the strings 'rs' to 'fence', and 'foundry' to 'boundry'. Do likewise for the DBops configuration file at /cgi-bin/rs/dbops/my/DBops/ConfigData.pm if you are changing the 'rs' string.
  2. Delete your /cgi-bin/rs/foundry/perl directory entirely since this contains compiled Template Toolkit templates which contain the old path names. Don't worry, the /perl redirectory will regenerate itself.
  3. Delete all the files in the directory /cgi-bin/rs/foundry/do/admin/templates/compiled -- once again, these files are compiled Template Toolkit templates which have to go. Don't delete the directory, just the files in it.
  4. Locate all of the .pl and .cgi executable files that exist in the 4 directories:

    /cgi-bin/rs/foundry/do
    /cgi-bin/rs/foundry/do/admin
    /cgi-bin/rs/foundry/do/editor
    /cgi-bin/rs/dbops/do/admin

    Open each one in a text editor and edit the path info at the top of each file. There should be 3 "use lib" lines that contain paths that contain the 'rs' and 'foundry' strings. Use cut and paste to fix all of these paths in all the files, replacing with 'fence' and 'boundry' as required. Don't make any mistakes here, or you'll get strange problems when the program runs.
  5. Finally, change the path names of:

    /rs/foundry
    /cgi-bin/rs/foundry/do/reviews.cgi

    These should be changed the same way, so as to end up with:

    /fence/boundry
    /cgi-bin/fence/boundry/do/reviews.cgi
  6. Actually, one more thing. If you have directory protection in place, using .htaccess and .htpasswd files, as Review Foundry and DBops provide, you may find you can no longer login after changing the paths. Simply delete those 2 directory protection files in the following directories, and reestablish them after logging in (Review Foundry will remind you that they are missing):

    /cgi-bin/fence/boundry/do/admin
    /cgi-bin/fence/boundry/do/editor
    /cgi-bin/fence/dbops/do/admin

Once you have made all those changes you should be debranded and the software ought to work using the new debranded paths. At that stage you can go through an UPGRADE process if you need to upgrade to a newer version of the software.

Installed. Now What?

This page of the manual will give you a run down on the important things to consider when thinking about what you should do now that you have installed Review Foundry on your server. If for some reason the install did not go smoothly, seek assistance at Random Mouse Software.

It is worth noting that Review Foundry, while built to be easy to use, is nonetheless a very complex program. It allows for customization, and therefore presents lots of ways to potentially cause problems if too much is attempted. Therefore, common sense suggests that you always pace yourself and never attempt to perform "radical surgery" unless you have a really good idea about the operation you are performing. Most of the time you can simply edit templates and add a column or two to the tables to acheive the results you are looking for.

Tutorial Pages

I strongly recommend that you have a look through the tutorials to get an idea of what you can do with the program. In particular there are a couple of tutorials that you just cannot afford to ignore: HOW TO ORGANIZE REVIEW SITE NAVIGATION and HOW TO TILE REVIEW RECORDS. Read those before you get stuck into customizing templates. If you don't, you'll be overlooking important functionality of the program.

I write tutorials to show more of the motivating factors that might drive a person to create a review site. Also, you can see more examples there of what your review pages might look like if you spend a little time properly configuring the program. You can make some very attractive pages with Review Foundry if you customize just a few aspects of it, so it is worth thinking about this stuff before rushing into it.

For the program creator (me, in this case) writing documentation is so boring that one looks for ways of getting out of spending time doing it. Tutorials represent one way out for me. Writing a tutorial doesn't seem anywhere near as much torture as writing another chapter of documentation. So I think you'll find that reading the tutorials is also much easier for you, the Review Foundry webmaster, than reading a chapter of documentation. But when it comes to doing something concrete, like adding columns to your tables to represent currency, you'll find the documentation chapters essential reading.

So read the tutorials to get inspired, and turn your attention to the main documentation pages when you have a particular problem to solve.

Administrative Pages

The first thing to do after installation is to attempt to bring up the Review Foundry adminstrative pages on your site. The program should be located at some URL like the following:

http://www.yourdomain.com/cgi-bin/rs/foundry/do/admin/admin.cgi

When you first access this page you should get warnings about the lack of directory protection. Review Foundry will offer to add .htaccess and .htpasswd files for both itself and the low-level database manager DBops. You should go ahead and have the program put in these files so that only someone with the appropriate password can gain access to the admin directories of either Review Foundry or DBops (you may never use DBops, which is fine, but you want to be sure no-one else does either!). When the directory protection files are in place you will get no more warnings about the lack of security.

Categories, Teams, and Yellowpages
It goes without saying that you will need to peruse the Review Foundry User Manual in order to properly familiarize yourself with the program. But go ahead and click around in the admin area to get an idea of where things are. You will find that there are 3 browsers in the admin navigation bar. These are named Categories, Teams, and Yellowpages. The first of these allows you to easily add Categories and the Items that go into them. The second, rarely used, allows you to create Teams (which are collections of members), while the third allows for the creation of Yellow Pages, into which Suppliers can be placed. You can read more about Items and Suppliers in other parts of the manual.

Build
Next up, the Build link in the admin navigation bar takes you to a page that allows you to build static pages, which is particularly useful for large sites with lots of traffic. The static pages will also be optimized for the search engines, so it's a good idea to build pages regardless of your level of traffic.

Index and Verify
The next two links in the navigation bar--Index and Verify--allow you to (a) index your tables from scratch so that the internal search engine can find things, and (b) spider all the sites that your Review Foundry pages point to (supposing that you have sites listed in your Review Foundry database) to ensure that they still exist. You will likely not use these two pages that often. Records are automatically indexed when they are created and modified, so indexing from scratch is rarely necessary, and verifying the integrity of links is something that only the most organized of us are prone to attend to!

Relations
The next link on the navigation bar is titled Relations and you can avoid this one entirely. It is an advanced feature (that addresses the relationships between tables) that should not be touched by anyone who isn't extremely familiar with the way Review Foundry works internally. Looking at the actual relations might, however, be useful. Just don't be tempted to start fiddling in there!

Database
Next on the list is the Database link. When you visit this page you can explore the structure of all the tables in Review Foundry that have a PRIMARY KEY. You can perform all sorts of operations on database records from this section. You can also alter the structure of Review Foundry tables, adding columns and keys, say, to the Item table to expand the kinds of information you collect and display. The Database area is where you go when you can't achieve something using the more straighforward and constrained actions of one of the 3 browsers. You will note that you can also create and drop tables. Under no circumstances should you drop a table that you did not create--unless of course you actually want your Rde Queen installation to simply stop working correctly.

Templates
The next administrative area that can be accessed is titled Templates. This is where you go to edit templates withing Review Foundry. Personally, I never use it, as I prefer to load my templates into a text editor, edit, then reupload the file to the place it came from. But using the template editor does allow you to edit in place, if you prefer. There are a LOT of templates in Review Foundry. These are all written using the Perl-mediated Template Toolkit. So if you intend to do lots of template editing it will pay you to learn something about TT (the Template Toolkit). You can read more about this elsewhere in the manual.

Configure
The Configure area offers links to a large number of different options that control the behavior of the program. Most of this is explained in detail on the relevant pages, and you can be sure that because of the large number of potential configurations available, no two Review Foundry installations are likely to be similiarly configured (so pay attention to what you do when you configure things!).

Moderate
When you get around to moderating reviews or other submissions that might come in, you'll do this from the administrative area accessed by the Moderate link. You should find that review moderation is a very straighforward set of operations (item and supplier submissions can also be handled from this section).

Static and Dynamic
The next two links in the administrative area lead to the public portion of your site. If you have built static pages there will be a link named Static to take you to that part of your document root in which the static pages have been built. Otherwise you can use the Dynamic link to get to the same, though dynamically-produced pages (the production of dynamic pages takes somewhat of a toll on your server, so go with static pages whenever you can).

Help
Finally, the Help link will give you access to the Review Foundry User Manual. Peruse it when you have questions. There is a lot of information in there and you will discover that there are quite a few things that you can do to your install to make it uniquely yours.

Protecting Your Administrative Pages

Some parts of the program, like the administrative pages, need to be protected from prying eyes. The best way to do this is to set up directory protection, so that when somebody attempts to access your admin pages their browser is challenged for a username/password combination (your browser will in turn ask you for the information).

Review Foundry will assume it is on an Apache server and look for .htaccess and .htpassws files in the following directories, which need to be protected:

/cgi-bin/rs/foundry/do/admin
/cgi-bin/rs/foundry/do/editor
/cgi-bin/rs/dbops/do/admin

If it finds the pair of files it assumes they are being used to protect the directories. If it does not find them it will ask you to set up these files yourself, and offer to guide you throught the process. If you are on an Apache web platform and follow these instructions you will provide a username and password pair and then be challenged for them when you attempt to return to the page you have just protected (because it is generated by a script in the protected directory). If you don't get challenged, you're not on an Apache platform and you need to find another way to get those directories protected from unauthorized access.

Protecting these directories is very important. Make sure you do it!

Once you have met the challenge of logging into any of these protected directories, your browser will ask you if it can remember the details for you each time you return. This is a good idea, as you won't have to be bothered with supplying your username/password pair each time you return. But do write them down somewhere.

If you find one day that you get challenged again, because your browser has had a hiccup and forgotten the username/password pair, and you find that you too have forgotten the information, simply delete the .htaccess and .htpasswd pair from the directory in question (it can be done from your FTP client) and reestablish them after you have gained access to the Review Foundry pages that allow you to set up directory protection (or use an alternate method required for non Apache web servers).

Public Pages

To access the dynamically-produced public portion of your Review Foundry pages (which is all you'll have available until you get around to building static pages later on) you'll access a URL that looks something like this:

http://www.yourdomain.com/cgi-bin/rs/foundry/do/reviews.cgi

Initially there won't be a whole lot to see here. And it will look fairly bare-boned. There are 3 main areas or branches. The branch marked Items leads to a drill down of all the Categories you have defined (or will shortly). The Members branch will allow people to search for Members who have registered, and if you get around to defining any Teams, those Teams will also be presented as a drill-down. Finally there is the Supplier branch in which you will find all of the Yellow Pages that you enter into the system (like Categories that hold Items, Yellow Pages hold the Suppliers you have assigned to them).

One of the first things you will have to decide upon is how you are going to represent the "things" that go into your Review Foundry database. Will they be Items, or will they be Suppliers? If you are dealing with businesses of some description you might want to represent them as Suppliers, simply because Suppliers get a Supplier Profile page in addition to the detail page that represents reviews. The Supplier Profile page is similar to a Member Profile page, and allows such things as a Supplier logo, a photo, detailed description, and so on. If instead your things are, for example, audio files, then they would better be represented as impersonal Items. In this case you might also consider reserving the Supplier space for the bands that create the audio files, as Items can be associated with Suppliers.

How best to represent the information that goes into the database is up to you to decide. Look through the Review Foundry User Manual carefully and figure out what is possible before you get started. You want to make the right decisions early on. Designing a sound data structure will be important to the success of your endeavor.

Once you have fleshed out a data structure and added a few items to the system you can add some practice reviews to see how the information appears on the pages. Only at this stage is it a good idea to start editing the templates--itself a long process if you are going to create a reviewing section that is uniquely your own. You will want to start with the navigation.ttml template which is used to enclose all public Review Foundry pages. This is where you can add all the material that would normally appear on every other page of your site, such as a global navigation bar, side panels, and footer material. Before you start adding various fonts and colors to your templates, check out what can be achieved by starting on the Styles / Colors configuration page. This alone may save you a lot of time! For more information on editing templates see the TEMPLATES section of the manual.

Again, be sure to check out the TUTORIALS found in this manual. They represent more hands-on discussions of how to go about setting up a site using Review Foundry for different purposes, and are a little more interesting than just reading manual pages.

Shared Or Non-Shared Reviews?

Before you charge ahead with setting up categories and items and so on, it is worth spending a minute to educate yourself about the difference between Shared and Non-Shared Reviews in Review Foundry. Because the two forms may be incompatible, you don't want to try switching from one form to the other some time down the road when it would cause problems. Better to establish the correct choice right at the start and save yourself from headaches later on.

You will find the configuration page for Shared Reviews on the same-named page under the Configure control panel.

By default, Review Foundry allows you to establish a set of independent rating attributes for every category/team/yellowpage you enter into the system. Because these attributes are independent, they cannot be shared between different categories/teams/yellowpages. For example, if an item is shared by two or more categories you might like a review submitted for it to appear in all the categories in which the item appears. However, that cannot happen if the rating attributes are not all the same for every category (the calculation of average ratings for a container depends on the rating attributes, so if they aren't the same everywhere things would break). So to make this work--have a given review appear in every category associated with the item to which the review is attached--we need to do something special. We need to make a universal set of rating attributes to be shared by all categories (or teams, or yellowpages). That is, no independent sets of rating attributes.

This is the meaning of Shared Reviews. There is only one set of rating attributes for ALL categories (or teams, or yellowpages). The downside is that ALL items must be rated in the same way. So they all need to be very similar. For example, if every item in the system is a surfboard, this will work out fine. If some are surfboards and some are wetsuits the number of common rating attributes that we can apply to both products is going to be a lot smaller. Perhaps, quality, and value for money, whereas had we been dealing solely in surfboards we could have used, say, surface finish, ease of handling, and fracture resistance. The upside is that if we are dealing only with surfboards, and we have implemented Shared Reviews, and if the surfboard model 'White Caps M80' appears in four separate categories, then a review submitted for it in any one of those categories will appear in all four categories when it is approved.

Sometimes this is exactly what you want. The more narrow the product or service niche you are dealing with, the more likely that Shared Reviews are going to be the way to go. Of course, if you intend to build static pages, you are going to need a lot more disk space to store all those duplicated reviews!

You can find more information about Shared Reviews elsewhere in the manual. See, for example, Shared Rating Types and the section on configuring Shared Reviews. But here's a case study to get you thinking more about the problem of making the right choices for data representation, and how the idea of Shared Reviews affects your decision making.

Case Study - Travel Site
A potential customer has asked me for advice about his intended travel review site. He wants to review airports, hotels, and general travel destinations. How should he go about representing these in Review Foundry?

His initial suggestion is that he place everything under the Yellowpage branch, so that his airports, hotels, and destinations are all Suppliers. The advantage Suppliers have over Items is that they get a Supplier Profile page in addition to the Detail page, where reviews are presented. Suppliers are usually prefered over Items when it comes to representing businesses or services.

Now, this might work if the customer is not intending to use Shared Reviews. He could set up separate Yellowpages to handle airports, hotels, and destinations. Each main top-level Yellowpage would have it's own set of rating attributes -- one set for airports, one for hotels, and another for destinations. Hotels and destinations could be placed into geographic Yellowpages, so that each yellowpage can only appear in one place. No Shared Reviews required.

But it turns out the customer is thinking of creating different kinds of Yellowpages, and his airports, hotels, and destinations might each appear in several different Yellowpages. Can he still use Shared Reviews in this case?

No. Not unless he is prepared to use the same set of rating attributes to describe everything. Airports would have to be rated on the same attributes that are used for hotels. That's probably not what he wants. So what else can he do? I had to think a little about this before coming up with what I think is the best solution. You will have to think long and hard about your own case too, most likely.

What I would do in this case is make airports Suppliers, and place hotels and destinations would be Items. Why? Three reasons:

  1. If I group hotels and destinations together I might be able to come up with a set of universal rating attributes that is more oriented toward the "neighborhood" of each of them. and that would allow me to use Shared Reviews for the Yellowpages. If the customer was prepared to forgo Shared Reviews he could also set up grographic Yellowpages and use a different set of rating attributes for hotels and destinations.
  2. If Yellowpages were organized geographically if would be easy to add Google Maps to both the Yellowpages and the Detail pages for the hotels and destinations.
  3. By making airlines Suppliers, and making use of the fact that Suppliers can be associated with Items in Review Foundry, it would be easy to attach airlines (in the Yellowpage branch) to destinations (in the Category branch). Links to reviews for the various airlines that service a destination would therefore be incorporated in a natural way. Hotels on the other hand (which are also Items) would not be associated with any airlines.

This representation is not too bad. The main complication is the required treatment of hotels and destinations as "similar things" if Shared Reviews are to be incorporated. If the customer was prepared to go with geographic Yellowpages that would not be an issue. Because airlines are off on their own, the customer is free to use Shared Reviews if he wants to, since the rating attributes for all Suppliers can be made the same (all airline-related attributes).

For your own case it will be up to you to figure out what compromises work best for your data.

Authenticating Your Forum Members

There is no requirement that Review Foundry be hooked up to a forum member database. The program is self-sufficient as regards maintaining member accounts. However, if you think you will want to authenticate your members using the member information in a forum, you will want to make sure the forum is in place and connected to Review Foundry before you start sending visitors to your Review Foundry pages.

The reason for this is that if you allowed RQ to create the member records first, and then later you decided to start authenticating these Review Foundry members on your forum database, your existing Review Foundry members would discover their logins no longer worked and they probably end up creating forum member accounts with username/email info that didn't match their existing Review Foundry account (and that would lead to lost reviews and so on).

So just be aware of that, and set up your forum early on if you intend to use one in combination with Review Foundry. Forum coupling is achieved by visiting the Configure > Auth Coupling page.

Critical Limitations

As with all things in life, you can never have your cake and eat it when it comes to running a website. If you decide to run Review Foundry in dynamic mode only, so that HTML pages are generated on the fly and served to the user's browser, you won't have to worry about disk space problems, because most of the data stays in your database and gets formatted on a per request basis.

That's fine if you don't have too much traffic. But as your traffic increases you may find that the CGI process is slowing down your server. Might be a good time to switch to static pages. That is, build all the pages that the user might want to look at ahead of time. Say, once per week. That means the pages are going to be served up really quickly by the webserver, and your users won't see much at all in terms of latency (system slowness). But built pages consist of files, and possibly a huge number of them, depending on a bunch of factors--not the least of which is the total number of reviewable things you have added to your Review Foundry installation. But there are other important factors too, and these are spelled out in this section on building pages without hitting your disk quota allocation: Reducing Total Page Count. Be sure to read it if you want to avoid making costly planning mistakes.

« Table of Contents   |   Obtain Review Foundry »

Copyright © 2004 Random Mouse Software. All Rights Reserved.