Review Site User Manual

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

GETTING STARTED WITH REVIEW SITE

How To Avoid Reading The User Manual

Review Site is very simple in construction. It might very well be possible to just look at the front end of the application, then look at the structure of the tables (there are only a few of them), and then infer exactly how the application works. If you can do that, you might be able to avoid reading the manual.

On the other hand, unless you have used a database manipulation backend like the one found in Review Site, it might not be completely obvious how you add a new product comparison column to the Review table. I suggest that you do read over the relevant sections for making table structure modifications. That's the only way to be sure you will get the maximum out of using the program.

Having said that, not everything you need to understand about Review Site is found in this user manual. In particular, the front end templates are parsed by the Smarty templating system. If you want to learn about Smarty, then you need to visit the official Smarty documentation pages and do your due diligence. The Smarty code found in the templates is pretty basic. There are foreach loops and some variable assignments using the capture formalism. I am not a Smarty guru, so my Smarty constructs are not advanced. You should be able to follow the template logic without much difficulty.

I am putting just about everything there is to know about running Review Site into the user manual. Because it is such a simple application, I really can do that and expect NOT to have to answer questions about how it works without adding "But, of course, you'd find that's covered in the manual had you taken the time to read it." So do consult the manual before thinking about asking me how something works. I simply don't have the time to repeat myself.

That said, feel free to use the appropriate forum 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 my programs 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. Besides, as far as Review Site goes, the idea is to keep the application simple. If you want complex, then there is always Review Foundry to consider.

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

Administrative Pages

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

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

When you first access this page you should get warnings about the lack of directory protection. Review Site will offer to add .htaccess and .htpasswd files. You should go ahead and have the program put in these files so that only someone with the appropriate password can gain access to these administrative pages. When the directory protection files are in place you will get no more warnings about the lack of security. Note: these directory protection files only work on Apache web servers, so if you are on a non-Apache web server you will have to implement some other form of directory protection. Be sure you do add protection of some sort or else your database access will be wide open to the world!

There are very few administrative pages offered in Review Site. Let's go over what each is for.

Database
The most important administrative page is found when you access the Database link. When you visit this page you can explore the structure of all the tables in Review Site that have a PRIMARY KEY. Admittedly, there are only a couple of tables to check out here, since Review Site is very simple in construction.

You can perform all sorts of operations on your Review Site database records using this interface. You can also alter the structure of Review Site tables, adding columns and keys, say, to the Review table to expand the kinds of information you collect and display. 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 Review Site installation to simply stop working correctly.

Configure
The Configure area offers links to a small number of different options that control the behavior of the program. Currently the only options are to configure the database connection parameters, and to adjust paths or URLs associated with the application. But you really don't need to touch these pages after you have installed the program.

Templates
If you are like me you'll be wanting to edit your templates locally in a plain old text editior before uploading them to your site. However, a template editor has been added to the application so that you can edit a template on-site using a simple TEXTAREA form element to present the template code for modification.

IMPORTANT: You CANNOT use any application like Dreamweaver, or similar, to edit your templates. No templates that contain markup for a templating language like Smarty are going to survive the manipulations of a WYSIWYG editor. If you want to alter your templates you are going to have to at least understand some HTML. To make any significant modifications you will have to also understand the Smarty syntax.

Dynamic Use the Dynamic link to go to the front end of the application so that you can see how your database record modifications have influenced what is shown on the public pages. Despite the fact that all public pages (bar the search engine) appear to be static HTML pages, the pages are all dynamic and are generated by the PHP scripts in the HTML area.

Help
Finally, the Help link will give you access to the Review Site User Manual which you are reading now. 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

I am conscious of the fact that I have repeated this information in several places in the user manual. However, protecting your administrative pages is so important that I feel compelled to drill the information into your brain. The best way to guard against unwanted access to your database is to set up directory protection on your Review Site administrative pages, so that when somebody attempts to gain access, their browser is challenged for a username/password combination.

Review Site will assume that it is on an Apache server and look for .htaccess and .htpasswd files in the following directory, which needs to be protected:

/cgi-bin/rs/reviewsite/do/admin

If it finds the pair of files it assumes they are being used to protect the directory. If it does not find them it will ask you to set up these files yourself, and offer to guide you through the process. In other words, Review Site will install those files for you if you let it. 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 that you have just protected. If you don't get challenged, you are not on an Apache platform and you need to find another way to get those directories protected from unauthorized access. Usually you can do this from a cPanel interface, or something similar, which offers file management features.

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

Once you have met the challenge of logging into this protected /admin directory, usually 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 files from the /admin directory (it can be done from your FTP client) and reestablish them after you have gained access to the Review Site pages that allow you to set up directory protection (or use an alternate method required for non Apache web servers).

Public Pages: Putting Review Site On Your Homepage

I have mentioned elsewhere that for SEO purposes (how the search engines see your content) you can rename the HTML directories that lead to the PHP scripts. So the URL to your index page might look something like this:

http://www.yourdomain.com/napa/wine/index.php

or if you haven't renamed the paths...

http://www.yourdomain.com/rs/reviewsite/index.php

When I create software I don't like assuming that I can take over the home directory and put anything I like in there. So I don't put scripts into the document root. However, you'll most likely want your Review Site public pages to be the first thing your visitor sees when they land on your home page. There are TWO ways to make this happen. The first is to use a .htaccess redirect. The second is to make a copy of the index.php script and put it into the document root. Let's look at those two options in detail...

Redirecting With A .htaccess File

This is a very simple option if you happen to be on a web server that takes instruction from commands found in a .htaccess file. Apache servers, in particular, follow this convention. Simply create a file named .htaccess and place it into your document root (e.g. /public_html). It should have a line like this to cause redirection to the index.php script in the /rs/reviewsite directory:

DirectoryIndex index.htm index.shtml index.php /rs/reviewsite/index.php
Be sure to add a newline (or carriage return) at the end of your file. If the web server finds any of the first 3 files in the document root it will redirect to them, so if you put in an index.php script, then that will be executed. Otherwise the server will redirect to the index.php script in your main Review Site directory, which is /rs/reviewsite

So the visitor will immediately see the main public page as soon as they enter your site.

Redirecting By Adding A Copy Of index.php To The Document Root

The other option is to make a copy of the script at /rs/reviewsite/index.php and place it into your document root. Once you have done that, open up the file so you can edit it. It will look something like this:

<?php

error_reporting(E_ALL);

// index.php is originally found in /rs/reviewsite

$reviewsite_root_dir = dirname(__FILE__);

require_once( $reviewsite_root_dir.'/_include/Site.php' );

$site_args = array(
	'mode'     => 'index',
	'root_dir' => $reviewsite_root_dir,
);

$index =& new Site( $site_args );
$page  = $index->content();

print $page;
exit;

?>

Note the line that specifies the location of the main Review Site directory. The variable $reviewsite_root_dir is automatically inferred from the value of dirname(__FILE__) which evaluates to the current directory. Since the script is no longer in the main Review Site directory this will no longer be a correct path. You need to edit that assignment. Change it to something like this:

$reviewsite_root_dir = '/some/absolute/path/to/public_html/rs/reviewsite';

Or whatever the name of you main Review Site directory happens to be. The point is that on the very next line the script is going to try to pull in the Site.php file and execute it. If the location of the main Review Site directory is not properly specified, that won't happen and you'll just get an error.

So, if you do get an error, then you have very likely specified the WRONG PATH. In this case, telnet or SSH into your account, navigate to the /rs/reviewsite directory, and issue a pwd command to get the present working directory. That will be an absolute path, and the one you should be using to specify the variable $reviewsite_root_dir.

Once you have got the path right you will immediately see the main Review Site page come up when you hit your homepage. Assuming, that is, that the presence of an index.php in the home directory causes that script to be executed first. Modify your .htaccess file if that is not the case.

SEO CONSIDERATIONS
If you DO make a copy of the index.php script and place it into your home page, you will want that location to appear in the navigation links on your site. To do this, visit the Configure > Miscellaneous page and toggle the misc_index_moved_to_home variable to 'Yes'.

When you do that Review Site will understand that the index.php file seen in the home directory is actually its own index file and it will refer to it in the links that appear on its pages. If you don't toggle this variable the application will still function fine, but it will refer to the index file normally found in /rs/reviewsite. From an SEO point of view there would be two pages with exactly the same content. By toggling misc_index_moved_to_home you remove that ambiguity since the index file at /rs/reviewsite will no longer be referred to.

Critical Limitations

As with all things in life, you can never have your cake and eat it when it comes to running a website. Review Site is designed to be ultra light-weight. You won't be able to add 100 review products and have it all look great. For one thing, the product comparison page will be extremely crowded, with all the products lined up side by side for inspection. No visitor is going to want to see anything that complex.

The idea behind Review Site is that you will only present the top handful of poroducts in your niche. So try to stick with 12 or less. Even 5 products, or even 3, may be sufficient if they represent the undisputed leaders in your niche. Your best best is probably to keep the number of reviewed products between 5 and 8.

Remember that you are going to have to review each of these products in detail, so as to (a) make your site unique and (b) add real visitor value to your pages. If you keep that in mind I am sure you will consider 8 reviewed products about the limit that you can handle for your niche.

Foreign Languages

Primarily, Review Site supports those West European languages accommodated by the Latin1, or ISO-8859-1 character set encoding. For example, the languages Dutch, English, French, German, Italian, Spanish, etc. However, you may be able to use non-Latin1 languages with the application. See the Configure > Miscellaneous page for instructions.


Next Section: UNDERSTANDING REVIEW RECORDS

« Table of Contents   |   Obtain Review Site »

Copyright © 2008 Random Mouse Software. All Rights Reserved.