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...
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:
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:
You also have a path in the HTML area which is normally named like so:
This needs to be renamed as well, before the install, to:
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
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:
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'.
In this case, leave the software in place, and make the following changes in the order specified:
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.
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.
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.
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:
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
Index and Verify
Static and Dynamic
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).
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:
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.
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
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:
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.
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.
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.
Copyright © 2004 Random Mouse Software. All Rights Reserved.