Review Site User Manual

TEMPLATES
Adjust Text:  a a a a
« Table of Contents   |   Obtain Review Site »

TEMPLATES

Admin Templates

You will never need to touch the templates that control the administrative portions of Review Site. However, just to be complete, I will mention that the administrative pages are generated using the Perl Template Toolkit templating system, so they operate somewhat differently to the Smarty templates. But like I said, you really don't need to understand how the administrative pages work.

Public Templates

The front end of Review Site is entirely template based. It is all written in Smarty markup language. This means that if you need to add functionality to the program, it is not that difficult to do it.

All of the front end Smarty-based templates live in the following directory:

/rs/reviewsite/my/skins/default/templates

As I write this there are only 14 templates listed in that directory:

about.tpl
article.tpl
compare.tpl
compare_form.tpl
compare_format_column.tpl
compare_item.tpl
contact.tpl
contact_form.tpl
contact_message_text.tpl
index.tpl
navigation.tpl
privacy.tpl
review.tpl
search.tpl

In the sections that follow I will describe briefly what each of these templates does. Note, however, that you can only fully understand a given template by studying it in detail. Of course, if you have no intention of modifying any of the templates, then you really don't need to know anything about how they work. All of the lanugae used in the templates can be configured from the Configure > Language control panel, as discussed next. So editing of templates is entirely optional.

Editing Public Templates

If you wish to edit the public templates there are two options. My preferred method is to download a template from the host, edit it in my favorite text editor (which happens to be NoteTab), and then reupload it when I am done. However, this doesn't prove to be convenient all the time, and it can be very useful to be able to edit templates in place. To this end, a template editor has been added to the back end of Review Site.

To use the template editor simply go to the Templates control panel and pull up the public template that you wish to edit. You will be presented with a TEXTAREA form that contains the template. Make your changes and click on the Save Edits button at the lower right of the page.

Note: Take care not to click on the Replace button by accident. This button allows you to remove ALL of the changes you have made to the template since day one. You'd only do this if perhaps you had so fouled your template that you had no idea how to make it operable again. This can happen, since templates are accumulations of Smarty templating code and you must maintain the proper syntax or your template will not compile.

It is wise when editing a template to not make too many changes at once. That way you will always be able to remember what changes you did make if it turns out you have rendered the template non-compilable. Always visit the public page once you have made some changes to see if the page is functioning as expected. Making corrections is always easier if you do it immediately after making an error, when the problem will likely become apparent to you after a little inspection of the template code.

Language In Templates

For the most part, if you go hunting in the public templates for the language that you see presented on the public pages, you won't find it. The exception is for the templates that control what appears on the About Us page and the Privacy page. As those pages represent large blocks of text it is easier to just present the text in the relevant template, about.tpl and contact.tpl, and let you edit those templates directly to effect the changes in language that you need to make.

For all other public templates the language is made available via the $global data structure which carries language variables in the form of the the lang sub data structure. All of the language is available for editing via the Configure > Language page in your administrative area. So, for example, if you wanted to change the language that appears before the search box, you would change the content of the navigation . search_for variable. That language is then placed on the page inside the navigation.tpl template using the following Smarty tag to access the variable:

	[% $global.lang.navigation.search_for %]

In general, the language variables are named after the template in which they appear, but you could certainly take any language variable tag found in one template and add it directly to another and it would display without a problem. That, in fact, is the main property of the $global hash - it can be used anywhere. That is not the case with the $s data structure, which is strictly local to the template in which it is found.

If you cannot achieve desired language changes simply by editing the language variables from the Configure > Language page, you can always edit the relevant template directly and add to it whatever new language you need.

About Page

The About Us page is governed by a single template: about.tpl

There is no specific data structure passed to this template. Instead, if you need to incorporate information from your configuration file, you can access the $global.cfg hash to pull out configuration values. Here's an example that mentions the site name and uses the URL to the home page, both taken out of the configuration file:

Welcome to <a href="[% $global.cfg.site_document_root_url %]">[% $global.cfg.site_name %]</a>

You can just fill up this template with regular HTML and tell the world about your site.

Article Page

See the section on UNDERSTANDING ARTICLE RECORDS for a full discussion of how Articles work in Review Site. The article.tpl template is fairly easy to understand. It does exactly two things. It places a list of available articles onto the page (it appears on the right side of the page possibly with an article image above it), and the article itself is formatted and presented using data in the $s.article_info hash.

If you do decide to add new columns into the Article table, you WILL be required to add the corresponding Smarty markup in order to extract the information and have it appear on the page. Again, how to do this is discussed in UNDERSTANDING ARTICLE RECORDS.

If you need to get to grips with how the templating system works, this is a good template to study, as it is really very simple.

Comparison Page

The comparison page is by far the most complex of all the pages in the Review Site front end. Your best bet is to steer clear of it. You will find lots of conditional loops for iterating over all the rows and columns associated with the table that is used to place every product in the system onto the page for side-by-side comparisons.

My recommendation is that you simply get to grips with how to add new comparison columns by reading the section on UNDERSTANDING REVIEW RECORDS. When you add a new comparison field to the Review table, the information in it is automatically formatted and added to the comparison page, so really you don't need to mess with anything here.

The comparison page works by figuring out what the comparison columns are in your Review table, and then organizing each product into a separate column that consists mainly of infomation from the comparison columns. The products are ordered frim left to right in order of decreasing value of the rating that you have assigned in your review. The top rated product, therefore, is always placed to the far left, and is always visible. If you have more than half a dozen or so products in your system, the worst rated ones will disappear off the right side of the screen and the visitor will have to scroll to see them.

Note: There are some colors on this page that can be altered from the administrative area. Visit the Configure > Comparisons page to see the few editable colors available.

Contact Us Page

The Contact Us page is actually relatively easy to understand if you study the templates. However, you really don't need to. The relevant templates (there are 3 of them, all prefixed with contact_) are not meant to be played with. So you might as well steer clear of these.

Index Page

The topmost page in Review Site is also known as the Index page. This is the page that visitors are meant to see first when they enter your site. The page is controlled by the index.tpl template. This is another template that you really don't need to touch, since all of the language that appears on it can be modified by visiting the Configure > Language page in the admin area and looking for the Index Page related language entries.

The are a couple of configurable elements on this page. One is the newsletter subscription form, which is discussed in detail in the section Adding A Subscriber Opt-In Form.

The other main configuration that is possible on the Index page concerns the 3 promotion columns that are visible just above the fold of the page. By default, the first column shows the Top Rated product in your system. The next column promotes the Article with the highest value for the Article.priority column. Finally, the last column promotes the Product Comparison page.

If you wish, you can alter this behavior and show the three best rated products in you Review table, one in each of the columns. To do this, visit the Configure > Miscellaneous page and look for the variable named misc_show_all_top_rated. Toggle from No to Yes to get the alternate behavior.


misc_show_all_top_rated     Yes   No

Navigation Template

The navigation template navigation.tpl is special in that its content appears on every public page. If you look at this template you will see that there is header material, which includes the site logo and the navigation links, and there is footer material, which includes the copyright notice and a few more links to other pages such as the privacy page.

The content of every other public page on the site is inserted into the middle of the navigation template using the following Smarty tag:

	[% $s.page_content %]

Just above this tag are a couple of div elements that are responsible for placing the logo and the site name at the top of every page. Those tags look something like the following:


<div style="
	position: absolute;
	top: 0px;
	left: 0px;
	width: 130px;
	height: 130px;
	padding-left: 10px;
	padding-top: 0px;
	border: 0px solid green;"
><a href="[% $global.cfg.site_document_root_url %][% $global.cfg.site_html_url %]"
	><img src="[% $s.images_url %]/index/[% $global.cfg.image_index_logo %]"
		style="float: left;" border="0" /></a></div>

<div style="
	position: absolute;
	top: 0px;
	left: 140px;
	width: 470px;
	padding-top: 16px;
	padding-left: 0px;
	font-size: 28px;
	font-weight: bold;
	font-family: 'Trebuchet MS', Arial, Helvetica, sans-serif;
	border: 0px solid green;
		">[% $global.cfg.site_name %]</div>

Note that the file name for the logo image, which is stored in /my/skins/default/images/index, is given by the value of the configuration variable [% $global.cfg.image_index_logo %]. So you can actually change the logo by going to the Configure > Skin Images page and selecting a new version of the logo.

You can find a few variations of the basic logo in directory /my/skins/default/images/index. These are displayed for your convenience if you visit the Configure > Skin Images page, where you can select a different one. If you have an alternate logo you would like to use, just prefix the file name with the string reviews and add it to that directory, at which point it will be displayed in Configure > Skin Images and you can them select it as the new logo.

If you want a customized version of this button (maybe with "Car Reviews", or whatever, on it), see the information at the bottom of the Configure > Skin Images page. I do not do any graphic design, but one of the designers who provided a pair of the logo images has indicated that he would be willing to receive requests for custom button orders.

I recommend you stick to a logo that is approximately 130 pixels wide by 130 pixels high. If you decide to use a logo with dimensions much different than this then you'll have to edit the CSS in the div element that holds the logo.

If you do need to re-organize this part of the navigation template, it is a good idea to activate the border width of these elements when editing. You will then be able to see the reach of the elements. This is important, because if either of these elements should overlap an interactive element, like the search box, the interactive element will be masked and will not be usable. So don't make the div elements much larger than they need to be.

Privacy Page

Like the About Us page, the privacy.tpl template is not passed any useful information. You can reference the $global.cfg hash, which is available to all templates, if you need to access configuration variables.

The primary purpose of this page is to tell people about the privacy policy you have put in place for your site. Some boiler plate text has already been added to this template, so really you only need to clean it up.

Reviews Page

The review.tpl template contains the code that generates both the page that lists products, and the page that details a product (shows you the product details and the review that you have written for it).

If you add new columns to the Review table you will have to add the appropriate Smarty tags to extract that new information and place it on the page. This is covered in detail in the section on UNDERSTANDING REVIEW RECORDS.

To alter the number of product summaries listed on the RIGHT side of the page, when looking at the list form of the page (not the detail page for a particular product) you can alter the maximum number of summaries displayed by changing the value of the misc_review_list_size variable, which you can find on the Configure > Miscellaneous control panel:


misc_review_list_size      

Search Page

The search.tpl template is pretty basic. It formats the matching articles and products that are picked up from a MySQL FULLTEXT search on several of the columns found in the Article and Review tables. These are the actual columns that are FULLTEXT indexed:

Article.title
Article.author
Article.summary
Article.content

Review.product_name
Review.product_summary
Review.product_description
Review.review_summary
Review.review_text

These columns ought to be sufficient to pick up keyword matches supplied by the input to the search box. Don't ask me to improve the way the search works. I am leaving this up to MySQL to figure out. Obviously, if you want certain products to be picked up on certain keywords, then stuff your keywords into the columns listed above.

If you decide to add more columns to the Article or Review table, and you need to include these in the FULLTEXT search, then read the next main section on the inner workings of the SEARCH ENGINE.


Next Section: SEARCH ENGINE

« Table of Contents   |   Obtain Review Site »

Copyright © 2008 Random Mouse Software. All Rights Reserved.